From jbosstools-commits at lists.jboss.org Mon Jan 24 00:36:47 2011 Content-Type: multipart/mixed; boundary="===============1000031484733879664==" MIME-Version: 1.0 From: jbosstools-commits at lists.jboss.org To: jbosstools-commits at lists.jboss.org Subject: [jbosstools-commits] JBoss Tools SVN: r28537 - trunk/hibernatetools/docs/reference/en-US. Date: Mon, 24 Jan 2011 00:36:46 -0500 Message-ID: <201101240536.p0O5akD6003715@svn01.web.mwc.hst.phx2.redhat.com> --===============1000031484733879664== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: mcaspers Date: 2011-01-24 00:36:46 -0500 (Mon, 24 Jan 2011) New Revision: 28537 Modified: trunk/hibernatetools/docs/reference/en-US/ant.xml Log: General Updates Modified: trunk/hibernatetools/docs/reference/en-US/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-US/ant.xml 2011-01-24 05:28:50 U= TC (rev 28536) +++ trunk/hibernatetools/docs/reference/en-US/ant.xml 2011-01-24 05:36:46 U= TC (rev 28537) @@ -8,14 +8,14 @@ Introduction = - The hibernate-tools.jar contains the core for th= e Hibernate Tools. It is used as the basis for b= oth the Ant tasks described in this document and the eclipse plugins both a= vailable from tools.hibernate.org. The hibernate-tools.jar file is located in your eclipse plugins directory at /plugin= s/org.hibernate.eclipse.x.x.x/lib/tools/hibernate-tools.jar. + The hibernate-tools.jar file contains the core c= ode for Hibernate Tools. It is used as the basis= for both the Ant tasks described in this document and the Eclipse plugins = both available from tools.hibernate.org. The hibernate-tools.jar file is located in your Eclipse plugins directory at /plug= ins/org.hibernate.eclipse.x.x.x/lib/tools/hibernate-tools.jar. This jar is 100% independent from the Eclipse platform and can t= hus be used independently of Eclipse. = Note: - There might be incompatibilities with respect to the Hibe= rnate3.jar bundled with the tools and your own jar. Thus to avoi= d any confusion it is recommended that you use the hibernate3.jar= and hibernate-annotations.jar files bundle= d with the tools when you want to use the Ant tasks. Do not worry about usi= ng the jar's from a later version of Hibernate (e.g. Hibernate 3.2) with a = project using an earlier version of Hibernate (e.g. a Hibernate 3.1) since = the output generated will work with previous Hibernate 3 versions. + There may be incompatibilities with respect to the hibern= ate3.jar bundled with the tools and your own JAR. To avoid any c= onfusion it is recommended that you use the hibernate3.jar and hibernate-annotations.jar files bundled with = the tools when you want to use the Ant tasks. Do not worry about using the = JAR's from a later version of Hibernate (e.g. Hibernate 3.2) with a project= using an earlier version of Hibernate (e.g. a Hibernate 3.1) since the gen= erated output will work with previous Hibernate 3 versions. @@ -24,7 +24,7 @@ The <hibernatetool> Ant Task = - To use the ant tasks you need to have the hiberna= tetool task defined. That is done in your b= uild.xml by inserting the following xml (assuming the jars are i= n the lib directory): = + To use the Ant tasks you need to have the hibernatetool = task defined. That is done in your build.xml file by i= nserting the following XML (assuming the JARs are located in the = lib directory): = = @@ -40,7 +40,7 @@ ]]> = - This <taskdef> defines an Ant task called hibernatetool which now can be used any= where in your Ant build.xml files. It is important to = include all the Hibernate Tools dependencies as = well as the JDBC driver. + This <taskdef> defines an Ant task called h= ibernatetool which now can be used anywhere in your Ant b= uild.xml files. It is important to include all the = Hibernate Tools dependencies as well as the JDBC driver. = @@ -49,7 +49,7 @@ = = - When using the hibernatetool task you have to specify one or more of the following: + When using the hibernatetool task you have to speci= fy one or more of the following: = = - Destination directory for files generated with exporte= rs + Destination directory for files generated with the exp= orters = @@ -135,7 +135,7 @@ = - Used to set properties to control the exporters. Mostl= y relevant for providing custom properties to user defined templates + Used to set properties that control the exporters. Mos= tly relevant for providing custom properties to user defined templates = @@ -180,7 +180,7 @@ Basic examples = - The following example shows the most basic setup for generating poj= o's via <hbm2java> from a normal hibernate.cfg= .xml. The output will be put in the ${build.dir}/gener= ated directory. + The following example shows the most basic setup for generating POJ= Os via <hbm2java> from a normal hibernate.cfg.= xml. The output will be placed in the ${build.dir}/gen= erated directory. = @@ -194,7 +194,11 @@ = = - The following example is similar, but now we are performing multipl= e exports from the same configuration. We are exporting the schema via <hbm2dll>, generating some DAO code via <hbm2dao>= ; and finally running a custom code generation via <hbmtemp= late>. This is again from a normal hibernate.cfg.xml file and the output is still placed in the ${build.dir}/= generated directory. Furthermore the example also shows how a cl= asspath is specified, which is useful when you have custom usertypes or som= e mappings that is needed to be looked up as a classpath resource. + The following example is similar, but now we are performing multipl= e exports from the same configuration. We are exporting the schema via <hbm2dll>, generating some DAO code via <hbm2dao>= ; and finally running some custom code generation via <hbmt= emplate>. This is again from a normal hibernate.cfg.xml= file, and the output is still placed in the ${build.d= ir}/generated directory. + = + = + + The example also shows how a classpath is specified, which is usef= ul when you have custom user types or some mappings that is needed to be lo= oked up as a classpath resource. = @@ -219,27 +223,27 @@ Hibernate Configurations = - Hibernatetool supports four different Hibernate = configurations: A standard Hibernate configuration (<configuration= >), Annotation based configuration (<annotationconfigu= ration>), JPA persistence based configuration (<jpaconfi= guration>) and a JDBC based configuration (<jdbcconfig= uration>) for use when reverse engineering. + Hibernatetool supports four different Hibernate = configurations: A standard Hibernate configuration (<configuration= >), Annotation based configuration (<annotationconfigu= ration>), JPA persistence based configuration (<jpaconfi= guration>) and a JDBC based configuration (<jdbcconfig= uration>) used when reverse engineering. = - Each have in common the fact that they are able to build up a Hiberna= te Configuration object, from which a set of exporters can be run in order = to generate various output. + Each can be used to build a Hibernate Configuration object, from whic= h a set of exporters can be run in order to generate various output formats. = Note: - Output can be anything, e.g. specific files, statements execution a= gainst a database, error reporting or anything else that can be done in jav= a code. + Output can be anything, e.g. specific files, statements execution a= gainst a database, error reporting or anything else that can be done in Jav= a code. = - The following sections describe what the various configurations = can do, plus lists the individual settings they have. + The following sections describe what the various configurations = can do, as well as listing their individual settings. =
Standard Hibernate Configuration (<configuration>)</tit= le> = <para> - A <code><configuration></code> is used to define a standard H= ibernate configuration. A standard Hibernate configuration reads the mappin= gs from a <filename>cfg.xml</filename> and/or a fileset. + A <code><configuration></code> tag is used to define a standa= rd Hibernate configuration. A standard Hibernate configuration reads the ma= ppings from a <filename>cfg.xml</filename> file and/or a fileset. </para> = <programlisting role=3D"XML"><![CDATA[<configuration @@ -359,13 +363,13 @@ <title>Example = - This example shows an example where no hibernate.cfg.xm= l exists, and a hibernate.properties file = and fileset is used instead. + This example shows an example where no hibernate.cfg.xm= l file exists, and a hibernate.properties f= ile and fileset is used instead. = Note: - Hibernate will still read any global hibernate.proper= ties available in the classpath, but the specified properties fi= le here will override those values for any non-global property. + Hibernate will still read any global hibernate.proper= ties files available in the classpath, but the specified propert= ies file here will override those values for any non-global property. = @@ -387,17 +391,17 @@
Annotation based Configuration (<annotationconfiguration&g= t;) = - An <annotationconfiguration> is used when y= ou want to read the metamodel from EJB3/Hibernate Annotations based POJO's.= + An <annotationconfiguration> tag is used wh= en you want to read the metamodel from EJB3 or Hibernate Annotations based = POJO's. = Important: - To use it remember to put the jar files needed for using hibernat= e annotations in the classpath of the <taskdef>, i.e. <= filename>hibernate-annotations.jar and hibernate-commo= ns-annotations.jar. + To use it remember to put the JAR files needed for using Hibernat= e annotations in the classpath of the <taskdef>, i.e. <= filename>hibernate-annotations.jar and hibernate-commo= ns-annotations.jar. = - The <annotationconfiguration> supports the same = attributes as a <configuration> except that the configur= ationfile attribute is now required as that is from where an Anno= tationConfiguration gets the list of classes/packages it should = load. + The <annotationconfiguration> tag supports the s= ame attributes as the <configuration> tag except that th= e configurationfile attribute is now required as that is where= an AnnotationConfiguration gets the list of classes a= nd packages it should load. = Thus the minimal usage is: @@ -417,19 +421,19 @@ JPA based configuration (<jpaconfiguration>) = - A <jpaconfiguration> is used when you want to re= ad the metamodel from JPA/Hibernate Annotation where you want to use the au= to-scan configuration as defined in the JPA spec (part of EJB3). In other w= ords, when you do not have a hibernate.cfg.xml, but in= stead have a setup where you use a persistence.xml fil= e packaged in a JPA compliant manner. + A <jpaconfiguration> tag is used when you want t= o read the metamodel from JPA or 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 hibernate.cfg.xml,= but instead have a setup where you use a persistence.xml file packaged in a JPA compliant manner. = - The <jpaconfiguration> will simply try and auto-= configure it self based on the available classpath, e.g. look for the META-INF/persistence.xml file. + The <jpaconfiguration> tag will try and auto-con= figure it self based on the available classpath, e.g. look for the META-INF/persistence.xml file. = - The persistenceunit attribute can be used to select a = specific persistence unit. If no persistenceunit is specified = it will automatically search for one and if a unique one is found, use it, = but having multiple persistence units will result in an error. + The persistenceunit attribute can be used to select a = specific persistence unit. If no persistenceunit attribute is = specified it will automatically search for one and if a unique one is found= , use it. However, having multiple persistence units will result in an erro= r. = - To use a <jpaconfiguration> you will need to spe= cify some additional jars from Hibernate EntityManager in the <tas= kdef> of the hibernatetool. The following shows a full setup: + To use a <jpaconfiguration> tag you will need to= specify some additional JARs from Hibernate EntityManager in the <= ;taskdef> section of the hibernatetool. The following demonstrate= s a full setup: = @@ -462,7 +466,7 @@ Note: - ejb3configuration was the name used in previous versions. It stil= l works but will emit a warning telling you to use jpaconfiguratio= n instead. + ejb3configuration was the name used in previous versions. It stil= l works but will display a warning telling you to use jpaconfigura= tion instead. = @@ -471,14 +475,14 @@
JDBC Configuration for reverse engineering (<jdbcconfigura= tion>) = - A <jdbcconfiguration> is used to perform re= verse engineering of the database from a JDBC connection. + A <jdbcconfiguration> tag is used to perfor= m reverse engineering of a database from a JDBC connection. = This configuration works by reading the connection properties eithe= r from a hibernate.cfg.xml file or a hiberna= te.properties file with a fileset. = - The <jdbcconfiguration> has the same attributes = as a <configuration> plus the following additional attri= butes: + The <jdbcconfiguration> tag has the same attribu= tes as a <configuration> tag, plus the following additio= nal attributes: = Example = - Here is an example of using <jdbcconfiguration> to generate Hibernate xml mappings via <hbm2hbmxml>. T= he connection settings here is read from a hibernate.properties = file but could just as well have been read from a hib= ernate.cfg.xml file. + Here is an example using a <jdbcconfiguration>= tag to generate Hibernate XML mappings via <hbm2hbmxml>= . The connection settings used here are read from a hibernate.pro= perties file, but they could also have been defined in a hibernate.cfg.xml file. = @@ -618,7 +622,7 @@ Exporters = - Exporters do the actual job of converting the hibernate metamodel int= o various artifacts, mainly code. The following section describes the curre= nt supported set of exporters in the Hibernate Tool distribution. It is also possible to implement user defined exporters, = which is done through the <hbmtemplate> exporter. + Exporters do the actual job of converting the Hibernate metamodel int= o various artifacts, mainly code. The following section describes the curre= nt supported set of exporters in the Hibernate Tool distribution. It is also possible to implement user defined exporters, = which is done through the <hbmtemplate> exporter. =
@@ -683,7 +687,7 @@ = - Try and create an update script representing the "de= lta" that is, between what is in the database and what the mappings sp= ecify. Ignores create and update attributes. (Do *not* use agains= t production databases, as there are no guarantees that the proper delta ca= n be generated nor that the underlying database can actually execute the re= quired operations). + Try and create an update script representing the "de= lta" that is, between what is in the database and what the mappings sp= ecify. Ignores create and update attributes. (Do *not* use agains= t production databases, as there are no guarantees that the proper delta ca= n be generated, nor that the underlying database can actually execute the r= equired operations). = @@ -785,7 +789,7 @@ Example = - Basic example of using <hbm2ddl>, which does = not export to the database but simply dumps the SQL to a file named sql.ddl. + Below is a basic example of using <hbm2ddl>, = which does not export to the database but simply dumps the SQL to a file na= med sql.ddl. = @@ -868,7 +872,7 @@
Example = - Basic example of using <hbm2java> to gene= rate POJO's that utilize JDK5 constructs. + Here is a basic example using <hbm2java> = to generate POJO's that utilize JDK5 constructs. = @@ -881,7 +885,7 @@ Hibernate Mapping files exporter (<hbm2hbmxml>) = - <hbm2hbmxml> generates a set of .hbm files. Intended to be used together with a <jdbcconfigur= ation> when performing reverse engineering, but can be used with = any kind of configuration. e.g. to convert from annotation based POJO's to = a hbm.xml file. + <hbm2hbmxml> generates a set of .hbm files. It is intended to be used together with a <jdbcco= nfiguration> when performing reverse engineering, but can be used= with any kind of configuration e.g. to convert from annotation based POJO'= s to a hbm.xml file. = @@ -923,7 +927,7 @@ Hibernate Configuration file exporter (<hbm2cfgxml>)</t= itle> = <para> - <code><hbm2cfgxml></code> generates a <filename>hibernate.cfg= .xml</filename> file. Intended to be used together with a <code><jdbccon= figuration></code> when performing reverse engineering, but it can be us= ed with any kind of configuration. The <code><hbm2cfgxml></code> will= contain the properties used and adds mapping entries for each mapped class. + <code><hbm2cfgxml></code> generates a <filename>hibernate.cfg= .xml</filename> file. It is intended to be used together with a <code><j= dbcconfiguration></code> when performing reverse engineering, but it can= be used with any kind of configuration. The <code><hbm2cfgxml></code= > will contain the properties that are used and adds mapping entries for ea= ch mapped class. </para> = <programlisting role=3D"XML"><![CDATA[<hbm2cfgxml @@ -1000,7 +1004,7 @@ ]]></programlisting> = <para> - Currently one session is opened and used for all queries and the qu= ery is executed via the <code>list()</code> method. In the future more opti= ons might become available, like performing <code>executeUpdate()</code>, u= se named queries and etc. + Currently one session is opened and used for all queries, which are= executed via the <code>list()</code> method. In the future more options mi= ght become available, like executing <code>executeUpdate()</code>, use name= d queries and etc. </para> = <para/> @@ -1009,7 +1013,7 @@ <title>Examples = - The simplest usage of <query> will just execut= e the query without dumping to a file. This can be used to verify that quer= ies can actually be performed. + The simplest usage of <query> will execute the= query without dumping to a file. This can be used to verify that queries c= an be performed successfully. = @@ -1023,7 +1027,7 @@ = Note: - Currently the dump is simply a call to toString() on each element. + Currently the dump is performed by calling the toSt= ring() function on each element. = @@ -1039,7 +1043,7 @@
Generic Hibernate metamodel exporter (<hbmtemplate>)</t= itle> = - <para>Generic exporter that can be controlled by a user provides a t= emplate or class.</para> + <para>Below is an example of a generic exporter that can be controll= ed by a user provided template or class.</para> = <programlisting role=3D"XML"><![CDATA[<hbmtemplate filepattern=3D"{package-name}/{class-name}.ftl" @@ -1049,7 +1053,7 @@ = <note> <title>Note: - Previous versions of the tools used Velocity. We are now using Freemarker which p= rovides us much better exception and error handling. + Previous versions of the tools used Velocity. We are now using Freemarker, which = provides much better exception and error handling. = @@ -1057,7 +1061,7 @@ Exporter via <hbmtemplate> = - The following is an example of reverse engineering via <= jdbcconfiguration> and usage of a custom Exporter via the &= lt;hbmtemplate>. + The following is an example of reverse engineering via a &l= t;jdbcconfiguration> tag and the use of a custom Exporter via the= <hbmtemplate> tag. = @@ -1081,7 +1085,7 @@ Relevant Resources Links = - Read more about Veloci= ty and Freemarker to = find out why using the last is better or refer to Max Andersen discussion o= n the topic in "A story about FreeMarker and Velocit= y". + You can read more about Velocity and Freemarker to find out why using the latter is better or refer to Max Andersens d= iscussion on the topic in "A story about FreeMarker = and Velocity".
@@ -1093,20 +1097,20 @@ Using properties to configure Exporters = - Exporters can be controlled by user properties. The user properties a= re specified via <property> or <propertyset>= and each exporter will have access to them directly in the template= s and via Exporter.setProperties(). + Exporters can be controlled by user properties. These user properties= are specified via a <property> or <propertyset= > tag, and each exporter will have access to them directly in the= templates and via Exporter.setProperties(). =
<property> and <propertyset> = - The <property> allows you bind a string value to= a key. The value will be available in the templates via $<key>= . The following example will assign the string value "tru= e" to the variable $descriptors. + The <property> tag allows you bind a string valu= e to a key. The value will be available in the templates via the $<= ;key> tag. The following example will assign the string value "true" to the variable $descriptors. = ]]> = - Most times using <property> is enough for specif= ying the properties needed for the exporters. Still the Ant tools supports = the notion of a <propertyset> which is used for grouping= a set of properties. More about the functionality of <propertyset= > is explained in detail in the Ant manual. + Usually using the <property> tag is enough when = specifying the properties required by the exporters. Still, the Ant tools s= upports the notion of a <propertyset> which is used for = grouping a set of properties. More about the functionality of <pro= pertyset> is can be found in the Ant manual.
= @@ -1118,18 +1122,18 @@ ]]> = - Placing the above <property> tag in <hi= bernatetool> or inside any exporter will automatically create an = instance of x.y.z.NameOfToolClass and it will be available in = the templates as $sometool. This is useful to delegate logic a= nd code generation to Java code instead of placing such logic in the templa= tes. + Placing the above <property> tag in the &l= t;hibernatetool> tag or inside any exporter will automatically cr= eate an instance of x.y.z.NameOfToolClass which will be availa= ble in the templates as $sometool. This is useful to delegate = logic and code generation to Java code instead of placing such logic in the= templates. =
Example = - Here is an example that uses <hbmtemplate> tog= ether with <property>, which will be available to the te= mplates/exporter. = + Here is an example that uses the <hbmtemplate>= tag together with the <property> tag, which will be ava= ilable to the templates and exporter. = Note: - This example actually simulates what <hbm2java&g= t; does. + This example actually simulates what the <hbm2ja= va> tag does. = --===============1000031484733879664==--