Author: ochikvina
Date: 2008-01-09 11:27:32 -0500 (Wed, 09 Jan 2008)
New Revision: 5564
Modified:
trunk/hibernatetools/docs/reference/en/modules/ant.xml
trunk/hibernatetools/docs/reference/en/modules/codegen.xml
Log:
http://jira.jboss.com/jira/browse/JBDS-173 - highlighting some meaningful words
Modified: trunk/hibernatetools/docs/reference/en/modules/ant.xml
===================================================================
--- trunk/hibernatetools/docs/reference/en/modules/ant.xml 2008-01-09 16:20:46 UTC (rev
5563)
+++ trunk/hibernatetools/docs/reference/en/modules/ant.xml 2008-01-09 16:27:32 UTC (rev
5564)
@@ -142,6 +142,10 @@
<para>
<programlisting><![CDATA[<hibernatetool
destdir="${build.dir}/generated">
+ <classpath>
+ <path location="${build.dir}/classes"/>
+ </classpath>
+
<configuration configurationfile="hibernate.cfg.xml"/>
<hbm2java/>
</hibernatetool>]]></programlisting>
Modified: trunk/hibernatetools/docs/reference/en/modules/codegen.xml
===================================================================
--- trunk/hibernatetools/docs/reference/en/modules/codegen.xml 2008-01-09 16:20:46 UTC
(rev 5563)
+++ trunk/hibernatetools/docs/reference/en/modules/codegen.xml 2008-01-09 16:27:32 UTC
(rev 5564)
@@ -2,34 +2,34 @@
<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 through the <meta> tag in the
- mapping files. The following section describes the possible meta tags and
- their use.</para>
+ <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 through the
<meta>
+ tag in the mapping files. The following section describes the possible meta tags and
their use.</para>
<section>
<title>The <literal><meta></literal>
attribute</title>
- <para>The <emphasis>
- <property><meta></property></emphasis> 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>The <emphasis>
+ <property><meta></property>
+ </emphasis> 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>
- <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>You can use the <emphasis>
+ <property><meta></property>
+ </emphasis> tag to e.g. tell <emphasis>
+ <property><hbm2java></property>
+ </emphasis> 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>
+ <property><meta></property>
+ </emphasis> attributes and the resulting java code.</para>
<programlisting><class name="Person">
<meta attribute="class-description">
@@ -47,9 +47,9 @@
</class></programlisting>
<para>The above <emphasis>
- <property>hbm.xml</property></emphasis> will produce something
like the following (code
- shortened for better understanding). Notice the Javadoc comment and the
- protected set methods:</para>
+ <property>hbm.xml</property>
+ </emphasis> will produce something like the following (code shortened for
better
+ understanding). Notice the Javadoc comment and the protected set
methods:</para>
<programlisting>// default package
@@ -100,9 +100,9 @@
<title>Supported meta tags</title>
<tgroup cols="2">
- <colspec colwidth="1.5*" />
+ <colspec colwidth="1.5*"/>
- <colspec colwidth="2*" />
+ <colspec colwidth="2*"/>
<thead>
<row>
@@ -114,172 +114,200 @@
<tbody>
<row>
- <entry><literal>class-description</literal></entry>
+ <entry>
+ <literal>class-description</literal>
+ </entry>
<entry>inserted into the javadoc for classes</entry>
</row>
<row>
- <entry><literal>field-description</literal></entry>
+ <entry>
+ <literal>field-description</literal>
+ </entry>
<entry>inserted into the javadoc for fields/properties</entry>
</row>
<row>
- <entry><literal>interface</literal></entry>
+ <entry>
+ <literal>interface</literal>
+ </entry>
- <entry>If true an interface is generated instead of an
- class.</entry>
+ <entry>If true an interface is generated instead of an
class.</entry>
</row>
<row>
- <entry><literal>implements</literal></entry>
+ <entry>
+ <literal>implements</literal>
+ </entry>
<entry>interface the class should implement</entry>
</row>
<row>
- <entry><literal>extends</literal></entry>
+ <entry>
+ <literal>extends</literal>
+ </entry>
- <entry>class the class should extend (ignored for
- subclasses)</entry>
+ <entry>class the class should extend (ignored for
subclasses)</entry>
</row>
<row>
- <entry><literal>generated-class</literal></entry>
+ <entry>
+ <literal>generated-class</literal>
+ </entry>
<entry>overrule the name of the actual class generated</entry>
</row>
<row>
- <entry><literal>scope-class</literal></entry>
+ <entry>
+ <literal>scope-class</literal>
+ </entry>
<entry>scope for class</entry>
</row>
<row>
- <entry><literal>scope-set</literal></entry>
+ <entry>
+ <literal>scope-set</literal>
+ </entry>
<entry>scope for setter method</entry>
</row>
<row>
- <entry><literal>scope-get</literal></entry>
+ <entry>
+ <literal>scope-get</literal>
+ </entry>
<entry>scope for getter method</entry>
</row>
<row>
- <entry><literal>scope-field</literal></entry>
+ <entry>
+ <literal>scope-field</literal>
+ </entry>
<entry>scope for actual field</entry>
</row>
<row>
- <entry><literal>default-value</literal></entry>
+ <entry>
+ <literal>default-value</literal>
+ </entry>
<entry>default initialization value for a field</entry>
</row>
<row>
- <entry><literal>use-in-tostring</literal></entry>
+ <entry>
+ <literal>use-in-tostring</literal>
+ </entry>
- <entry>include this property in the
- <literal>toString()</literal></entry>
+ <entry>include this property in the
<literal>toString()</literal></entry>
</row>
<row>
- <entry><literal>use-in-equals</literal></entry>
+ <entry>
+ <literal>use-in-equals</literal>
+ </entry>
- <entry>include this property in the
<literal>equals()</literal>
- and <literal>hashCode()</literal> method. If no use-in-equals is
- specified, no equals/hashcode will be generated.</entry>
+ <entry>include this property in the
<literal>equals()</literal> and
+ <literal>hashCode()</literal> method. If no use-in-equals is
specified, no
+ equals/hashcode will be generated.</entry>
</row>
<row>
- <entry><literal>gen-property</literal></entry>
+ <entry>
+ <literal>gen-property</literal>
+ </entry>
- <entry>property will not be generated if false (use with
- care)</entry>
+ <entry>property will not be generated if false (use with
care)</entry>
</row>
<row>
- <entry><literal>property-type</literal></entry>
+ <entry>
+ <literal>property-type</literal>
+ </entry>
- <entry>Overrides the default type of property. Use this with any
- tag's to specify the concrete type instead of just Object.</entry>
+ <entry>Overrides the default type of property. Use this with any
tag's to specify the
+ concrete type instead of just Object.</entry>
</row>
<row>
- <entry><literal>class-code</literal></entry>
+ <entry>
+ <literal>class-code</literal>
+ </entry>
- <entry>Extra code that will inserted at the end of the
- class</entry>
+ <entry>Extra code that will inserted at the end of the
class</entry>
</row>
<row>
- <entry><literal>extra-import</literal></entry>
+ <entry>
+ <literal>extra-import</literal>
+ </entry>
- <entry>Extra import that will inserted at the end of all other
- imports</entry>
+ <entry>Extra import that will inserted at the end of all other
imports</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Attributes declared via the <emphasis>
- <property><meta></property></emphasis> tag are
- per default <emphasis>
- <property>"inherited"</property></emphasis>
inside an <emphasis>
- <property>hbm.xml</property></emphasis> file.</para>
+ <property><meta></property>
+ </emphasis> 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>hbm.xml</property></emphasis> file, just after
- <emphasis>
-
<property><hibernate-mapping></property></emphasis>. Now
all classes defined in
- that <emphasis>
- <property>hbm.xml</property></emphasis> file will implement
- <literal>IAuditable</literal>!</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>hbm.xml</property>
+ </emphasis> file, just after <emphasis>
+ <property><hibernate-mapping></property>
+ </emphasis>. Now all classes defined in that <emphasis>
+ <property>hbm.xml</property>
+ </emphasis> file will implement
<literal>IAuditable</literal>!</para>
- <note><para>This applies to <emphasis>all</emphasis>
- <literal><meta></literal>-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 protected.</para>
- </note>
+ <note>
+ <para>This applies to <emphasis>all</emphasis>
+ <literal><meta></literal>-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
+ 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>
- <property>"class-scope"</property></emphasis>
to the current class, not the subclasses.</para>
+ <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>
+ <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 <emphasis>
+ <property><meta></property>
+ </emphasis> attributes.</para>
<section>
- <title>Dangers of a class level <literal>use-in-string and
- use-in-equals</literal> meta attributes when having bi-directional
- associations</title>
+ <title>Dangers of a class level <literal>use-in-string and
use-in-equals</literal> meta
+ attributes when having bi-directional associations</title>
- <para>If we have two entities with a bi-directional association
- between them and define at class scope level the meta attributes:
- <literal>use-in-string, use-in-equals</literal>:</para>
+ <para>If we have two entities with a bi-directional association between
them and define at
+ class scope level the meta attributes: <emphasis>
+ <property>use-in-string</property>
+ </emphasis>, <emphasis>
+ <property>use-in-equals</property>
+ </emphasis>:</para>
<programlisting><hibernate-mapping>
<class name="Person">
@@ -290,7 +318,8 @@
</hibernate-mapping></programlisting>
<para>And for <emphasis>
- <property>Event.hbm</property></emphasis> file:</para>
+ <property>Event.hbm</property>
+ </emphasis> file:</para>
<programlisting><hibernate-mapping>
<class name="events.Event" table="EVENTS">
@@ -309,19 +338,21 @@
</hibernate-mapping></programlisting>
<para>Then <emphasis>
- <property><hbm2java></property></emphasis> will
assume you want to
- include all properties and collections in the
- <literal>toString()/equals()</literal> methods and this can result
in
- infinite recursive calls.</para>
+ <property><hbm2java></property>
+ </emphasis> will assume you want to include all properties and
collections in the
+
<property>toString()</property>/<property>equals()</property>
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
- <literal>toString()/equals()</literal> methods. Therefore it is not
a
- good practice to put at class scope such meta attributes, unless you
- are defining a class without bi-directional associations.</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 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
+ associations.</para>
- <para>We recomend instead to add the <literal>meta</literal>
- attributes at the property level:</para>
+ <para>We recomend instead to add the <emphasis>
+ <property>meta</property>
+ </emphasis> attributes at the property level:</para>
<programlisting><hibernate-mapping>
<class name="events.Event" table="EVENTS">
@@ -364,75 +395,68 @@
</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
<literal><meta></literal>
+ attribute <literal>use-in-equals</literal></title>
- <para>For <literal>equal()/hashCode()</literal> 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>
+ <para>For <property>equal()/hashCode()</property> 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>
<para>This is important because Java's hashbased collections, such as
- java.util.Set relies on equals() and hashcode() to be correct and not
- change for objects in the set; this can be a problem if the id gets
- assigned for an object after you inserted it into a set.</para>
+ <property>java.util.Set</property> relies on
<property>equals()</property> and
+ <property>hashcode()</property> to be correct and not change for
objects in the set;
+ this can be a problem if the id gets assigned for an object after you inserted
it into a
+ set.</para>
<para>Therefore automatically configuration the generation of
- <literal>equals()/hashCode()</literal> methods specifying at class
- scope level the <emphasis>
- <property><meta></property></emphasis>
attribute
- <literal>use-in-equals</literal> could be a dangerous decision that
- could produce non expected side-effect.</para>
+ <property>equals()/hashCode()</property> methods specifying at
class scope level the <emphasis>
+ <property><meta></property>
+ </emphasis> attribute
<emphasis><property>use-in-equals</property></emphasis> could be a
dangerous decision that
+ could produce non expected side-effect.</para>
- <para><ulink
-
url="http://www.hibernate.org/109.html">Here</ulink> you
can get more in-depth
- explanation on the subject of equals() and hashcode().</para>
+ <para><ulink
url="http://www.hibernate.org/109.html">Here</ulink> you can get more
in-depth
+ explanation on the subject of <property>equals()</property> and
<property>hashcode()</property>.</para>
</section>
</section>
<section>
- <title>Advanced <literal><meta></literal>
attribute
- examples</title>
+ <title>Advanced
<emphasis><property><meta></property></emphasis>
attribute examples</title>
- <para>This section shows an example for using meta attributes (including
- userspecific attributes) together with the code generation features in
- <property>Hibernate Tools</property>.</para>
+ <para>This section shows an example for using meta attributes (including
userspecific
+ attributes) together with the code generation features in
<property>Hibernate
+ Tools</property>.</para>
- <para>The usecase being implemented is to automatically insert some pre-
- and post-conditions into the getter and setters of the generated POJO.
- </para>
+ <para>The usecase being implemented is to automatically insert some pre- and
post-conditions
+ into the getter and setters of the generated POJO. </para>
<section>
<title>Generate pre/post-conditions for methods</title>
- <para>With an <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 property
- scope level and <property>Hibernate Tools</property> does not provide
such
- <emphasis>
- <property><meta></property></emphasis>
attributes.</para>
+ <para>With an <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 property scope level and
<property>Hibernate
+ Tools</property> does not provide such <emphasis>
+ <property><meta></property>
+ </emphasis> attributes.</para>
- <para>A possibly solution for this is to modify the freemarker
- templates responsible for generating the POJO's. If you look inside
- <emphasis>
- <property>hibernate-tools.jar</property></emphasis>, you
can find the template:
- <emphasis>
-
<property>pojo/PojoPropertyAccessor.ftl</property></emphasis></para>
+ <para>A possibly solution for this is to modify the freemarker templates
responsible for
+ generating the POJO's. If you look inside <emphasis>
+ <property>hibernate-tools.jar</property>
+ </emphasis>, you can find the template: <emphasis>
+ <property>pojo/PojoPropertyAccessor.ftl</property>
+ </emphasis></para>
- <para>This file is as the named indicates used to generate property
- accessors for pojo's.</para>
+ <para>This file is as the named indicates used to generate property
accessors for pojo's.</para>
<para>Extract the <emphasis>
- <property>PojoPropertyAccessor.ftl</property></emphasis>
into a
- local folder i.e. <emphasis>
- <property>${hbm.template.path}</property></emphasis>,
respecting
- the whole path, for example:
- <emphasis>
-
<property>${hbm.template.path}/pojo/PojoPropertyAccessor.ftl</property></emphasis></para>
+ <property>PojoPropertyAccessor.ftl</property>
+ </emphasis> into a local folder i.e. <emphasis>
+ <property>${hbm.template.path}</property>
+ </emphasis>, respecting the whole path, for example: <emphasis>
+
<property>${hbm.template.path}/pojo/PojoPropertyAccessor.ftl</property>
+ </emphasis></para>
<para>The contents of the file is something like this:</para>
@@ -446,9 +470,8 @@
}
</#foreach></programlisting>
- <para>We can add conditionally pre/post-conditions on our
- <literal>set</literal> method generation just adding a little
- Freemarker syntax to the above source code:</para>
+ <para>We can add conditionally pre/post-conditions on our
<literal>set</literal> method
+ generation just adding a little Freemarker syntax to the above source
code:</para>
<programlisting><#foreach property in
pojo.getAllPropertiesIterator()>
${pojo.getPropertyGetModifiers(property)} ${pojo.getJavaTypeName(property, jdk5)}
${pojo.getGetterSignature(property)}() {
@@ -468,18 +491,16 @@
</programlisting>
<para>Now if in any <emphasis>
- <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
- contents will be generated into the body of the relevant
- <literal>set</literal> method.</para>
+ <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
+ 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> preventing no
<literal>Person</literal> can
- have an empty name. So we have to modify the
- <emphasis>
- <property>Person.hbm.xml</property></emphasis> file like
this:</para>
+ <para>As an example let us add a pre-condition for property
<literal>name</literal>
+ preventing no <literal>Person</literal> can have an empty name. So
we have to modify the <emphasis>
+ <property>Person.hbm.xml</property>
+ </emphasis> file like this:</para>
<programlisting><hibernate-mapping>
<class name="Person">
@@ -496,20 +517,19 @@
</class>
</hibernate-mapping></programlisting>
- <note> <para>I) If you don'' use
<literal><[[CDATA[]]></literal>
- you have to scape the & symbol, i.e.: &amp; </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>
- </note>
+ <note>
+ <para>I) If you don'' use
<literal><[[CDATA[]]></literal> you have
+ to scape the & symbol, i.e.: &amp; </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>
+ </note>
- <para>Finally we have to generate the
<property>Person.java</property>
- 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>
+ <para>Finally we have to generate the
<property>Person.java</property> 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>
<programlisting>
<target name="hbm2java">
@@ -531,10 +551,10 @@
</target></programlisting>
<para>Invoking the target <emphasis>
- <property><hbm2java></property></emphasis>
will
- generate on the <emphasis>
- <property>${hbm2java.dest.dir}</property></emphasis> the
file
- <property>Person.java</property>:</para>
+ <property><hbm2java></property>
+ </emphasis> will generate on the <emphasis>
+ <property>${hbm2java.dest.dir}</property>
+ </emphasis> the file
<property>Person.java</property>:</para>
<programlisting>// default package
import java.io.Serializable;
@@ -571,8 +591,8 @@
}
}</programlisting>
- <para></para>
+ <para/>
</section>
</section>
</section>
-</chapter>
\ No newline at end of file
+</chapter>