Beginning Hibernate From Novice to Professional phần 10 pptx

T he < table-filter> e lement allows you to include and exclude groups of tables from the mapping process on the basis of pattern matches on their names. Where the <schema- selection> element allows you to specify a set of tables matching a single pattern to be reverse e ngineered, the < table-filter> e lement operates within this and allows multiple patterns to be applied to include and exclude tables. Here’s an example: <table-filter match-name="NOTEPAD_ARCHIVE*" exclude="true"/> Although the previous <schema-selection> element included all tables within the current schema that matched the pattern NOTE*, this table filter excludes any tables that match the pattern NOTEPAD_ARCHIVE* from reverse engineering. Table filters are applied in order, so using this technique, you can build up a filter that only includes a specific set of tables. The <table> task permits almost total control over the mapping details of the entity. You can select a specific table by catalog, schema, and name. You can specify the class name that it should take, how the primary key column(s) relate to that class’s properties, the primary key generator that it should use, the column types and properties that they are associated with, and the details of the associations formed by foreign key relationships. Our simple example places the generated entity into an appropriate class, with a nonstandard primary key property name and a nonstandard type mapping for one of the columns ( note). It also excludes one of the columns ( audit) from the entity model. <table schema="PUBLIC" name="NOTEPAD" class="com.hibernatebook.tools.Notepad"> <primary-key> <column name="id" jdbc-type="INTEGER" property="notepadPk" type="int"/> </primary-key> <column name="note" jdbc-type="VARCHAR" type="char" property="note"/> <column name="audit" exclude="true"/> </table> If it looks like you will have to manage the reverse engineering process to this level of detail, it may in fact be more appropriate to create some or all of the mapping files manually, which gives you total control over the specification of those entities. Complex specification of mapping information in the reverse engineering file is really only appropriate if it is for excep- tional classes when the gener al cases are common; or if you expect to need to regenerate the model from the schema very frequently in response to changes in the schema details. Templates With the exception of <hbmtemplate> and <query>, all the Ant exporter tasks take the meta- model infor mation from the configuration, pass it to a set of FreeMarker templates, and write the output to files. For more information on the FreeMarker template scripting language, see the FreeMarker site at http://freemarker.sourceforge.net. APPENDIX B ■ HIBERNATE TOOLS294 6935appB_final.qxd 8/2/06 9:15 PM Page 294 ■Note Earlier versions of Hibernate Tools used the Velocity template language instead of FreeMarker, but in other respects, they behaved in the same way. If the existing exporters do not meet your needs, you can specify your own additional code generation tasks using the <hbmtemplate> task. Table B-11 shows the attributes that can be supplied to this task. Table B-11. The Properties Available to the <hbmtemplate> Exporter Element Property Default Description destdir If set, overrides, for this exporter only, the destination directory specified on the Hibernate tool task. exporterclass Specifies a class to use to generate output. It will be invoked once only , and the configuration object, output directory, tem- plate path and prefix, and any configuration properties will be passed into it. filepattern When using templates, represents the FreeMarker macro that should be used to determine the file name for the entity being processed. template Specifies the template to use to generate output. It will be invoked for each of the entities in the configuration metamodel. templatepath Specifies the path from which your template(s) will be loaded, overriding any default location. templateprefix Specifies an optional prefix to your template file name within the template path. It is set by the standard tasks, so overriding this allows you to import your own tasks instead. Again, you have two options when carrying out this process. You can set the exporterclass attribute to the name of the class to be used to carry out the export process. This class must implement the org.hibernate.tool.hbm2x.Exporter interface. This is passed a reference to the current configuration object and any other attributes that were set on the <hbmtemplate> task. Alter nativ ely , you can specify the name of a FreeMarker template to be used in processing the configuration object and the name of a prefix. <hbmtemplate destdir="generated_txt" templateprefix="foo" template="template/MyTemplate.ftl" filepattern="{package-name}/{class-name}.txt"> Note that filepattern contains FreeMarker macros that will be expanded at run time to determine the appropriate file names for the tool’s output. The task will search for this file on the classpath, and then as a file resource. If the configuration object does not contain some of the information that you need in order to produce the desired output, you can also specify additional arbitrary details using a standard Ant property or property set. Here’s an example: APPENDIX B ■ HIBERNATE TOOLS 295 6935appB_final.qxd 8/2/06 9:15 PM Page 295 < hbmtemplate …> <property key="bar" value="BAR!"/> </hbmtemplate> In addition to any properties you add to the template task yourself, you will have access to t he scripting variables listed in Table B-12. Table B-12. The Standard Scripting Variables Available to a Template Task Variable Description artifacts An instance of org.hibernate.tool.hbm2x.ArtifactCollector that can be pop- ulated with values to reflect the actions taken during output generation c2h An instance of the org.hibernate.tool.hbm2x.Cfg2HbmTool class providing helper methods for conver ting configuration object values into Hibernate mapping files c2j An instance of the org.hibernate.tool.hbm2x.Cfg2JavaTool class providing helper methods for converting configuration object values into Java class files cfg A reference to the configuration object outputdir The path specified as the <hbmtemplate> element’s destdir attribute template_path A list of the paths to directories containing FreeMarker templates The standard Hibernate Tools exporter tasks are implemented in much the same way. Although we haven’t shown this when discussing their attributes earlier, all the exporter tasks support the templatepath and templateprefix attributes, allowing you to override their default behavior by instructing them to use a different set of FreeMarker macros than those included in the hibernate-tools.jar file. All attributes also support the use of property sets to pass in information that is required by your custom macros but isn’t available from the configuration object. A very simple FreeMarker script is shown in the following code. This is not very useful in itself, as the first four variables simply display their hashcode representations from the default toString() implementation, but it provides you with a syntactically valid starting point for exploration of the code generation tools. Configuration object: ${cfg} Artifacts object: ${artifacts} Cfg2Hbm Helper: ${c2h} Cfg2Java Helper: ${c2j} Output Directory: ${outputdir} Template path: ${template_path[0]} Configuring the Classpath There are two distinct classpaths to consider when setting up the Hibernate Tools Ant tasks: the classpath of the task definition, and the classpath to be used b y the tasks. The task defini- tion needs to have in its classpath the Hibernate Tools JAR file, the Hibernate libraries, the Hibernate Annotations libraries, and the JDBC driver that will be used to access the database. A typical configur ation of this classpath is as follo ws: APPENDIX B ■ HIBERNATE TOOLS296 6935appB_final.qxd 8/2/06 9:15 PM Page 296 < path id="classpath.base"> <pathelement location="${hibernate.path}"/> <fileset dir="${hibernate.lib}" includes="**/*.jar"/> < pathelement location="${hibernate.annotations.path}"/> <fileset dir="${hibernate.annotations.lib}" includes="**/*.jar"/> </path> <path id="classpath.tools"> <path refid="classpath.base"/> <pathelement location="${hibernate.tools.path}"/> <pathelement location="${jdbc.driver.path}"/> </path> The task definition (as shown earlier in this section) would use the classpath with the ID classpath.tools. The tasks themselves will need access to two additional sets of resources: the configura- tion file(s) and the compiled classes. <path id="classpath.apps"> <path refid="classpath.base"/> <pathelement path="${src}"/> <pathelement path="${bin}"/> <pathelement location="${jdbc.driver.path}"/> </path> The configuration files will include the hibernate.cfg.xml and/or hibernate.properties files, along with any log4j configuration files, cache configuration files, and applicable XML mapping files. If you are using annotations in any of your tasks, you will need to ensure that the task is assigned a dependency upon the compiled POJOs—annotations cannot be read at run time from Java source files, only from compiled classes. Summary In this appendix, we have discussed the installation and use of Hibernate Tools, including the Eclipse plug-in and the Ant tasks. Together, these remove most of the need to manually create boilerplate configuration code. In Appendix C, we discuss how Hibernate can be used as the data access layer within the S pr ing Framework. APPENDIX B ■ HIBERNATE TOOLS 297 6935appB_final.qxd 8/2/06 9:15 PM Page 297 6935appB_final.qxd 8/2/06 9:15 PM Page 298 Hibernate and Spring The Spring Application Framework offers developers an environment that ties together numerous APIs into a coherent whole. Spring applies the philosophy of “dependency injec- tion” by providing appropriate configurable wrapper classes for all sorts of popular Java libraries. The standard Spring API is immense, and its standardized approach to dependency management means that any existing API can in principle become a “Spring” API. If you want a good introduction to using Spring, then we recommend the excellent Pro Spring, by Rob Harrop and Jan Machacek (Apress, 2005). For an overview, visit the Spring web site at http://springframework.org. In view of its scope, we cannot and do not make any attempt to teach you even the basics of the Spring Framework in this appendix—instead, we assume that you are already familiar with Spring in general, and offer a focused introduction to the Hibernate-related components. Throughout this appendix, we refer to a simple sample application that represents a “newsstand” of papers consisting of sets of articles. At the end of this appendix, we include the complete Spring bean configuration file for the example application; and as with all the examples in this book, the entire application itself can be downloaded from the Apress web site ( www.apress.com). Spring Libraries The S pring Framework essentially provides wrappers and utility classes for working with vari- ous other frameworks, as well as some of its own implementations. For example, it provides its own model-view-controller (MVC) patterned web application framework, and also supports Struts and vanilla JSPs. Spring is distributed as a small set of JAR files that contain the Spring-specific functional- ity. The third-party components are made available with the “including dependencies” distri- bution of Spring, but can also be downloaded independently from their respective web sites. It is possible to copy all the libraries that Spring is capable of using into the classpath, but this is a somewhat inelegant approach. We prefer to pick the core Spring JARs and add to them only what is necessary to support the application being built. For our example application, we have therefore included the following sets of libraries: • The Hibernate JAR and its required dependencies • The Hibernate Annotations JAR and its required dependencies 299 APPENDIX C ■ ■ ■ 6935appC_final.qxd 8/2/06 9:17 PM Page 299 • The Java Standard Template Library JARs • The HSQLDB driver JAR • The Spring JAR This requires the list of JAR files shown in Listing C-1 to be included in the WEB-INF/lib directory of our example application. Listing C-1. The Required JAR Files antlr-2.7.6rc1.jar asm-attrs.jar asm.jar cglib-2.1.3.jar commons-collections-2.1.1.jar commons-logging-1.0.4.jar dom4j-1.6.1.jar ehcache-1.1.jar ejb3-persistence.jar hibernate-annotations.jar hibernate3.jar hsqldb.jar jdbc2_0-stdext.jar jstl.jar jta.jar spring.jar standard.jar xml-apis.jar Configuring Hibernate from a Spring Application A conventional Hibernate application needs access to its database and the entity mapping information. The point of access to a fully configured Hibernate environment is the session factory, from which Session objects are obtained. Spring provides a bean to represent the session factory , but pro vides a few additional options in or der to configure its r esources. In our example application, we take the line of least resistance and use a Hibernate config- ur ation file ( hibernate.cfg.xml) to r epresent both the mapping information and the database configuration. F or easy r efer ence when setting up a S pring application, we show a sample Hibernate configuration file in Listing C-2. Listing C-2. F amiliar Territory: A Standard Hibernate Configuration File Used in Spring <?xml version='1.0' encoding='utf-8'?> <!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD//EN" "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> APPENDIX C ■ HIBERNATE AND SPRING300 6935appC_final.qxd 8/2/06 9:17 PM Page 300 < hibernate-configuration> <session-factory> <property name="connection.driver_class"> o rg.hsqldb.jdbcDriver </property> <property name="connection.url"> jdbc:hsqldb:file:/spring/db/springdb;SHUTDOWN=true </property> <property name="connection.username">sa</property> <property name="connection.password"></property> <property name="hibernate.connection.pool_size">0</property> <property name="show_sql">true</property> <property name="dialect">org.hibernate.dialect.HSQLDialect</property> <mapping class="com.hibernatebook.spring.Paper"/> <mapping class="com.hibernatebook.spring.Article"/> </session-factory> </hibernate-configuration> Spring represents the configured session factory as a LocalSessionFactoryBean. Our exam- ple application uses annotations to manage the mappings, so we specify that the Hibernate AnnotationConfiguration type should be used in our bean instead of the default Configuration. ■Caution Spring maintains two sets of Hibernate packages: org.springframework.orm.hibernate for Hibernate 2 functionality, and org.springframework.orm.hibernate3 for Hibernate 3 functional- ity—a single-character difference. Be careful to select the correct one, as debugging the ClassNotFound and similar exceptions that result if you use the wrong one can be extremely time-consuming! We also specify the location and name of the configuration file relative to the classpath as indicated by the classpath: prefix (see Listing C-3). Listing C-3. Configuring a Session Factory Bean in Spring <bean id="sessionFactory" class=" org.springframework.orm.hibernate3.LocalSessionFactoryBean"> <property name="configurationClass" value=" org.hibernate.cfg.AnnotationConfiguration" /> <property name="configLocation" value=" classpath:hibernate.cfg.xml" /> </bean> As noted, our simple w eb application der iv es its database connection details fr om the Hibernate configuration file. However, a larger web application typically needs to provide database r esour ces to other applications , in which case a H iber nate-specific configuration file APPENDIX C ■ HIBERNATE AND SPRING 301 6935appC_final.qxd 8/2/06 9:17 PM Page 301 is not the appropriate location for its details to be stored. Moreover, a well-behaved web appli- cation will draw its database configuration from a JNDI-provided DataSource object so that connection details can be uniformly managed at deployment time. Spring allows data sources to be managed centrally as beans, and if a JndiObjectFactoryBean bean is used, it can in turn draw its details from JNDI. The LocalSessionFactoryBean therefore provides a dataSource property into which the appro- priate Spring DataSource bean can be injected. Typically, to manage a data source from within the Spring configuration, but without deferring the details to a JNDI resource, you would use the DriverManagerDataSource bean (see Listing C-4). Listing C-4. Configuring a Typical BasicDataSource Bean <bean id="sampleDataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource" destroy-method="close"> <property name="driverClassName"> <value>org.hsqldb.jdbcDriver</value> </property> <property name="url"> <value> jdbc:hsqldb:file:/spring/db/springdb;SHUTDOWN=true </value> </property> <property name="username" value="sa"/> <property name="password" value=""/> </bean> Alternatively, if the data source resources are to be drawn from an existing JNDI-accessi- ble data source, then the Spring JndiObjectFactoryBean should be used to represent the data source (see Listing C-5). Listing C-5. Configuring a Typical JndiObjectFactoryBean <bean id="sampleDataSource" class="org.springframework.jndi.JndiObjectFactoryBean"> <property name="jndiName" value="java:comp/env/jdbc/spring"/> </bean> It is not just the connection details that can be migrated from the Hibernate configuration file into the S pring configur ation. The property attributes and the mappings (class names or mapping file names) can also be assigned during the configuration of a LocalSessionFactory bean (see Listing C-6). APPENDIX C ■ HIBERNATE AND SPRING302 6935appC_final.qxd 8/2/06 9:17 PM Page 302 Listing C-6. Configuring Hibernate Purely from Spring < bean id="sampleSessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean"> <property name="dataSource" ref="sampleDataSource"/> < property name="mappingResources"> <list> <value>com/hibernatebook/spring/Paper.hbm.xml</value> <value>com/hibernatebook/spring/Article.hbm.xml</value> </list> </property> <property name="hibernateProperties"> <props> <prop key="hibernate.connection.pool_size">0</prop> <prop key="hibernate.show_sql">true</prop> <prop key="hibernate.dialect">org.hibernate.dialect.HSQLDialect</prop> </props> </property> </bean> Note that in Listing C-6, purely in order to demonstrate the use of mapping files in a LocalSessionFactoryBean configuration, we omit the specification of a Hibernate AnnotationConfiguration for the configurationClass property, causing it to default to the normal (mapping file–based) Hibernate Configuration object. Typically, the mappings themselves are specified in the conventional Hibernate manner through XML mapping files or Java annotations. It would be entirely possible to arrange to configure these externally, but no default Spring classes are provided to achieve this, and it is difficult to see any obvious benefit that would accrue from such an approach. Using Hibernate in Your Spring Beans With your session factory configured as a Spring bean, you can now go on to create DAOs that take advantage of Hibernate’s functionality. Here, Spring really starts to come into its own, as it provides you with the invaluable HibernateDaoSupport class to form the basis of your DAOs (see Listing C-7). Listing C-7. Declaring the Interface for Our DAO package com.hibernatebook.spring.dao; import java.util.List; import com.hibernatebook.spring.Article; import com.hibernatebook.spring.Paper; APPENDIX C ■ HIBERNATE AND SPRING 303 6935appC_final.qxd 8/2/06 9:17 PM Page 303 [...]... attribute, 104 primary keys, 101 103 sequenceName attribute, 104 @GenericGenerator annotation key generation strategies, 130–131 @Id annotation compounding primary keys, 105 , 107 108 , 110 primary keys, 101 103 @IdClass annotation compounding primary keys, 105 , 107 108 , 110 @Index annotation, 130 @IndexColumn annotation collection ordering, 117 ordering collections, 129 @Inheritance annotation compared to @Inheritance,... @DiscriminatorColumn annotation attributes, 120 @Embeddable annotation as marker annotation, 114 @Embeddable class, 105 , 107 108 , 110 @Embedded annotation marking and embedded property, 114 @EmbeddedId annotation compounding primary keys, 105 , 107 108 , 110 @Entity annotation adding to class, 101 attributes, 128 @Enumerated annotation embeddable entities, 114 @GeneratedValue annotation, 102 generator attribute,... http:/ /hibernate. sourceforge.net /hibernate- configuration-3.0.dtd s Caution If you do not update your mapping configuration from the Hibernate 2 form to the Hibernate 3 form, the time it takes to create a configuration and session factory will increase from around 20 seconds to a matter of minutes Obviously, it will not be possible for you to have two configuration files with the same (default) name of hibernate. cfg.xml,... is made with the hibernate. query.factoryclass configuration attribute, which selects the class to load for translating HQL into database queries The options are listed in Table D-1 Table D-1 The HQL Processing Classes Query Factory Class HQL Version org .hibernate. hql.ast.ASTQueryTranslatorFactory 3 (default) org .hibernate. hql.classic.ClassicQueryTranslatorFactory 2 It is not possible to switch between... package, 315 atomicity (transactions), 183 AUTO value GeneratorType enumeration, 103 auto-flush listener AutoFlushEventListene interface, 252 auto-import attribute hibernate- mapping element, 142 autoboxing, Java 5 features, 93 AutoFlushEventListene interface, 252–253 avg() aggregate function Projection class, 220 avg() function, 207 s B backwards compatibility Hibernate 2 session factory, 23 ... still parsed at run time, you will not need to run extensive tests to spot syntactical problems with them 315 6935appD_final.qxd 316 8/2/06 9:14 PM Page 316 APPENDIX D s UPGRADING FROM HIBERNATE 2 The object retrieved from the session factory in Hibernate 3 implements both the pure Hibernate 3 org .hibernate. Session interface and a Hibernate 2–friendly org .hibernate classic.Session interface By using... where to use, 225 Filters annotation, 127 find() method HibernateTemplate class, 305 findDirty interceptor method, 256 6935idx_final.qxd 8/2/06 9:55 PM Page 325 sINDEX s G ge() method Restrictions class, 215 generator attribute @GeneratedValue annotation, 102 , 104 element, 147, 163 class attribute, 147 GeneratorType enumeration javax.persistence package, 102 primary key generators, 102 GenericDialect,... with @Id, @IdClass and @EmbeddedId, 105 , 107 108 , 110 code listings, 132, 136–137 configuring annotated classes, 125–126 cons of annotations, 94 database table mapping with @Table and @SecondaryTable, 110 111 EJB 3 persistence annotations, 96–97, 100 generating primary key values with @SequenceGenerator, 103 generating primary key values with @TableGenerator, 104 105 inheritance, 120–122 large objects,... files, and database schemas Hibernate 3 has started a process of migrating to external support for these processes Where these tools are retained, they can be found in the org .hibernate. tool package and its subpackages For example, previously a facility provided by the CodeGenerator class to generate DDL from your mappings existed in Hibernate 2 This is still provided in Hibernate 3, but the fully qualified... section of the Hibernate web site (http:/ /hibernate org) The Hibernate team maintains and updates this section to reflect users’ experiences, so you can find hints and tips gathered from developers at the cutting edge of just this sort of upgrade Package and DTD Changes The package names for Hibernate 2 have changed with Hibernate 3 Hibernate 2 used a base package of net.sf .hibernate, while Hibernate 3 . org .hibernate. tool.hbm2x.ArtifactCollector that can be pop- ulated with values to reflect the actions taken during output generation c2h An instance of the org .hibernate. tool.hbm2x.Cfg2HbmTool. around Hibernate. APPENDIX C ■ HIBERNATE AND SPRING312 6935appC_final.qxd 8/2/06 9:17 PM Page 312 Upgrading from Hibernate 2 Hibernate 3 represents a major change from the ways of doing things in Hibernate. destination directory specified on the Hibernate tool task. exporterclass Specifies a class to use to generate output. It will be invoked once only , and the configuration object, output directory, tem- plate