As can be seen from the examples in Chapters 1 through 4, the *.hbm.xml files are at the heart of an application's use of Hibernate. Depending on your needs, you may or may not work with *.hbm.xml files directly (for example, you may prefer to work with Java code and use XDoclet, as shown in Chapter 3, or to start from an existing database, as shown in Chapter 4), but it's vital to understand the structure and options available in a *.hbm.xml mapping files. The options presented in XDoclet and Middlegen are based on the options available in these mapping files.
This chapter is intended as a reference, organized alphabetically, by tag. A description of each tag is included, as well as some notes and comments on usage where appropriate. If you are just orienting yourself to Hibernate, you may wish to skip or skim this chapter and instead go on to the conceptual elements and tools covered in the remainder of this book. Regardless, at some point you will almost certainly need to consult this reference to make full use of Hibernate or to understand the meaning of one or another attribute.
The vast majority of the tags discussed in this chapter deal with relationship management. For an overall view of the Java and database relationship strategies supported by Hibernate, consult Chapter 7.
The basic format of a *.hbm.xml mapping file is shown in Listing 5.1. The first line is a standard XML declaration. The DOCTYPE specifies a DTD (defining the structure of the mapping document). This DTD is included in the main hibernate2.jar file and is also available online. If you are using the standard XML parsing libraries included with the Hibernate distribution, Hibernate will use the DTD included in the hibernate2.jar file, not the online file. Opening the file in a strict XML editor or viewer, however, may result in an error if no Internet connection is available.
Depending on your needs, you may wish to replace the PUBLIC DOCTYPE declaration with a SYSTEM declaration pointing to a file on the local file system, as shown in Listing 5.2. This should only be done during development, and should be avoided if possible.
Obviously, the location of the DTD on your local file system may vary.
Example 5.2. Mapping File with Local DTD Declaration
<?xml version="1.0"?> <!DOCTYPE hibernate-mapping SYSTEM "C:devenvhibernate-2.1.2src etsfhibernatehibernate-mapping-2.0.dtd"> <hibernate-mapping> ... </hibernate-mapping>
The root element is hibernate-mapping. Most often, you will find one or more class declaration elements in a hibernate-mapping, as well as import declarations to bring in other classes, queries, and other information. For the full range of options, see the hibernate-mapping tag below.
The remainder of this chapter serves as a reference for *.hbm.xml files, organized alphabetically by tag. Each tag notes where the tag may appear, the contents of the tag (i.e., what nested tags are permitted and/or required), required attributes, and optional attributes.
The any association allows you to map a single foreign key to any other class.
For example, let's say that you wish to use a single table to keep track of who is creating new records in a database relating to users, groups, and roles. When a new permission is created, you want to log the primary key and the type of new permission (even though a single table is used). By using two columns, you create a foreign-key binding to this new record (the first column is the discriminator, the second is the foreign key).
The concept of an any association is difficult to understand outside the context of Hibernate's handling of class hierarchy relationships. You are strongly encouraged to review the subclass tag and also Chapter 7 for a detailed description of how Hibernate handles class relationships.
class, subclass, joined-subclass, component, dynamic-component, composite-element, nested-composite-element
| Optionally, one or more meta tags. |
| Optionally, one or more tags. Only needed if you specify a |
| A minimum of two |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, or a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
Possible values are none, all, save-update, or delete. For more information, see the many-to-one tag, cascade attribute.
The type of the discriminator (the first column). For a discussion of possible types, see the property tag, type attribute. If you set this to a basic type, such as string or integer, you will need to specify the mapping of the value to a type using the meta-value tag.
An array is a basic element in the Java programming language—you will see it in use when you write your first static public void main(String[] args) statement. An array tag is used to map this basic data type to the database, where the contents of the array are of an arbitrary object type (if you are only working with Java language primitives in the array, see the primitive-array tag). In practice an array is similar to a list, with the important distinction that an array cannot be lazily loaded—it must be loaded as part of the containing object.
| Optionally, one or more meta-tags. |
| Optional, one tag only. |
| A single key tag must be specified. |
| Required. For lists, this column contains sequential integers numbered from zero. |
| A single relationship tag must be specified. For more information, see the appropriate tag and Chapter 7. |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute in hibernate-mapping for more information).
The possible values for this attribute are none, all, save-update, delete, all-delete-orphan, and delete-orphan. For more information, see the map tag, cascade attribute.
If set to true, this association is marked as the many end of a one-to-many bi-directional relationship or as one end of a bi-directional many-to-many relationship. For more information, see the inverse attribute, map tag, and Chapter 7.
Typically, this will be one or more column_name asc or column_name desc strings, expressed as SQL (not HQL).
Use this attribute to specify an arbitrary SQL WHERE condition to be used when retrieving or deleting data for the collection.
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
Used only during schema generation/update. For more information, see the check attribute of the column tag.
A bag is one of the many ways to represent what in database terminology would be referred to as a foreign-key relationship. A Java programmer would think of this as a way to persist the pure notion of a java.util.Collection. Simply put, a bag is an unordered collection that may contain duplicate elements.
Note that according to the official Hibernate documentation, large Hibernate bags mapped with inverse="false" are inefficient and should be avoided. Because there is no key that may be used to identify an individual row, rows cannot be created, deleted or updated individually.
For more information on collections, see Chapter 7.
| Optionally, one or more meta-tags. |
| Optional, one only. |
| A single key tag must be specified. |
| A single relationship tag must be specified. |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
The possible values for this attribute are none, all, save-update, delete, all-delete-orphan, and delete-orphan. For more information, see the map tag, cascade attribute.
Used only during schema generation/update. For more information, see the check attribute of the column tag.
If set to true, this association is marked as the many end of a one-to-many bi-directional relationship or one end of a bi-directional many-to-many relationship. For more information, see the inverse attribute, map tag.
If set to true, the class won't actually load data from the database until specifically requested. For more information, see the lazy attribute of the class tag.
Typically, this will be one or more column_name asc or column_name desc strings, expressed as SQL (not HQL).
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute in hibernate-mapping for more information).
Specifying a cache allows Hibernate to know more about a particular entity, enabling it to retain more memory in data (and therefore minimizing database access).
If you are using a hibernate.cfg.xml file instead of hibernate .properties, you may wish to specify cache information using <class-cache> and <collection-cache> elements in that file.
Possible values are read-only, read-write, nonstrict-read-write, and transactional. For more on choosing a strategy (and other performance-related information), see Chapter 10.
This is the basic declaration of a mapping file. Conceptually, each class tag describes a table, with a wide variety of options.
A class only contains nested tags. The tags should appear in the following order:
| Optional. One or more tags. |
| Optional. One tag only. |
| One or the other is required (but not both). |
| Optional. Only one possible. Only needed if you intend to map multiple classes to a single table. See Chapter 2 for an example of use. |
| Optional. Only one possible. Only needed if you intend to track object versioning. See Chapter 2 for an example of use, Chapter 9 for more information. |
| All of these are optional, and they can appear in any order, as needed. |
| Optional. You can declare one or more |
The number of objects to be retrieved in a single fetch from the database.
This attribute is only used during schema generation. For more information, see the column tag, check attribute.
This attribute specifies a strategy for distinguishing this class from other classes in a persisted class hierarchy.
For example, let's say you wish to persist the following classes: com.example .Animal, com.example.Cat, and com.example.Dog. Cat and Dog both extend Animal, and Animal is considered a concrete class. You wish to persist all three objects to the same table. Hibernate uses a column in the table, as specified by the discriminator tag, to keep track of the type information for the record. By default, the value stored in the database for this column would be com .example.Animal, com.example.Cat, or com.example.Dog.
You may find that this is inefficient, or inelegant, or you may have existing data that uses a different model. For example, you may wish to merely store the values A, C, and D instead of the full class name. This attribute lets you specify the binding between this class and the discriminator value. Continuing the example, the com.example.Cat class would then specify discriminator-value="C".
A true/false attribute. Similar to dynamic-update below, if set to true, Hibernate will generate SQL at runtime, persisting only the non-null fields. Note that dynamic-insert is less prone to versioning complexity (an example of which is shown in Chapter 2) and can be used in a wider variety of situations.
A true/false attribute. If set to true, causes the class to generate specific SQL for the changes in an object at runtime, as opposed to simply automatically persisting the whole object. In certain situations (but not all), this may improve performance. If you wish to use dynamic-update, you will need to be aware of the issues around optimistic locking (see the optimistic-lock attribute, below).
If set to true, the class won't actually load data from the database until specifically requested. This is a very important, useful attribute (especially for collections and properties). For example, you may wish to load a Customer object without actually loading all of the related Orders. By specifying that a class or property is lazy, Hibernate will generate a proxy object that, when requested, will actually retrieve the data.
Specifying lazy=true is the same as setting the proxy to the same class. Thus, for example, <class name="com.example.MyObject" proxy="com .example.MyObject"> and <class name="com.example.MyObject" lazy="true"> are equivalent.
If set to false, the values of this class cannot be changed. Hibernate is able to perform some optimizations if this is set to false.
Possible values for this attribute are none, version, dirty, and all. You will want to set this (and be aware of the implications of the various strategies) both for use by the dynamic-update attribute and as a general tool. For an example of versioning, see Chapter 2. For more information on optimistic locking, see Chapter 9.
This attribute allows the class to use a custom implementation of the net.sf.hibernate.persister.Class Persister interface. This allows you to specify a wholly new mechanism for saving a persistent object. In theory, you could create a new ClassPersister implementation that uses XML, LDAP, stored procedures, or even Web services. In practice, it's often easier to just use native APIs for these data stores.
Possible values are implicit and explicit. By default, Hibernate will return all objects that match a request for a given superclass. For example, in a hierarchy containing com.example .Animal, com.example.Cat, and com.example.Dog, a request for all com.example.Animal objects will return all com.example.Animal, com.example.Cat, and com.example.Dog objects. Normally, this is appropriate and correct.
Setting this attribute to explicit means that you will have to specifically name the subclasses to retrieve them. For example, com.example.Animal requests will only return com.example.Animal objects. You would have to explicitly name com.example.Dog and com.example.Cat to retrieve those objects as well.
Generally speaking, it's better to leave this set to implicit, and if you wish to retrieve a subset, simply specify that in the query.
Normally, you won't need this attribute—just use the lazy="true" attribute instead.
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute in hibernate-mapping for more information).
If set to true, Hibernate won't actually send an update unless it is certain that the object has been modified (potentially a useful performance enhancement). If the object was used outside the session and then associated using net.sf.hibernate.Session.update(), Hibernate will first issue a SQL SELECT before updating the object.
A collection-id tag is used to specify a primary key column and generator for an idbag. For more information, see the tag idbag and the tag id.
| Optionally, one or more meta-tags. |
| Optionally, one or more column tags may be specified. |
| A single |
Specify the type for the unique identifier (using a Hibernate type, as described in the property tag sidebar). Any basic type except binary, blob, and clob is allowed. Make sure that the choice of type matches the type of the generator. Popular choices include long and string. For more information on possible types, see the tag property, attribute type.
Used when Hibernate is asked to generate or update the schema. For more information, see the property tag, length attribute.
The column element may be used to specify additional details about a column over the column attributes afforded by a variety of other tags. In particular, the column tag allows for much greater control over the schema generation.
For certain tags, such as any, many-to-any, and index-many-to-any, you will need to specify multiple column tags to properly configure the relationship.
id, discriminator, property, many-to-one, key-property, key-many-to-one, any, element, many-to-many, key, index, index-many-to-many, many-to-any, index-many-to-any, collection-id
This attribute is only used during schema generation. It allows you to specify an arbitrary constraint that should be put on the table. Note that the implications of this are database-specific, so it should be used with care.
Used during schema update and generation, this attribute can specify the name of a multi-column index.
Used when Hibernate is asked to generate or update the schema. For more information, see the property tag, length attribute.
A true/false attribute. If this value is set to true, values of null may not be stored in the database for this property. Only used when Hibernate is asked to generate or update the schema.
Use this attribute to specify a specific SQL type to be used when generating or updating this column.
A true/false attribute. Allows you to specify a constraint in the database. Only used when Hibernate is asked to generate or update the schema.
A component is primarily a mechanism for managing the complexity of a table with many columns. For example, imagine a table with 20 columns used to store information about a person. Five columns are used to track information about the person's medical information. You could use the component tag to clump these five columns into a single medical information object.
The component has a strict one-to-one, parent/child relationship with the wrapping class. You can use a parent tag to add a reference property pointing to the wrapping class (using the example above, this would let a medical record get back to the owning person object). If all of the properties of a component are set to null, the component can be considered null.
For more information, including an example of the use of components, see Chapter 7.
| Optionally, one or more meta-tags. |
| Optionally, a single parent tag may be present. If this tag is present, a property will be generated that allows a component to retrieve the parent object. |
| May be included in any order. |
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
If set to false, this component will be ignored when a SQL INSERT is issued for this class. This can only be specified for the component as a whole, not the properties of the component.
A composite-element allows you to specify a class, instead of simple properties, for the values of a collection. In many ways, a composite-element is to a collection as a component is to a class. Indeed, much of the behavior of a composite-element is like that of a component (see the component tag for more information). For more information on this (and the related nested-composite-element tag), see Chapter 7.
Let's say that you want to use a new class to hold the returned elements of a set. Much like a component, you define the class, properties, and so on, using composite-element, but the composite-element isn't explicitly bound to a specific table (like a class); instead, it's bound to the table specified to the collection tag.
Composite elements may not hold nested collections. If you wish to use a component in a composite-element, use the nested-composite-element tag instead (and you might want to rethink the complexity of your model in this situation).
A composite key allows you to specify a primary key by “gluing” together other properties. For example, let's say that you know that your users are going to be tracked by social security number (a nine-digit number in the United States) and by driver's license (an eight-digit string in California). Instead of using an id tag, you would use the composite-id tag to for object identity.
You may specify a composite key by using the name, class, and unsaved-value attributes. If you do this, in effect you are using the composite-id as a component (see the component tag for more information).
If you wish to specify a composite key using the name, class, and unsaved-value attributes, the class containing the composite-id should contain a property for each key column, implement the java.io .Serializable interface, and provide correct implementations of the equals() and hashCode() methods (as described in Chapter 6). If you use this strategy, to load an object you would first need to instantiate it, set the proper values, and then call Session.load().
See the tag class, attribute default-access for more information.
Specifies the class (used as a component) to represent the identifier.
Specifies the property name for the class.
If set to any, then new transient instances (not associated with a given persistent record) are considered newly instantiated. For more information, see the id tag, unsaved-value attribute.
A composite-index allows you to map a key to a component (instead of, say, the primary key). Imagine, for instance, that you have defined a person class with a component containing the social security number. You could use the composite-index tag to refer to the component containing the social security number while also including the other relevant properties (using the key-property and key-many-to-one tags).
WARNING
This tag is not commonly used. Generally speaking, it means that you are using a table with many columns (as described by the component tag and in Chapter 7) and that you are also using composite keys (two or more columns to uniquely identify a record in another table, as described under the composite-id tag). If this is your situation, I would strongly recommend that you consider a redesign of your database schema.
A composite-index must contain at least one (and optionally more) key-property and/or key-many-to-one tags.
A discriminator tag is used to specify the column to be used to determine the class of the loaded object when a single table is used to store a class hierarchy. For an example of the use of the discriminator tag, see Chapter 3. For more information, see the tag subclass.
This true/false attribute is only useful if you have records in the table that don't map to a persistent class. For example, you may have a table that contains Animal, Cat, Dog, and Fish records, but no Fish persistent class is available. Therefore, you do not want to load any Fish records when you request Animal objects. In this situation, specify force=true, and Hibernate will ignore the Fish records.
Length of the column. For more information, see the tag property, attribute length.
A true/false attribute. Normally, this should be left to true, unless you are using a specific legacy data that uses a null type for a column (for example, you might have legacy data where a null column value is used to map to the base class).
Type of the column to be used. For more information, see the tag property, attribute class.
At times, you may want to decouple the properties of an object from your application code. For example, imagine that you don't know all the properties you want to associate with a person object (or, in database terminology, you don't know the columns on the person table). You can make changes as needed to the database and the *.hbm.xml file (editing the various properties nested in the dynamic-component tag), but your Java code will work with the component as if it were simply a java.util.Map containing the specified properties (for more information on java.util.Map, see Chapter 7). The property names refer to the map keys, and the values to the returned results.
| Any of these tags may be may be included in any order. |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
If set to false, this property/column will be ignored when a SQL UPDATE is issued for this component. This is only usable for properties of a class (not a component tag).
This tag is used to declare the data types and columns for the elements of collections. In many ways, an element's relationship to a collection is similar to the relationship between a property and a class—it's a way to bind the contained objects to a specific set of columns. You don't specify the name for an element; you'll get the results back as part of the collection only.
The element tag is used when you don't want or need to wrap the contents of a collection in another object type. For example, if you want to represent a collection of primitive int values, you would use the element tag to indicate the column and type of the collection.
The type attribute can be set according to the following rules, as described in the property tag sidebar, Hibernate Supported Data Types.
Used when Hibernate is asked to generate or update the schema. For more information, see the property tag, length attribute.
A true/false attribute. Only used when Hibernate is asked to generate or update the schema. For more information, see the property tag, unique attribute.
A generator is used to specify a unique identifier (typically for use as a primary key). You use this tag to specify the implementation of net.sf .hibernate.id.IdentifierGenerator to be used to generate the primary key when the object is added or saved. For more information on built-in Hibernate generators, see Chapter 6.
| Depending on the class you specify as a |
Either a Hibernate shortcut name or the fully qualified class name of an implementation of net.sf.hibernate.id.IdentifierGenerator. For more information on possible generators, see Chapter 6, Built-In Hibernate Generators.
This tag serves as the root element for a *.hbm.xml mapping file. Most commonly, this tag will include one or more class declarations. If you have more than a few classes, it's considered good form to break up your *.hbm.xml file on a per-class basis, but if you are just starting out with a few classes, you can declare them in a single *.hbm.xml file.
You are only allowed to include the following tags in the order shown. You may include as many of each tag as you need.
| Zero, one, or more tags. |
| Zero, one, or more tags. |
Zero, one or more of these tags. If using a subclass or joined-subclass directly inside a hibernate-mapping, use the import tag to declare the base class. | |
| Used to externalize a HQL query in the mapping file (as opposed to in your Java code). See Chapter 8 for more information. |
| Used to externalize a SQL query in the mapping file (as opposed to in your Java code). See Chapter 8 for more information. |
The possible values are true and false. Allows you to use unqualified class names in the query language. Normally, the only reason you'd set this to false is if you have two classes with the same name and only distinguished by the class package—obviously, you are strongly discouraged against doing this, because it is likely to run into confusion and unpredictable results in other areas.
The auto-import tag does not affect Java code generation. You'll need to declare the full class name for classes, subclasses, and other entities in your mapping.
By default, Hibernate will use standard JavaBean style get/set pairs to access properties, not direct access to the private variables. By setting this attribute to the value field, Hibernate will use simple primitive attribute values to directly modify class data. Put another way, property access means using myObject.setName(), whereas field access means using myObject.name field directly. This affects both Java code generation and also the manner in which Hibernate will access the object.
The possible values for this attribute are none, save-update, and all. This attribute is used to determine the settings for collections and properties. For more information, see the various collection declarations (for example, set, list, map, bag, array, primitive-array) and Chapter 7.
Allows you to specify the package prefix for unqualified names in class declarations. Note that this attribute does not affect code generation. Even if you set it, you'll still need to declare the full package and class name in your classes.
As a matter of course, every object and record has a notion of an identifier, or id. Typically, this is a single integer or string allowing for a quick and easy way to access an object. Normally, this identifier should have no real meaning other than bookkeeping in the databases (this is known as a synthetic identifier). In database terminology, the identifier is often referred to as the primary key. An id is required for all base classes modeled by Hibernate (see the class tag for more information).
The main purpose of an id tag is to specify the column and method to be used for generating a new identifier—a generator tag. For more information on the strategies available for generating identifiers, see the generator tag.
May only contain the following tags, in this order.
| Optional, one or more. |
| Optional, use this tag in lieu of the equivalent attributes. |
| Required. |
Possible values are field, property, and a fully qualified class name. See hibernate-mapping tag, default-access for more information on this attribute.
See the tag property, attribute type.
If specified, you can access the id as a named property (e.g. using getId() and setId() methods). If not present, use net.sf.hibernate Session.getIdentifier(Object object) to retrieve the identifier for an object loaded/created by the session. Normally, it's easiest to specify a name.
Specify the type (using a Hibernate type, as described in the type sidebar, property tag) for the unique identifier. Any basic type except binary, blob, and clob is allowed. Popular choices include long and string. For more information on possible types, see the tag property, attribute type. Make sure the type you choose is compatible with your choice of generator.
Before using an idbag, read the documentation for the use of a bag.
A normal many-to-many relationship is modeled using an association table. For example, let's say that you wish to link the User table with the Beverage table to indicate preferred beverages. To keep track of this link, you create an association table with two columns, userID and beverageID. The default implementation of bag does not include a mechanism for using an additional primary key ID column—you refer to records in the link table using the userID and beverageID. The idbag tag allows you to specify a link table with a primary key ID column using a collection-id tag, which in turn allows you to specify a generator tag.
In most respects, an idbag is treated the same as a bag. The advantage of idbag is faster updates and deletes. As of Hibernate version 2.1.2, the identity generator mechanism is not supported for idbag. In addition, as of Hibernate 2.1.2, there is no provision for easily obtaining the generated key.
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
The possible values for this attribute are none, all, save-update, delete, all-delete-orphan, and delete-orphan. For more information, see the map tag, cascade attribute.
Used only during schema generation/update. For more information, see the check attribute of the column tag.
If set to true, the class won't actually load data from the database until specifically requested. For more information, see the lazy attribute of the class tag.
Typically, this will be one or more column_name asc or column_name desc strings, expressed as SQL (not HQL).
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute of the hibernate-mapping tag for more information).
Use this attribute to specify the table the collection data this element maps against.
This tag serves three important functions—it allows you to import another *.hbm.xml class when you use a subclass directly inside of a hibernate-mapping file, it allows you to effectively “rename” a class, and it also allows you to refer to two classes differing only by package statement with a short name.
Superficially, this tag emulates the standard Java keyword import and serves as an important mechanism for linking persistent classes. Interestingly, the rename attribute allows you to change the imported class name to another value.
For example, let's say you'd like to refer to the class com.example.SampleObject in this mapping file, but you want to refer to it as SampleObject instead of by the fully qualified name.
A less common usage is when you have two classes with the same class name, distinguished only by package statement. For example, consider the two classes com.example.ExampleObject and com.example.persistent .ExampleObject (a terrible idea, by the way). You would like to be able to refer to these classes using a shorter syntax than the full class name in your queries, and you don't want to turn off the auto-import="true" in your hibernate-mapping. You therefore include the following import declarations in your hibernate-mapping:
<import class="com.example.ExampleObject" rename= "BaseObject" /> <import class="com.example.persistent.ExampleObject" rename="PersistObject" />
It's generally poor form to rely on package declarations to distinguish classes; if possible, try to avoid this situation.
Declares the type and column for a collection index. For more information, see the appropriate collection tag.
The name of the database column. Optional if specified with a column tag, but required if no column tag specified.
Used when Hibernate is asked to generate or update the schema. For more information, see the property tag, length attribute.
Required if an index is used in a map. For information on the type attribute, see the property tag, type attribute.
This tag allows you to use the any relationship as the index of a map. In effect, you're using a link to any other arbitrary object as the index of your map—an unusual and complex mapping.
For more information, see the index and any tags.
| The first declared column is used as the discriminator (see the discriminator tag for more information). |
| At least one, and possibly more, additional |
The type of the discriminator (in other words, the type of the first column). For more information, see the any tag, meta-type attribute.
This tag allows you to specify an entity class to use as the key for a map. Normally, a map uses an ordinary index, which in turn is more or less analogous to a property. By specifying an index-many-to-many tag, you can instead use a foreign key as the index (and, in turn, obtain classes that map to this foreign key).
An index-many-to-many (much like a property) can optionally contain one or more column tags.
The name of the database column. Optional if specified with a column tag, but required if no column tag is specified.
Used only during schema export and update. For more information, see the many-to-one tag, foreign-key attribute.
A joined-subclass is used to define a multiple-table object hierarchy in Hibernate. For more information, see Chapter 7.
If you wish to use a single table for your subclasses instead, see the tag joined-subclass. Note that you can't use both subclass and joined-subclass in the same class tag—you need to choose one strategy or the other.
You can declare subclasses in their own *.hbm.xml mapping file, directly inside the hibernate-mapping element. If you wish to do this, make sure that you specify the subclass's superclass using the extends attribute (see below).
The following tags are allowed (or required):
| Optional, one or more. |
| Required to specify the primary key. |
| As many as required, in the order desired. |
| You can nest additional |
For more information, see the class tag, dynamic-insert attribute.
For more information, see the class tag, dynamic-update attribute.
For more information, see the subclass tag, extends attribute.
For more information, see the class tag, lazy attribute.
For more information, see the class tag, persister attribute.
For more information, see the class tag, proxy attribute.
For more information, see the class tag, schema attribute.
Use this to declare a foreign key for tags that require it. For more information, see the requiring tag.
The name of the database column. Optional if specified with a column tag instead, but required if no column tag specified.
Used only during schema export and update. For more information, see the many-to-one tag, foreign-key attribute.
Used by the composite-id and composite-index tags. The key-many-to-one tag is used to specify a foreign key as an identifier in a composite-id or composite-index.
Note that this property is always set to not-null, and never to cascade.
| Zero, one, or more tags, as appropriate. |
| A |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
The property type of the returned object. For more information, see the many-to-one tag, class attribute.
Used only during schema export and update. For more information, see the many-to-one tag, foreign-key attribute.
A key-property is used by the tags composite-id and composite-index. The key-property tags are used to specify the properties of the composite-id or composite-index.
| Zero, one, or more tags, as appropriate. |
| A |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default access for more information.
Used when Hibernate is asked to generate or update the schema. For more information, see the property tag, length attribute.
A bag is one of the many ways to represent what in database terminology would be referred to as a foreign-key relationship. A Java programmer would think of this as a way to persist a java.util.List. The important distinction to remember is that a list is an ordered collection (also known as a sequence). The most interesting feature of a list (over, say, a bag; see Chapter 7 for more information) is the ability to specify precisely where in the list an element should be inserted. Additionally, elements can be accessed by an integer index. An index column is required in order to maintain this ordering.
Many developers expect to use a java.util.List (and therefore the list tag) when retrieving a collection from the database, but instead are retrieving the order from the database as part of a query, not as part of the data record. For example, the posts in a weblog might be retrieved by date, in which case the order is determined by date, not by the precise order as maintained by a list in the database. Because of this, for most common operations a sorted map, key, or set more accurately represents the desired model.
| Optionally, zero, one, or more meta-tags. |
| Optional, one tag only. |
| A single key tag must be specified. |
| Required. This column contains sequential integers numbered from zero. |
| A single relationship tag must be specified. |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
The possible values for this attribute are none, all, save-update, delete, all-delete-orphan, and delete-orphan. For more information, see the map tag, cascade attribute.
Used only during schema generation/update. For more information, see the check attribute of the column tag.
If set to true, this association is marked as the many end of a one-to-many bi-directional relationship or one end of a bi-directional many-to-many relationship. For more information, see the inverse attribute, map tag.
If set to true, the class won't actually load data from the database until specifically requested. For more information, see the lazy attribute of the class tag.
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute in hibernate-mapping for more information).
A many-to-any tag allows you to define a polymorphic association to any table with the given type. While you use the any tag to declare this sort of foreign-key relationship in a class, subclass, etc., the many-to-any tag is used to declare a foreign-key-plus-discriminator relationship in a collection.
To better understand this tag, see the many-to-one and any tags.
| Optionally, one or more |
| The first declared |
| At least one and possibly more additional |
The type of the discriminator (in other words, the type of the first column). For more information, see the any tag, meta-type attribute.
This tag is used to describe a many-to-many relational model. It requires an association table (as specified by the collection tag's table attribute). This tag is used to identify the relevant foreign key of the association table. For more information on relationships, see Chapter 7.
You'll use this tag inside a collection tag (map, set, bag, idbag, list, array). The collection tag serves to identify how this relationship works, whereas the many-to-many tag serves to establish the column and class bindings.
| Optionally, one or more meta-tags. |
| Can optionally contain one or more column tags (much like a property). |
The name of the database column. Optional if specified with a column tag, but required if no column tag is specified.
Used only during schema export and update. For more information, see the many-to-one tag, foreign-key attribute.
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
Defines a simple foreign-key association between two tables. For example, if you have a schema that defines a weblog with many associated posts, you would use the many-to-one tag to map the Post.getWeblog() method.
To define the other end of this relationship, use a collection, one of the set, list, map, bag, array, or primitive-array tags. For more information on relationships, see Chapter 7.
| One or more tags, as appropriate. |
| A |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
Possible values are none, all, save-update, or delete. Specifies operations that should be cascaded from the parent to the associated object. For example, let's say you load the post and the associated weblog (cascade="save-update"). Therefore, changes made to the associated weblog object will be made when the post is saved.
The property type of the returned object. The class property type is used to determine the target table. Using the weblog and posts example, if you have set the name of the weblog class to com.example.Weblog, you would set the class attribute of this end of the relationship to com.example.Weblog (for an example of this, see Chapter 2). Hibernate may auto-detect this association using reflection from the Java code, but it's often a good idea to set the class manually (for example, if you are relying on the *.hbm.xml file for code generation).
Used to specify foreign-key constraint generated for this association— Hibernate only uses this for generating and updating schema.
If set to false, this property/column will be ignored when a SQL INSERT is issued for this. This is only usable for properties of a class (not a component; see the component tag for more information).
A true/false attribute. For more information, see the property tag, not-null attribute.
Normally, Hibernate will bind to the referenced table's primary key. On occasion, you may wish to define an association based on an alternative column. Generally speaking, this is a terrible design (if possible, you're usually better off adding a primary key instead), but you may need this feature for certain legacy data.
Possible values are true, false, or auto. If set to true and the session configuration allows, outer-join fetching will always be used. If set to auto (and allowed by the session configuration), the association will be fetched by an outer-join if the associated class has no proxy. If set to false, an outer-join will never be used. For more information on joins, see Chapter 8.
A true/false attribute. For more information, see the property tag, unique attribute.
If set to false, this property/column will be ignored when a SQL UPDATE is issued for this. This is only usable for properties of a class (not a component; see the component tag for more information).
A map is one of the many ways to represent what in database terminology would be referred to as a foreign key. A Java programmer would think of this as a way to persist a java.util.Map or, if a sorting order is specified, a java.util.SortedMap.
To be precise, a map is an object that maps keys to values (typically, name/value pairs, such as Java properties). A map cannot contain duplicate keys, and each key can map to at most one value. A sorted map will maintain the keys in order.
For more information on maps and other collection tags, see Chapter 7.
| Optionally, one or more meta-tags. |
| Optional, one only. |
| A single |
| A single index key must be specified. |
| A single relationship tag must be specified. |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
The possible values for this attribute are none, all, save-update, delete, all-delete-orphan, and delete-orphan This attribute allows you to perform certain operations automatically as the total graph of objects is manipulated. This allows you to perform a broad suite of functionality very quickly, at the risk of significant possible unintended consequences.
For example, you might wish to delete all of the posts associated with a weblog automatically when the weblog is deleted (as shown in Chapter 2). Unfortunately, this carries two risks. First, unless you are very careful, you risk inadvertently deleting data (for example, if you later switch to a model in which a weblog might have multiple authors, but neglect to properly update your mapping). Second, Hibernate will issue individual DELETE statements for each deleted child (in order to ensure that all proper triggers, etc., are called), which may be far less efficient than explicit bulk deletes (see Chapter 8 for more information on this topic).
Used only during schema generation/update. For more information, see the check attribute of the column tag.
If set to true, this association is marked as the many end of a one-to-many bi-directional relationship or one end of a bi-directional many-to-many relationship.
The rule of thumb is that one end of a bi-directional relationship should be marked as inverse="true". For a one-to-many relationship, this will always be the collection tag (map, set, bag, etc.). For a many-to-many relationship, the end of the relationship containing the least amount of data should generally be marked inverse="true".
Changes made to the inverse end of an association are not persisted automatically. This means that you will want to issue a explicit Session.save() on both ends of an association to ensure that changes are properly saved.
Mapping one end of an association with inverse="true" doesn't affect the operation of cascading operations.
Here's a simple way to remember the meaning of inverse: if inverse is set to true, the association should be considered read-only (excluding cascading operations); changes to the association must be made to the owning, that is, non-inverse, or inverse=false, side.
If set to true, the class won't actually load data from the database until specifically requested. For more information, see the lazy attribute of the class tag.
Typically, this will be one or more column_name asc or column_name desc strings, expressed as SQL (not HQL).
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute of the hibernate-mapping tag for more information).
This attribute may be set to unsorted, natural or the fully qualified class name of an implementation of java.util.Comparator.
This tag is used primarily by code generators to hold values that are not directly related to object/relational bindings. Keep in mind that these tags are considered inherited. For example, if you specify <meta attribute=" interface">com.example.BusinessObject</meta> in your hibernate-mapping, all the classes and subclasses declared in that mapping will implement the com.example.BusinessObject interface.
hibernate-mapping, class, subclass, joined-subclass, id, composite-id, version, timestamp, property, many-to-one, one-to-one, key-property, key-many-to-one, any, component, map, set, bag, idbag, list, array, primitive-array, many-to-many, collection-id
Arbitrary text, typically a name/value pair relationship between the attribute and the tag content. The following meta values are expected by Hibernate and the various Hibernate tools.
Attribute | Description |
|---|---|
| The contents of this |
| Contents are added to the |
| Set to |
| Use this to specify a specific interface for the class to implement. |
| Use to specify a class the class should extend. Ignored for subclasses. |
| Use this to override the name of the generated class. |
| Sets the scope for class (e.g., |
| Sets the scope for generated set method (e.g., |
Sets the scope for generated set method (e.g., | |
| Sets the scope for the generated field (e.g., |
| If set to |
| Adds |
| Adds both bound and |
| If set to |
| Overrides the default type of property. If you are using the |
| Allows you to indicate that the code generator should generate methods to easily retrieve objects by property. For example, you may wish to add a method to easily retrieve an object by the id, or a user record by e-mail address. As of version 2.0.2 of the Hibernate Extensions download, you must use the term finder, but future releases may require the use of the term finder-method. |
session-method | If you are using |
Meta-tags are, by default, inherited to lower declarations. For example, if you declare <meta attribute="scope-set">private</a> in your hibernate-mapping, then all the set methods in all of the classes nested in the hibernate-mapping will be declared private. You can override this if needed. If you declare a particular property's meta scope-set tag to be public, that will override the hibernate-mapping and class declaration.
The meta-value tag is used by the any and many-to-any tags to map discriminator values to classes. For example, let's say that you are using the any tag, and you have set the meta-type attribute of the tag to string. This means that we are using a string column to track the type of the type of reference being stored. For Hibernate to map these references to objects, the meta-value tag is used to bind a given constant to a specific Java class.
The meta-value tag is essentially analogous to the discriminator-value attribute of the subclass tag.
The only use of a nested-composite-element is to specify a composite-element that in turn contains components. See composite-element for more information.
| Optionally, a parent tag may be specified to provide a property to retrieve the owning collection. For more information, see the component and parent tags. |
| One or more of these may be specified. |
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
A one-to-many association is used to describe a foreign-key relationship. This is the “other end” of a many-to-one relationship; you may wish to read the many-to-one documentation as well. For more information on relationships, see Chapter 7.
Consider a weblog that contains many posts (where each post belongs to only one weblog, but a weblog can have zero, one, or more posts, as shown in Chapter 2). To obtain the posts from a weblog, you need to first use a collection tag as a property of the weblog class (using the map, set, bag, list, or array tag). You would then put the one-to-many tag inside the collection tag.
Put another way, a class tag is used to declare the base class (weblog). A collection tag is used to describe how the association should be managed. Then a one-to-many tag is used to specify the target class (posts).
Note that Hibernate does not support bi-directional one-to-many associations with an indexed collection (list, map, or array) as the many end.
For more information on relationships, see Chapter 7.
Declares a one-to-one association between two entities. These come in two flavors. Either two different tables share the same primary key, or there is an ordinary foreign-key relationship. If you have two tables sharing the same primary key, you will want to set the generator class to foreign (see the generator tag and Chapter 6 for more information). For more information on relationships, see Chapter 7.
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
Possible values are none, all, save-update, or delete. For more information, see the many-to-one tag, class attribute.
The property type of the returned object. For more information, see the many-to-one tag, class attribute.
If set to true, specifies that a foreign-key constraint on the primary key of the mapped table references the table of the associated class. This option affects the order in which Session.save() and Session.delete() are cascaded. It is also used by Hibernate's schema export.
Used only during schema export and update. For more information, see the many-to-one tag, foreign-key attribute.
Possible values are true, false, or auto. For more information, see the many-to-one tag, outer-join attribute.
A name/value pair, only used to configure a generator. See the generator tag and Chapter 6 for more information.
The contents of the param tag are the value that you wish to set, dependent on the generator being used.
The only use of the parent tag is to provide a component, composite-element, or nested-composite-element with a property pointing back to the owning class. For more information, see the component tag.
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
A primitive array is used to model an array of primitive Java language types (for example, an array of long, instead of java.lang.Long). For more information on arrays, see the array tag.
| Optionally, one or more meta-tags. |
| Optional, one only. |
| A single key tag must be specified. |
| Required. This column contains sequential integers numbered from zero. |
| A single relationship tag must be specified. This is much more strict than the options available for a normal |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
Used only during schema generation/update. For more information, see the check attribute of the column tag.
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute of the hibernate-mapping tag for more information).
Simply put, a property is used to map a JavaBean-style property to a single table column. Optionally, Hibernate can access a variable directly.
class, subclass, joined-subclass, component, dynamic-component, composite-element, nested-composite-element
| One or more tags, as appropriate. |
| A |
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
Use this to specify a SQL expression for this property. For example, you might specify database-specific formatting or other rules. This is only usable for properties of a class (not a component tag).
If set to false, this property/column will be ignored when a SQL INSERT is issued for this. This is only usable for properties of a class (not a component tag).
Used when Hibernate is asked to generate or update the schema. Typically, this is used to specify the length attribute of a character data field. A Hibernate-generated Java source does not include any special handlers for worrying about the length of a string, so you'll only see length-related errors at runtime from the database (if at all).
A true/false attribute. If this value is set to true, values of null may not be stored in the database for this property. Only used when Hibernate is asked to generate or update the schema.
The type attribute can be set according to the following rules, as described in the sidebar Hibernate-Supported Data Types.
You may wish to remove HQL strings from your Java code and instead store them in your *.hbm.xml files (much as you might use a properties file to externalize message strings).
You can declare a query in a *.hbm.xml file by name, with the contents of the tag containing the actual query. For example, you can put the following tag in your *.hbm.xml file:
<query name="com.example.Cat.by.name.and.minimum.weight"><![CDATA[
from com.example. Cat as cat
where cat.name = ?
and cat.weight > ?
] ]></query>
In your Java code, you would therefore use the following to run this query:
net.sf.hibernate.Query myQuery =
mySession.
getNamedQuery
("com.example.Cat.by.name.and.minimum.weight");
myQuery.setString(0, "Bob");
myQuery.setInt(1, 5);
List cats = myQuery.list();
While externalizing your HQL statements using a query tag may be useful, you will almost certainly want to externalize native SQL statements using the sql-query tag.
The contents of a query are raw character data, to be executed the same as any other HQL query. Use CDATA wrappers (as shown above) to wrap your HQL to avoid confusing the XML parser.
The return tag is only used when nested inside a sql-query tag. It is used to specify the class which should be used for data returned from the sql-query. For more information, see sql-query.
A set is one of the many ways to represent what in database terminology would be referred to as a foreign key—it is probably the most typical, natural mapping for a foreign key. A Java programmer would think of this as a way to persist a java.util.Set or, if a sorting order is specified, a java.util.SortedSet.
To be precise, a set is a collection that contains no duplicate elements (note that a set has no notion of a key; you are merely working directly with the elements). More formally, sets contain no pair of elements e1 and e2 such that e1.equals(e2), and at most one null element. A sorted set will maintain the elements in order.
For more information (and a comparison with other collection types), see Chapter 7.
| Optionally, one or more meta-tags. |
| Optional, one only. |
| A single key tag must be specified. |
| A single relationship tag must be specified. |
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default access for more information.
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
The possible values for this attribute are none, all, save-update, delete, all-delete-orphan, and delete-orphan. For more information, see the map tag, cascade attribute.
Used only during schema generation/update. For more information, see the check attribute of the column tag.
If set to true, the class won't actually load data from the database until specifically requested. For more information, see the lazy attribute of the class tag.
Typically, this will be one or more column_name asc or column_name desc strings, expressed as SQL (not HQL).
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute in hibernate-mapping for more information).
This attribute may be set to unsorted, natural or the fully qualified class name of an implementation of java.util.Comparator.
Use this attribute to specify the table the collection data should be retrieved from.
Defines a named SQL query in the *.hbm.xml file. It's a good idea to externalize your native SQL queries, if possible, to aid in migrating your application to new or updated databases.
Hibernate requires you to wrap references to aliases in your native SQL in braces. So, instead of writing SELECT cat.* FROM CAT AS cat WHERE ROWNUM<10, you must write SELECT {cat.*} FROM CAT AS {cat} WHERE ROWNUM<10.
Your native SQL queries may contain named and positional parameters, just like HQL. You will want to use a return tag to specify the class to which the returned data should be mapped, and you'll want to specify the referenced table using the synchronize tag if you wish to use a cache (see the cache tag for more information on using a cache with Hibernate).
For more information on using a sql-query (including an example of the code used to retrieve and execute a sql-query), see the tag query.
See the query tag, name attribute for more information.
A subclass is used to define a single-table object hierarchy in Hibernate. For more information, see Chapter 7. You can declare subclasses in their own *.hbm.xml file directly inside the hibernate-mapping. If you wish to do this, make sure that you specify the subclass's superclass using the extends attribute (see below).
Only the following tags may be present. Note that you can include a subclass inside another subclass, allowing for potentially very deep hierarchies.
| Optional, one or more. |
| May be included in any order. |
| Optional, one or more. |
You might decide that the full class name for the discriminator column is inefficient. If so, you might, for example, set the discriminator-value attribute for com.example .Animal to A, com.example.Bird to B, and com.example.Cat to C. Then the contents of the discriminator column, as shown above, would merely be A, C, and B.
For more information, see the class tag, discriminator-value attribute.
A true/false attribute. For more information, see the class tag, dynamic-update attribute.
A true/false attribute. For more information, see the class tag, dynamic-update attribute.
This attribute allows you to declare a subclass in an independent *.hbm.xml file. For example, you might wish to declare com.example.Animal, com.example.Bird and com.example .Cat in their own *.hbm.xml files. You would therefore set extends="com.example.Animal" for the subclass declaration of com.example.Bird and com.example.Cat.
If you make use of this feature, be sure to declare the parent classes first when importing your *.hbm.xml files (in other words, make sure that Hibernate has loaded the Animal.hbm.xml file before loading the Bird.hbm.xml and Cat.hbm.xml files).
A true/false attribute. For more information, see the class tag, lazy attribute.
For more information, see the class tag, persister attribute.
For more information, see the class tag, proxy attribute.
The synchronize tag is only used when nested inside a sql-query tag. It is used to indicate the table that should be considered when you attempt to cache the result set (for example, if sql-query retrieves data from the Cat table, you'd want to use this tag to specify the Cat table so the cache will know to invalidate the results if the Cat table is altered).
See the sql-query tag for more information.
If you wish to use optimistic locking, you need to specify either a timestamp tag or a version tag to indicate the record version. You can access the timestamp property just as you would access any other property.
A timestamp tag is not used to store arbitrary time and data in a record, only in conjunction with optimistic locking. For more information on optimistic locking, see the tag class, attribute optimistic-locking and Chapter 9. If you wish to store timestamp data, such as a user's birthday, use the property tag instead.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
Possible values are null, negative, and undefined. The value used to distinguish a newly created or unloaded object from an object previously loaded. The default, undefined, means that the identifier property is used instead (see the tag id for more information).
If you wish to use optimistic locking, you need to specify either a version tag or a timestamp tag to indicate the record version. You can access a version property just as you would access any other property.
For more information on optimistic locking, see the timestamp tag and Chapter 9.
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
The type of the column. The only supported types for this attribute when used with this tag are long, integer, short, timestamp, and calendar. For more information, see the tag property, attribute type.
Possible values are null, negative, and undefined. The value used to distinguish a newly created or unloaded object from an object previously loaded. The default, undefined, means that the identifier property is used instead (see the tag id for more information).