Mapping File Reference
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.
any
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.
Used By
class, subclass, joined-subclass, component, dynamic-component, composite-element, nested-composite-element
Contents
meta | Optionally, one or more meta tags. | meta-value | Optionally, one or more tags. Only needed if you specify a meta-type attribute other than class. | column | A minimum of two column tags are required (and possibly more for a composite identifier). The first column effectively serves as the discriminator (see the subclass tag for a detailed description of the use and purpose of a discriminator). The second (and other) columns store the identifier. |
Required Attributes
id-type
The type of the identifier (in other words, the type of the second and later columns).
name
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Optional Attributes
access (optional, defaults to property)
Possible values are field, property, or a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
cascade (optional, defaults to none)
Possible values are none, all, save-update, or delete. For more information, see the many-to-one tag, cascade attribute.
meta-type (optional, defaults to class)
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.
array
An array is a basic element in the Java programming languageyou 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 loadedit must be loaded as part of the containing object.
Used By
class, subclass, joined-subclass, component, dynamic-component
Contents
meta | Optionally, one or more meta-tags. | cache | Optional, one tag only. | key | A single key tag must be specified. | index | Required. For lists, this column contains sequential integers numbered from zero. | element | one-to-many | many-to-many | composite-element | many-to-any | A single relationship tag must be specified. For more information, see the appropriate tag and Chapter 7. |
Required Attributes
name
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Optional Attributes
access (defaults to property)
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
table (defaults to name value)
Use this attribute to specify the table for the collection data.
schema (defaults to none)
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute in hibernate-mapping for more information).
cascade (defaults to none)
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.
inverse (defaults to false)
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.
order-by (defaults to none)
Typically, this will be one or more column_name asc or column_name desc strings, expressed as SQL (not HQL).
where (defaults to none)
Use this attribute to specify an arbitrary SQL WHERE condition to be used when retrieving or deleting data for the collection.
batch-size (defaults to 1)
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
outer-join (defaults to auto)
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
check (defaults to none)
Used only during schema generation/update. For more information, see the check attribute of the column tag.
element-class
Used to specify the fully qualified class name for the type of the objects in the array.
bag
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.
Used By
class, subclass, joined-subclass, component, dynamic-component
Contents
meta | Optionally, one or more meta-tags. | cache | Optional, one only. | key | A single key tag must be specified. | element | one-to-many | many-to-many | composite-element | many-to-any | A single relationship tag must be specified. |
Required Attributes
name
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Optional Attributes
access (defaults to property)
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
batch size (defaults to 1)
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
cascade (defaults to none)
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.
check (defaults to none)
Used only during schema generation/update. For more information, see the check attribute of the column tag.
inverse (defaults to false)
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.
lazy (defaults to false)
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.
order-by (defaults to none)
Typically, this will be one or more column_name asc or column_name desc strings, expressed as SQL (not HQL).
outer-join (defaults to auto)
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
table (defaults to name value)
Use this attribute to specify the table for the collection data.
schema (defaults to none)
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute in hibernate-mapping for more information).
where (defaults to none)
Use this attribute to specify an arbitrary SQL WHERE condition to be used when retrieving or deleting data for the collection.
cache
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.
Contents
A cache tag has no content or nested tags.
Used By
class, map, set, bag, idbag, list, array, primitive-array
Required Attributes
usage
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.
class
This is the basic declaration of a mapping file. Conceptually, each class tag describes a table, with a wide variety of options.
Used By
hibernate-mapping
Contents
A class only contains nested tags. The tags should appear in the following order:
meta | Optional. One or more tags. | cache | Optional. One tag only. | id | composite-id | One or the other is required (but not both). | discriminator | 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. | version | timestamp | 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. | property | many-to-one | one-to-one | component | dynamic-component | any | map | set | list |bag | idbag | array | primitive-array | All of these are optional, and they can appear in any order, as needed. | subclass | joined-subclass | Optional. You can declare one or more subclasses OR one or more joined-subclasses, but you can't mix the use of subclass and joined-subclass in a single class declaration. Requires a discriminator attribute. |
Required Attributes
name
The fully qualified class name. For example, com.example.Order.
Optional Attributes
batch-size (defaults to 1)
The number of objects to be retrieved in a single fetch from the database.
check (defaults to none)
This attribute is only used during schema generation. For more information, see the column tag, check attribute.
discriminator-value (defaults to fully qualified class name)
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".
dynamic-insert (defaults to false)
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.
dynamic-update (defaults to false)
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).
lazy (defaults to false)
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.
mutable (defaults to true)
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.
optimistic-lock (defaults to version)
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.
persister (defaults to Hibernate internal)
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.
polymorphism (defaults to implicit)
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.
proxy (defaults to none)
Normally, you won't need this attributejust use the lazy="true" attribute instead.
|
Hibernate allows you to perform lazy data retrieval using proxy objects. For example, let's say that you are defining a class for a weblog (com.example.Weblog). You may not always want to retrieve all of the associated weblog posts (com.example.Post) every time you retrieve the weblog. By declaring a proxy, a proxy object (com.example.UnloadedPost) is returned instead when you retrieve a Weblog. Using the CGLIB library, Hibernate automatically enhances the com.example.Weblog to seamlessly replace the com.example.UnloadedPost when the posts are requested by a client using the com.example.Weblog object.
In practice you will rarely use this attribute and will instead simply use the lazy attribute. You'll only need to consider the proxy attribute (and worry about writing your own implementation) if for some reason you feel you require greater control over lazy-loaded objects. Before considering this approach, make sure that you understand how to use mapping files and queries to control loading of objects (see Chapter 8). |
schema (defaults to none)
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute in hibernate-mapping for more information).
select-before-update (defaults to false)
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.
table (defaults to unqualified name)
Use this to specify the table mapped to this class. By default, this will be the unqualified class name. For example, if the name is specified as com.example.Order, the default table name would be Order.
where (defaults to none)
Allows you to specify an arbitrary SQL WHERE clause when retrieving an object.
collection-id
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.
Used By
idbag
Contents
meta | Optionally, one or more meta-tags. | column | Optionally, one or more column tags may be specified. | generator | A single generator tag is required. |
Required Attributes
column
The name of the database column.
type
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.
Optional Attributes
length (defaults to 255)
Used when Hibernate is asked to generate or update the schema. For more information, see the property tag, length attribute.
column
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.
Used By
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
Contents
A column tag has no content or nested tags.
Required Attributes
name
The name of the column.
Optional Attributes
check (defaults to none)
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.
index (defaults to none)
Used during schema update and generation, this attribute can specify the name of a multi-column index.
length (defaults to 255)
Used when Hibernate is asked to generate or update the schema. For more information, see the property tag, length attribute.
not-null (defaults to false unless in an id)
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.
sql-type (defaults to value specified by the parent tag)
Use this attribute to specify a specific SQL type to be used when generating or updating this column.
unique (defaults to false unless in an id)
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.
unique-key (defaults to none)
Only used during schema update and generation. Used to specify the name of a multi-column unique constraint.
component
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.
Used By
class, subclass, joined-subclass, component, dynamic-component
Contents
meta | Optionally, one or more meta-tags. | parent | 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. | property | many-to-one | one-to-one | component | dynamic-component | any | map |set | list | bag | idbag | array | primitive-array | May be included in any order. |
Required Attributes
name
The name of the component. Unlike a property, you should use an initial uppercase character, because the component will be mapped to a class.
Optional Attributes
access (defaults to property)
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
class
Specify the fully qualified class name for the class of this component.
insert (defaults to true)
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.
update (defaults to true)
If set to false, this component will be ignored when a SQL UPDATE is issued for this class. This can only be specified for the component as a whole, not the properties of the component.
composite-element
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).
Used By
map, set, bag, idbag, list, array
Contents
parent | 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. | property | many-to-one | any | nested-composite-element | One or more of these may be specified. |
Required Attributes
class
The name of the class to be used to wrap the properties.
composite-id
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.
|
I must confess that I have never needed to use a composite-id. A synthetic long or GUID identifier (see the generator tag for more information) has always worked quite well for me; it generally outperforms a composite-id and is easier to work with. The obvious exception is for collection tables (as described in more detail in Chapter 7), but in Hibernate these are typically modeled implicitly using collection tags, not explicitly as composites. |
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().
Used By
class
Contents
meta | Optional, one or more. | key-property | key-many-to-one | At least one of these required. |
Optional Attributes
access (defaults to property)
See the tag class, attribute default-access for more information.
class (optional unless a name and unsaved-value also specified)
Specifies the class (used as a component) to represent the identifier.
name (optional unless a name and unsaved-value also specified)
Specifies the property name for the class.
unsaved-value (defaults to none)
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.
composite-index
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.
Used By
`map
Contents
A composite-index must contain at least one (and optionally more) key-property and/or key-many-to-one tags.
Required Attributes
class
The fully qualified name of the target component class.
discriminator
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.
Used By
class
Contents
Normally, no contents, although a column tag may be used instead of the column attributes.
Optional Attributes
column (defaults to class)
Name of the column to be used to store the discriminator.
force (defaults to false)
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 (defaults to 255)
Length of the column. For more information, see the tag property, attribute length.
not-null (defaults to true)
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 (defaults to string)
Type of the column to be used. For more information, see the tag property, attribute class.
dynamic-component
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.
Used By
class, subclass, joined-subclass, component, dynamic-component
Contents
property | many-to-one | one-to-one | component | dynamic-component | any | map | set | list | bag | array | primitive-array | Any of these tags may be may be included in any order. |
Required Attributes
name (required)
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Optional Attributes
access (defaults to property)
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
update (defaults to true)
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).
insert (defaults to true)
If set to false, this property/column will be ignored when a SQL INSERT is issued for this component. This is only usable for properties of a class (not a component tag).
element
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 classit'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.
Used By
map, set, bag, idbag, list, array, primitive-array
Contents
An element (much like a property) can optionally contain one or more column tags.
Required Attributes
Type
The type attribute can be set according to the following rules, as described in the property tag sidebar, Hibernate Supported Data Types.
Optional Attributes
column
The name of the database column.
length
Used when Hibernate is asked to generate or update the schema. For more information, see the property tag, length attribute.
not-null (defaults to false)
A TRue/false attribute. For more information, see the property tag, not-null attribute.
unique (defaults to false)
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.
generator
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.
Used By
id, collection-id
Contents
param | Depending on the class you specify as a generator, you may need to pass one or more param tags to properly configure the class. |
Required Attributes
class
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.
hibernate-mapping
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.
Contents
You are only allowed to include the following tags in the order shown. You may include as many of each tag as you need.
meta | Zero, one, or more tags. | import | Zero, one, or more tags. | class, subclass, joined-subclass | 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. | query | Used to externalize a HQL query in the mapping file (as opposed to in your Java code). See Chapter 8 for more information. | sql-query | Used to externalize a SQL query in the mapping file (as opposed to in your Java code). See Chapter 8 for more information. |
Optional Attributes
auto-import (defaults to true)
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 packageobviously, 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.
default-access (defaults to property)
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.
default-cascade (defaults to none)
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.
package (default to none)
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.
schema (defaults to none)
This attribute is used to specify a specific schema name. This functionality should be considered database-specific.
id
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 Java Virtual Machine keeps track of objects using a identifier (loosely analogous to a handle). This is completely different from, and should not be confused with, the id expressed in the database.
For more information on this topic, see Chapter 6. |
The main purpose of an id tag is to specify the column and method to be used for generating a new identifiera generator tag. For more information on the strategies available for generating identifiers, see the generator tag.
Used By
class
Contents
May only contain the following tags, in this order.
meta | Optional, one or more. | column | Optional, use this tag in lieu of the equivalent attributes. | generator | Required. |
Optional Attributes
access (defaults to property)
Possible values are field, property, and a fully qualified class name. See hibernate-mapping tag, default-access for more information on this attribute.
column (defaults to name attribute value)
Specify the name of the primary key column.
length
See the tag property, attribute type.
name
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.
type
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.
unsaved-value (optional, defaults to null)
Possible values include any, none, null, or an arbitrary constant value. Make sure that the default here is the same as the default value in your Java code for an object created with a no-argument constructor.
idbag
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 columnyou 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.
Used By
class, subclass, joined-subclass, component, dynamic-component
Contents
meta | Optionally, one or more meta-tags. | cache | Optional, one tag only. | collection-id | Required, allows you to specify a generator for the primary key. | key | A single key tag must be specified. | element | many-to-many | composite-element | many-to-any | A single relationship tag must be specified. |
Required Attributes
name
The name of the property. Use an initial lowercase character. For more information, see the property tag, name attribute.
Optional Attributes
access (defaults to property)
Possible values are field, property, and a fully qualified class name. See the tag hibernate-mapping, attribute default-access for more information.
batch-size (defaults to 1)
This allows you to specify the number of elements to be retrieved when data is retrieved via lazy instantiation.
cascade (defaults to none)
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.
check (defaults to none)
Used only during schema generation/update. For more information, see the check attribute of the column tag.
lazy (defaults to false)
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.
order-by (defaults to none)
Typically, this will be one or more column_name asc or column_name desc strings, expressed as SQL (not HQL).
outer-join (defaults to auto)
Possible values are true, false, or auto. For more information, see the tag many-to-one, attribute outer-join.
schema (defaults to none)
Used to specify the schema name. Overrides the hibernate-mapping setting (see the schema attribute of the hibernate-mapping tag for more information).
table (defaults to name value)
Use this attribute to specify the table the collection data this element maps against.
where (defaults to none)
Use this attribute to specify an arbitrary SQL WHERE condition to be used when retrieving or deleting data for the collection.
import
This tag serves three important functionsit 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.
Used By
hibernate-mapping
Contents
None.
Required Attributes
class
The original, fully qualified class name.
Optional Attributes
rename (defaults to the qualified name)
This optional attribute lets you specify a different class name (and is really needed only if you import two classes distinguished solely by package name).
index
Declares the type and column for a collection index. For more information, see the appropriate collection tag.
Used By
map, list, array, primitive-array
Contents
An index (much like a property) can optionally contain one or more column tags.
Optional Attributes
column
The name of the database column. Optional if specified with a column tag, but required if no column tag specified.
length
Used when Hibernate is asked to generate or update the schema. For more information, see the property tag, length attribute.
type (required for maps)
Required if an index is used in a map. For information on the type attribute, see the property tag, type attribute.
index-many-to-any
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 mapan unusual and complex mapping.
For more information, see the index and any tags.
Used By
map
Contents
column | The first declared column is used as the discriminator (see the discriminator tag for more information). | column | At least one, and possibly more, additional column tags are used as foreign keys. |
Required Attributes
id-type (required)
The type of the identifier (in other words, the type of the second and later columns).
Optional Attributes
meta-type (defaults to class)
The type of the discriminator (in other words, the type of the first column). For more information, see the any tag, meta-type attribute.
index-many-to-many
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).
Used By
map
Contents
An index-many-to-many (much like a property) can optionally contain one or more column tags.
Required Attributes
class (required)
The fully qualified name of the target class.
Optional Attributes
column (required if no column tag)
The name of the database column. Optional if specified with a column tag, but required if no column tag is specified.
foreign-key (defaults to none)
Used only during schema export and update. For more information, see the many-to-one tag, foreign-key attribute.
joined-subclass
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 tagyou 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).
Used By
class, subclass, hibernate-mapping
Contents
The following tags are allowed (or required):
meta | Optional, one or more. | key | Required to specify the primary key. | property | many-to-one | one-to-one | component | dynamic-component | any | map | set | list | bag | idbag | array | primitive-array | As many as required, in the order desired. | joined-subclass | You can nest additional joined-subclasses if desired. |
Required Attributes
name
Specify the fully qualified class name of the subclass.
Optional Attributes
check (defaults to none)
For more information, see the tag column, attribute check.
dynamic-insert (defaults to false)
For more information, see the class tag, dynamic-insert attribute.
dynamic-update (defaults to false)
For more information, see the class tag, dynamic-update attribute.
extends (defaults to parent class/subclass)
For more information, see the subclass tag, extends attribute.
lazy (defaults to false)
For more information, see the class tag, lazy attribute.
persister (defaults to Hibernate internal)
For more information, see the class tag, persister attribute.
proxy (defaults to none)
For more information, see the class tag, proxy attribute.
schema (defaults to none)
For more information, see the class tag, schema attribute.
table (defaults to unqualified class name)
Use this to specify the table mapped to by this class. By default, this will be the unqualified class name. For example, if the name is specified as com.example.Cat, the default table name is Cat.
key
Use this to declare a foreign key for tags that require it. For more information, see the requiring tag.
Used By
joined-subclass, map, set, bag, idbag, list, array, primitive-array
Contents
A key (much like a property) can optionally contain one or more column tags.
Optional Attributes
column (required if no column tag)
The name of the database column. Optional if specified with a column tag instead, but required if no column tag specified.
foreign-key (defaults to none)
Used only during schema export and update. For more information, see the many-to-one tag, foreign-key attribute.
key-many-to-one
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.
Used By
composite-id, composite-index
| 
