8:44 a.m.
Author: chukhutsina
Date: 2009-07-18 09:44:04 -0400 (Sat, 18 Jul 2009)
New Revision: 16657
Modified:
trunk/hibernatetools/docs/reference/en/modules/ant.xml
trunk/hibernatetools/docs/reference/en/modules/codegen.xml
trunk/hibernatetools/docs/reference/en/modules/codegenarchitecture.xml
trunk/hibernatetools/docs/reference/en/modules/plugins.xml
trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml
Log:
<html><head><meta name="qrichtext" content="1"
/></head><body style="font-size:9pt;font-family:Sans Serif">
<p>https://jira.jboss.org/jira/browse/JBDS-652-Hibernate Tools Reference Guide was
checked and updated. </p>
</body></html>
Modified: trunk/hibernatetools/docs/reference/en/modules/ant.xml
===================================================================
--- trunk/hibernatetools/docs/reference/en/modules/ant.xml 2009-07-17 22:37:13 UTC (rev
16656)
+++ trunk/hibernatetools/docs/reference/en/modules/ant.xml 2009-07-18 13:44:04 UTC (rev
16657)
@@ -51,11 +51,9 @@
classpathref="toolslib" />
]]></programlisting>
- <para>This <emphasis>
- <property>
- <literal><taskdef></literal>
- </property>
- </emphasis> defines an Ant task called <emphasis>
+ <para>This
+ <code><taskdef></code>
+ defines an Ant task called <emphasis>
<property> hibernatetool </property>
</emphasis> which now can be used anywhere in your ant <emphasis>
<property>build.xml</property>
@@ -203,9 +201,7 @@
<section>
<title>Basic examples</title>
- <para>The following example shows the most basic setup for generating
pojo's via <emphasis>
- <property><hbm2java></property>
- </emphasis> from a normal <emphasis>
+ <para>The following example shows the most basic setup for generating
pojo's via <code><hbm2java></code> from a normal
<emphasis>
<property>
<literal>hibernate.cfg.xml</literal>
</property>. </emphasis> The output will be put in the
<emphasis>
@@ -223,11 +219,8 @@
<para>The following example is similar, but now we are performing multiple
exports from the
- same configuration. We are exporting the schema via <emphasis>
- <property><hbm2dll></property>, </emphasis>
generates some DAO code via <emphasis>
- <property><hbm2dao></property>
- </emphasis> and finally runs a custom code generation via <emphasis>
- <property><hbmtemplate></property>. </emphasis>
This is again from a normal <emphasis>
+ same configuration. We are exporting the schema via
<code><hbm2dll></code>, generates some DAO code via
<code><hbm2dao></code>
+ and finally runs a custom code generation via
<code><hbmtemplate></code>. This is again from a normal
<emphasis>
<property>hibernate.cfg.xml</property>
</emphasis> and the output is still put in the <emphasis>
<property>
@@ -258,13 +251,13 @@
<section>
<title>Hibernate Configurations</title>
- <para><literal>Hibernatetool</literal> supports four different
Hibernate configurations: A
- standard Hibernate configuration <emphasis>
- (<property><configuration></property>),
</emphasis> Annotation based
- configuration <emphasis>
(<property><annotationconfiguration></property>),
- </emphasis> JPA persistence based configuration <emphasis>
- (<property><jpaconfiguration></property>)
</emphasis> and a JDBC based
- configuration <emphasis>
(<property><jdbcconfiguration></property>) </emphasis>
+ <para><emphasis>Hibernatetool</emphasis> supports four different
Hibernate configurations: A
+ standard Hibernate configuration
+ (<code><configuration></code>), Annotation based
+ configuration (<code><annotationconfiguration></code>),
+ JPA persistence based configuration
+ (<code><jpaconfiguration></code>) and a JDBC based
+ configuration (<code><jdbcconfiguration></code>)
for use when reverse engineering.</para>
<para>Each have in common that they are able to build up a Hibernate
Configuration object from
@@ -282,9 +275,9 @@
<section>
<title>Standard Hibernate Configuration
(<configuration>)</title>
- <para>A <emphasis>
- <property><configuration></property>
- </emphasis> is used to define a standard Hibernate configuration. A
standard Hibernate
+ <para>A
+ <code><configuration></code>
+ is used to define a standard Hibernate configuration. A standard Hibernate
configuration reads the mappings from a <emphasis>
<property>cfg.xml</property>
</emphasis> and/or a fileset.</para>
@@ -440,25 +433,25 @@
<section>
<title>Annotation based Configuration
(<annotationconfiguration>)</title>
- <para>An <emphasis>
- <property><annotationconfiguration></property>
- </emphasis> is used when you want to read the metamodel from EJB3/Hibernate
Annotations
+ <para>An
+ <code><annotationconfiguration></code>
+ is used when you want to read the metamodel from EJB3/Hibernate Annotations
based POJO's.</para>
<important>
<title>Important:</title>
<para>To use it remember to put the jar files needed for using hibernate
annotations in the
- classpath of the <emphasis>
- <property><taskdef></property>, </emphasis>
i. e.
+ classpath of the
+ <code><taskdef></code>, i. e.
hibernate-annotations.jar and hibernate-commons-annotations.jar.</para>
</important>
- <para>The <emphasis>
- <property><annotationconfiguration></property>
- </emphasis> supports the same attributes as a <emphasis>
- <property><configuration></property>
- </emphasis> except that the configurationfile attribute is now required as
that is from
- where an <literal>AnnotationConfiguration</literal> gets the list of
classes/packages it
+ <para>The
+ <code><annotationconfiguration></code>
+ supports the same attributes as a
+ <code><configuration></code>
+ except that the configurationfile attribute is now required as that is from
+ where an <emphasis>AnnotationConfiguration</emphasis> gets the list
of classes/packages it
should load.</para>
<para>Thus the minimal usage is:</para>
@@ -477,9 +470,8 @@
<section>
<title>JPA based configuration
(<jpaconfiguration>)</title>
- <para>A <emphasis>
- <property><jpaconfiguration></property>
- </emphasis> is used when you want to read the metamodel from JPA/Hibernate
Annotation where
+ <para>A <code><jpaconfiguration></code>
+ is used when you want to read the metamodel from JPA/Hibernate Annotation where
you want to use the auto-scan configuration as defined in the JPA spec (part of
EJB3). In
other words, when you do not have a <emphasis>
<property>hibernate.cfg.xml</property>, </emphasis> but
instead have a setup where you use
@@ -487,9 +479,8 @@
<property>persistence.xml</property>
</emphasis> packaged in a JPA compliant manner.</para>
- <para>The <emphasis>
- <property><jpaconfiguration></property>
- </emphasis> will simply just try and auto-configure it self based on the
available
+ <para>The <code><jpaconfiguration></code>
+ will simply just try and auto-configure it self based on the available
classpath, e.g. look for <emphasis>
<property>META-INF/persistence.xml</property>.
</emphasis></para>
@@ -500,12 +491,9 @@
</emphasis> is specified it will automatically search for one and if a
unique one is found,
use it, but if multiple persistence units are available it will
error.</para>
- <para>To use a <emphasis>
- <property><jpaconfiguration></property>
- </emphasis> you will need to specify some additional jars from Hibernate
EntityManager in
- the <emphasis>
- <property><taskdef></property>
- </emphasis> of the hibernatetool. The following shows a full
setup:</para>
+ <para>To use a <code><jpaconfiguration></code>
+ you will need to specify some additional jars from Hibernate EntityManager in
+ the <code><taskdef></code> of the hibernatetool. The
following shows a full setup:</para>
<programlisting role="XML"><![CDATA[<path
id="ejb3toolslib">
<path refid="jpatoolslib"/> <!-- ref to previously defined toolslib
-->
@@ -545,11 +533,7 @@
<section>
<title>JDBC Configuration for reverse engineering
(<jdbcconfiguration>)</title>
- <para>A <emphasis>
- <property>
- <literal><jdbcconfiguration></literal>
- </property>
- </emphasis> is used to perform reverse engineering of the database from a
JDBC connection.</para>
+ <para>A <code><jdbcconfiguration></code> is used to
perform reverse engineering of the database from a JDBC connection.</para>
<para>This configuration works by reading the connection properties either
from <emphasis>
<property>hibernate.cfg.xml</property>
@@ -557,15 +541,9 @@
<property>hibernate.properties</property>
</emphasis> with a fileset.</para>
- <para>The <emphasis>
- <property>
- <literal><jdbcconfiguration></literal>
- </property>
- </emphasis> has the same attributes as a <emphasis>
- <property>
- <literal><configuration></literal>
- </property>
- </emphasis> plus the following additional attributes:</para>
+ <para>The <code><jdbcconfiguration></code> has the
same attributes as a
+ <code><configuration></code>
+ plus the following additional attributes:</para>
<programlisting role="XML"><![CDATA[<jdbcconfiguration
...
@@ -635,9 +613,8 @@
</entry>
<entry>
- <para>Name of a class that implements
- org.hibernate.cfg.reveng.ReverseEngineeringStrategy. Used for setting
up the
- strategy the tools will use to control the reverse engineering, e.g.
naming of
+ <para>Name of a class that implements
org.hibernate.cfg.reveng.ReverseEngineeringStrategy.
+ Used for setting up the strategy the tools will use to control the
reverse engineering, e.g. naming of
properties, which tables to include/exclude etc. Using a class instead
of (or as
addition to) a reveng.xml file gives you full programmatic control of
the reverse
engineering.</para>
@@ -673,7 +650,7 @@
<entry>
<para>If true, columns named VERSION or TIMESTAMP with appropriate
types will be
mapped with the appropriate optimistic locking corresponding to
- <version> or <timestamp>.</para>
+ <code><version></code> or
<code><timestamp></code>.</para>
</entry>
<entry>
@@ -689,12 +666,8 @@
<section>
<title>Example</title>
- <para>Here is an example of using <emphasis>
- <property>
- <literal><jdbcconfiguration></literal>
- </property>
- </emphasis> to generate Hibernate xml mappings via <emphasis>
- <property><hbm2hbmxml></property>.</emphasis>
The connection settings here
+ <para>Here is an example of using
<code><jdbcconfiguration></code> to generate Hibernate xml
mappings via
+ <code><hbm2hbmxml></code>. The connection settings
here
is read from a <emphasis>
<property> hibernate.properties </property>
</emphasis> file but could just as well have been read from a
<emphasis>
@@ -715,18 +688,14 @@
<para>Exporters are the parts that do the actual job of converting the
hibernate metamodel into
various artifacts, mainly code. The following section describes the current
supported set of
exporters in the <property>Hibernate Tool</property> distribution. It
is also possible for
- userdefined exporters, that is done through the <emphasis>
- <property>
- <literal><hbmtemplate></literal>
- </property>
- </emphasis> exporter.</para>
+ userdefined exporters, that is done through the
+ <code><hbmtemplate></code>
+ exporter.</para>
<section>
<title>Database schema exporter (<hbm2ddl>)</title>
- <para><emphasis>
- <property><hbm2ddl></property>
- </emphasis> lets you run schemaexport and schemaupdate which generates the
appropriate SQL
+ <para><code><hbm2ddl></code> lets you run
schemaexport and schemaupdate which generates the appropriate SQL
DDL and allow you to store the result in a file or export it directly to the
database.
Remember that if a custom naming strategy is needed it is placed on the
configuration
element.</para>
@@ -891,8 +860,7 @@
<section>
<title>Example</title>
- <para>Basic example of using <emphasis>
- <property><hbm2ddl></property>, </emphasis>
which does not export to the
+ <para>Basic example of using
<code><hbm2ddl></code>, which does not export to the
database but simply dumps the sql to a file named <emphasis>
<property>sql.ddl</property>. </emphasis></para>
@@ -904,11 +872,9 @@
</section>
<section>
- <title>POJO java code exporter
(<literal><hbm2java></literal>)</title>
+ <title>POJO java code exporter (<hbm2java>)</title>
- <para><emphasis>
- <property><hbm2java></property>
- </emphasis> is a java codegenerator. Options for controlling whether JDK 5
syntax can be
+ <para><code><hbm2java></code> is a java
codegenerator. Options for controlling whether JDK 5 syntax can be
used and whether the POJO should be annotated with EJB3/Hibernate
Annotations.</para>
<programlisting role="XML"><![CDATA[<hbm2java
@@ -976,9 +942,7 @@
<section>
<title>Example</title>
- <para>Basic example of using <emphasis>
- <property><hbm2java></property>
- </emphasis> to generate POJO's that utilize jdk5
constructs.</para>
+ <para>Basic example of using
<code><hbm2java></code> to generate POJO's that utilize jdk5
constructs.</para>
<programlisting role="XML"><![CDATA[<hibernatetool
destdir="${build.dir}/generated">
<configuration configurationfile="hibernate.cfg.xml"/>
@@ -988,13 +952,11 @@
</section>
<section>
- <title>Hibernate Mapping files exporter
(<literal><hbm2hbmxml></literal>)</title>
+ <title>Hibernate Mapping files exporter
(<hbm2hbmxml>)</title>
- <para><emphasis>
- <property><hbm2hbmxml></property>
- </emphasis> generates a set of .hbm files. Intended to be used together
with a <emphasis>
- <property><jdbcconfiguration></property>
- </emphasis> when performing reverse engineering, but can be used with any
kind of
+ <para><code><hbm2hbmxml></code> generates a set of
.hbm files. Intended to be used together with a
+ <code><jdbcconfiguration></code>
+ when performing reverse engineering, but can be used with any kind of
configuration. e.g. to convert from annotation based pojo's to
<emphasis>
<property>hbm.xml</property>. </emphasis></para>
@@ -1009,23 +971,17 @@
<section>
<title>Example</title>
- <para>Basic usage of <emphasis>
- <property><hbm2hbmxml></property>.
</emphasis></para>
+ <para>Basic usage of <code><hbm2hbmxml></code>.
</para>
<programlisting role="XML"><![CDATA[<hibernatetool
destdir="${build.dir}/generated">
<configuration configurationfile="hibernate.cfg.xml"/>
<hbm2hbmxml/>
</hibernatetool>]]></programlisting>
- <para><emphasis>
- <property><hbm2hbmxml></property>
- </emphasis> is normally used with a <emphasis>
- <property><jdbcconfiguration></property>
- </emphasis> like in the above example, but any other configuration can
also be used to
+ <para><code><hbm2hbmxml></code> is normally used
with a <code><jdbcconfiguration></code> like in the above
example, but any other configuration can also be used to
convert between the different ways of performing mappings. Here is an example
of that,
- using an <emphasis>
- <property><annotationconfiguration></property>
- </emphasis>.</para>
+ using an <code><annotationconfiguration></code>
+ .</para>
<note>
<title>Note:</title>
@@ -1041,17 +997,12 @@
</section>
<section>
- <title>Hibernate Configuration file exporter
(<literal><hbm2cfgxml></literal>)</title>
+ <title>Hibernate Configuration file exporter
(<hbm2cfgxml>)</title>
- <para><emphasis>
- <property><hbm2cfgxml></property>
- </emphasis> generates a <emphasis>
- <property>hibernate.cfg.xml</property>. </emphasis> Intended
to be used together with a <emphasis>
- <property><jdbcconfiguration></property>
- </emphasis> when performing reverse engineering, but it can be used with
any kind of
- configuration. The <emphasis>
- <property><hbm2cfgxml></property>
- </emphasis> will contain the properties used and adds mapping entries for
each mapped class.</para>
+ <para><code><hbm2cfgxml></code> generates a
<emphasis>
+ <property>hibernate.cfg.xml</property>. </emphasis> Intended
to be used together with a <code><jdbcconfiguration></code>
+ when performing reverse engineering, but it can be used with any kind of
+ configuration. The <code><hbm2cfgxml></code> will
contain the properties used and adds mapping entries for each mapped class.</para>
<programlisting role="XML"><![CDATA[<hbm2cfgxml
ejb3="true|false"
@@ -1105,11 +1056,10 @@
</section>
<section>
- <title>Documentation exporter
(<literal><hbm2doc></literal>)</title>
+ <title>Documentation exporter (<hbm2doc>)</title>
- <para><emphasis>
- <property><hbm2doc></property>
- </emphasis> generates html documentation a'la javadoc for the database
schema et.al.</para>
+ <para><code><hbm2doc></code>
+ generates html documentation a'la javadoc for the database schema
et.al.</para>
<programlisting
role="XML"><![CDATA[<hbm2doc/>]]></programlisting>
</section>
@@ -1117,9 +1067,7 @@
<section>
<title>Query exporter (<query>)</title>
- <para><emphasis>
- <property><query></property>
- </emphasis> is used to execute a HQL query statements and optionally sends
the output to a
+ <para><code><query></code> is used to execute a HQL
query statements and optionally sends the output to a
file. It can be used for verifying the mappings and for basic data
extraction.</para>
<programlisting role="XML"><![CDATA[<query
@@ -1137,9 +1085,7 @@
<section>
<title>Examples</title>
- <para>The simplest usage of <emphasis>
- <property><query></property>
- </emphasis> will just execute the query without dumping to a file. This
can be used to
+ <para>The simplest usage of <code><query></code>
will just execute the query without dumping to a file. This can be used to
verify that queries can actually be performed.</para>
<programlisting role="XML"><![CDATA[<hibernatetool>
@@ -1147,9 +1093,8 @@
<query>from java.lang.Object</query>
</hibernatetool>]]></programlisting>
- <para>Multiple queries can be executed by nested <emphasis>
- <property><hql></property>
- </emphasis> elements. In this example we also let the output be dumped to
<emphasis>
+ <para>Multiple queries can be executed by nested
<code><hql></code> elements.
+ In this example we also let the output be dumped to <emphasis>
<property>queryresult.txt</property>.
</emphasis></para>
<note>
@@ -1168,7 +1113,7 @@
</section>
<section id="hbmtemplate">
- <title>Generic Hibernate metamodel exporter
(<literal><hbmtemplate></literal>)</title>
+ <title>Generic Hibernate metamodel exporter
(<hbmtemplate>)</title>
<para>Generic exporter that can be controlled by a user provides a template
or class.</para>
@@ -1187,11 +1132,9 @@
<section>
<title>Exporter via <hbmtemplate></title>
- <para>The following is an example of reverse engineering via
<emphasis>
- <property><jdbcconfiguration></property>
- </emphasis> and usage of a custom Exporter via the <emphasis>
- <property><hbmtemplate></property>
- </emphasis>.</para>
+ <para>The following is an example of reverse engineering via
+ <code><jdbcconfiguration></code> and usage of a
custom Exporter via the
+ <code><hbmtemplate></code>.</para>
<programlisting role="XML"><![CDATA[ <hibernatetool
destdir="${destdir}">
<jdbcconfiguration
@@ -1227,68 +1170,45 @@
<section>
<title>Using properties to configure Exporters</title>
- <para>Exporters can be controlled by user properties. The user properties are
specified via <emphasis>
- <property><property></property>
- </emphasis> or <emphasis>
- <property>
- <literal><propertyset></literal>
- </property>
- </emphasis> and each exporter will have access to them directly in the
templates and via
+ <para>Exporters can be controlled by user properties. The user properties are
specified via
+ <code><property></code>
+ or
+ <code><propertyset></code>
+ and each exporter will have access to them directly in the templates and via
<property>Exporter.setProperties()</property>.</para>
<section>
- <title><literal><property></literal> and
- <literal><propertyset></literal></title>
+ <title><property> and
+ <propertyset></title>
- <para>The <emphasis>
- <property><property></property>
- </emphasis> allows you bind a string value to a key. The value will be
available in the
- templates via <emphasis>
- <property>$<key></property>
- </emphasis>. The following example will assign the string value
<emphasis>
- <property>"true"</property>
- </emphasis> to the variable <emphasis>
- <property>$descriptors</property>
- </emphasis>.</para>
+ <para>The <code><property></code>
+ allows you bind a string value to a key. The value will be available in the
+ templates via <code>$<key></code>.
+ The following example will assign the string value
+ <code>"true"</code>
+ to the variable
+ <code>$descriptors</code>
+ .</para>
<programlisting role="XML"><![CDATA[<property
key="descriptors" value="true"/>]]></programlisting>
- <para>Most times using <emphasis>
- <property>
- <literal><property></literal>
- </property>
- </emphasis> is enough for specifying the properties needed for the
exporters. Still the ant
- tools supports the notion of <emphasis>
- <property>
- <literal><propertyset></literal>
- </property>
- </emphasis> that is used for grouping a set of properties. More about the
functionality of <emphasis>
- <property>
- <literal><propertyset></literal>
- </property>
- </emphasis> is explained in detail in the <ulink
url="http://ant.apache.org/manual/">Ant
+ <para>Most times using <code><property></code> is
enough for specifying the properties needed for the exporters. Still the ant
+ tools supports the notion of <code><propertyset></code>
that is used for grouping a set of properties. More about the functionality of
<code><propertyset></code>
+ is explained in detail in the <ulink
url="http://ant.apache.org/manual/">Ant
manual</ulink>.</para>
</section>
<section>
<title>Getting access to user specific classes</title>
- <para>If the templates need to access some user class it becomes possible by
specifying a <emphasis>
- <property>"toolclass"</property>
- </emphasis> in the properties.</para>
+ <para>If the templates need to access some user class it becomes possible by
specifying a <code>
+ "toolclass"</code> in the properties.</para>
<programlisting role="XML"><![CDATA[<property
key="hibernatetool.sometool.toolclass"
value="x.y.z.NameOfToolClass"/>
]]></programlisting>
- <para>Placing the above <emphasis>
- <property>
- <literal><property></literal>
- </property>
- </emphasis> tag in <emphasis>
- <property>
- <literal><hibernatetool></literal>
- </property>
- </emphasis> or inside any exporter will automatically create an instance
of
+ <para>Placing the above <code><property></code> tag
in <code><hibernatetool></code>
+ or inside any exporter will automatically create an instance of
<literal>x.y.z.NameOfToolClass</literal> and it will be available
in the templates as
<literal>$sometool</literal>. This is useful to delegate logic and
code generation to java
code instead of placing such logic in the templates.</para>
@@ -1296,14 +1216,11 @@
<section>
<title>Example</title>
- <para>Here is an example that uses <emphasis>
- <property><hbmtemplate></property>
- </emphasis> together with <emphasis>
- <property><property></property>
- </emphasis> which will be available to the templates/exporter.
</para>
+ <para>Here is an example that uses
<code><hbmtemplate></code>
+ together with <code><property></code> which will be
available to the templates/exporter. </para>
<note>
<title>Note:</title>
- <para> This example actually simulates what <hbm2java>
actually does.</para>
+ <para> This example actually simulates what
<code><hbm2java></code> actually does.</para>
</note>
<programlisting role="XML"><![CDATA[<hibernatetool
destdir="${build.dir}/generated">
Modified: trunk/hibernatetools/docs/reference/en/modules/codegen.xml
===================================================================
--- trunk/hibernatetools/docs/reference/en/modules/codegen.xml 2009-07-17 22:37:13 UTC
(rev 16656)
+++ trunk/hibernatetools/docs/reference/en/modules/codegen.xml 2009-07-18 13:44:04 UTC
(rev 16657)
@@ -2,37 +2,28 @@
<chapter id="codegen">
<title>Controlling POJO code generation</title>
- <para>When using <emphasis>
- <property><hbm2java></property>
- </emphasis> or the eclipse plugin to generate POJO java code you have the
possibility to control
- certain aspects of the code generation. This is primarily done with the
<emphasis>
- <property><meta></property>
- </emphasis> tag in the mapping files. The following section describes the
possible <emphasis>
- <property><meta></property>
- </emphasis> tags and their use.</para>
+ <para>When using <code><hbm2java></code> or the eclipse
plugin to generate POJO java code you have the possibility to control
+ certain aspects of the code generation. This is primarily done with the
<code><meta></code>
+ tag in the mapping files. The following section describes the possible <code>
+ <meta>
+ </code> tags and their use.</para>
<section>
- <title>The <literal><meta></literal>
attribute</title>
+ <title>The <meta> attribute</title>
- <para>The <emphasis>
- <property><meta></property>
- </emphasis> tag is a simple way of annotating the <emphasis>
+ <para>The <code><meta></code> tag is a simple way of
annotating the <emphasis>
<property>hbm.xml</property>
</emphasis> with information, so tools have a natural place to store/read
information that is
not directly related to the Hibernate core.</para>
- <para>You can use the <emphasis>
- <property><meta></property>
- </emphasis> tag to e.g. tell <emphasis>
- <property><hbm2java></property>
- </emphasis> to only generate <emphasis>
+ <para>You can use the <code><meta></code> tag to e.g.
tell <code><hbm2java></code>
+ to only generate <emphasis>
<property>"protected"</property>
</emphasis> setters, have classes always implement a certain set of
interfaces or even have
them extend a certain base class and even more.</para>
- <para>The following example shows how to use various <emphasis>
- <property><meta></property>
- </emphasis> attributes and the resulting java code.</para>
+ <para>The following example shows how to use various
<code><meta></code>
+ attributes and the resulting java code.</para>
<programlisting role="XML"><![CDATA[<class
name="Person">
<meta attribute="class-description">
@@ -258,52 +249,49 @@
</tgroup>
</table>
- <para>Attributes declared via the <emphasis>
- <property><meta></property>
- </emphasis> tag are per default <emphasis>
+ <para>Attributes declared via the
<code><meta></code>
+ tag are per default <emphasis>
<property>"inherited"</property>
</emphasis> inside an <emphasis>
<property>hbm.xml</property>
</emphasis> file.</para>
<para>What does that mean? It means that if you e.g want to have all your
classes implement
- <literal>IAuditable</literal> then you just add an <emphasis>
<meta
-
attribute="implements">IAuditable</meta></emphasis>
in the top of the <emphasis>
+ <property>IAuditable</property> then you just add an <code>
<meta
+
attribute="implements">IAuditable</meta></code> in
the top of the <emphasis>
<property>hbm.xml</property>
- </emphasis> file, just after <emphasis>
- <property><hibernate-mapping></property>.
</emphasis> Now all classes defined
+ </emphasis> file, just after
<code><hibernate-mapping></code>. Now all classes defined
in that <emphasis>
<property>hbm.xml</property>
- </emphasis> file will implement
<literal>IAuditable</literal>!</para>
+ </emphasis> file will implement
<property>IAuditable</property>!</para>
<note>
<title>Note:</title>
<para>This applies to <emphasis>all</emphasis>
- <literal><meta></literal>-tags. Thus it can also e.g.
be used to specify that
+ <code><meta></code>-tags. Thus it can also e.g. be used
to specify that
all fields should be declare protected, instead of the default private. This is
done by
- adding <literal><meta
-
attribute="scope-field">protected</meta></literal> at
e.g. just under
- the <literal><class></literal> tag and all fields of
that class will be
+ adding <code><meta
+
attribute="scope-field">protected</meta></code> at
e.g. just under
+ the <code><class></code> tag and all fields of that
class will be
protected.</para>
</note>
- <para>To avoid having a <emphasis>
- <property><meta></property>
- </emphasis> tag inherited then you can simply specify <emphasis>
inherit = "false"</emphasis>
- for the attribute, e.g. <emphasis> <meta attribute =
"scope-class" inherit =
- "false">public abstract</meta></emphasis>
will restrict the <emphasis>
+ <para>To avoid having a <code><meta></code>
+ tag inherited then you can simply specify <code> inherit =
"false"</code>
+ for the attribute, e.g. <code> <meta attribute =
"scope-class" inherit =
+ "false">public abstract</meta></code> will
restrict the <emphasis>
<property>"class-scope"</property>
</emphasis> to the current class, not the subclasses.</para>
<section>
<title>Recommendations</title>
- <para>The following are some good practices when using <emphasis>
- <property><meta></property>
- </emphasis> attributes.</para>
+ <para>The following are some good practices when using
+ <code><meta></code>
+ attributes.</para>
<section>
- <title>Dangers of a class level <literal>use-in-string and
use-in-equals</literal> meta
+ <title>Dangers of a class level <property>use-in-string and
use-in-equals</property> meta
attributes when having bi-directional associations</title>
<para>If we have two entities with a bi-directional association between
them and define at
@@ -340,14 +328,13 @@
</class>
</hibernate-mapping>]]></programlisting>
- <para>Then <emphasis>
- <property><hbm2java></property>
- </emphasis> will assume you want to include all properties and
collections in the
- <property>toString()/equals()</property> methods and this can
result in infinite
+ <para>Then <code><hbm2java></code>
+ will assume you want to include all properties and collections in the
+ <code>toString()/equals()</code> methods and this can result in
infinite
recursive calls.</para>
<para>To remedy this you have to decide which side of the association will
include the other
- part (if at all) in the <property>toString()/equals()</property>
methods. Therefore it is
+ part (if at all) in the <code>toString()/equals()</code> methods.
Therefore it is
not a good practice to put at class scope such <emphasis>
<property>meta</property>
</emphasis> attributes, unless you are defining a class without
bi-directional
@@ -398,10 +385,10 @@
</section>
<section>
- <title>Be aware of putting at class scope level
<literal><meta></literal>
- attribute <literal>use-in-equals</literal></title>
+ <title>Be aware of putting at class scope level <meta>
+ attributeuse-in-equals</title>
- <para>For <property>equal()/hashCode()</property> method
generation, you have to take into
+ <para>For <code>equal()/hashCode()</code> method generation,
you have to take into
account that the attributes that participate on such method definition, should
take into
account only attributes with business meaning (the name, social security
number, etc, but
no generated id's, for example).</para>
@@ -413,9 +400,7 @@
set.</para>
<para>Therefore automatically configuration of the generation of
- <property>equals()/hashCode()</property> methods specifying at
class scope level the <emphasis>
- <property><meta></property>
- </emphasis> attribute <emphasis>
+ <property>equals()/hashCode()</property> methods specifying at
class scope level the <code><meta></code> attribute
<emphasis>
<property>use-in-equals</property>
</emphasis> could be a dangerous decision that could produce non
expected
side-effect.</para>
@@ -439,13 +424,12 @@
<section>
<title>Generate pre/post-conditions for methods</title>
- <para>With a <emphasis> <meta
attribute="class-code"></emphasis>, you can add
- additional methods on a given class, nevertheless such <emphasis>
- <property><meta></property>
- </emphasis> attribute can not be used at a property scope level and
<property>Hibernate
- Tools</property> does not provide such <emphasis>
- <property><meta></property>
- </emphasis> attributes.</para>
+ <para>With a <code> <meta
attribute="class-code"></code>, you can add
+ additional methods on a given class, nevertheless such
<code><meta></code>
+ attribute can not be used at a property scope level and
<property>Hibernate
+ Tools</property> does not provide such <code>
+ ><meta>
+ </code> attributes.</para>
<para>A possible solution for this is to modify the freemarker templates
responsible for
generating the POJO's. If you look inside <emphasis>
@@ -509,11 +493,11 @@
<property>.hbm.xml</property>
</emphasis> file we define the <emphasis>
<property><meta></property>
- </emphasis> attributes: <literal>pre-cond</literal> or
<literal>post-cond</literal>, their
+ </emphasis> attributes: <code>pre-cond</code> or
<code>post-cond</code>, their
contents will be generated into the body of the relevant
<literal>set</literal>
method.</para>
- <para>As an example let us add a pre-condition for property
<literal>name</literal>
+ <para>As an example let us add a pre-condition for property
<code>name</code>
preventing no <property>Person</property> can have an empty name.
Hence we have to modify
the <emphasis>
<property>Person.hbm.xml</property>
@@ -537,7 +521,7 @@
<note>
<title>Note:</title>
<para>I) To escape the & symbol we put &amp;. You can
use
- <![CDATA[]]> instead.</para>
+ <code> <![CDATA[]]></code> instead.</para>
<para>II) Note that we are referring to "firstName" directly
and this is the parameter
name not the actual field name. If you want to refer the field you have to
use
"this.firstName" instead. </para>
@@ -546,9 +530,8 @@
<para>Finally we have to generate the <emphasis>
<property>Person.java</property>
</emphasis> class, for this we can use both Eclipse and Ant as long as
you remember to set
- or fill in the templatepath setting. For Ant we configure <emphasis>
- <property><hibernatetool></property>
- </emphasis> task via <literal>the templatepath</literal>
attribute as in:</para>
+ or fill in the templatepath setting. For Ant we configure
<code><hibernatetool></code>
+ task via <literal>the templatepath</literal> attribute as
in:</para>
<programlisting role="XML"><![CDATA[
<target name="hbm2java">
@@ -569,9 +552,8 @@
</hibernatetool>
</target>]]></programlisting>
- <para>Invoking the target <emphasis>
- <property><hbm2java></property>
- </emphasis> will generate on the <emphasis>
+ <para>Invoking the target
<code><hbm2java></code>
+ will generate on the <emphasis>
<property>${hbm2java.dest.dir}</property>
</emphasis> the file <emphasis>
<property>Person.java</property>
Modified: trunk/hibernatetools/docs/reference/en/modules/codegenarchitecture.xml
===================================================================
--- trunk/hibernatetools/docs/reference/en/modules/codegenarchitecture.xml 2009-07-17
22:37:13 UTC (rev 16656)
+++ trunk/hibernatetools/docs/reference/en/modules/codegenarchitecture.xml 2009-07-18
13:44:04 UTC (rev 16657)
@@ -12,10 +12,10 @@
<para>The meta model is the model used by Hibernate Core to perform its object
relational
mapping. The model includes information about tables, columns, classes,
properties,
components, values, collections etc. The API is in
<literal>org.hibernate.mapping</literal>
- and its main entry point is the <literal>Configuration</literal> class,
the same class that is
+ and its main entry point is the <property>Configuration</property>
class, the same class that is
used to build a session factory.</para>
- <para>The model represented by the <literal>Configuration</literal>
class can be build in many
+ <para>The model represented by the
<property>Configuration</property> class can be build in many
ways. The following list the currently supported ones in <property>Hibernate
Tools</property>. </para>
<para>
@@ -25,11 +25,9 @@
<property>hbm.xml</property>
</emphasis> files, requires a <emphasis>
<property>hibernate.cfg.xml</property>
- </emphasis>. Named core in Eclipse and <emphasis>
- <property>
- <literal><configuration></literal>
- </property>
- </emphasis> in ant.</para>
+ </emphasis>. Named core in Eclipse and
+ <code><configuration></code>
+ in ant.</para>
</listitem>
<listitem>
@@ -37,11 +35,9 @@
<property>hbm.xml</property>
</emphasis> and annotated classes, requires a <emphasis>
<property>hibernate.cfg.xml</property>
- </emphasis>. Named annotations in Eclipse and <emphasis>
- <property>
- <literal><annotationconfiguration></literal>
- </property>
- </emphasis> in ant.</para>
+ </emphasis>. Named annotations in Eclipse and
+ <code><annotationconfiguration></code>
+ in ant.</para>
</listitem>
<listitem>
@@ -49,22 +45,18 @@
<property>hbm.xml</property>
</emphasis> and annotated classes requires that the project has a
<emphasis>
<property>META-INF/persistence.xml</property>
- </emphasis> in its classpath. Named JPA in Eclipse and
<emphasis>
- <property>
- <literal><jpaconfiguration></literal>
- </property>
- </emphasis> in ant.</para>
+ </emphasis> in its classpath. Named JPA in Eclipse and
+ <code><jpaconfiguration></code>
+ in ant.</para>
</listitem>
<listitem>
<para>A JDBC configuration uses <property>Hibernate
Tools</property> reverse engineering
and reads its mappings via JDBC metadata + additional reverse engineering
files
(reveng.xml). Automatically used in Eclipse when doing reverse engineering
from JDBC and
- named <emphasis>
- <property>
- <literal><jdbcconfiguration></literal>
- </property>
- </emphasis> in ant.</para>
+ named
+ <code><jdbcconfiguration></code>
+ in ant.</para>
</listitem>
</itemizedlist>
</para>
Modified: trunk/hibernatetools/docs/reference/en/modules/plugins.xml
===================================================================
--- trunk/hibernatetools/docs/reference/en/modules/plugins.xml 2009-07-17 22:37:13 UTC
(rev 16656)
+++ trunk/hibernatetools/docs/reference/en/modules/plugins.xml 2009-07-18 13:44:04 UTC
(rev 16657)
@@ -811,7 +811,7 @@
mapping will always be created. If this option is enabled and there are
matching
foreign-keys each key column is still considered a 'basic'
scalar (string, long,
etc.) instead of a reference to an entity. If you disable this option
a
- <key-many-to-one> instead. Note: a
<many-to-one>
+ <code><key-many-to-one></code> instead. Note:
a <code><many-to-one></code>
property is still created, but is simply marked as non-updatable and
non-insertable.</para>
</entry>
@@ -1281,13 +1281,11 @@
<title>Java property/class completion</title>
<para>Package, class, and field completion is enabled for relevant XML
attributes. The
- auto-completion detects its context and limits the completion for e.g.
<emphasis>
- <property><property></property>
- </emphasis> and only shows the properties/fields available in the enclosing
<emphasis>
- <property><class></property>
- </emphasis>, <emphasis>
- <property><subclass></property>
- </emphasis> etc. It is also possible to navigate from the <emphasis>
+ auto-completion detects its context and limits the completion for e.g.
<code><property></code> and only shows the properties/fields
available in the enclosing
+ <code><class></code>
+ ,
+ <code><subclass></code>
+ etc. It is also possible to navigate from the <emphasis>
<property>hbm.xml</property>
</emphasis> files to the relevant class/field in java code.</para>
@@ -1365,9 +1363,7 @@
<para>In <emphasis>
<property>cfg.xml</property>
- </emphasis> code completion for the value of <emphasis>
- <property><property> name</property>
- </emphasis> attributes is available.</para>
+ </emphasis> code completion for the value of
<code><property> name</code> attributes is
available.</para>
<figure>
Modified: trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml
===================================================================
--- trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml 2009-07-17
22:37:13 UTC (rev 16656)
+++ trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml 2009-07-18
13:44:04 UTC (rev 16657)
@@ -2,12 +2,9 @@
<chapter id="reverseengineering">
<title>Controlling reverse engineering</title>
- <para>When using the <emphasis>
- <property><jdbcconfiguration></property>,
</emphasis> the ant task will read the
+ <para>When using the <code><jdbcconfiguration></code>,
the ant task will read the
database metadata and thus will perform a reverse engineering of the database schema
into a
- normal Hibernate Configuration. It is from this object e.g. <emphasis>
- <property><hbm2java></property>
- </emphasis>can generate other artifacts such as <emphasis>
+ normal Hibernate Configuration. It is from this object e.g.
<code><hbm2java></code>can generate other artifacts such as
<emphasis>
<property>.java</property>
</emphasis>, <emphasis>
<property>.hbm.xml</property>
@@ -46,7 +43,7 @@
<note>
<title>Note:</title>
<para>Many databases are case-sensitive with their names and thus if you
cannot make some
- table match and you are sure it is not excluded by a <table-filter>
then check
+ table match and you are sure it is not excluded by a
<code><table-filter></code> then check
if the case matches; most databases stores table names in
uppercase.</para>
</note>
@@ -109,26 +106,19 @@
<section>
<title>Schema Selection (<schema-selection>)</title>
- <para><emphasis>
- <property><schema-selection></property>
- </emphasis> is used to drive which schemas the reverse engineering will try
and
+ <para><code><schema-selection></code> is used to
drive which schemas the reverse engineering will try and
process.</para>
- <para>By default the reverse engineering will read all schemas and then use
<emphasis>
- <property><table-filter></property>
- </emphasis> to decide which tables get reverse engineered and which do not;
this makes it
+ <para>By default the reverse engineering will read all schemas and then use
<code><table-filter></code>
+ to decide which tables get reverse engineered and which do not; this makes it
easy to get started but can be inefficient on databases with many
schemas.</para>
- <para>With <emphasis>
- <property><schema-selection></property>
- </emphasis> it is thus possible to limit the actual processed schemas and
thus significantly
- speed-up the reverse engineering. <emphasis>
- <property><table-filter></property>
- </emphasis> is still used to then decide which tables will be
included/excluded.</para>
+ <para>With <code><schema-selection></code> it is
thus possible to limit the actual processed schemas and thus significantly
+ speed-up the reverse engineering.
<code><table-filter></code> is still used to then decide which
tables will be included/excluded.</para>
<note>
<title>Note:</title>
- <para>If no <literal><schema-selection></literal>
is specified, the reverse
+ <para>If no <code><schema-selection></code> is
specified, the reverse
engineering works as if all schemas should be processed. This is equal to:
<![CDATA[<schema-selection/>]]>. Which in turn is equal to:
<![CDATA[<schema-selection match-catalog=".*"
match-schema=".*" match-table=".*"/>]]></para>
@@ -164,9 +154,7 @@
<section id="type_map">
<title>Type mappings (<type-mapping>)</title>
- <para>The <emphasis>
- <property><type-mapping></property>
- </emphasis> section specifies how the JDBC types found in the database
should be mapped to
+ <para>The <code><type-mapping></code> section
specifies how the JDBC types found in the database should be mapped to
Hibernate types. e.g. <emphasis>
<property>java.sql.Types.VARCHAR</property></emphasis> with a
length of 1 should be mapped to the
Hibernate type <emphasis>
@@ -358,9 +346,8 @@
<section>
<title>Table filters (<table-filter>)</title>
- <para>The <emphasis>
- <property><table-filter></property>
- </emphasis> let you specify matching rules for performing general
filtering/setup for
+ <para>The <code><table-filter></code>
+ let you specify matching rules for performing general filtering/setup for
tables, e.g. let you include or exclude specific tables based on the schema or
even a
specific prefix.</para>
@@ -446,9 +433,8 @@
<section id="tab_and_col">
<title>Specific table configuration (<table>)</title>
- <para><emphasis>
- <property><table></property>
- </emphasis> allows you to provide explicit configuration on how a table
should be reverse
+ <para><code><table></code>
+ allows you to provide explicit configuration on how a table should be reverse
engineered. Amongst other things it allows controlling over the naming of a class
for the
table, specifying which identifier generator should be used for the primary key
etc.</para>
@@ -531,9 +517,7 @@
<section>
<title><primary-key></title>
- <para>A <emphasis>
- <property><primary-key></property>
- </emphasis> allows you to define a primary-key for tables that
don't have it
+ <para>A <code><primary-key></code> allows you to
define a primary-key for tables that don't have it
defined in the database, and probably more importantly it allows you to define
which
identifier strategy should be used (even for already existing
primary-key's).</para>
@@ -605,9 +589,7 @@
<section>
<title><column></title>
- <para>With a <emphasis>
- <property><column></property>
- </emphasis> it is possible to explicitly name the resulting property for
a column. It is
+ <para>With a <code><column></code> it is possible
to explicitly name the resulting property for a column. It is
also possible to redefine what jdbc and/or Hibernate type a column should be
processed as
and finally it is possible to completely exclude a column from
processing.</para>
@@ -696,9 +678,8 @@
<section>
<title><foreign-key></title>
- <para>The <emphasis>
- <property><foreign-key></property>
- </emphasis> has two purposes. One for allowing to define foreign-keys in
databases that
+ <para>The <code><foreign-key></code>
+ has two purposes. One for allowing to define foreign-keys in databases that
does not support them or does not have them defined in their schema. Secondly,
to allow
defining the name of the resulting properties (many-to-one, one-to-one and
one-to-many's).</para>