From jbosstools-commits at lists.jboss.org Wed Jan 9 11:27:33 2008 Content-Type: multipart/mixed; boundary="===============8076400873663394187==" MIME-Version: 1.0 From: jbosstools-commits at lists.jboss.org To: jbosstools-commits at lists.jboss.org Subject: [jbosstools-commits] JBoss Tools SVN: r5564 - trunk/hibernatetools/docs/reference/en/modules. Date: Wed, 09 Jan 2008 11:27:32 -0500 Message-ID: --===============8076400873663394187== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 w= ords Modified: trunk/hibernatetools/docs/reference/en/modules/ant.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ = + + + + = ]]> Modified: trunk/hibernatetools/docs/reference/en/modules/codegen.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/hibernatetools/docs/reference/en/modules/codegen.xml 2008-01-09 1= 6:20:46 UTC (rev 5563) +++ trunk/hibernatetools/docs/reference/en/modules/codegen.xml 2008-01-09 1= 6:27:32 UTC (rev 5564) @@ -2,34 +2,34 @@ Controlling POJO code generation = - When using - <hbm2java> 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. + When using + <hbm2java> + 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. =
The <literal><meta></literal> attribute = - The - <meta> tag is a simple way of - annotating the - hbm.xml with information, so tools= have - a natural place to store/read information that is not directly related= to - the Hibernate core. + The + <meta> + tag is a simple way of annotating the + hbm.xml + with information, so tools have a natural place to store= /read information that is + not directly related to the Hibernate core. = - You can use the - <meta> tag to e.g. tell - - <hbm2java> to only generate = - "protected" setters, have - classes always implement a certain set of interfaces or even have them - extend a certain base class and even more. + You can use the + <meta> + tag to e.g. tell + <hbm2java> + to only generate + "protected" + setters, have classes always implement a certain set of = interfaces or even have + them extend a certain base class and even more. = The following example shows how to use various - <meta> - attributes and the resulting java code. + <meta> + attributes and the resulting java code. = <class name=3D"Person"> <meta attribute=3D"class-description"> @@ -47,9 +47,9 @@ </class> = The above - hbm.xml will produce something like = the following (code - shortened for better understanding). Notice the Javadoc comment and the - protected set methods: + hbm.xml + will produce something like the following (code shortene= d for better + understanding). Notice the Javadoc comment and the protected set met= hods: = // default package = @@ -100,9 +100,9 @@ Supported meta tags = - + = - + = @@ -114,172 +114,200 @@ = - class-description + + class-description + = inserted into the javadoc for classes = - field-description + + field-description + = inserted into the javadoc for fields/properties = - interface + + interface + = - If true an interface is generated instead of an - class. + If true an interface is generated instead of an class.<= /entry> = - implements + + implements + = interface the class should implement = - extends + + extends + = - class the class should extend (ignored for - subclasses) + class the class should extend (ignored for subclasses)<= /entry> = - generated-class + + generated-class + = overrule the name of the actual class generated = - scope-class + + scope-class + = scope for class = - scope-set + + scope-set + = scope for setter method = - scope-get + + scope-get + = scope for getter method = - scope-field + + scope-field + = scope for actual field = - default-value + + default-value + = default initialization value for a field = - use-in-tostring + + use-in-tostring + = - include this property in the - toString() + include this property in the toString() = - use-in-equals + + use-in-equals + = - include this property in the equals() - and hashCode() method. If no use-in-equals = is - specified, no equals/hashcode will be generated. + include this property in the equals() and + hashCode() method. If no use-in-equals is= specified, no + equals/hashcode will be generated. = - gen-property + + gen-property + = - property will not be generated if false (use with - care) + property will not be generated if false (use with care)= = - property-type + + property-type + = - Overrides the default type of property. Use this with a= ny - tag's to specify the concrete type instead of just Object. + Overrides the default type of property. Use this with a= ny tag's to specify the + concrete type instead of just Object. = - class-code + + class-code + = - Extra code that will inserted at the end of the - class + Extra code that will inserted at the end of the class = - extra-import + + extra-import + = - Extra import that will inserted at the end of all other - imports + Extra import that will inserted at the end of all other= imports = Attributes declared via the - <meta> tag are - per default - "inherited" inside an - hbm.xml file. + <meta> + tag are per default + "inherited" + inside an + hbm.xml + file. = - What does that mean? It means that if you e.g want to have all y= our - classes implement IAuditable then you just add an - - <meta - attribute=3D"implements">IAuditable</meta> in the = top of - the - hbm.xml file, just after - - <hibernate-mapping>. Now all= classes defined in - that - hbm.xml file will implement - IAuditable! + What does that mean? It means that if you e.g want to have all y= our classes implement + IAuditable then you just add an <= meta + attribute=3D"implements">IAuditable</meta> in = the top of the + hbm.xml + file, just after + <hibernate-mapping> + . Now all classes defined in that + hbm.xml + file will implement IAuditable! = - This applies to all - <meta>-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 <meta - attribute=3D"scope-field">protected</meta> at e.g. = just - under the <class> tag and all fields of that - class will be protected. - + + This applies to all + <meta>-tags. Thus it can also e.g. be use= d to specify that + all fields should be declare protected, instead of the default pri= vate. This is done by + adding <meta + attribute=3D"scope-field">protected</meta> at e= .g. just under + the <class> tag and all fields of that cl= ass will be + protected. + = To avoid having a - <meta> tag inherited then - you can simply specify - inherit =3D "false" for the - attribute, e.g. - <meta attribute =3D "scope-class" - inherit =3D "false">public abstract</meta> will r= estrict - the - "class-scope" to the cu= rrent class, not the subclasses. + <meta> + tag inherited then you can simply specify inh= erit =3D "false" + for the attribute, e.g. <meta attribute =3D "scope-cla= ss" inherit =3D + "false">public abstract</meta> will restrict t= he + "class-scope" + to the current class, not the subclasses. =
Recommendations = - The following are some good practices when using - - <meta> attributes. + The following are some good practices when using + <meta> + attributes. =
- Dangers of a class level <literal>use-in-string and - use-in-equals</literal> meta attributes when having bi-directional - associations + Dangers of a class level <literal>use-in-string and use-in-= equals</literal> meta + attributes when having bi-directional associations = - If we have two entities with a bi-directional association - between them and define at class scope level the meta attributes: - use-in-string, use-in-equals: + If we have two entities with a bi-directional association be= tween them and define at + class scope level the meta attributes: + use-in-string + , + use-in-equals + : = <hibernate-mapping> <class name=3D"Person"> @@ -290,7 +318,8 @@ </hibernate-mapping> = And for - Event.hbm file: + Event.hbm + file: = <hibernate-mapping> = <class name=3D"events.Event" table=3D"EVENTS"> @@ -309,19 +338,21 @@ </hibernate-mapping> = Then - <hbm2java> will assume you= want to - include all properties and collections in the - toString()/equals() methods and this can result= in - infinite recursive calls. + <hbm2java> + will assume you want to include all properties and c= ollections in the + toString()/equals() = methods and this can + result in infinite recursive calls. = - To remedy this you have to decide which side of the associat= ion - will include the other part (if at all) in the - toString()/equals() methods. Therefore it is no= t a - good practice to put at class scope such meta attributes, unless y= ou - are defining a class without bi-directional associations. + To remedy this you have to decide which side of the associat= ion will include the other + part (if at all) in the toString()/equals() + methods. Therefore it is not a good practice to put at class sco= pe such + meta + attributes, unless you are defining a class without = bi-directional + associations. = - We recomend instead to add the meta - attributes at the property level: + We recomend instead to add the + meta + attributes at the property level: = <hibernate-mapping> = <class name=3D"events.Event" table=3D"EVENTS"> = @@ -364,75 +395,68 @@
=
- Be aware of putting at class scope level - <literal><meta></literal> attribute - <literal>use-in-equals</literal> + Be aware of putting at class scope level <literal><meta&= gt;</literal> + attribute <literal>use-in-equals</literal> = - For equal()/hashCode() 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). + For equal()/hashCode() method generatio= n, + you have to take into account that the attributes that participa= te on such method + definition, should take into account only attributes with busine= ss meaning (the name, + social security number, etc, but no generated id's, for example)= . = 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. + java.util.Set relies on equals(= ) and + hashcode() to be correct and not change f= or objects in the set; + this can be a problem if the id gets assigned for an object afte= r you inserted it into a + set. = Therefore automatically configuration the generation of - equals()/hashCode() methods specifying at class - scope level the - <meta> attribute - use-in-equals could be a dangerous decision that - could produce non expected side-effect. + equals()/hashCode() methods specifying at c= lass scope level the + <meta> + attribute use-in-equals could be a dangerous decision that + could produce non expected side-effect. = - Here you can = get more in-depth - explanation on the subject of equals() and hashcode(). + Here you can get more in-depth + explanation on the subject of equals() and = hashcode().
=
- Advanced <literal><meta></literal> attribute - examples + Advanced <emphasis><property><meta></property></emphasi= s> attribute examples = - This section shows an example for using meta attributes (inclu= ding - userspecific attributes) together with the code generation features = in - Hibernate Tools. + This section shows an example for using meta attributes (inclu= ding userspecific + attributes) together with the code generation features in Hibernate + Tools. = - The usecase being implemented is to automatically insert some = pre- - and post-conditions into the getter and setters of the generated POJ= O. - + The usecase being implemented is to automatically insert some = pre- and post-conditions + into the getter and setters of the generated POJO. =
Generate pre/post-conditions for methods = - With an - <meta attribute=3D"class-code">, - you can add additional methods on a given class, nevertheless such - - <meta> attribute can not= be used at property - scope level and Hibernate Tools does not prov= ide such - - <meta> attributes. + With an <meta attribute=3D"class-code">, you can add + additional methods on a given class, nevertheless such + <meta> + attribute can not be used at property scope level an= d Hibernate + Tools does not provide such + <meta> + attributes. = - A possibly solution for this is to modify the freemarker - templates responsible for generating the POJO's. If you look inside - - hibernate-tools.jar, you can f= ind the template: - - pojo/PojoPropertyAccessor.ftl<= /para> + A possibly solution for this is to modify the freemarker tem= plates responsible for + generating the POJO's. If you look inside + hibernate-tools.jar + , you can find the template: + pojo/PojoPropertyAccessor.ftl + = - This file is as the named indicates used to generate property - accessors for pojo's. + This file is as the named indicates used to generate propert= y accessors for pojo's. = Extract the - PojoPropertyAccessor.ftl into a - local folder i.e. - ${hbm.template.path}, respecti= ng - the whole path, for example: - - ${hbm.template.path}/pojo/PojoPropertyAccessor.ftl + PojoPropertyAccessor.ftl + into a local folder i.e. + ${hbm.template.path} + , respecting the whole path, for example: + ${hbm.template.path}/pojo/PojoPropertyAccessor.ftl + = The contents of the file is something like this: = @@ -446,9 +470,8 @@ } </#foreach> = - We can add conditionally pre/post-conditions on our - set method generation just adding a little - Freemarker syntax to the above source code: + We can add conditionally pre/post-conditions on our set method + generation just adding a little Freemarker syntax to the above s= ource code: = <#foreach property in pojo.getAllPropertiesIter= ator()> ${pojo.getPropertyGetModifiers(property)} ${pojo.getJavaTypeName(prope= rty, jdk5)} ${pojo.getGetterSignature(property)}() { @@ -468,18 +491,16 @@ = Now if in any - *hbm.xml file we define the - - <meta> attributes: - pre-cond or post-cond, their - contents will be generated into the body of the relevant - set method. + *hbm.xml + file we define the + <meta> + attributes: pre-cond or = post-cond, their + contents will be generated into the body of the relevant set method. = - As an example let us add a pre-condition for property - name preventing no Person can - have an empty name. So we have to modify the - - Person.hbm.xml file like this:= + As an example let us add a pre-condition for property name + preventing no Person can have an empty name. = So we have to modify the + Person.hbm.xml + file like this: = <hibernate-mapping> <class name=3D"Person"> @@ -496,20 +517,19 @@ </class> </hibernate-mapping> = - I) If you don'' use <[[CDATA[]]> - you have to scape the & symbol, i.e.: &amp; - II). Note that we - are referring to "firstName" directly and this is the parameter na= me - not the actual field name. If you want to refer the field you have= to - use "this.firstName" instead. - + + I) If you don'' use <[[CDATA[]]> you have + to scape the & symbol, i.e.: &amp; + II). Note that we are referring to "firstName" directly an= d this is the parameter + name not the actual field name. If you want to refer the field= you have to use + "this.firstName" instead. + = - Finally we have to generate the Person.java - 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 - <hibernatetool> task via - the templatepath attribute as in: + Finally we have to generate the Person.java class, for this we + can use both Eclipse and Ant as long as you remember to set or f= ill in the templatepath + setting. For Ant we configure + <hibernatetool> + task via the templatepath attribu= te as in: = <target name=3D"hbm2java"> @@ -531,10 +551,10 @@ </target> = Invoking the target - <hbm2java> will - generate on the - ${hbm2java.dest.dir} the file - Person.java: + <hbm2java> + will generate on the + ${hbm2java.dest.dir} + the file Person.java: = // default package import java.io.Serializable; @@ -571,8 +591,8 @@ } } = - +
- \ No newline at end of file + --===============8076400873663394187==--