diff --git a/reference/en/modules/toolset_guide.xml b/reference/en/modules/toolset_guide.xml index 0f43b63944..ef4d3d72a2 100644 --- a/reference/en/modules/toolset_guide.xml +++ b/reference/en/modules/toolset_guide.xml @@ -1,85 +1,71 @@ - + Toolset Guide - Roundtrip engineering with Hibernate is possible using a set of commandline tools - maintained as part of the Hibernate project, along with Hibernate support built into - XDoclet, Middlegen and AndroMDA. + Roundtrip engineering with Hibernate is possible using a set of Eclipse plugins, + commandline tools, as well as Ant tasks. - The Hibernate main package comes bundled with the most important tool (it can even - be used from "inside" Hibernate on-the-fly): + The Hibernate Tools currently include plugins for the Eclipse + IDE as well as Ant tasks for reverse engineering of existing databases: - DDL schema generation from a mapping file - (aka SchemaExport, hbm2ddl) + Mapping Editor: An editor for Hibernate XML mapping files, + supporting auto-completion and syntax highlighting. It also supports semantic + auto-completion for class names and property/field names, making it much more versatile than a normal XML editor. + + Console: The console is a new view in Eclipse. In addition to + a tree overview of your console configurations, you also get an interactive view + of your persistent classes and their relationships. The console allows you to + execute HQL queries against your database and browse the result directly in + Eclipse. + + + Development Wizards: Several wizards are provided with the + Hibernate Eclipse tools; you can use a wizard to quickly generate Hibernate configuration + (cfg.xml) files, or you may even completely reverse engineer an existing database schema + into POJO source files and Hibernate mapping files. The reverse engineering wizard + supports customizable templates. + + + Ant Tasks: + + - Other tools directly provided by the Hibernate project are delivered with a separate - package, Hibernate Extensions. This package includes tools for - the following tasks: - - - - - Java source generation from a mapping file (aka CodeGenerator, - hbm2java) - - - mapping file generation from compiled Java classes or from - Java source with XDoclet markup (aka MapGenerator, - class2hbm) - - - - - There's actually another utility living in Hibernate Extensions: ddl2hbm. - It is considered deprecated and will no longer be maintained, Middlegen does a better job - for the same task. + Please refer to the Hibernate Tools package and it's documentation + for more information. - Third party tools with Hibernate support are: + However, the Hibernate main package comes bundled with an integrated tool (it can even + be used from "inside" Hibernate on-the-fly): SchemaExport aka + hbm2ddl. - - - Middlegen (mapping file generation from an existing database schema) - - - AndroMDA (MDA (Model-Driven Architecture) approach generating code for - persistent classes from UML diagrams and their XML/XMI representation) - - - - - These 3rd party tools are not documented in this reference. Please refer to the Hibernate - website for up-to-date information (a snapshot of the site is included in the Hibernate - main package). - - - - Schema Generation + + Automatic schema generation - DDL may be generated from your mapping files by a command line utility. A batch file - is located in the hibernate-x.x.x/bin directory of the core - Hibernate package. - - - - The generated schema include referential integrity constraints (primary and foreign keys) for entity - and collection tables. Tables and sequences are also created for mapped identifier generators. + DDL may be generated from your mapping files by a Hibernate utility. The generated + schema includes referential integrity constraints (primary and foreign keys) for + entity and collection tables. Tables and sequences are also created for mapped + identifier generators. You must specify a SQL Dialect via the - hibernate.dialect property when using this tool. + hibernate.dialect property when using this tool, as DDL + is highly vendor specific. + + + + First, customize your mapping files to improve the generated schema. @@ -450,650 +436,5 @@ new SchemaUpdate(cfg).execute(false);]]> - - Code Generation - - - The Hibernate code generator may be used to generate skeletal Java implementation classes - from a Hibernate mapping file. This tool is included in the Hibernate Extensions package - (a separate download). - - - - hbm2java parses the mapping files and generates fully working Java - source files from these. Thus with hbm2java one could "just" provide the - .hbm files, and then don't worry about hand-writing/coding the Java files. - - - - java -cp hibernate_classpaths - org.hibernate.tool.hbm2java.CodeGenerator options - mapping_files - - - - Code Generator Command Line Options - - - - - - Option - Description - - - - - --output=output_dir - root directory for generated code - - - --config=config_file - optional file for configuring hbm2java - - - -
- - - The config file (optional) - - - The config file provides for a way to specify multiple "renderers" for the source code - and to declare <meta> attributes that is "global" in scope. See - more about this in the <meta> attribute section. - - - - codegen.test.IAuditable - - -]]> - - - This config file declares a global meta attribute "implements" and specify two renderers, the - default one (BasicRenderer) and a renderer that generates Finders (See more in "Basic Finder - generation" below). - - - - The second renderer is provided with a package and suffix attribute. - - - - The package attribute specifies that the generated source files from this renderer should be - placed here instead of the package scope specified in the .hbm files. - - - - The suffix attribute specifies the suffix for generated files. E.g. here a file named - Foo.java would be FooFinder.java instead. - - - - It is also possible to send down arbitrary parameters to the renders by adding <param> attributes - to the <generate> elements. - - - - hbm2java currently has support for one such parameter, - namely - generate-concrete-empty-classes which - informs the BasicRenderer to only generate empty - concrete classes that extends a base class for all your - classes. The following config.xml example illustrate - this feature - - - - - - true - Base - - ]]> - - - Notice that this config.xml configure 2 (two) - renderers. One that generates the Base classes, and a - second one that just generates empty concrete classes. - - - - - 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. - - - - You can use the <meta> tag to 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: - - - - - Javadoc for the Person class - @author Frodo - - IAuditable - - protected - - - - The name of the person - -]]> - - - will produce something like the following (code shortened for better understanding). Notice the - Javadoc comment and the protected set methods: - - - - - - Supported meta tags - - - - - - Attribute - Description - - - - - class-description - inserted into the javadoc for classes - - - field-description - inserted into the javadoc for fields/properties - - - interface - If true an interface is generated instead of an class. - - - implements - interface the class should implement - - - extends - class the class should extend (ignored for subclasses) - - - generated-class - overrule the name of the actual class generated - - - scope-class - scope for class - - - scope-set - scope for setter method - - - scope-get - scope for getter method - - - scope-field - scope for actual field - - - use-in-tostring - include this property in the toString() - - - implement-equals - include a equals() and hashCode() method in this class. - - - use-in-equals - include this property in the equals() and hashCode() method. - - - bound - add propertyChangeListener support for a property - - - constrained - bound + vetoChangeListener support for a property - - - gen-property - property will not be generated if false (use with care) - - - property-type - Overrides the default type of property. Use this with any tag's to specify the concrete type instead of just Object. - - - class-code - Extra code that will inserted at the end of the class - - - extra-import - Extra import that will inserted at the end of all other imports - - - finder-method - see "Basic finder generator" below - - - session-method - see "Basic finder generator" below - - - -
- - - Attributes declared via the <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 your classes - implement IAuditable then you just add an - <meta attribute="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! - (Except if a class also has an "implements" meta attribute, because local specified - meta tags always overrules/replaces any inherited meta tags). - - - - Note: This applies to all <meta>-tags. - Thus it can also e.g. be used to specify that all fields should be declared protected, - instead of the default private. This is done by adding <meta - attribute="scope-field">protected</meta> at e.g. just under the - <class> tag and all fields of that class will be protected. - - - - To avoid having a <meta>-tag inherited then you can simply - specify inherit="false" for the attribute, e.g. - <meta attribute="scope-class" inherit="false">public abstract</meta> - will restrict the "class-scope" to the current class, not the subclasses. - - - - - - Basic finder generator - - - It is now possible to have hbm2java generate basic finders for - Hibernate properties. This requires two things in the hbm.xml - files. - - - - The first is an indication of which fields you want to generate finders for. You indicate - that with a meta block inside a property tag such as: - - - - findByName -]]> - - - The finder method name will be the text enclosed in the meta tags. - - - - The second is to create a config file for hbm2java of the format: - - - - - -]]> - - - And then use the param to hbm2java --config=xxx.xml where - xxx.xml is the config file you just created. - - - - An optional parameter is meta tag at the class level of the format: - - - - com.whatever.SessionTable.getSessionTable().getSession(); -]]> - - - Which would be the way in which you get sessions if you use the - Thread Local Session pattern (documented in the Design Patterns - area of the Hibernate website). - - - - - - Velocity based renderer/generator - - It is now possible to use velocity as an alternative rendering mechanism. - The follwing config.xml shows how to configure hbm2java to use its velocity renderer. - - - - - pojo.vm - - ]]> - - - The parameter named template is a resource path to the velocity macro file you want to use. - This file must be available via the classpath for hbm2java. Thus remember to add the directory where pojo.vm - is located to your ant task or shell script. (The default location is ./tools/src/velocity) - - - - Be aware that the current pojo.vm generates only the most basic parts of the java beans. - It is not as complete and feature rich as the default renderer - primarily a lot of the meta tags - are not supported. - - - - - - - - Mapping File Generation - - - A skeletal mapping file may be generated from compiled persistent classes using - a command line utility called MapGenerator. This utility is part of - the Hibernate Extensions package. - - - - The Hibernate mapping generator provides a mechanism to produce mappings from - compiled classes. It uses Java reflection to find properties - and uses heuristics to guess an appropriate mapping from the property type. - The generated mapping is intended to be a starting point only. There is no way to produce - a full Hibernate mapping without extra input from the user. However, the tool does - take away some of the repetitive "grunt" work involved in producing a mapping. - - - - Classes are added to the mapping one at a time. The tool will reject - classes that it judges are are not Hibernate persistable. - - - - To be Hibernate persistable a class - - - - - must not be a primitive type - - - must not be an array - - - must not be an interface - - - must not be a nested class - - - must have a default (zero argument) constructor. - - - - - Note that interfaces and nested classes actually are persistable by Hibernate, but - this would not usually be intended by the user. - - - - MapGenerator will climb the superclass chain of all added classes attempting - to add as many Hibernate persistable superclasses as possible to the same database table. - The search stops as soon as a property is found that has a name appearing on a list of - candidate UID names. - - - - The default list of candidate UID property names is: uid, UID, - id, ID, key, KEY, - pk, PK. - - - - Properties are discovered when there are two methods in the class, a setter and a getter, where the - type of the setter's single argument is the same as the return type of the zero argument getter, - and the setter returns void. Furthermore, the setter's name must start with the - string set and either the getter's name starts with get or - the getter's name starts with is and the type of the property is boolean. In - either case, the remainder of their names must match. This matching portion is the name of - the property, except that the initial character of the property name is made lower case if - the second letter is lower case. - - - - The rules for determining the database type of each property are as follows: - - - - - - If the Java type is Hibernate.basic(), then the property is a - simple column of that type. - - - - - For hibernate.type.Type custom types a simple column is used as well. - - - - - If the property type is an array, then a Hibernate array is used, and MapGenerator - attempts to reflect on the array element type. - - - - - If the property has type java.util.List, java.util.Map, or - java.util.Set, then the corresponding Hibernate types are used, but - MapGenerator cannot further process the insides of these types. - - - - - If the property's type is any other class, MapGenerator defers the decision - on the database representation until all classes have been processed. At this point, if the - class was discovered through the superclass search described above, then the property is - an many-to-one association. If the class has any properties, then it is - a component. Otherwise it is serializable, or not persistable. - - - - - - Running the tool - - - The tool writes XML mappings to standard out and/or to a file. - - - - When invoking the tool you must place your compiled classes on the classpath. - - - - java -cp hibernate_and_your_class_classpaths - org.hibernate.tool.class2hbm.MapGenerator options and - classnames - - - - There are two modes of operation: command line or interactive. - - - - The interactive mode is selected by providing the single command line argument - --interact. This mode provides a prompt response console. Using it you - can set the UID property name for each class using the uid=XXX command - where XXX is the UID property name. Other command alternatives are simply - a fully qualified class name, or the command done which emits the XML and terminates. - - - - In command line mode the arguments are the options below interspersed with fully qualified - class names of the classes to be processed. Most of the options are meant to be used - multiple times; each use affects subsequently added classes. - - - - MapGenerator Command Line Options - - - - - - Option - Description - - - - - --quiet - don't output the O-R Mapping to stdout - - - --setUID=uid - set the list of candidate UIDs to the singleton uid - - - --addUID=uid - add uid to the front of the list of candidate UIDs - - - --select=mode - mode use select mode mode(e.g., - distinct or all) for subsequently - added classes - - - --depth=<small-int> - limit the depth of component data recursion for subsequently added classes - - - --output=my_mapping.xml - output the O-R Mapping to a file - - - full.class.Name - add the class to the mapping - - - --abstract=full.class.Name - see below - - - -
- - - The abstract switch directs the map generator tool to ignore specific super classes so - that classes with common inheritance are not mapped to one large table. For instance, - consider these class hierarchies: - - - - Animal-->Mammal-->Human - - - Animal-->Mammal-->Marsupial-->Kangaroo - - - - If the --abstractswitch is not used, all classes will - be mapped as subclasses of Animal, resulting in one large table containing - all the properties of all the classes plus a discriminator column to indicate which subclass is - actually stored. If Mammal is marked as abstract, - Human and Marsupial will be mapped to - separate <class> declarations and stored in separate tables. - Kangaroo will still be a subclass of Marsupial - unless Marsupial is also marked as abstract. - - - - - -