Hibernate Element Reference
From Javapedia
Contents |
[edit] <hibernate-mapping> element
The root element of hibernate mapping document is <hibernate-mapping> element. This element has several optional attributes. The schema and catalog attributes specify that tables referred to in this mapping belong to the named schema and/or catalog. If specified, tablenames will be qualified by the given schema and catalog names. If missing, tablenames will be unqualified. The default-cascade attribute specifies what cascade style should be assumed for properties and Collections which do not specify a cascade attribute. The auto-import attribute lets us use unqualified class names in the query language, by default.
<hibernate-mapping
schema="schemaName"
catalog="catalogName"
default-cascade="cascade_style"
default-access="field|property|ClassName"
default-lazy="true|false"
auto-import="true|false"
package="package.name"
/>
(1) schema (optional): The name of a database schema. (2) catalog (optional): The name of a database catalog. (3) default-cascade (optional - defaults to none): A default cascade style. (4) default-access (optional - defaults to property): The strategy Hibernate should use for accessing all properties. Can be a custom implementation of PropertyAccessor. (5) default-lazy (optional - defaults to true): The default value for unspecifed lazy attributes of class and collection mappings. (6) auto-import (optional - defaults to true): Specifies whether we can use unqualified class names (of classes in this mapping) in the query language. (7) package (optional): Specifies a package prefix to assume for unqualified class names in the mapping document.
[edit] <class> element
The <Class> element maps the domain object with corresponding entity in the database. hibernate-mapping element allows you to nest several persistent <class> mappings, as shown above. It is however good practice to map only a single persistent class in one mapping file and name it after the persistent superclass, e.g. User.hbm.xml, Group.hbm.xml.
<class
name="ClassName"
table="tableName" discriminator-value="discriminator_value" mutable="true|false" schema="owner" catalog="catalog" proxy="ProxyInterface" dynamic-update="true|false" dynamic-insert="true|false" select-before-update="true|false" polymorphism="implicit|explicit" where="arbitrary sql where condition" persister="PersisterClass" batch-size="N" optimistic-lock="none|version|dirty|all" lazy="true|false" entity-name="EntityName" catalog="catalog" check="arbitrary sql check condition" rowid="rowid" subselect="SQL expression" abstract="true|false" />
(1) name (optional): The fully qualified Java class name of the persistent class (or interface). If this attribute is missing, it is assumed that the mapping is for a non-POJO entity. (2) table (optional - defaults to the unqualified class name): The name of its database table. (3) discriminator-value (optional - defaults to the class name): A value that distiguishes individual subclasses, used for polymorphic behaviour. Acceptable values include null and not null. (4) mutable (optional, defaults to true): Specifies that instances of the class are (not) mutable. (5) schema (optional): Override the schema name specified by the root <hibernate-mapping> element. (6) catalog (optional): Override the catalog name specified by the root <hibernate-mapping> element. (7) proxy (optional): Specifies an interface to use for lazy initializing proxies. You may specify the name of the class itself. (8) dynamic-update (optional, defaults to false): Specifies that UPDATE SQL should be generated at runtime and contain only those columns whose values have changed. (9) dynamic-insert (optional, defaults to false): Specifies that INSERT SQL should be generated at runtime and contain only the columns whose values are not null. (10) select-before-update (optional, defaults to false): Specifies that Hibernate should never perform an SQL UPDATE unless it is certain that an object is actually modified. In certain cases (actually, only when a transient object has been associated with a new session using update()), this means that Hibernate will perform an extra SQL SELECT to determine if an UPDATE is actually required. (11) polymorphism (optional, defaults to implicit): Determines whether implicit or explicit query polymorphism is used. (12) where (optional) specify an arbitrary SQL WHERE condition to be used when retrieving objects of this class (13) persister (optional): Specifies a custom ClassPersister. (14) batch-size (optional, defaults to 1) specify a "batch size" for fetching instances of this class by identifier. (15) optimistic-lock (optional, defaults to version): Determines the optimistic locking strategy. (16) lazy (optional): Lazy fetching may be completely disabled by setting lazy="false". (17) entity-name (optional): Hibernate3 allows a class to be mapped multiple times (to different tables, potentially), and allows entity mappings that are represented by Maps or XML at the java level. In these cases, you should provide an explicit arbitrary name for the entity. See Section 4.4, “Dynamic models” for more information. (18) catalog (optional): The name of a database catalog used for this class and its table. (19) check (optional): A SQL expression used to generate a multi-row check constraint for automatic schema generation. (20) rowid (optional): Hibernate can use so called ROWIDs on databases which support. E.g. on Oracle, Hibernate can use the rowid extra column for fast updates if you set this option to rowid. A ROWID is an implementation detail and represents the physical location of a stored tuple. (21) subselect (optional): Maps an immutable and read-only entity to a database subselect. Useful if you want to have a view instead of a base table, but don't. See below for more information. (22) abstract (optional): Used to mark abstract superclasses in <union-subclass> hierarchies.
[edit] <id> element
The <id> element defines the mapping from that property to the primary key column. Mapped classes must declare the primary key column of the database table. Most classes will also have a JavaBeans-style property holding the unique identifier of an instance.
<id
name="propertyName"
type="typename"
column="column_name"
unsaved-value="null|any|none|undefined|id_value"
access="field|property|ClassName">
<generator class="generatorClass"/>
/>
(1) name (optional): The name of the identifier property. (2) type (optional): A name that indicates the Hibernate type. (3) column (optional - defaults to the property name): The name of the primary key column. (4) unsaved-value (optional - defaults to a "sensible" value): An identifier property value that indicates that an instance is newly instantiated (unsaved), distinguishing it from detached instances that were saved or loaded in a previous session. (5) access (optional - defaults to property): The strategy Hibernate should use for accessing the property value.
[edit] <many-to-one> element
An ordinary association to another persistent class is declared using a many-to-one element. The relational model is a many-to-one association: a foreign key in one table is referencing the primary key column(s) of the target table.
<many-to-one
name="propertyName"
column="column_name"
class="ClassName"
cascade="cascade_style"
fetch="join|select"
update="true|false"
insert="true|false"
property-ref="propertyNameFromAssociatedClass"
access="field|property|ClassName"
unique="true|false"
not-null="true|false"
optimistic-lock="true|false"
lazy="true|false"
entity-name="EntityName"
/>
(1) name: The name of the property. (2) column (optional): The name of the foreign key column. This may also be specified by nested <column> element(s). (3) class (optional - defaults to the property type determined by reflection): The name of the associated class. (4) cascade (optional): Specifies which operations should be cascaded from the parent object to the associated object. (5) join (optional - defaults to select): Chooses between outer-join fetching or sequential select fetching. (6) update, insert (optional - defaults to true) specifies that the mapped columns should be included in SQL UPDATE and/or INSERT statements. Setting both to false allows a pure "derived" association whose value is initialized from some other property that maps to the same colum(s) or by a trigger or other application. (7) property-ref: (optional) The name of a property of the associated class that is joined to this foreign key. If not specified, the primary key of the associated class is used. (8) access (optional - defaults to property): The strategy Hibernate should use for accessing the property value. (9) unique (optional): Enable the DDL generation of a unique constraint for the foreign-key column. Also, allow this to be the target of a property-ref. This makes the association multiplicity effectively one to one. (10) not-null (optional): Enable the DDL generation of a nullability constraint for the foreign key columns. (11) optimistic-lock (optional - defaults to true): Specifies that updates to this property do or do not require acquisition of the optimistic lock. In other words, dertermines if a version increment should occur when this property is dirty. (12) lazy (optional - defaults to false): Specifies that this property should be fetched lazily when the instance variable is first accessed (requires build-time bytecode instrumentation).
A typical many-to-one declaration looks as simple as this:
<many-to-one name="product" class="Product" column="PRODUCT_ID"/>
[edit] <one-to-one> element
A one-to-one association to another persistent class is declared using a one-to-one element. .
<one-to-one
name="propertyName" (1)
class="ClassName" (2)
cascade="cascade_style" (3)
constrained="true|false" (4)
fetch="join|select" (5)
property-ref="propertyNameFromAssociatedClass" (6)
access="field|property|ClassName" (7)
formula="any SQL expression" (8)
entity-name="EntityName"
/>
(1) name: The name of the property. (2) class (optional - defaults to the property type determined by reflection): The name of the associated class. (3) cascade (optional) specifies which operations should be cascaded from the parent object to the associated object. (4) constrained (optional) 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 save() and delete() are cascaded, and determines whether the association may be proxied (it is also used by the schema export tool). (5) fetch (optional - defaults to select): Chooses between outer-join fetching or sequential select fetching. (6) property-ref: (optional) The name of a property of the associated class that is joined to the primary key of this class. If not specified, the primary key of the associated class is used. (7) access (optional - defaults to property): The strategy Hibernate should use for accessing the property value. (8) formula (optional): Almost all one to one associations map to the primary key of the owning entity. In the rare case that this is not the case, you may specify a some other column, columns or expression to join on using an SQL formula. (See org.hibernate.test.onetooneformula for an example.)
A typical many-to-one declaration looks as simple as this:
<many-to-one name="product" class="Product" column="PRODUCT_ID"/>
