5.1.9. property

5.1.9. property

The <property> element declares a persistent, JavaBean style property of the class.

<property
        name="propertyName"
        column="column_name"
        type="typename"
        update="true|false"
        insert="true|false"
        formula="arbitrary SQL expression"
        access="field|property|ClassName"
        lazy="true|false"
        unique="true|false"
        not-null="true|false"
        optimistic-lock="true|false"
        generated="never|insert|always"
        node="element-name|@attribute-name|element/@attribute|."
        index="index_name"
        unique_key="unique_key_id"
        length="L"
        precision="P"
        scale="S"
/>

name: the name of the property, with an initial lowercase letter.

column (optional - defaults to the property name): the name of the mapped database table column. This may also be specified by nested <column> element(s).

type (optional): a name that indicates the Hibernate type.

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" property whose value is initialized from some other property that maps to the same colum(s) or by a trigger or other application.

formula (optional): an SQL expression that defines the value for a computed property. Computed properties do not have a column mapping of their own.

access (optional - defaults to property): The strategy Hibernate should use for accessing the property value.

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).

unique (optional): Enable the DDL generation of a unique constraint for the columns. Also, allow this to be the target of a property-ref.

not-null (optional): Enable the DDL generation of a nullability constraint for the columns.

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, determines if a version increment should occur when this property is dirty.

generated (optional - defaults to never): Specifies that this property value is actually generated by the database. See the discussion of Section 5.6, “Generated Properties” generated properties.

typename could be:

  1. The name of a Hibernate basic type (eg. integer, string, character, date, timestamp, float, binary, serializable, object, blob).

  2. The name of a Java class with a default basic type (eg. int, float, char, java.lang.String, java.util.Date, java.lang.Integer, java.sql.Clob).

  3. The name of a serializable Java class.

  4. The class name of a custom type (eg. com.illflow.type.MyCustomType).

If you do not specify a type, Hibernate will use reflection upon the named property to take a guess at the correct Hibernate type. Hibernate will try to interpret the name of the return class of the property getter using rules 2, 3, 4 in that order. However, this is not always enough. In certain cases you will still need the type attribute. (For example, to distinguish between Hibernate.DATE and Hibernate.TIMESTAMP, or to specify a custom type.)

The access attribute lets you control how Hibernate will access the property at runtime. By default, Hibernate will call the property get/set pair. If you specify access="field", Hibernate will bypass the get/set pair and access the field directly, using reflection. You may specify your own strategy for property access by naming a class that implements the interface org.hibernate.property.PropertyAccessor.

An especially powerful feature are derived properties. These properties are by definition read-only, the property value is computed at load time. You declare the computation as a SQL expression, this translates to a SELECT clause subquery in the SQL query that loads an instance:

<property name="totalPrice"
    formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p
                WHERE li.productId = p.productId
                AND li.customerId = customerId
                AND li.orderNumber = orderNumber )"/>

Note that you can reference the entities own table by not declaring an alias on a particular column (customerId in the given example). Also note that you can use the nested <formula> mapping element if you don't like to use the attribute.