diff --git a/documentation/envers/src/main/docbook/en-US/content/architecture.xml b/documentation/envers/src/main/docbook/en-US/content/architecture.xml deleted file mode 100644 index 414f84b4ca..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/architecture.xml +++ /dev/null @@ -1,382 +0,0 @@ - - - - - - - - Architecture - - - Overview - - - A (very) high-level view of the Hibernate architecture: - - - - - - - - - - - - - This diagram shows Hibernate using the database and configuration data to - provide persistence services (and persistent objects) to the application. - - - - We would like to show a more detailed view of the runtime architecture. - Unfortunately, Hibernate is flexible and supports several approaches. We will - show the two extremes. The "lite" architecture has the application - provide its own JDBC connections and manage its own transactions. This approach - uses a minimal subset of Hibernate's APIs: - - - - - - - - - - - - - The "full cream" architecture abstracts the application away from the - underlying JDBC/JTA APIs and lets Hibernate take care of the details. - - - - - - - - - - - - - Heres some definitions of the objects in the diagrams: - - - - SessionFactory (org.hibernate.SessionFactory) - - - A threadsafe (immutable) cache of compiled mappings for a single database. - A factory for Session and a client of - ConnectionProvider. Might hold an optional (second-level) - cache of data that is reusable between transactions, at a - process- or cluster-level. - - - - - Session (org.hibernate.Session) - - - A single-threaded, short-lived object representing a conversation between - the application and the persistent store. Wraps a JDBC connection. Factory - for Transaction. Holds a mandatory (first-level) cache - of persistent objects, used when navigating the object graph or looking up - objects by identifier. - - - - - Persistent objects and collections - - - Short-lived, single threaded objects containing persistent state and business - function. These might be ordinary JavaBeans/POJOs, the only special thing about - them is that they are currently associated with (exactly one) - Session. As soon as the Session is closed, - they will be detached and free to use in any application layer (e.g. directly - as data transfer objects to and from presentation). - - - - - Transient and detached objects and collections - - - Instances of persistent classes that are not currently associated with a - Session. They may have been instantiated by - the application and not (yet) persisted or they may have been instantiated by a - closed Session. - - - - - Transaction (org.hibernate.Transaction) - - - (Optional) A single-threaded, short-lived object used by the application to - specify atomic units of work. Abstracts application from underlying JDBC, - JTA or CORBA transaction. A Session might span several - Transactions in some cases. However, transaction demarcation, - either using the underlying API or Transaction, is never - optional! - - - - - ConnectionProvider (org.hibernate.connection.ConnectionProvider) - - - (Optional) A factory for (and pool of) JDBC connections. Abstracts application from - underlying Datasource or DriverManager. - Not exposed to application, but can be extended/implemented by the developer. - - - - - TransactionFactory (org.hibernate.TransactionFactory) - - - (Optional) A factory for Transaction instances. Not exposed to the - application, but can be extended/implemented by the developer. - - - - - Extension Interfaces - - - Hibernate offers many optional extension interfaces you can implement to customize - the behavior of your persistence layer. See the API documentation for details. - - - - - - - - Given a "lite" architecture, the application bypasses the - Transaction/TransactionFactory and/or - ConnectionProvider APIs to talk to JTA or JDBC directly. - - - - - Instance states - - An instance of a persistent classes may be in one of three different states, - which are defined with respect to a persistence context. - The Hibernate Session object is the persistence context: - - - - - transient - - - The instance is not, and has never been associated with - any persistence context. It has no persistent identity - (primary key value). - - - - - persistent - - - The instance is currently associated with a persistence - context. It has a persistent identity (primary key value) - and, perhaps, a corresponding row in the database. For a - particular persistence context, Hibernate - guarantees that persistent identity - is equivalent to Java identity (in-memory location of the - object). - - - - - detached - - - The instance was once associated with a persistence - context, but that context was closed, or the instance - was serialized to another process. It has a persistent - identity and, perhaps, a corresponding row in the database. - For detached instances, Hibernate makes no guarantees - about the relationship between persistent identity and - Java identity. - - - - - - - - JMX Integration - - - JMX is the J2EE standard for management of Java components. Hibernate may be managed via - a JMX standard service. We provide an MBean implementation in the distribution, - org.hibernate.jmx.HibernateService. - - - - For an example how to deploy Hibernate as a JMX service on the JBoss Application Server, - please see the JBoss User Guide. On JBoss AS, you also get these benefits if you deploy - using JMX: - - - - - - Session Management: The Hibernate Session's life cycle - can be automatically bound to the scope of a JTA transaction. This means you no - longer have to manually open and close the Session, this - becomes the job of a JBoss EJB interceptor. You also don't have to worry about - transaction demarcation in your code anymore (unless you'd like to write a portable - persistence layer of course, use the optional Hibernate Transaction - API for this). You call the HibernateContext to access a - Session. - - - - - HAR deployment: Usually you deploy the Hibernate JMX service using a JBoss - service deployment descriptor (in an EAR and/or SAR file), it supports all the usual - configuration options of a Hibernate SessionFactory. However, you still - have to name all your mapping files in the deployment descriptor. If you decide to use - the optional HAR deployment, JBoss will automatically detect all mapping files in your - HAR file. - - - - - - Consult the JBoss AS user guide for more information about these options. - - - - Another feature available as a JMX service are runtime Hibernate statistics. See - . - - - - - JCA Support - - Hibernate may also be configured as a JCA connector. Please see the website for more - details. Please note that Hibernate JCA support is still considered experimental. - - - - - Contextual Sessions - - Most applications using Hibernate need some form of "contextual" sessions, where a given - session is in effect throughout the scope of a given context. However, across applications - the definition of what constitutes a context is typically different; and different contexts - define different scopes to the notion of current. Applications using Hibernate prior - to version 3.0 tended to utilize either home-grown ThreadLocal-based - contextual sessions, helper classes such as HibernateUtil, or utilized - third-party frameworks (such as Spring or Pico) which provided proxy/interception-based contextual sessions. - - - Starting with version 3.0.1, Hibernate added the SessionFactory.getCurrentSession() - method. Initially, this assumed usage of JTA transactions, where the - JTA transaction defined both the scope and context of a current session. - The Hibernate team maintains that, given the maturity of the numerous stand-alone - JTA TransactionManager implementations out there, most (if not all) - applications should be using JTA transaction management whether or not - they are deployed into a J2EE container. Based on that, the - JTA-based contextual sessions is all you should ever need to use. - - - However, as of version 3.1, the processing behind - SessionFactory.getCurrentSession() is now pluggable. To that - end, a new extension interface (org.hibernate.context.CurrentSessionContext) - and a new configuration parameter (hibernate.current_session_context_class) - have been added to allow pluggability of the scope and context of defining current sessions. - - - See the Javadocs for the org.hibernate.context.CurrentSessionContext - interface for a detailed discussion of its contract. It defines a single method, - currentSession(), by which the implementation is responsible for - tracking the current contextual session. Out-of-the-box, Hibernate comes with three - implementations of this interface. - - - - - - org.hibernate.context.JTASessionContext - current sessions - are tracked and scoped by a JTA transaction. The processing - here is exactly the same as in the older JTA-only approach. See the Javadocs - for details. - - - - - org.hibernate.context.ThreadLocalSessionContext - current - sessions are tracked by thread of execution. Again, see the Javadocs for details. - - - - - org.hibernate.context.ManagedSessionContext - current - sessions are tracked by thread of execution. However, you are responsible to - bind and unbind a Session instance with static methods - on this class, it does never open, flush, or close a Session. - - - - - - The first two implementations provide a "one session - one database transaction" programming - model, also known and used as session-per-request. The beginning - and end of a Hibernate session is defined by the duration of a database transaction. - If you use programmatic transaction demarcation in plain JSE without JTA, you are advised to - use the Hibernate Transaction API to hide the underlying transaction system - from your code. If you use JTA, use the JTA interfaces to demarcate transactions. If you - execute in an EJB container that supports CMT, transaction boundaries are defined declaratively - and you don't need any transaction or session demarcation operations in your code. - Refer to for more information and code examples. - - - - The hibernate.current_session_context_class configuration parameter - defines which org.hibernate.context.CurrentSessionContext implementation - should be used. Note that for backwards compatibility, if this config param is not set - but a org.hibernate.transaction.TransactionManagerLookup is configured, - Hibernate will use the org.hibernate.context.JTASessionContext. - Typically, the value of this parameter would just name the implementation class to - use; for the three out-of-the-box implementations, however, there are three corresponding - short names, "jta", "thread", and "managed". - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/association_mapping.xml b/documentation/envers/src/main/docbook/en-US/content/association_mapping.xml deleted file mode 100755 index e57d361d38..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/association_mapping.xml +++ /dev/null @@ -1,650 +0,0 @@ - - - - - - - - Association Mappings - - - Introduction - - - Association mappings are the often most difficult thing to get right. In - this section we'll go through the canonical cases one by one, starting - with unidirectional mappings, and then considering the bidirectional cases. - We'll use Person and Address in all - the examples. - - - - We'll classify associations by whether or not they map to an intervening - join table, and by multiplicity. - - - - Nullable foreign keys are not considered good practice in traditional data - modelling, so all our examples use not null foreign keys. This is not a - requirement of Hibernate, and the mappings will all work if you drop the - nullability constraints. - - - - - - Unidirectional associations - - - many to one - - - A unidirectional many-to-one association is the most - common kind of unidirectional association. - - - - - - - - - - - - - -]]> - - - - - - one to one - - - A unidirectional one-to-one association on a foreign key - is almost identical. The only difference is the column unique constraint. - - - - - - - - - - - - - -]]> - - - - A unidirectional one-to-one association on a primary key - usually uses a special id generator. (Notice that we've reversed the direction - of the association in this example.) - - - - - - - - - - - - person - - - -]]> - - - - - - one to many - - - A unidirectional one-to-many association on a foreign key - is a very unusual case, and is not really recommended. - - - - - - - - - - - - - - - - -]]> - - - - We think it's better to use a join table for this kind of association. - - - - - - - - Unidirectional associations with join tables - - - one to many - - - A unidirectional one-to-many association on a join table - is much preferred. Notice that by specifying unique="true", - we have changed the multiplicity from many-to-many to one-to-many. - - - - - - - - - - - - - - - - -]]> - - - - - - many to one - - - A unidirectional many-to-one association on a join table - is quite common when the association is optional. - - - - - - - - - - - - - - - - -]]> - - - - - - one to one - - - A unidirectional one-to-one association on a join table - is extremely unusual, but possible. - - - - - - - - - - - - - - - - -]]> - - - - - - many to many - - - Finally, we have a unidirectional many-to-many association. - - - - - - - - - - - - - - - - -]]> - - - - - - - - Bidirectional associations - - - one to many / many to one - - - A bidirectional many-to-one association is the - most common kind of association. (This is the standard parent/child - relationship.) - - - - - - - - - - - - - - - - - -]]> - - - - - If you use a List (or other indexed collection) you need - to set the key column of the foreign key to not null, - and let Hibernate manage the association from the collections side to maintain the index - of each element (making the other side virtually inverse by setting - update="false" and insert="false"): - - - - - ... - - - - - - ... - - - - - -]]> - - - It is important that you define not-null="true" on the - <key> element of the collection mapping if the - underlying foreign key column is NOT NULL. Don't only - declare not-null="true" on a possible nested - <column> element, but on the <key> - element. - - - - - - one to one - - - A bidirectional one-to-one association on a foreign key - is quite common. - - - - - - - - - - - - - - -]]> - - - - A bidirectional one-to-one association on a primary key - uses the special id generator. - - - - - - - - - - - - - person - - - -]]> - - - - - - - - Bidirectional associations with join tables - - - one to many / many to one - - - A bidirectional one-to-many association on a join table. - Note that the inverse="true" can go on either end of the - association, on the collection, or on the join. - - - - - - - - - - - - - - - - - - - - -]]> - - - - - - one to one - - - A bidirectional one-to-one association on a join table - is extremely unusual, but possible. - - - - - - - - - - - - - - - - - - - - -]]> - - - - - - many to many - - - Finally, we have a bidirectional many-to-many association. - - - - - - - - - - - - - - - - - - - - -]]> - - - - - - - - - More complex association mappings - - - More complex association joins are extremely rare. - Hibernate makes it possible to handle more complex situations using - SQL fragments embedded in the mapping document. For example, if a table - with historical account information data defines - accountNumber, effectiveEndDate - and effectiveStartDatecolumns, mapped as follows: - - - - - - case when effectiveEndDate is null then 1 else 0 end - - - -]]> - - - Then we can map an association to the current instance - (the one with null effectiveEndDate) using: - - - - - '1' -]]> - - - In a more complex example, imagine that the association between - Employee and Organization is maintained - in an Employment table full of historical employment data. - Then an association to the employee's most recent employer - (the one with the most recent startDate) might be mapped this way: - - - - - - select employeeId, orgId - from Employments - group by orgId - having startDate = max(startDate) - - -]]> - - - You can get quite creative with this functionality, but it is usually more practical - to handle these kinds of cases using HQL or a criteria query. - - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/basic_mapping.xml b/documentation/envers/src/main/docbook/en-US/content/basic_mapping.xml deleted file mode 100644 index 56fdc875f5..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/basic_mapping.xml +++ /dev/null @@ -1,3587 +0,0 @@ - - - - - - - Basic O/R Mapping - - - Mapping declaration - - - Object/relational mappings are usually defined in an XML document. The mapping - document is designed to be readable and hand-editable. The mapping language is - Java-centric, meaning that mappings are constructed around persistent class - declarations, not table declarations. - - - - Note that, even though many Hibernate users choose to write the XML by hand, - a number of tools exist to generate the mapping document, including XDoclet, - Middlegen and AndroMDA. - - - - Lets kick off with an example mapping: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - We will now discuss the content of the mapping document. We will only describe the - document elements and attributes that are used by Hibernate at runtime. The mapping - document also contains some extra optional attributes and elements that affect the - database schemas exported by the schema export tool. (For example the - not-null attribute.) - - - - - - Doctype - - - All XML mappings should declare the doctype shown. The actual DTD may be found - at the URL above, in the directory hibernate-x.x.x/src/org/hibernate - or in hibernate3.jar. Hibernate will always look for - the DTD in its classpath first. If you experience lookups of the DTD using an - Internet connection, check your DTD declaration against the contents of your - claspath. - - - - EntityResolver - - As mentioned previously, Hibernate will first attempt to resolve DTDs in its classpath. The - manner in which it does this is by registering a custom org.xml.sax.EntityResolver - implementation with the SAXReader it uses to read in the xml files. This custom - EntityResolver recognizes two different systemId namespaces. - - - - - a hibernate namespace is recognized whenever the - resolver encounteres a systemId starting with - http://hibernate.sourceforge.net/; the resolver - attempts to resolve these entities via the classlaoder which loaded - the Hibernate classes. - - - - - a user namespace is recognized whenever the - resolver encounteres a systemId using a classpath:// - URL protocol; the resolver will attempt to resolve these entities - via (1) the current thread context classloader and (2) the - classloader which loaded the Hibernate classes. - - - - - An example of utilizing user namespacing: - - - -]> - - - - - ... - - - &types; -]]> - - Where types.xml is a resource in the your.domain - package and contains a custom typedef. - - - - - - hibernate-mapping - - - 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. - - - - - - - - - - - - - ]]> - - - - schema (optional): The name of a database schema. - - - - - catalog (optional): The name of a database catalog. - - - - - default-cascade (optional - defaults to none): - A default cascade style. - - - - - default-access (optional - defaults to property): - The strategy Hibernate should use for accessing all properties. Can be a custom - implementation of PropertyAccessor. - - - - - default-lazy (optional - defaults to true): - The default value for unspecifed lazy attributes of class and - collection mappings. - - - - - auto-import (optional - defaults to true): - Specifies whether we can use unqualified class names (of classes in this mapping) - in the query language. - - - - - package (optional): Specifies a package prefix to assume for - unqualified class names in the mapping document. - - - - - - - If you have two persistent classes with the same (unqualified) name, you should set - auto-import="false". Hibernate will throw an exception if you attempt - to assign two classes to the same "imported" name. - - - - Note that the hibernate-mapping element allows you to nest - several persistent <class> mappings, as shown above. - It is however good practice (and expected by some tools) to map only a single - persistent class (or a single class hierarchy) in one mapping file and name - it after the persistent superclass, e.g. Cat.hbm.xml, - Dog.hbm.xml, or if using inheritance, - Animal.hbm.xml. - - - - - - class - - - You may declare a persistent class using the class element: - - - - - - - - - - - - - - - - - - - - - - - - - - - ]]> - - - - 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. - - - - - table (optional - defaults to the unqualified class name): The - name of its database table. - - - - - 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. - - - - - mutable (optional, defaults to true): Specifies - that instances of the class are (not) mutable. - - - - - schema (optional): Override the schema name specified by - the root <hibernate-mapping> element. - - - - - catalog (optional): Override the catalog name specified by - the root <hibernate-mapping> element. - - - - - proxy (optional): Specifies an interface to use for lazy - initializing proxies. You may specify the name of the class itself. - - - - - dynamic-update (optional, defaults to false): - Specifies that UPDATE SQL should be generated at runtime and - contain only those columns whose values have changed. - - - - - 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. - - - - - 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. - - - - - polymorphism (optional, defaults to implicit): - Determines whether implicit or explicit query polymorphism is used. - - - - - where (optional) specify an arbitrary SQL WHERE - condition to be used when retrieving objects of this class - - - - - persister (optional): Specifies a custom ClassPersister. - - - - - batch-size (optional, defaults to 1) specify a "batch size" - for fetching instances of this class by identifier. - - - - - optimistic-lock (optional, defaults to version): - Determines the optimistic locking strategy. - - - - - lazy (optional): Lazy fetching may be completely disabled by setting - lazy="false". - - - - - entity-name (optional, defaults to the class name): 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 - and - for more information. - - - - - check (optional): A SQL expression used to generate a multi-row - check constraint for automatic schema generation. - - - - - 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. - - - - - 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. - - - - - abstract (optional): Used to mark abstract superclasses in - <union-subclass> hierarchies. - - - - - - - It is perfectly acceptable for the named persistent class to be an interface. You would then - declare implementing classes of that interface using the <subclass> - element. You may persist any static inner class. You should specify the - class name using the standard form ie. eg.Foo$Bar. - - - - Immutable classes, mutable="false", may not be updated or deleted by the - application. This allows Hibernate to make some minor performance optimizations. - - - - The optional proxy attribute enables lazy initialization of persistent - instances of the class. Hibernate will initially return CGLIB proxies which implement - the named interface. The actual persistent object will be loaded when a method of the - proxy is invoked. See "Initializing collections and proxies" below. - - - Implicit polymorphism means that instances of the class will be returned - by a query that names any superclass or implemented interface or the class and that instances - of any subclass of the class will be returned by a query that names the class itself. - Explicit polymorphism means that class instances will be returned only - by queries that explicitly name that class and that queries that name the class will return - only instances of subclasses mapped inside this <class> declaration - as a <subclass> or <joined-subclass>. For - most purposes the default, polymorphism="implicit", is appropriate. - Explicit polymorphism is useful when two different classes are mapped to the same table - (this allows a "lightweight" class that contains a subset of the table columns). - - - - The persister attribute lets you customize the persistence strategy used for - the class. You may, for example, specify your own subclass of - org.hibernate.persister.EntityPersister or you might even provide a - completely new implementation of the interface - org.hibernate.persister.ClassPersister that implements persistence via, - for example, stored procedure calls, serialization to flat files or LDAP. See - org.hibernate.test.CustomPersister for a simple example (of "persistence" - to a Hashtable). - - - - Note that the dynamic-update and dynamic-insert - settings are not inherited by subclasses and so may also be specified on the - <subclass> or <joined-subclass> elements. - These settings may increase performance in some cases, but might actually decrease - performance in others. Use judiciously. - - - - Use of select-before-update will usually decrease performance. It is very - useful to prevent a database update trigger being called unnecessarily if you reattach a - graph of detached instances to a Session. - - - - If you enable dynamic-update, you will have a choice of optimistic - locking strategies: - - - - - version check the version/timestamp columns - - - - - all check all columns - - - - - dirty check the changed columns, allowing some concurrent updates - - - - - none do not use optimistic locking - - - - - We very strongly recommend that you use version/timestamp - columns for optimistic locking with Hibernate. This is the optimal strategy with - respect to performance and is the only strategy that correctly handles modifications - made to detached instances (ie. when Session.merge() is used). - - - - There is no difference between a view and a base table for a Hibernate mapping, as - expected this is transparent at the database level (note that some DBMS don't support - views properly, especially with updates). Sometimes you want to use a view, but can't - create one in the database (ie. with a legacy schema). In this case, you can map an - immutable and read-only entity to a given SQL subselect expression: - - - - - select item.name, max(bid.amount), count(*) - from item - join bid on bid.item_id = item.id - group by item.name - - - - - ... -]]> - - - Declare the tables to synchronize this entity with, ensuring that auto-flush happens - correctly, and that queries against the derived entity do not return stale data. - The <subselect> is available as both as an attribute and - a nested mapping element. - - - - - - id - - - 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. The <id> element defines the mapping from that - property to the primary key column. - - - - - - - - - - - - node="element-name|@attribute-name|element/@attribute|." - - -]]> - - - - name (optional): The name of the identifier property. - - - - - type (optional): A name that indicates the Hibernate type. - - - - - column (optional - defaults to the property name): The - name of the primary key column. - - - - - 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. - - - - - access (optional - defaults to property): The - strategy Hibernate should use for accessing the property value. - - - - - - - If the name attribute is missing, it is assumed that the class has no - identifier property. - - - - The unsaved-value attribute is almost never needed in Hibernate3. - - - - There is an alternative <composite-id> declaration to allow access to - legacy data with composite keys. We strongly discourage its use for anything else. - - - - Generator - - - The optional <generator> child element names a Java class used - to generate unique identifiers for instances of the persistent class. If any parameters - are required to configure or initialize the generator instance, they are passed using the - <param> element. - - - - - uid_table - next_hi_value_column - -]]> - - - All generators implement the interface org.hibernate.id.IdentifierGenerator. - This is a very simple interface; some applications may choose to provide their own specialized - implementations. However, Hibernate provides a range of built-in implementations. There are shortcut - names for the built-in generators: - - - - increment - - - generates identifiers of type long, short or - int that are unique only when no other process is inserting data - into the same table. - Do not use in a cluster. - - - - - identity - - - supports identity columns in DB2, MySQL, MS SQL Server, Sybase and - HypersonicSQL. The returned identifier is of type long, - short or int. - - - - - sequence - - - uses a sequence in DB2, PostgreSQL, Oracle, SAP DB, McKoi or a generator - in Interbase. The returned identifier is of type long, - short or int - - - - - hilo - - - uses a hi/lo algorithm to efficiently generate identifiers of - type long, short or int, - given a table and column (by default hibernate_unique_key and - next_hi respectively) as a source of hi values. The hi/lo - algorithm generates identifiers that are unique only for a particular database. - - - - - seqhilo - - - uses a hi/lo algorithm to efficiently generate identifiers of type - long, short or int, - given a named database sequence. - - - - - uuid - - - uses a 128-bit UUID algorithm to generate identifiers of type string, - unique within a network (the IP address is used). The UUID is encoded - as a string of hexadecimal digits of length 32. - - - - - guid - - - uses a database-generated GUID string on MS SQL Server and MySQL. - - - - - native - - - picks identity, sequence or - hilo depending upon the capabilities of the - underlying database. - - - - - assigned - - - lets the application to assign an identifier to the object before - save() is called. This is the default strategy - if no <generator> element is specified. - - - - - select - - - retrieves a primary key assigned by a database trigger by selecting - the row by some unique key and retrieving the primary key value. - - - - - foreign - - - uses the identifier of another associated object. Usually used in conjunction - with a <one-to-one> primary key association. - - - - - sequence-identity - - - a specialized sequence generation strategy which utilizes a - database sequence for the actual value generation, but combines - this with JDBC3 getGeneratedKeys to actually return the generated - identifier value as part of the insert statement execution. This - strategy is only known to be supported on Oracle 10g drivers - targetted for JDK 1.4. Note comments on these insert statements - are disabled due to a bug in the Oracle drivers. - - - - - - - - - - Hi/lo algorithm - - The hilo and seqhilo generators provide two alternate - implementations of the hi/lo algorithm, a favorite approach to identifier generation. The - first implementation requires a "special" database table to hold the next available "hi" value. - The second uses an Oracle-style sequence (where supported). - - - - - hi_value - next_value - 100 - -]]> - - - - hi_value - 100 - -]]> - - - Unfortunately, you can't use hilo when supplying your own - Connection to Hibernate. When Hibernate is using an application - server datasource to obtain connections enlisted with JTA, you must properly configure - the hibernate.transaction.manager_lookup_class. - - - - - UUID algorithm - - The UUID contains: IP address, startup time of the JVM (accurate to a quarter - second), system time and a counter value (unique within the JVM). It's not - possible to obtain a MAC address or memory address from Java code, so this is - the best we can do without using JNI. - - - - - Identity columns and sequences - - For databases which support identity columns (DB2, MySQL, Sybase, MS SQL), you - may use identity key generation. For databases that support - sequences (DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) you may use - sequence style key generation. Both these strategies require - two SQL queries to insert a new object. - - - - - person_id_sequence - -]]> - - - -]]> - - - For cross-platform development, the native strategy will - choose from the identity, sequence and - hilo strategies, dependant upon the capabilities of the - underlying database. - - - - - Assigned identifiers - - If you want the application to assign identifiers (as opposed to having - Hibernate generate them), you may use the assigned generator. - This special generator will use the identifier value already assigned to the - object's identifier property. This generator is used when the primary key - is a natural key instead of a surrogate key. This is the default behavior - if you do no specify a <generator> element. - - - - Choosing the assigned generator makes Hibernate use - unsaved-value="undefined", forcing Hibernate to go to - the database to determine if an instance is transient or detached, unless - there is a version or timestamp property, or you define - Interceptor.isUnsaved(). - - - - - Primary keys assigned by triggers - - For legacy schemas only (Hibernate does not generate DDL with triggers). - - - - - socialSecurityNumber - -]]> - - - In the above example, there is a unique valued property named - socialSecurityNumber defined by the class, as a - natural key, and a surrogate key named person_id - whose value is generated by a trigger. - - - - - - - - Enhanced identifier generators - - - Starting with release 3.2.3, there are 2 new generators which represent a re-thinking of 2 different - aspects of identifier generation. The first aspect is database portability; the second is optimization - (not having to query the database for every request for a new identifier value). These two new - generators are intended to take the place of some of the named generators described above (starting - in 3.3.x); however, they are included in the current releases and can be referenced by FQN. - - - - The first of these new generators is org.hibernate.id.enhanced.SequenceStyleGenerator - which is intended firstly as a replacement for the sequence generator and secondly as - a better portability generator than native (because native - (generally) chooses between identity and sequence which have - largely different semantics which can cause subtle isssues in applications eyeing portability). - org.hibernate.id.enhanced.SequenceStyleGenerator however achieves portability in - a different manner. It chooses between using a table or a sequence in the database to store its - incrementing values depending on the capabilities of the dialect being used. The difference between this - and native is that table-based and sequence-based storage have the same exact - semantic (in fact sequences are exactly what Hibernate tries to emmulate with its table-based - generators). This generator has a number of configuration parameters: - - - - sequence_name (optional, defaults to hibernate_sequence): - The name of the sequence (or table) to be used. - - - - - initial_value (optional, defaults to 1): The initial - value to be retrieved from the sequence/table. In sequence creation terms, this is analogous - to the clause typical named "STARTS WITH". - - - - - increment_size (optional, defaults to 1): The value by - which subsequent calls to the sequence/table should differ. In sequence creation terms, this - is analogous to the clause typical named "INCREMENT BY". - - - - - force_table_use (optional, defaults to false): Should - we force the use of a table as the backing structure even though the dialect might support - sequence? - - - - - value_column (optional, defaults to next_val): Only - relevant for table structures! The name of the column on the table which is used to - hold the value. - - - - - optimizer (optional, defaults to none): - See - - - - - - The second of these new generators is org.hibernate.id.enhanced.TableGenerator which - is intended firstly as a replacement for the table generator (although it actually - functions much more like org.hibernate.id.MultipleHiLoPerTableGenerator) and secondly - as a re-implementation of org.hibernate.id.MultipleHiLoPerTableGenerator utilizing the - notion of pluggable optimiziers. Essentially this generator defines a table capable of holding - a number of different increment values simultaneously by using multiple distinctly keyed rows. This - generator has a number of configuration parameters: - - - - table_name (optional, defaults to hibernate_sequences): - The name of the table to be used. - - - - - value_column_name (optional, defaults to next_val): - The name of the column on the table which is used to hold the value. - - - - - segment_column_name (optional, defaults to sequence_name): - The name of the column on the table which is used to hold the "segement key". This is the - value which distinctly identifies which increment value to use. - - - - - segment_value (optional, defaults to default): - The "segment key" value for the segment from which we want to pull increment values for - this generator. - - - - - segment_value_length (optional, defaults to 255): - Used for schema generation; the column size to create this segment key column. - - - - - initial_value (optional, defaults to 1): - The initial value to be retrieved from the table. - - - - - increment_size (optional, defaults to 1): - The value by which subsequent calls to the table should differ. - - - - - optimizer (optional, defaults to ): - See - - - - - - - - Identifier generator optimization - - For identifier generators which store values in the database, it is inefficient for them to hit the - database on each and every call to generate a new identifier value. Instead, you'd ideally want to - group a bunch of them in memory and only hit the database when you have exhausted your in-memory - value group. This is the role of the pluggable optimizers. Currently only the two enhanced generators - ( support this notion. - - - - none (generally this is the default if no optimizer was specified): This - says to not perform any optimizations, and hit the database each and every request. - - - - - hilo: applies a hi/lo algorithm around the database retrieved values. The - values from the database for this optimizer are expected to be sequential. The values - retrieved from the database structure for this optimizer indicates the "group number"; the - increment_size is multiplied by that value in memory to define a group - "hi value". - - - - - pooled: like was discussed for hilo, this optimizers - attempts to minimize the number of hits to the database. Here, however, we simply store - the starting value for the "next group" into the database structure rather than a sequential - value in combination with an in-memory grouping algorithm. increment_size - here refers to the values coming from the database. - - - - - - - - composite-id - - - node="element-name|." - - - - ...... -]]> - - - For a table with a composite key, you may map multiple properties of the class - as identifier properties. The <composite-id> element - accepts <key-property> property mappings and - <key-many-to-one> mappings as child elements. - - - - - -]]> - - - Your persistent class must override equals() - and hashCode() to implement composite identifier equality. It must - also implements Serializable. - - - - Unfortunately, this approach to composite identifiers means that a persistent object - is its own identifier. There is no convenient "handle" other than the object itself. - You must instantiate an instance of the persistent class itself and populate its - identifier properties before you can load() the persistent state - associated with a composite key. We call this approach an embedded - composite identifier, and discourage it for serious applications. - - - - A second approach is what we call a mapped composite identifier, - where the identifier properties named inside the <composite-id> - element are duplicated on both the persistent class and a separate identifier class. - - - - - -]]> - - - In this example, both the composite identifier class, MedicareId, - and the entity class itself have properties named medicareNumber - and dependent. The identifier class must override - equals() and hashCode() and implement. - Serializable. The disadvantage of this approach is quite - obvious—code duplication. - - - - The following attributes are used to specify a mapped composite identifier: - - - - - - mapped (optional, defaults to false): - indicates that a mapped composite identifier is used, and that the contained - property mappings refer to both the entity class and the composite identifier - class. - - - - - class (optional, but required for a mapped composite identifier): - The class used as a composite identifier. - - - - - - We will describe a third, even more convenient approach where the composite identifier - is implemented as a component class in . The - attributes described below apply only to this alternative approach: - - - - - - name (optional, required for this approach): A property of - component type that holds the composite identifier (see chapter 9). - - - - - access (optional - defaults to property): - The strategy Hibernate should use for accessing the property value. - - - - - class (optional - defaults to the property type determined by - reflection): The component class used as a composite identifier (see next section). - - - - - - This third approach, an identifier component is the one we recommend - for almost all applications. - - - - - - discriminator - - - The <discriminator> element is required for polymorphic persistence - using the table-per-class-hierarchy mapping strategy and declares a discriminator column of the - table. The discriminator column contains marker values that tell the persistence layer what - subclass to instantiate for a particular row. A restricted set of types may be used: - string, character, integer, - byte, short, boolean, - yes_no, true_false. - - - - - - - - - - - ]]> - - - - column (optional - defaults to class) the - name of the discriminator column. - - - - - type (optional - defaults to string) a - name that indicates the Hibernate type - - - - - force (optional - defaults to false) - "force" Hibernate to specify allowed discriminator values even when retrieving - all instances of the root class. - - - - - insert (optional - defaults to true) - set this to false if your discriminator column is also part - of a mapped composite identifier. (Tells Hibernate to not include the column - in SQL INSERTs.) - - - - - formula (optional) an arbitrary SQL expression that is - executed when a type has to be evaluated. Allows content-based discrimination. - - - - - - - Actual values of the discriminator column are specified by the - discriminator-value attribute of the <class> and - <subclass> elements. - - - - The force attribute is (only) useful if the table contains rows with - "extra" discriminator values that are not mapped to a persistent class. This will not - usually be the case. - - - - Using the formula attribute you can declare an arbitrary SQL expression - that will be used to evaluate the type of a row: - - - ]]> - - - - - version (optional) - - - The <version> element is optional and indicates that - the table contains versioned data. This is particularly useful if you plan to - use long transactions (see below). - - - - - - - - - - - - - ]]> - - - - column (optional - defaults to the property name): The name - of the column holding the version number. - - - - - name: The name of a property of the persistent class. - - - - - type (optional - defaults to integer): - The type of the version number. - - - - - access (optional - defaults to property): The - strategy Hibernate should use for accessing the property value. - - - - - unsaved-value (optional - defaults to undefined): - A version 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. (undefined specifies that the identifier - property value should be used.) - - - - - generated (optional - defaults to never): - Specifies that this version property value is actually generated by the database. - See the discussion of generated properties. - - - - - insert (optional - defaults to true): - Specifies whether the version column should be included in SQL insert statements. - May be set to false if and only if the database column - is defined with a default value of 0. - - - - - - - Version numbers may be of Hibernate type long, integer, - short, timestamp or calendar. - - - - A version or timestamp property should never be null for a detached instance, so - Hibernate will detect any instance with a null version or timestamp as transient, - no matter what other unsaved-value strategies are specified. - Declaring a nullable version or timestamp property is an easy way to avoid - any problems with transitive reattachment in Hibernate, especially useful for people - using assigned identifiers or composite keys! - - - - - timestamp (optional) - - - The optional <timestamp> element indicates that the table contains - timestamped data. This is intended as an alternative to versioning. Timestamps are by nature - a less safe implementation of optimistic locking. However, sometimes the application might - use the timestamps in other ways. - - - - - - - - - - - - ]]> - - - - column (optional - defaults to the property name): The name - of a column holding the timestamp. - - - - - name: The name of a JavaBeans style property of - Java type Date or Timestamp of the - persistent class. - - - - - access (optional - defaults to property): The - strategy Hibernate should use for accessing the property value. - - - - - unsaved-value (optional - defaults to null): - A version 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. (undefined specifies that the identifier - property value should be used.) - - - - - source (optional - defaults to vm): - From where should Hibernate retrieve the timestamp value? From the database, - or from the current JVM? Database-based timestamps incur an overhead because - Hibernate must hit the database in order to determine the "next value", - but will be safer for use in clustered environments. Note also, that not - all Dialects are known to support retrieving of the - database's current timestamp, while others might be unsafe for usage - in locking due to lack of precision (Oracle 8 for example). - - - - - generated (optional - defaults to never): - Specifies that this timestamp property value is actually generated by the database. - See the discussion of generated properties. - - - - - - - Note that <timestamp> is equivalent to - <version type="timestamp">. And - <timestamp source="db"> is equivalent to - <version type="dbtimestamp"> - - - - - - property - - - The <property> element declares a persistent, JavaBean style - property of the class. - - - - - - - - - - - - - - - - - - - - ]]> - - - - 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 generated properties. - - - - - - - typename could be: - - - - - - The name of a Hibernate basic type (eg. integer, string, character, - date, timestamp, float, binary, serializable, object, blob). - - - - - 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). - - - - - The name of a serializable Java class. - - - - - 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: - - - ]]> - - - 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. - - - - - - many-to-one - - - 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. - - - - - - - - - - - - - - - - - - - - - - - - ]]> - - - - name: The name of the property. - - - - - column (optional): The name of the foreign key column. - This may also be specified by nested <column> - element(s). - - - - - class (optional - defaults to the property type - determined by reflection): The name of the associated class. - - - - - cascade (optional): Specifies which operations should - be cascaded from the parent object to the associated object. - - - - - fetch (optional - defaults to select): - Chooses between outer-join fetching or sequential select fetching. - - - - - 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. - - - - - 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. - - - - - access (optional - defaults to property): The - strategy Hibernate should use for accessing the property value. - - - - - 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. - - - - - not-null (optional): Enable the DDL generation of a nullability - constraint for the foreign key 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, dertermines if a version increment should occur when - this property is dirty. - - - - - lazy (optional - defaults to proxy): - By default, single point associations are proxied. lazy="no-proxy" - specifies that the property should be fetched lazily when the instance variable - is first accessed (requires build-time bytecode instrumentation). - lazy="false" specifies that the association will always - be eagerly fetched. - - - - - not-found (optional - defaults to exception): - Specifies how foreign keys that reference missing rows will be handled: - ignore will treat a missing row as a null association. - - - - - entity-name (optional): The entity name of the associated class. - - - - - formula (optional): an SQL expression that defines the value for a - computed foreign key. - - - - - - - Setting a value of the cascade attribute to any meaningful - value other than none will propagate certain operations to the - associated object. The meaningful values are the names of Hibernate's basic - operations, persist, merge, delete, save-update, evict, replicate, lock, - refresh, as well as the special values delete-orphan - and all and comma-separated combinations of operation - names, for example, cascade="persist,merge,evict" or - cascade="all,delete-orphan". See - for a full explanation. Note that single valued associations (many-to-one and - one-to-one associations) do not support orphan delete. - - - - A typical many-to-one declaration looks as simple as this: - - - ]]> - - - The property-ref attribute should only be used for mapping legacy - data where a foreign key refers to a unique key of the associated table other than - the primary key. This is an ugly relational model. For example, suppose the - Product class had a unique serial number, that is not the primary - key. (The unique attribute controls Hibernate's DDL generation with - the SchemaExport tool.) - - - ]]> - - - Then the mapping for OrderItem might use: - - - ]]> - - - This is certainly not encouraged, however. - - - - If the referenced unique key comprises multiple properties of the associated entity, you should - map the referenced properties inside a named <properties> element. - - - - If the referenced unique key is the property of a component, you may specify a property path: - - - ]]> - - - - - one-to-one - - - A one-to-one association to another persistent class is declared using a - one-to-one element. - - - - - - - - - - - - - - - - ]]> - - - - name: The name of the property. - - - - - class (optional - defaults to the property type - determined by reflection): The name of the associated class. - - - - - cascade (optional) specifies which operations should - be cascaded from the parent object to the associated object. - - - - - 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). - - - - - fetch (optional - defaults to select): - Chooses between outer-join fetching or sequential select fetching. - - - - - 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. - - - - - access (optional - defaults to property): The - strategy Hibernate should use for accessing the property value. - - - - - 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.) - - - - - lazy (optional - defaults to proxy): - By default, single point associations are proxied. lazy="no-proxy" - specifies that the property should be fetched lazily when the instance variable - is first accessed (requires build-time bytecode instrumentation). - lazy="false" specifies that the association will always - be eagerly fetched. Note that if constrained="false", - proxying is impossible and Hibernate will eager fetch the association! - - - - - entity-name (optional): The entity name of the associated class. - - - - - - - There are two varieties of one-to-one association: - - - - primary key associations - - - unique foreign key associations - - - - - Primary key associations don't need an extra table column; if two rows are related by - the association then the two table rows share the same primary key value. So if you want - two objects to be related by a primary key association, you must make sure that they - are assigned the same identifier value! - - - - For a primary key association, add the following mappings to Employee and - Person, respectively. - - - ]]> - ]]> - - - Now we must ensure that the primary keys of related rows in the PERSON and - EMPLOYEE tables are equal. We use a special Hibernate identifier generation strategy - called foreign: - - - - - - employee - - - ... - -]]> - - - A newly saved instance of Person is then assigned the same primary - key value as the Employee instance refered with the employee - property of that Person. - - - - Alternatively, a foreign key with a unique constraint, from Employee to - Person, may be expressed as: - - - ]]> - - - And this association may be made bidirectional by adding the following to the - Person mapping: - - - ]]> - - - - - natural-id - - - - - ...... -]]> - - - Even though we recommend the use of surrogate keys as primary keys, you should still try - to identify natural keys for all entities. A natural key is a property or combination of - properties that is unique and non-null. If it is also immutable, even better. Map the - properties of the natural key inside the <natural-id> element. - Hibernate will generate the necessary unique key and nullability constraints, and your - mapping will be more self-documenting. - - - - We strongly recommend that you implement equals() and - hashCode() to compare the natural key properties of the entity. - - - - This mapping is not intended for use with entities with natural primary keys. - - - - - - mutable (optional, defaults to false): - By default, natural identifier properties as assumed to be immutable (constant). - - - - - - - - component, dynamic-component - - - The <component> element maps properties of a - child object to columns of the table of a parent class. Components may, in - turn, declare their own properties, components or collections. See - "Components" below. - - - - - - - - - - - - - - - - - - ........ -]]> - - - - name: The name of the property. - - - - - class (optional - defaults to the property type - determined by reflection): The name of the component (child) class. - - - - - insert: Do the mapped columns appear in SQL - INSERTs? - - - - - update: Do the mapped columns appear in SQL - UPDATEs? - - - - - access (optional - defaults to property): The - strategy Hibernate should use for accessing the property value. - - - - - lazy (optional - defaults to false): Specifies - that this component should be fetched lazily when the instance variable is first - accessed (requires build-time bytecode instrumentation). - - - - - optimistic-lock (optional - defaults to true): - Specifies that updates to this component 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. - - - - - unique (optional - defaults to false): - Specifies that a unique constraint exists upon all mapped columns of the - component. - - - - - - - The child <property> tags map properties of the - child class to table columns. - - - - The <component> element allows a <parent> - subelement that maps a property of the component class as a reference back to the - containing entity. - - - - The <dynamic-component> element allows a Map - to be mapped as a component, where the property names refer to keys of the map, see - . - - - - - - properties - - - The <properties> element allows the definition of a named, - logical grouping of properties of a class. The most important use of the construct - is that it allows a combination of properties to be the target of a - property-ref. It is also a convenient way to define a multi-column - unique constraint. - - - - - - - - - - - - - - - ........ -]]> - - - - name: The logical name of the grouping - - not an actual property name. - - - - - insert: Do the mapped columns appear in SQL - INSERTs? - - - - - update: Do the mapped columns appear in SQL - UPDATEs? - - - - - optimistic-lock (optional - defaults to true): - Specifies that updates to these properties do or do not require acquisition of the - optimistic lock. In other words, determines if a version increment should occur when - these properties are dirty. - - - - - unique (optional - defaults to false): - Specifies that a unique constraint exists upon all mapped columns of the - component. - - - - - - - For example, if we have the following <properties> mapping: - - - - - ... - - - - - -]]> - - - Then we might have some legacy data association which refers to this unique key of - the Person table, instead of to the primary key: - - - - - - -]]> - - - We don't recommend the use of this kind of thing outside the context of mapping - legacy data. - - - - - - subclass - - - Finally, polymorphic persistence requires the declaration of each subclass of - the root persistent class. For the table-per-class-hierarchy - mapping strategy, the <subclass> declaration is used. - - - - - - - - - - - - - ..... -]]> - - - - name: The fully qualified class name of the subclass. - - - - - discriminator-value (optional - defaults to the class name): A - value that distiguishes individual subclasses. - - - - - proxy (optional): Specifies a class or interface to use for - lazy initializing proxies. - - - - - lazy (optional, defaults to true): Setting - lazy="false" disables the use of lazy fetching. - - - - - - - Each subclass should declare its own persistent properties and subclasses. - <version> and <id> properties - are assumed to be inherited from the root class. Each subclass in a heirarchy must - define a unique discriminator-value. If none is specified, the - fully qualified Java class name is used. - - - - For information about inheritance mappings, see . - - - - - - joined-subclass - - - Alternatively, each subclass may be mapped to its own table (table-per-subclass - mapping strategy). Inherited state is retrieved by joining with the table of the - superclass. We use the <joined-subclass> element. - - - - - - - - - - - - - - - ..... -]]> - - - - name: The fully qualified class name of the subclass. - - - - - table: The name of the subclass table. - - - - - proxy (optional): Specifies a class or interface to use - for lazy initializing proxies. - - - - - lazy (optional, defaults to true): Setting - lazy="false" disables the use of lazy fetching. - - - - - - - No discriminator column is required for this mapping strategy. Each subclass must, - however, declare a table column holding the object identifier using the - <key> element. The mapping at the start of the chapter - would be re-written as: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - For information about inheritance mappings, see . - - - - - - union-subclass - - - A third option is to map only the concrete classes of an inheritance hierarchy - to tables, (the table-per-concrete-class strategy) where each table defines all - persistent state of the class, including inherited state. In Hibernate, it is - not absolutely necessary to explicitly map such inheritance hierarchies. You - can simply map each class with a separate <class> - declaration. However, if you wish use polymorphic associations (e.g. an association - to the superclass of your hierarchy), you need to - use the <union-subclass> mapping. - - - - - - - - - - - - - ..... -]]> - - - - name: The fully qualified class name of the subclass. - - - - - table: The name of the subclass table. - - - - - proxy (optional): Specifies a class or interface to use - for lazy initializing proxies. - - - - - lazy (optional, defaults to true): Setting - lazy="false" disables the use of lazy fetching. - - - - - - - No discriminator column or key column is required for this mapping strategy. - - - - For information about inheritance mappings, see . - - - - - - join - - - Using the <join> element, it is possible to map - properties of one class to several tables, when there's a 1-to-1 relationship between the tables. - - - - - - - - - - - - - - - - - ... -]]> - - - - - table: The name of the joined table. - - - - - schema (optional): Override the schema name specified by - the root <hibernate-mapping> element. - - - - - catalog (optional): Override the catalog name specified by - the root <hibernate-mapping> element. - - - - - fetch (optional - defaults to join): - If set to join, the default, Hibernate will use an inner join - to retrieve a <join> defined by a class or its superclasses - and an outer join for a <join> defined by a subclass. - If set to select then Hibernate will use a sequential select for - a <join> defined on a subclass, which will be issued only - if a row turns out to represent an instance of the subclass. Inner joins will still - be used to retrieve a <join> defined by the class and its - superclasses. - - - - - inverse (optional - defaults to false): - If enabled, Hibernate will not try to insert or update the properties defined - by this join. - - - - - optional (optional - defaults to false): - If enabled, Hibernate will insert a row only if the properties defined by this - join are non-null and will always use an outer join to retrieve the properties. - - - - - - - For example, the address information for a person can be mapped to a separate - table (while preserving value type semantics for all properties): - - - - - ... - - - - - - - - ...]]> - - - This feature is often only useful for legacy data models, we recommend fewer - tables than classes and a fine-grained domain model. However, it is useful - for switching between inheritance mapping strategies in a single hierarchy, as - explained later. - - - - - - key - - - We've seen the <key> element crop up a few times - now. It appears anywhere the parent mapping element defines a join to - a new table, and defines the foreign key in the joined table, that references - the primary key of the original table. - - - - - - - - - - - - ]]> - - - - - column (optional): The name of the foreign key column. - This may also be specified by nested <column> - element(s). - - - - - on-delete (optional, defaults to noaction): - Specifies whether the foreign key constraint has database-level cascade delete - enabled. - - - - - property-ref (optional): Specifies that the foreign key refers - to columns that are not the primary key of the orginal table. (Provided for - legacy data.) - - - - - not-null (optional): Specifies that the foreign key columns - are not nullable (this is implied whenever the foreign key is also part of the - primary key). - - - - - update (optional): Specifies that the foreign key should never - be updated (this is implied whenever the foreign key is also part of the primary - key). - - - - - unique (optional): Specifies that the foreign key should have - a unique constraint (this is implied whenever the foreign key is also the primary key). - - - - - - - We recommend that for systems where delete performance is important, all keys should be - defined on-delete="cascade", and Hibernate will use a database-level - ON CASCADE DELETE constraint, instead of many individual - DELETE statements. Be aware that this feature bypasses Hibernate's - usual optimistic locking strategy for versioned data. - - - - The not-null and update attributes are useful when - mapping a unidirectional one to many association. If you map a unidirectional one to many - to a non-nullable foreign key, you must declare the key column using - <key not-null="true">. - - - - - - column and formula elements - - Any mapping element which accepts a column attribute will alternatively - accept a <column> subelement. Likewise, <formula> - is an alternative to the formula attribute. - - - ]]> - - SQL expression]]> - - - column and formula attributes may even be combined - within the same property or association mapping to express, for example, exotic join - conditions. - - - - - 'MAILING' -]]> - - - - - import - - - Suppose your application has two persistent classes with the same name, and you don't want to - specify the fully qualified (package) name in Hibernate queries. Classes may be "imported" - explicitly, rather than relying upon auto-import="true". You may even import - classes and interfaces that are not explicitly mapped. - - - ]]> - - - - - - - ]]> - - - - class: The fully qualified class name of of any Java class. - - - - - rename (optional - defaults to the unqualified class name): - A name that may be used in the query language. - - - - - - - - - any - - - There is one further type of property mapping. The <any> mapping element - defines a polymorphic association to classes from multiple tables. This type of mapping always - requires more than one column. The first column holds the type of the associated entity. - The remaining columns hold the identifier. It is impossible to specify a foreign key constraint - for this kind of association, so this is most certainly not meant as the usual way of mapping - (polymorphic) associations. You should use this only in very special cases (eg. audit logs, - user session data, etc). - - - - The meta-type attribute lets the application specify a custom type that - maps database column values to persistent classes which have identifier properties of the - type specified by id-type. You must specify the mapping from values of - the meta-type to class names. - - - - - - - - -]]> - - - - - - - - - - - - - - ..... - - - ..... -]]> - - - - name: the property name. - - - - - id-type: the identifier type. - - - - - meta-type (optional - defaults to string): - Any type that is allowed for a discriminator mapping. - - - - - cascade (optional- defaults to none): - the cascade style. - - - - - access (optional - defaults to property): The - strategy Hibernate should use for accessing the property value. - - - - - 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, define if a version increment should occur if this - property is dirty. - - - - - - - - - - - Hibernate Types - - - Entities and values - - - To understand the behaviour of various Java language-level objects with respect - to the persistence service, we need to classify them into two groups: - - - - An entity exists independently of any other objects holding - references to the entity. Contrast this with the usual Java model where an - unreferenced object is garbage collected. Entities must be explicitly saved and - deleted (except that saves and deletions may be cascaded - from a parent entity to its children). This is different from the ODMG model of - object persistence by reachablity - and corresponds more closely to how - application objects are usually used in large systems. Entities support - circular and shared references. They may also be versioned. - - - - An entity's persistent state consists of references to other entities and - instances of value types. Values are primitives, - collections (not what's inside a collection), components and certain immutable - objects. Unlike entities, values (in particular collections and components) - are persisted and deleted by reachability. Since value - objects (and primitives) are persisted and deleted along with their containing - entity they may not be independently versioned. Values have no independent - identity, so they cannot be shared by two entities or collections. - - - - Up until now, we've been using the term "persistent class" to refer to - entities. We will continue to do that. Strictly speaking, however, not all - user-defined classes with persistent state are entities. A - component is a user defined class with value semantics. - A Java property of type java.lang.String also has value - semantics. Given this definition, we can say that all types (classes) provided - by the JDK have value type semantics in Java, while user-defined types may - be mapped with entity or value type semantics. This decision is up to the - application developer. A good hint for an entity class in a domain model are - shared references to a single instance of that class, while composition or - aggregation usually translates to a value type. - - - - We'll revisit both concepts throughout the documentation. - - - - The challenge is to map the Java type system (and the developers' definition of - entities and value types) to the SQL/database type system. The bridge between - both systems is provided by Hibernate: for entities we use - <class>, <subclass> and so on. - For value types we use <property>, - <component>, etc, usually with a type - attribute. The value of this attribute is the name of a Hibernate - mapping type. Hibernate provides many mappings (for standard - JDK value types) out of the box. You can write your own mapping types and implement your - custom conversion strategies as well, as you'll see later. - - - - All built-in Hibernate types except collections support null semantics. - - - - - - Basic value types - - - The built-in basic mapping types may be roughly categorized into - - - - integer, long, short, float, double, character, byte, - boolean, yes_no, true_false - - - Type mappings from Java primitives or wrapper classes to appropriate - (vendor-specific) SQL column types. boolean, yes_no - and true_false are all alternative encodings for - a Java boolean or java.lang.Boolean. - - - - - string - - - A type mapping from java.lang.String to - VARCHAR (or Oracle VARCHAR2). - - - - - date, time, timestamp - - - Type mappings from java.util.Date and its subclasses - to SQL types DATE, TIME and - TIMESTAMP (or equivalent). - - - - - calendar, calendar_date - - - Type mappings from java.util.Calendar to - SQL types TIMESTAMP and DATE - (or equivalent). - - - - - big_decimal, big_integer - - - Type mappings from java.math.BigDecimal and - java.math.BigInteger to NUMERIC - (or Oracle NUMBER). - - - - - locale, timezone, currency - - - Type mappings from java.util.Locale, - java.util.TimeZone and - java.util.Currency - to VARCHAR (or Oracle VARCHAR2). - Instances of Locale and Currency are - mapped to their ISO codes. Instances of TimeZone are - mapped to their ID. - - - - - class - - - A type mapping from java.lang.Class to - VARCHAR (or Oracle VARCHAR2). - A Class is mapped to its fully qualified name. - - - - - binary - - - Maps byte arrays to an appropriate SQL binary type. - - - - - text - - - Maps long Java strings to a SQL CLOB or - TEXT type. - - - - - serializable - - - Maps serializable Java types to an appropriate SQL binary type. You - may also indicate the Hibernate type serializable with - the name of a serializable Java class or interface that does not default - to a basic type. - - - - - clob, blob - - - Type mappings for the JDBC classes java.sql.Clob and - java.sql.Blob. These types may be inconvenient for some - applications, since the blob or clob object may not be reused outside of - a transaction. (Furthermore, driver support is patchy and inconsistent.) - - - - - - imm_date, imm_time, imm_timestamp, imm_calendar, imm_calendar_date, - imm_serializable, imm_binary - - - - Type mappings for what are usually considered mutable Java types, where - Hibernate makes certain optimizations appropriate only for immutable - Java types, and the application treats the object as immutable. For - example, you should not call Date.setTime() for an - instance mapped as imm_timestamp. To change the - value of the property, and have that change made persistent, the - application must assign a new (nonidentical) object to the property. - - - - - - - - - Unique identifiers of entities and collections may be of any basic type except - binary, blob and clob. - (Composite identifiers are also allowed, see below.) - - - - The basic value types have corresponding Type constants defined on - org.hibernate.Hibernate. For example, Hibernate.STRING - represents the string type. - - - - - - Custom value types - - - It is relatively easy for developers to create their own value types. For example, - you might want to persist properties of type java.lang.BigInteger - to VARCHAR columns. Hibernate does not provide a built-in type - for this. But custom types are not limited to mapping a property (or collection element) - to a single table column. So, for example, you might have a Java property - getName()/setName() of type - java.lang.String that is persisted to the columns - FIRST_NAME, INITIAL, SURNAME. - - - - To implement a custom type, implement either org.hibernate.UserType - or org.hibernate.CompositeUserType and declare properties using the - fully qualified classname of the type. Check out - org.hibernate.test.DoubleStringType to see the kind of things that - are possible. - - - - - -]]> - - - Notice the use of <column> tags to map a property to multiple - columns. - - - - The CompositeUserType, EnhancedUserType, - UserCollectionType, and UserVersionType - interfaces provide support for more specialized uses. - - - - You may even supply parameters to a UserType in the mapping file. To - do this, your UserType must implement the - org.hibernate.usertype.ParameterizedType interface. To supply parameters - to your custom type, you can use the <type> element in your mapping - files. - - - - - 0 - -]]> - - - The UserType can now retrieve the value for the parameter named - default from the Properties object passed to it. - - - - If you use a certain UserType very often, it may be useful to define a - shorter name for it. You can do this using the <typedef> element. - Typedefs assign a name to a custom type, and may also contain a list of default - parameter values if the type is parameterized. - - - - 0 -]]> - - ]]> - - - It is also possible to override the parameters supplied in a typedef on a case-by-case basis - by using type parameters on the property mapping. - - - - Even though Hibernate's rich range of built-in types and support for components means you - will very rarely need to use a custom type, it is nevertheless - considered good form to use custom types for (non-entity) classes that occur frequently - in your application. For example, a MonetaryAmount class is a good - candidate for a CompositeUserType, even though it could easily be mapped - as a component. One motivation for this is abstraction. With a custom type, your mapping - documents would be future-proofed against possible changes in your way of representing - monetary values. - - - - - - - - Mapping a class more than once - - It is possible to provide more than one mapping for a particular persistent class. In this - case you must specify an entity name do disambiguate between instances - of the two mapped entities. (By default, the entity name is the same as the class name.) - Hibernate lets you specify the entity name when working with persistent objects, when writing - queries, or when mapping associations to the named entity. - - - - ... - - - - - - - - ... - -]]> - - - Notice how associations are now specified using entity-name instead of - class. - - - - - - SQL quoted identifiers - - You may force Hibernate to quote an identifier in the generated SQL by enclosing the table or - column name in backticks in the mapping document. Hibernate will use the correct quotation - style for the SQL Dialect (usually double quotes, but brackets for SQL - Server and backticks for MySQL). - - - - - - ... -]]> - - - - - - Metadata alternatives - - - XML isn't for everyone, and so there are some alternative ways to define O/R mapping metadata in Hibernate. - - - - Using XDoclet markup - - - Many Hibernate users prefer to embed mapping information directly in sourcecode using - XDoclet @hibernate.tags. We will not cover this approach in this - document, since strictly it is considered part of XDoclet. However, we include the - following example of the Cat class with XDoclet mappings. - - - - - - See the Hibernate web site for more examples of XDoclet and Hibernate. - - - - - - Using JDK 5.0 Annotations - - - JDK 5.0 introduced XDoclet-style annotations at the language level, type-safe and - checked at compile time. This mechnism is more powerful than XDoclet annotations and - better supported by tools and IDEs. IntelliJ IDEA, for example, supports auto-completion - and syntax highlighting of JDK 5.0 annotations. The new revision of the EJB specification - (JSR-220) uses JDK 5.0 annotations as the primary metadata mechanism for entity beans. - Hibernate3 implements the EntityManager of JSR-220 (the persistence API), - support for mapping metadata is available via the Hibernate Annotations - package, as a separate download. Both EJB3 (JSR-220) and Hibernate3 metadata is supported. - - - - This is an example of a POJO class annotated as an EJB entity bean: - - - orders; - - // Getter/setter and business methods -}]]> - - - Note that support for JDK 5.0 Annotations (and JSR-220) is still work in progress and - not completed. Please refer to the Hibernate Annotations module for more details. - - - - - - - Generated Properties - - Generated properties are properties which have their values generated by the - database. Typically, Hibernate applications needed to refresh - objects which contain any properties for which the database was generating values. - Marking properties as generated, however, lets the application delegate this - responsibility to Hibernate. Essentially, whenever Hibernate issues an SQL INSERT - or UPDATE for an entity which has defined generated properties, it immediately - issues a select afterwards to retrieve the generated values. - - - Properties marked as generated must additionally be non-insertable and non-updateable. - Only versions, - timestamps, and - simple properties can be marked as - generated. - - - never (the default) - means that the given property value - is not generated within the database. - - - insert - states that the given property value is generated on - insert, but is not regenerated on subsequent updates. Things like created-date would - fall into this category. Note that even thought - version and - timestamp properties can - be marked as generated, this option is not available there... - - - always - states that the property value is generated both - on insert and on update. - - - - - Auxiliary Database Objects - - Allows CREATE and DROP of arbitrary database objects, in conjunction with - Hibernate's schema evolution tools, to provide the ability to fully define - a user schema within the Hibernate mapping files. Although designed specifically - for creating and dropping things like triggers or stored procedures, really any - SQL command that can be run via a java.sql.Statement.execute() - method is valid here (ALTERs, INSERTS, etc). There are essentially two modes for - defining auxiliary database objects... - - - The first mode is to explicitly list the CREATE and DROP commands out in the mapping - file: - - - ... - - CREATE TRIGGER my_trigger ... - DROP TRIGGER my_trigger - -]]> - - The second mode is to supply a custom class which knows how to construct the - CREATE and DROP commands. This custom class must implement the - org.hibernate.mapping.AuxiliaryDatabaseObject interface. - - - ... - - - -]]> - - Additionally, these database objects can be optionally scoped such that they only - apply when certain dialects are used. - - - ... - - - - - -]]> - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/batch.xml b/documentation/envers/src/main/docbook/en-US/content/batch.xml deleted file mode 100755 index d985e10b99..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/batch.xml +++ /dev/null @@ -1,374 +0,0 @@ - - - - - - - Batch processing - - - A naive approach to inserting 100 000 rows in the database using Hibernate might - look like this: - - - - - - This would fall over with an OutOfMemoryException somewhere - around the 50 000th row. That's because Hibernate caches all the newly inserted - Customer instances in the session-level cache. - - - - In this chapter we'll show you how to avoid this problem. First, however, if you - are doing batch processing, it is absolutely critical that you enable the use of - JDBC batching, if you intend to achieve reasonable performance. Set the JDBC batch - size to a reasonable number (say, 10-50): - - - - - - Note that Hibernate disables insert batching at the JDBC level transparently if you - use an identiy identifier generator. - - - - You also might like to do this kind of work in a process where interaction with - the second-level cache is completely disabled: - - - - - - However, this is not absolutely necessary, since we can explicitly set the - CacheMode to disable interaction with the second-level cache. - - - - Batch inserts - - - When making new objects persistent, you must flush() and - then clear() the session regularly, to control the size of - the first-level cache. - - - - - - - - Batch updates - - - For retrieving and updating data the same ideas apply. In addition, you need to - use scroll() to take advantage of server-side cursors for - queries that return many rows of data. - - - - - - - - The StatelessSession interface - - Alternatively, Hibernate provides a command-oriented API that may be used for - streaming data to and from the database in the form of detached objects. A - StatelessSession has no persistence context associated - with it and does not provide many of the higher-level life cycle semantics. - In particular, a stateless session does not implement a first-level cache nor - interact with any second-level or query cache. It does not implement - transactional write-behind or automatic dirty checking. Operations performed - using a stateless session do not ever cascade to associated instances. Collections - are ignored by a stateless session. Operations performed via a stateless session - bypass Hibernate's event model and interceptors. Stateless sessions are vulnerable - to data aliasing effects, due to the lack of a first-level cache. A stateless - session is a lower-level abstraction, much closer to the underlying JDBC. - - - - - - Note that in this code example, the Customer instances returned - by the query are immediately detached. They are never associated with any persistence - context. - - - - The insert(), update() and delete() operations - defined by the StatelessSession interface are considered to be - direct database row-level operations, which result in immediate execution of a SQL - INSERT, UPDATE or DELETE respectively. Thus, - they have very different semantics to the save(), saveOrUpdate() - and delete() operations defined by the Session - interface. - - - - - - DML-style operations - - - As already discussed, automatic and transparent object/relational mapping is concerned - with the management of object state. This implies that the object state is available - in memory, hence manipulating (using the SQL Data Manipulation Language - (DML) statements: INSERT, UPDATE, DELETE) - data directly in the database will not affect in-memory state. However, Hibernate provides methods - for bulk SQL-style DML statement execution which are performed through the - Hibernate Query Language (HQL). - - - - The pseudo-syntax for UPDATE and DELETE statements - is: ( UPDATE | DELETE ) FROM? EntityName (WHERE where_conditions)?. Some - points to note: - - - - - - In the from-clause, the FROM keyword is optional - - - - - There can only be a single entity named in the from-clause; it can optionally be - aliased. If the entity name is aliased, then any property references must - be qualified using that alias; if the entity name is not aliased, then it is - illegal for any property references to be qualified. - - - - - No joins (either implicit or explicit) - can be specified in a bulk HQL query. Sub-queries may be used in the where-clause; - the subqueries, themselves, may contain joins. - - - - - The where-clause is also optional. - - - - - - As an example, to execute an HQL UPDATE, use the - Query.executeUpdate() method (the method is named for - those familiar with JDBC's PreparedStatement.executeUpdate()): - - - - - - HQL UPDATE statements, by default do not effect the - version - or the timestamp property values - for the affected entities; this is in keeping with the EJB3 specification. However, - you can force Hibernate to properly reset the version or - timestamp property values through the use of a versioned update. - This is achieved by adding the VERSIONED keyword after the UPDATE - keyword. - - - - - Note that custom version types (org.hibernate.usertype.UserVersionType) - are not allowed in conjunction with a update versioned statement. - - - - To execute an HQL DELETE, use the same Query.executeUpdate() - method: - - - - - - The int value returned by the Query.executeUpdate() - method indicate the number of entities effected by the operation. Consider this may or may not - correlate to the number of rows effected in the database. An HQL bulk operation might result in - multiple actual SQL statements being executed, for joined-subclass, for example. The returned - number indicates the number of actual entities affected by the statement. Going back to the - example of joined-subclass, a delete against one of the subclasses may actually result - in deletes against not just the table to which that subclass is mapped, but also the "root" - table and potentially joined-subclass tables further down the inheritence hierarchy. - - - - The pseudo-syntax for INSERT statements is: - INSERT INTO EntityName properties_list select_statement. Some - points to note: - - - - - - Only the INSERT INTO ... SELECT ... form is supported; not the INSERT INTO ... VALUES ... form. - - - The properties_list is analogous to the column speficiation - in the SQL INSERT statement. For entities involved in mapped - inheritence, only properties directly defined on that given class-level can be - used in the properties_list. Superclass properties are not allowed; and subclass - properties do not make sense. In other words, INSERT - statements are inherently non-polymorphic. - - - - - select_statement can be any valid HQL select query, with the caveat that the return types - must match the types expected by the insert. Currently, this is checked during query - compilation rather than allowing the check to relegate to the database. Note however - that this might cause problems between Hibernate Types which are - equivalent as opposed to equal. This might cause - issues with mismatches between a property defined as a org.hibernate.type.DateType - and a property defined as a org.hibernate.type.TimestampType, even though the - database might not make a distinction or might be able to handle the conversion. - - - - - For the id property, the insert statement gives you two options. You can either - explicitly specify the id property in the properties_list (in which case its value - is taken from the corresponding select expression) or omit it from the properties_list - (in which case a generated value is used). This later option is only available when - using id generators that operate in the database; attempting to use this option with - any "in memory" type generators will cause an exception during parsing. Note that - for the purposes of this discussion, in-database generators are considered to be - org.hibernate.id.SequenceGenerator (and its subclasses) and - any implementors of org.hibernate.id.PostInsertIdentifierGenerator. - The most notable exception here is org.hibernate.id.TableHiLoGenerator, - which cannot be used because it does not expose a selectable way to get its values. - - - - - For properties mapped as either version or timestamp, - the insert statement gives you two options. You can either specify the property in the - properties_list (in which case its value is taken from the corresponding select expressions) - or omit it from the properties_list (in which case the seed value defined - by the org.hibernate.type.VersionType is used). - - - - - - An example HQL INSERT statement execution: - - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/best_practices.xml b/documentation/envers/src/main/docbook/en-US/content/best_practices.xml deleted file mode 100644 index d123d80878..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/best_practices.xml +++ /dev/null @@ -1,250 +0,0 @@ - - - - - - - Best Practices - - - - Write fine-grained classes and map them using <component>. - - - Use an Address class to encapsulate street, - suburb, state, postcode. - This encourages code reuse and simplifies refactoring. - - - - - Declare identifier properties on persistent classes. - - - Hibernate makes identifier properties optional. There are all sorts of reasons why - you should use them. We recommend that identifiers be 'synthetic' (generated, with - no business meaning). - - - - - Identify natural keys. - - - Identify natural keys for all entities, and map them using - <natural-id>. Implement equals() and - hashCode() to compare the properties that make up the natural key. - - - - - Place each class mapping in its own file. - - - Don't use a single monolithic mapping document. Map com.eg.Foo in - the file com/eg/Foo.hbm.xml. This makes particularly good sense in - a team environment. - - - - - Load mappings as resources. - - - Deploy the mappings along with the classes they map. - - - - - Consider externalising query strings. - - - This is a good practice if your queries call non-ANSI-standard SQL functions. - Externalising the query strings to mapping files will make the application more - portable. - - - - - Use bind variables. - - - As in JDBC, always replace non-constant values by "?". Never use string manipulation to - bind a non-constant value in a query! Even better, consider using named parameters in - queries. - - - - - Don't manage your own JDBC connections. - - - Hibernate lets the application manage JDBC connections. This approach should be considered - a last-resort. If you can't use the built-in connections providers, consider providing your - own implementation of org.hibernate.connection.ConnectionProvider. - - - - - Consider using a custom type. - - - Suppose you have a Java type, say from some library, that needs to be persisted but doesn't - provide the accessors needed to map it as a component. You should consider implementing - org.hibernate.UserType. This approach frees the application - code from implementing transformations to / from a Hibernate type. - - - - - Use hand-coded JDBC in bottlenecks. - - - In performance-critical areas of the system, some kinds of operations might benefit from - direct JDBC. But please, wait until you know something is a bottleneck. - And don't assume that direct JDBC is necessarily faster. If you need to use direct JDBC, it might - be worth opening a Hibernate Session and using that JDBC connection. That - way you can still use the same transaction strategy and underlying connection provider. - - - - - Understand Session flushing. - - - From time to time the Session synchronizes its persistent state with the database. Performance will - be affected if this process occurs too often. You may sometimes minimize unnecessary flushing by - disabling automatic flushing or even by changing the order of queries and other operations within a - particular transaction. - - - - - In a three tiered architecture, consider using detached objects. - - - When using a servlet / session bean architecture, you could pass persistent objects loaded in - the session bean to and from the servlet / JSP layer. Use a new session to service each request. - Use Session.merge() or Session.saveOrUpdate() to - synchronize objects with the database. - - - - - In a two tiered architecture, consider using long persistence contexts. - - - Database Transactions have to be as short as possible for best scalability. However, it is often - neccessary to implement long running application transactions, a single - unit-of-work from the point of view of a user. An application transaction might span several - client request/response cycles. It is common to use detached objects to implement application - transactions. An alternative, extremely appropriate in two tiered architecture, is to maintain - a single open persistence contact (session) for the whole life cycle of the application transaction - and simply disconnect from the JDBC connection at the end of each request and reconnect at the - beginning of the subsequent request. Never share a single session across more than one application - transaction, or you will be working with stale data. - - - - - Don't treat exceptions as recoverable. - - - This is more of a necessary practice than a "best" practice. When an exception occurs, roll back - the Transaction and close the Session. If you don't, Hibernate - can't guarantee that in-memory state accurately represents persistent state. As a special case of this, - do not use Session.load() to determine if an instance with the given identifier - exists on the database; use Session.get() or a query instead. - - - - - Prefer lazy fetching for associations. - - - Use eager fetching sparingly. Use proxies and lazy collections for most associations to classes that - are not likely to be completely held in the second-level cache. For associations to cached classes, - where there is an a extremely high probability of a cache hit, explicitly disable eager fetching using - lazy="false". When an join fetching is appropriate to a particular use - case, use a query with a left join fetch. - - - - - - Use the open session in view pattern, or a disciplined - assembly phase to avoid problems with unfetched data. - - - - Hibernate frees the developer from writing tedious Data Transfer Objects (DTO). - In a traditional EJB architecture, DTOs serve dual purposes: first, they work around the problem - that entity beans are not serializable; second, they implicitly define an assembly phase where - all data to be used by the view is fetched and marshalled into the DTOs before returning control - to the presentation tier. Hibernate eliminates the first purpose. However, you will still need - an assembly phase (think of your business methods as having a strict contract with the presentation - tier about what data is available in the detached objects) unless you are prepared to hold the - persistence context (the session) open across the view rendering process. This is not a limitation - of Hibernate! It is a fundamental requirement of safe transactional data access. - - - - - Consider abstracting your business logic from Hibernate. - - - Hide (Hibernate) data-access code behind an interface. Combine the DAO and - Thread Local Session patterns. You can even have some classes persisted by - handcoded JDBC, associated to Hibernate via a UserType. (This advice is - intended for "sufficiently large" applications; it is not appropriate for an application with - five tables!) - - - - - Don't use exotic association mappings. - - - Good usecases for a real many-to-many associations are rare. Most of the time you need - additional information stored in the "link table". In this case, it is much better to - use two one-to-many associations to an intermediate link class. In fact, we think that - most associations are one-to-many and many-to-one, you should be careful when using any - other association style and ask yourself if it is really neccessary. - - - - - Prefer bidirectional associations. - - - Unidirectional associations are more difficult to query. In a large application, almost - all associations must be navigable in both directions in queries. - - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/collection_mapping.xml b/documentation/envers/src/main/docbook/en-US/content/collection_mapping.xml deleted file mode 100644 index d09cf76f20..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/collection_mapping.xml +++ /dev/null @@ -1,1260 +0,0 @@ - - - - - - - Collection Mapping - - - Persistent collections - - - Hibernate requires that persistent collection-valued fields be declared - as an interface type, for example: - - - - - - The actual interface might be java.util.Set, - java.util.Collection, java.util.List, - java.util.Map, java.util.SortedSet, - java.util.SortedMap or ... anything you like! (Where - "anything you like" means you will have to write an implementation of - org.hibernate.usertype.UserCollectionType.) - - - - Notice how we initialized the instance variable with an instance of - HashSet. This is the best way to initialize collection - valued properties of newly instantiated (non-persistent) instances. When - you make the instance persistent - by calling persist(), - for example - Hibernate will actually replace the HashSet - with an instance of Hibernate's own implementation of Set. - Watch out for errors like this: - - - - - - The persistent collections injected by Hibernate behave like - HashMap, HashSet, - TreeMap, TreeSet or - ArrayList, depending upon the interface type. - - - - Collections instances have the usual behavior of value types. They are - automatically persisted when referenced by a persistent object and - automatically deleted when unreferenced. If a collection is passed from one - persistent object to another, its elements might be moved from one table to - another. Two entities may not share a reference to the same collection - instance. Due to the underlying relational model, collection-valued properties - do not support null value semantics; Hibernate does not distinguish between - a null collection reference and an empty collection. - - - - You shouldn't have to worry much about any of this. Use persistent collections - the same way you use ordinary Java collections. Just make sure you understand - the semantics of bidirectional associations (discussed later). - - - - - - Collection mappings - - - - There are quite a range of mappings that can be generated for collections, covering - many common relational models. We suggest you experiment with the schema generation tool - to get a feeling for how various mapping declarations translate to database tables. - - - - - The Hibernate mapping element used for mapping a collection depends upon - the type of the interface. For example, a <set> - element is used for mapping properties of type Set. - - - - - - - - -]]> - - - Apart from <set>, there is also - <list>, <map>, - <bag>, <array> and - <primitive-array> mapping elements. The - <map> element is representative: - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - - name the collection property name - - - - - table (optional - defaults to property name) the - name of the collection table (not used for one-to-many associations) - - - - - schema (optional) the name of a table schema to - override the schema declared on the root element - - - - - lazy (optional - defaults to true) - may be used to disable lazy fetching and specify that the association is - always eagerly fetched, or to enable "extra-lazy" fetching where most - operations do not initialize the collection (suitable for very large - collections) - - - - - inverse (optional - defaults to false) - mark this collection as the "inverse" end of a bidirectional association - - - - - cascade (optional - defaults to none) - enable operations to cascade to child entities - - - - - sort (optional) specify a sorted collection with - natural sort order, or a given comparator class - - - - - order-by (optional, JDK1.4 only) specify a table column (or columns) - that define the iteration order of the Map, Set - or bag, together with an optional asc or desc - - - - - where (optional) specify an arbitrary SQL WHERE - condition to be used when retrieving or removing the collection (useful if the - collection should contain only a subset of the available data) - - - - - fetch (optional, defaults to select) Choose - between outer-join fetching, fetching by sequential select, and fetching by sequential - subselect. - - - - - batch-size (optional, defaults to 1) specify a - "batch size" for lazily fetching instances of this collection. - - - - - access (optional - defaults to property): The - strategy Hibernate should use for accessing the collection property value. - - - - - optimistic-lock (optional - defaults to true): - Species that changes to the state of the collection results in increment of the - owning entity's version. (For one to many associations, it is often reasonable to - disable this setting.) - - - - - mutable (optional - defaults to true): - A value of false specifies that the elements of the - collection never change (a minor performance optimization in some cases). - - - - - - - Collection foreign keys - - - Collection instances are distinguished in the database by the foreign key of - the entity that owns the collection. This foreign key is referred to as the - collection key column (or columns) of the collection - table. The collection key column is mapped by the <key> - element. - - - - There may be a nullability constraint on the foreign key column. For most - collections, this is implied. For unidirectional one to many associations, - the foreign key column is nullable by default, so you might need to specify - not-null="true". - - - ]]> - - - The foreign key constraint may use ON DELETE CASCADE. - - - ]]> - - - See the previous chapter for a full definition of the <key> - element. - - - - - - Collection elements - - - Collections may contain almost any other Hibernate type, including all basic types, - custom types, components, and of course, references to other entities. This is an - important distinction: an object in a collection might be handled with "value" - semantics (its life cycle fully depends on the collection owner) or it might be a - reference to another entity, with its own life cycle. In the latter case, only the - "link" between the two objects is considered to be state held by the collection. - - - - The contained type is referred to as the collection element type. - Collection elements are mapped by <element> or - <composite-element>, or in the case of entity references, - with <one-to-many> or <many-to-many>. - The first two map elements with value semantics, the next two are used to map entity - associations. - - - - - - Indexed collections - - - All collection mappings, except those with set and bag semantics, need an - index column in the collection table - a column that maps to an - array index, or List index, or Map key. The - index of a Map may be of any basic type, mapped with - <map-key>, it may be an entity reference mapped with - <map-key-many-to-many>, or it may be a composite type, - mapped with <composite-map-key>. The index of an array or - list is always of type integer and is mapped using the - <list-index> element. The mapped column contains - sequential integers (numbered from zero, by default). - - - - - - - - ]]> - - - - column_name (required): The name of the column holding the - collection index values. - - - - - base (optional, defaults to 0): The value - of the index column that corresponds to the first element of the list or array. - - - - - - - - - - - - ]]> - - - - column (optional): The name of the column holding the - collection index values. - - - - - formula (optional): A SQL formula used to evaluate the - key of the map. - - - - - type (reguired): The type of the map keys. - - - - - - - - - - - - ]]> - - - - column (optional): The name of the foreign key - column for the collection index values. - - - - - formula (optional): A SQL formula used to evaluate the - foreign key of the map key. - - - - - class (required): The entity class used as the map key. - - - - - - - - If your table doesn't have an index column, and you still wish to use List - as the property type, you should map the property as a Hibernate <bag>. - A bag does not retain its order when it is retrieved from the database, but it may be - optionally sorted or ordered. - - - - - - Collections of values and many-to-many associations - - - Any collection of values or many-to-many association requires a dedicated - collection table with a foreign key column or columns, - collection element column or columns and possibly - an index column or columns. - - - - For a collection of values, we use the <element> tag. - - - - - - - - - ]]> - - - - column (optional): The name of the column holding the - collection element values. - - - - - formula (optional): An SQL formula used to evaluate the - element. - - - - - type (required): The type of the collection element. - - - - - - - A many-to-many association is specified using the - <many-to-many> element. - - - - - - - - - - - - - - ]]> - - - - column (optional): The name of the element foreign key column. - - - - - formula (optional): An SQL formula used to evaluate the element - foreign key value. - - - - - class (required): The name of the associated class. - - - - - fetch (optional - defaults to join): - enables outer-join or sequential select fetching for this association. This - is a special case; for full eager fetching (in a single SELECT) - of an entity and its many-to-many relationships to other entities, you would - enable join fetching not only of the collection itself, - but also with this attribute on the <many-to-many> - nested element. - - - - - unique (optional): Enable the DDL generation of a unique - constraint for the foreign-key column. This makes the association multiplicity - effectively one to many. - - - - - not-found (optional - defaults to exception): - Specifies how foreign keys that reference missing rows will be handled: - ignore will treat a missing row as a null association. - - - - - entity-name (optional): The entity name of the associated class, - as an alternative to class. - - - - - 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. - - - - - - - Some examples, first, a set of strings: - - - - - -]]> - - - A bag containing integers (with an iteration order determined by the - order-by attribute): - - - - - -]]> - - - An array of entities - in this case, a many to many association: - - - - - - -]]> - - - A map from string indices to dates: - - - - - - -]]> - - - A list of components (discussed in the next chapter): - - - - - - - - - - -]]> - - - - - One-to-many associations - - - A one to many association links the tables of two classes - via a foreign key, with no intervening collection table. This mapping loses - certain semantics of normal Java collections: - - - - - - An instance of the contained entity class may not belong to more than - one instance of the collection - - - - - An instance of the contained entity class may not appear at more than - one value of the collection index - - - - - - An association from Product to Part requires - existence of a foreign key column and possibly an index column to the Part - table. A <one-to-many> tag indicates that this is a one to many - association. - - - - - - - - - ]]> - - - - class (required): The name of the associated class. - - - - - not-found (optional - defaults to exception): - Specifies how cached identifiers that reference missing rows will be handled: - ignore will treat a missing row as a null association. - - - - - entity-name (optional): The entity name of the associated class, - as an alternative to class. - - - - - - - Notice that the <one-to-many> element does not need to - declare any columns. Nor is it necessary to specify the table - name anywhere. - - - - Very important note: If the foreign key column of a - <one-to-many> association is declared NOT NULL, - you must declare the <key> mapping - not-null="true" or use a bidirectional association - with the collection mapping marked inverse="true". See the discussion - of bidirectional associations later in this chapter. - - - - This example shows a map of Part entities by name (where - partName is a persistent property of Part). - Notice the use of a formula-based index. - - - - - - -]]> - - - - - - Advanced collection mappings - - - Sorted collections - - - Hibernate supports collections implementing java.util.SortedMap and - java.util.SortedSet. You must specify a comparator in the mapping file: - - - - - - - - - - - -]]> - - - Allowed values of the sort attribute are unsorted, - natural and the name of a class implementing - java.util.Comparator. - - - - Sorted collections actually behave like java.util.TreeSet or - java.util.TreeMap. - - - - If you want the database itself to order the collection elements use the - order-by attribute of set, bag - or map mappings. This solution is only available under - JDK 1.4 or higher (it is implemented using LinkedHashSet or - LinkedHashMap). This performs the ordering in the SQL query, - not in memory. - - - - - - - - - - - -]]> - - - Note that the value of the order-by attribute is an SQL ordering, not - a HQL ordering! - - - - Associations may even be sorted by some arbitrary criteria at runtime using a collection - filter(). - - - - - - - - Bidirectional associations - - - A bidirectional association allows navigation from both - "ends" of the association. Two kinds of bidirectional association are - supported: - - - - one-to-many - - - set or bag valued at one end, single-valued at the other - - - - - many-to-many - - - set or bag valued at both ends - - - - - - - - - You may specify a bidirectional many-to-many association simply by mapping two - many-to-many associations to the same database table and declaring one end as - inverse (which one is your choice, but it can not be an - indexed collection). - - - - Here's an example of a bidirectional many-to-many association; each category can - have many items and each item can be in many categories: - - - - - ... - - - - - - - - - ... - - - - - - -]]> - - - Changes made only to the inverse end of the association are not - persisted. This means that Hibernate has two representations in memory for every - bidirectional association, one link from A to B and another link from B to A. This - is easier to understand if you think about the Java object model and how we create - a many-to-many relationship in Java: - - - - - - The non-inverse side is used to save the in-memory representation to the database. - - - - You may define a bidirectional one-to-many association by mapping a one-to-many association - to the same table column(s) as a many-to-one association and declaring the many-valued - end inverse="true". - - - - - .... - - - - - - - - - .... - -]]> - - - Mapping one end of an association with inverse="true" doesn't - affect the operation of cascades, these are orthogonal concepts! - - - - - - Bidirectional associations with indexed collections - - A bidirectional association where one end is represented as a <list> - or <map> requires special consideration. If there is a property of - the child class which maps to the index column, no problem, we can continue using - inverse="true" on the collection mapping: - - - - - .... - - - - - - - - - - .... - - -]]> - - - But, if there is no such property on the child class, we can't think of the association as - truly bidirectional (there is information available at one end of the association that is - not available at the other end). In this case, we can't map the collection - inverse="true". Instead, we could use the following mapping: - - - - - .... - - - - - - - - - - .... - -]]> - - - Note that in this mapping, the collection-valued end of the association is responsible for - updates to the foreign key. TODO: Does this really result in some unnecessary update statements? - - - - - - Ternary associations - - - There are three possible approaches to mapping a ternary association. One is to use a - Map with an association as its index: - - - - - - -]]> - - - - - -]]> - - - A second approach is to simply remodel the association as an entity class. This - is the approach we use most commonly. - - - - A final alternative is to use composite elements, which we will discuss later. - - - - - - <literal>Using an <idbag></literal> - - - If you've fully embraced our view that composite keys are a bad thing and that - entities should have synthetic identifiers (surrogate keys), then you might - find it a bit odd that the many to many associations and collections of values - that we've shown so far all map to tables with composite keys! Now, this point - is quite arguable; a pure association table doesn't seem to benefit much from - a surrogate key (though a collection of composite values might). - Nevertheless, Hibernate provides a feature that allows you to map many to many - associations and collections of values to a table with a surrogate key. - - - - The <idbag> element lets you map a List - (or Collection) with bag semantics. - - - - - - - - -]]> - - - As you can see, an <idbag> has a synthetic id generator, - just like an entity class! A different surrogate key is assigned to each collection - row. Hibernate does not provide any mechanism to discover the surrogate key value - of a particular row, however. - - - - Note that the update performance of an <idbag> is - much better than a regular <bag>! - Hibernate can locate individual rows efficiently and update or delete them - individually, just like a list, map or set. - - - - In the current implementation, the native identifier generation - strategy is not supported for <idbag> collection identifiers. - - - - - - - - - - - - Collection examples - - - The previous sections are pretty confusing. So lets look at an example. This - class: - - - - - - has a collection of Child instances. If each - child has at most one parent, the most natural mapping is a - one-to-many association: - - - - - - - - - - - - - - - - - - - - - -]]> - - - This maps to the following table definitions: - - - - - - If the parent is required, use a bidirectional one-to-many - association: - - - - - - - - - - - - - - - - - - - - - - -]]> - - - Notice the NOT NULL constraint: - - - - - - Alternatively, if you absolutely insist that this association should be unidirectional, - you can declare the NOT NULL constraint on the <key> - mapping: - - - - - - - - - - - - - - - - - - - - - -]]> - - - On the other hand, if a child might have multiple parents, a many-to-many - association is appropriate: - - - - - - - - - - - - - - - - - - - - - -]]> - - - Table definitions: - - - - - - For more examples and a complete walk-through a parent/child relationship mapping, - see . - - - - Even more exotic association mappings are possible, we will catalog all possibilities - in the next chapter. - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/component_mapping.xml b/documentation/envers/src/main/docbook/en-US/content/component_mapping.xml deleted file mode 100644 index 436a02852b..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/component_mapping.xml +++ /dev/null @@ -1,429 +0,0 @@ - - - - - - - Component Mapping - - - The notion of a component is re-used in several different contexts, - for different purposes, throughout Hibernate. - - - - Dependent objects - - - A component is a contained object that is persisted as a value type, not an entity - reference. The term "component" refers to the object-oriented notion of composition - (not to architecture-level components). For example, you might model a person like this: - - - - - - - - Now Name may be persisted as a component of - Person. Notice that Name defines getter - and setter methods for its persistent properties, but doesn't need to declare - any interfaces or identifier properties. - - - - Our Hibernate mapping would look like: - - - - - - - - - - - - -]]> - - - The person table would have the columns pid, - birthday, - initial, - first and - last. - - - - Like all value types, components do not support shared references. In other words, two - persons could have the same name, but the two person objects would contain two independent - name ojects, only "the same" by value. The null value semantics of a component are - ad hoc. When reloading the containing object, Hibernate will assume - that if all component columns are null, then the entire component is null. This should - be okay for most purposes. - - - - The properties of a component may be of any Hibernate type (collections, many-to-one - associations, other components, etc). Nested components should not - be considered an exotic usage. Hibernate is intended to support a very fine-grained - object model. - - - - The <component> element allows a <parent> - subelement that maps a property of the component class as a reference back to the - containing entity. - - - - - - - - - - - - - -]]> - - - - - Collections of dependent objects - - - Collections of components are supported (eg. an array of type - Name). Declare your component collection by - replacing the <element> tag with a - <composite-element> tag. - - - - - - - - - -]]> - - - Note: if you define a Set of composite elements, it is - very important to implement equals() and - hashCode() correctly. - - - - Composite elements may contain components but not collections. If your - composite element itself contains - components, use the <nested-composite-element> - tag. This is a pretty exotic case - a collection of components which - themselves have components. By this stage you should be asking yourself - if a one-to-many association is more appropriate. Try remodelling the - composite element as an entity - but note that even though the Java model - is the same, the relational model and persistence semantics are still - slightly different. - - - - Please note that a composite element mapping doesn't support null-able properties - if you're using a <set>. Hibernate - has to use each columns value to identify a record when deleting objects - (there is no separate primary key column in the composite element table), - which is not possible with null values. You have to either use only - not-null properties in a composite-element or choose a - <list>, <map>, - <bag> or <idbag>. - - - - A special case of a composite element is a composite element with a nested - <many-to-one> element. A mapping like this allows - you to map extra columns of a many-to-many association table to the - composite element class. The following is a many-to-many association - from Order to Item where - purchaseDate, price and - quantity are properties of the association: - - - - .... - - - - - - - - - -]]> - - - Of course, there can't be a reference to the purchae on the other side, for - bidirectional association navigation. Remember that components are value types and - don't allow shared references. A single Purchase can be in the - set of an Order, but it can't be referenced by the Item - at the same time. - - - Even ternary (or quaternary, etc) associations are possible: - - - .... - - - - - - - -]]> - - - Composite elements may appear in queries using the same syntax as - associations to other entities. - - - - - - Components as Map indices - - - The <composite-map-key> element lets you map a - component class as the key of a Map. Make sure you override - hashCode() and equals() correctly on - the component class. - - - - - Components as composite identifiers - - - You may use a component as an identifier of an entity class. Your component - class must satisfy certain requirements: - - - - - - It must implement java.io.Serializable. - - - - - It must re-implement equals() and - hashCode(), consistently with the database's - notion of composite key equality. - - - - - - Note: in Hibernate3, the second requirement is not an absolutely hard - requirement of Hibernate. But do it anyway. - - - - You can't use an IdentifierGenerator to generate composite keys. - Instead the application must assign its own identifiers. - - - - Use the <composite-id> tag (with nested - <key-property> elements) in place of the usual - <id> declaration. For example, the - OrderLine class has a primary key that depends upon - the (composite) primary key of Order. - - - - - - - - - - - - - - - - - .... - -]]> - - - Now, any foreign keys referencing the OrderLine table are also - composite. You must declare this in your mappings for other classes. An association - to OrderLine would be mapped like this: - - - - - - - -]]> - - - (Note that the <column> tag is an alternative to the - column attribute everywhere.) - - - - A many-to-many association to OrderLine also - uses the composite foreign key: - - - - - - - - - -]]> - - - The collection of OrderLines in Order would - use: - - - - - - - - -]]> - - - (The <one-to-many> element, as usual, declares no columns.) - - - - If OrderLine itself owns a collection, it also has a composite - foreign key. - - - - .... - .... - - - - - - - - - ... - - -]]> - - - - - Dynamic components - - - You may even map a property of type Map: - - - - - - -]]> - - - The semantics of a <dynamic-component> mapping are identical - to <component>. The advantage of this kind of mapping is - the ability to determine the actual properties of the bean at deployment time, just - by editing the mapping document. Runtime manipulation of the mapping document is - also possible, using a DOM parser. Even better, you can access (and change) Hibernate's - configuration-time metamodel via the Configuration object. - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/configuration.xml b/documentation/envers/src/main/docbook/en-US/content/configuration.xml deleted file mode 100644 index b87575d865..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/configuration.xml +++ /dev/null @@ -1,1759 +0,0 @@ - - - - - - - Configuration - - - Because Hibernate is designed to operate in many different environments, there - are a large number of configuration parameters. Fortunately, most have sensible - default values and Hibernate is distributed with an example - hibernate.properties file in etc/ that shows - the various options. Just put the example file in your classpath and customize it. - - - - Programmatic configuration - - - An instance of org.hibernate.cfg.Configuration represents an entire set of mappings - of an application's Java types to an SQL database. The org.hibernate.cfg.Configuration - is used to build an (immutable) org.hibernate.SessionFactory. The mappings - are compiled from various XML mapping files. - - - - You may obtain a org.hibernate.cfg.Configuration instance by instantiating - it directly and specifying XML mapping documents. If the mapping files are in the classpath, - use addResource(): - - - - - - An alternative (sometimes better) way is to specify the mapped class, and - let Hibernate find the mapping document for you: - - - - - - Then Hibernate will look for mapping files named /org/hibernate/auction/Item.hbm.xml - and /org/hibernate/auction/Bid.hbm.xml in the classpath. This approach eliminates any - hardcoded filenames. - - - - A org.hibernate.cfg.Configuration also allows you to specify configuration - properties: - - - - - - This is not the only way to pass configuration properties to Hibernate. - The various options include: - - - - - - Pass an instance of java.util.Properties to - Configuration.setProperties(). - - - - - Place a file named hibernate.properties in a root directory of the classpath. - - - - - Set System properties using java -Dproperty=value. - - - - - Include <property> elements in - hibernate.cfg.xml (discussed later). - - - - - - hibernate.properties is the easiest approach if you want to get started quickly. - - - - The org.hibernate.cfg.Configuration is intended as a startup-time object, - to be discarded once a SessionFactory is created. - - - - - - Obtaining a SessionFactory - - - When all mappings have been parsed by the org.hibernate.cfg.Configuration, - the application must obtain a factory for org.hibernate.Session instances. - This factory is intended to be shared by all application threads: - - - - - - Hibernate does allow your application to instantiate more than one - org.hibernate.SessionFactory. This is useful if you are using more than - one database. - - - - - - JDBC connections - - - Usually, you want to have the org.hibernate.SessionFactory create and pool - JDBC connections for you. If you take this approach, opening a org.hibernate.Session - is as simple as: - - - - - - As soon as you do something that requires access to the database, a JDBC connection will be obtained from - the pool. - - - - For this to work, we need to pass some JDBC connection properties to Hibernate. All Hibernate property - names and semantics are defined on the class org.hibernate.cfg.Environment. We will - now describe the most important settings for JDBC connection configuration. - - - - Hibernate will obtain (and pool) connections using java.sql.DriverManager - if you set the following properties: - - - - Hibernate JDBC Properties - - - - - - Property name - Purpose - - - - - - hibernate.connection.driver_class - - - JDBC driver class - - - - - hibernate.connection.url - - - JDBC URL - - - - - hibernate.connection.username - - - database user - - - - - hibernate.connection.password - - - database user password - - - - - hibernate.connection.pool_size - - - maximum number of pooled connections - - - - -
- - - Hibernate's own connection pooling algorithm is however quite rudimentary. - It is intended to help you get started and is not intended for use - in a production system or even for performance testing. You should - use a third party pool for best performance and stability. Just replace the - hibernate.connection.pool_size property with connection - pool specific settings. This will turn off Hibernate's internal pool. For - example, you might like to use C3P0. - - - - C3P0 is an open source JDBC connection pool distributed along with Hibernate in the lib - directory. Hibernate will use its org.hibernate.connection.C3P0ConnectionProvider - for connection pooling if you set hibernate.c3p0.* properties. If you'd like to use Proxool - refer to the packaged hibernate.properties and the Hibernate web site for more - information. - - - - Here is an example hibernate.properties file for C3P0: - - - - - - For use inside an application server, you should almost always configure Hibernate to obtain connections - from an application server javax.sql.Datasource registered in JNDI. You'll - need to set at least one of the following properties: - - - - Hibernate Datasource Properties - - - - - - Property name - Purpose - - - - - - hibernate.connection.datasource - - - datasource JNDI name - - - - - hibernate.jndi.url - - - URL of the JNDI provider (optional) - - - - - hibernate.jndi.class - - - class of the JNDI InitialContextFactory (optional) - - - - - hibernate.connection.username - - - database user (optional) - - - - - hibernate.connection.password - - - database user password (optional) - - - - -
- - - Here's an example hibernate.properties file for an application server provided JNDI - datasource: - - - - - - JDBC connections obtained from a JNDI datasource will automatically participate - in the container-managed transactions of the application server. - - - - Arbitrary connection properties may be given by prepending "hibernate.connection" to the - connection property name. For example, you may specify a charSet - connection property using hibernate.connection.charSet. - - - - You may define your own plugin strategy for obtaining JDBC connections by implementing the - interface org.hibernate.connection.ConnectionProvider, and specifying your - custom implementation via the hibernate.connection.provider_class property. - - - - - - Optional configuration properties - - - There are a number of other properties that control the behaviour of Hibernate at runtime. All are optional - and have reasonable default values. - - - - Warning: some of these properties are "system-level" only. System-level properties can - be set only via java -Dproperty=value or hibernate.properties. They - may not be set by the other techniques described above. - - - - Hibernate Configuration Properties - - - - - - Property name - Purpose - - - - - - hibernate.dialect - - - The classname of a Hibernate org.hibernate.dialect.Dialect which - allows Hibernate to generate SQL optimized for a particular relational database. - - eg. - full.classname.of.Dialect - - - In most cases Hibernate will actually be able to chose the correct - org.hibernate.dialect.Dialect implementation to use based on the - JDBC metadata returned by the JDBC driver. - - - - - - hibernate.show_sql - - - Write all SQL statements to console. This is an alternative - to setting the log category org.hibernate.SQL - to debug. - - eg. - true | false - - - - - - hibernate.format_sql - - - Pretty print the SQL in the log and console. - - eg. - true | false - - - - - - hibernate.default_schema - - - Qualify unqualified table names with the given schema/tablespace - in generated SQL. - - eg. - SCHEMA_NAME - - - - - - hibernate.default_catalog - - - Qualify unqualified table names with the given catalog - in generated SQL. - - eg. - CATALOG_NAME - - - - - - hibernate.session_factory_name - - - The org.hibernate.SessionFactory will be automatically - bound to this name in JNDI after it has been created. - - eg. - jndi/composite/name - - - - - - hibernate.max_fetch_depth - - - Set a maximum "depth" for the outer join fetch tree - for single-ended associations (one-to-one, many-to-one). - A 0 disables default outer join fetching. - - eg. - recommended values between 0 and - 3 - - - - - - hibernate.default_batch_fetch_size - - - Set a default size for Hibernate batch fetching of associations. - - eg. - recommended values 4, 8, - 16 - - - - - - hibernate.default_entity_mode - - - Set a default mode for entity representation for all sessions - opened from this SessionFactory - - dynamic-map, dom4j, - pojo - - - - - - hibernate.order_updates - - - Force Hibernate to order SQL updates by the primary key value - of the items being updated. This will result in fewer transaction - deadlocks in highly concurrent systems. - - eg. - true | false - - - - - - hibernate.generate_statistics - - - If enabled, Hibernate will collect statistics useful for - performance tuning. - - eg. - true | false - - - - - - hibernate.use_identifier_rollback - - - If enabled, generated identifier properties will be - reset to default values when objects are deleted. - - eg. - true | false - - - - - - hibernate.use_sql_comments - - - If turned on, Hibernate will generate comments inside the SQL, for - easier debugging, defaults to false. - - eg. - true | false - - - - - -
- - - Hibernate JDBC and Connection Properties - - - - - Property name - Purpose - - - - - - hibernate.jdbc.fetch_size - - - A non-zero value determines the JDBC fetch size (calls - Statement.setFetchSize()). - - - - - hibernate.jdbc.batch_size - - - A non-zero value enables use of JDBC2 batch updates by Hibernate. - - eg. - recommended values between 5 and 30 - - - - - - hibernate.jdbc.batch_versioned_data - - - Set this property to true if your JDBC driver returns - correct row counts from executeBatch() (it is usually - safe to turn this option on). Hibernate will then use batched DML for - automatically versioned data. Defaults to false. - - eg. - true | false - - - - - - hibernate.jdbc.factory_class - - - Select a custom org.hibernate.jdbc.Batcher. Most applications - will not need this configuration property. - - eg. - classname.of.BatcherFactory - - - - - - hibernate.jdbc.use_scrollable_resultset - - - Enables use of JDBC2 scrollable resultsets by Hibernate. - This property is only necessary when using user supplied - JDBC connections, Hibernate uses connection metadata otherwise. - - eg. - true | false - - - - - - hibernate.jdbc.use_streams_for_binary - - - Use streams when writing/reading binary or serializable - types to/from JDBC. *system-level property* - - eg. - true | false - - - - - - hibernate.jdbc.use_get_generated_keys - - - Enable use of JDBC3 PreparedStatement.getGeneratedKeys() - to retrieve natively generated keys after insert. Requires JDBC3+ driver - and JRE1.4+, set to false if your driver has problems with the Hibernate - identifier generators. By default, tries to determine the driver capabilities - using connection metadata. - - eg. - true|false - - - - - - hibernate.connection.provider_class - - - The classname of a custom org.hibernate.connection.ConnectionProvider - which provides JDBC connections to Hibernate. - - eg. - classname.of.ConnectionProvider - - - - - - hibernate.connection.isolation - - - Set the JDBC transaction isolation level. Check java.sql.Connection - for meaningful values but note that most databases do not support all isolation levels and some - define additional, non-standard isolations. - - eg. - 1, 2, 4, 8 - - - - - - hibernate.connection.autocommit - - - Enables autocommit for JDBC pooled connections (not recommended). - - eg. - true | false - - - - - - hibernate.connection.release_mode - - - Specify when Hibernate should release JDBC connections. By default, - a JDBC connection is held until the session is explicitly closed or - disconnected. For an application server JTA datasource, you should use - after_statement to aggressively release connections - after every JDBC call. For a non-JTA connection, it often makes sense to - release the connection at the end of each transaction, by using - after_transaction. auto will - choose after_statement for the JTA and CMT transaction - strategies and after_transaction for the JDBC - transaction strategy. - - eg. - auto (default) | on_close | - after_transaction | after_statement - - - Note that this setting only affects Sessions returned from - SessionFactory.openSession. For Sessions - obtained through SessionFactory.getCurrentSession, the - CurrentSessionContext implementation configured for use - controls the connection release mode for those Sessions. - See - - - - - - hibernate.connection.<propertyName> - - - Pass the JDBC property <propertyName> - to DriverManager.getConnection(). - - - - - hibernate.jndi.<propertyName> - - - Pass the property <propertyName> to - the JNDI InitialContextFactory. - - - - -
- - - Hibernate Cache Properties - - - - - - Property name - Purpose - - - - - - hibernate.cache.provider_class - - - The classname of a custom CacheProvider. - - eg. - classname.of.CacheProvider - - - - - - hibernate.cache.use_minimal_puts - - - Optimize second-level cache operation to minimize writes, at the - cost of more frequent reads. This setting is most useful for - clustered caches and, in Hibernate3, is enabled by default for - clustered cache implementations. - - eg. - true|false - - - - - - hibernate.cache.use_query_cache - - - Enable the query cache, individual queries still have to be set cachable. - - eg. - true|false - - - - - - hibernate.cache.use_second_level_cache - - - May be used to completely disable the second level cache, which is enabled - by default for classes which specify a <cache> - mapping. - - eg. - true|false - - - - - - hibernate.cache.query_cache_factory - - - The classname of a custom QueryCache interface, - defaults to the built-in StandardQueryCache. - - eg. - classname.of.QueryCache - - - - - - hibernate.cache.region_prefix - - - A prefix to use for second-level cache region names. - - eg. - prefix - - - - - - hibernate.cache.use_structured_entries - - - Forces Hibernate to store data in the second-level cache - in a more human-friendly format. - - eg. - true|false - - - - - -
- - - Hibernate Transaction Properties - - - - - - Property name - Purpose - - - - - - hibernate.transaction.factory_class - - - The classname of a TransactionFactory - to use with Hibernate Transaction API - (defaults to JDBCTransactionFactory). - - eg. - classname.of.TransactionFactory - - - - - - jta.UserTransaction - - - A JNDI name used by JTATransactionFactory to - obtain the JTA UserTransaction from the - application server. - - eg. - jndi/composite/name - - - - - - hibernate.transaction.manager_lookup_class - - - The classname of a TransactionManagerLookup - - required when JVM-level caching is enabled or when using hilo - generator in a JTA environment. - - eg. - classname.of.TransactionManagerLookup - - - - - - hibernate.transaction.flush_before_completion - - - If enabled, the session will be automatically flushed during the - before completion phase of the transaction. Built-in and - automatic session context management is preferred, see - . - - eg. - true | false - - - - - - hibernate.transaction.auto_close_session - - - If enabled, the session will be automatically closed during the - after completion phase of the transaction. Built-in and - utomatic session context management is preferred, see - . - - eg. - true | false - - - - - -
- - - Miscellaneous Properties - - - - - - Property name - Purpose - - - - - - hibernate.current_session_context_class - - - Supply a (custom) strategy for the scoping of the "current" - Session. See - for more - information about the built-in strategies. - - eg. - jta | thread | - managed | custom.Class - - - - - - hibernate.query.factory_class - - - Chooses the HQL parser implementation. - - eg. - org.hibernate.hql.ast.ASTQueryTranslatorFactory or - org.hibernate.hql.classic.ClassicQueryTranslatorFactory - - - - - - hibernate.query.substitutions - - - Mapping from tokens in Hibernate queries to SQL tokens - (tokens might be function or literal names, for example). - - eg. - hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC - - - - - - hibernate.hbm2ddl.auto - - - Automatically validate or export schema DDL to the database - when the SessionFactory is created. With - create-drop, the database schema will be - dropped when the SessionFactory is closed - explicitly. - - eg. - validate | update | - create | create-drop - - - - - - hibernate.cglib.use_reflection_optimizer - - - Enables use of CGLIB instead of runtime reflection (System-level - property). Reflection can sometimes be useful when troubleshooting, - note that Hibernate always requires CGLIB even if you turn off the - optimizer. You can not set this property in hibernate.cfg.xml. - - eg. - true | false - - - - - -
- - - SQL Dialects - - - You should always set the hibernate.dialect property to the correct - org.hibernate.dialect.Dialect subclass for your database. If you - specify a dialect, Hibernate will use sensible defaults for some of the - other properties listed above, saving you the effort of specifying them manually. - - - - Hibernate SQL Dialects (<literal>hibernate.dialect</literal>) - - - - - RDBMS - Dialect - - - - - DB2 org.hibernate.dialect.DB2Dialect - - - DB2 AS/400 org.hibernate.dialect.DB2400Dialect - - - DB2 OS390 org.hibernate.dialect.DB2390Dialect - - - PostgreSQL org.hibernate.dialect.PostgreSQLDialect - - - MySQL org.hibernate.dialect.MySQLDialect - - - MySQL with InnoDB org.hibernate.dialect.MySQLInnoDBDialect - - - MySQL with MyISAM org.hibernate.dialect.MySQLMyISAMDialect - - - Oracle (any version) org.hibernate.dialect.OracleDialect - - - Oracle 9i/10g org.hibernate.dialect.Oracle9Dialect - - - Sybase org.hibernate.dialect.SybaseDialect - - - Sybase Anywhere org.hibernate.dialect.SybaseAnywhereDialect - - - Microsoft SQL Server org.hibernate.dialect.SQLServerDialect - - - SAP DB org.hibernate.dialect.SAPDBDialect - - - Informix org.hibernate.dialect.InformixDialect - - - HypersonicSQL org.hibernate.dialect.HSQLDialect - - - Ingres org.hibernate.dialect.IngresDialect - - - Progress org.hibernate.dialect.ProgressDialect - - - Mckoi SQL org.hibernate.dialect.MckoiDialect - - - Interbase org.hibernate.dialect.InterbaseDialect - - - Pointbase org.hibernate.dialect.PointbaseDialect - - - FrontBase org.hibernate.dialect.FrontbaseDialect - - - Firebird org.hibernate.dialect.FirebirdDialect - - - -
- - - - - Outer Join Fetching - - - If your database supports ANSI, Oracle or Sybase style outer joins, outer join - fetching will often increase performance by limiting the number of round - trips to and from the database (at the cost of possibly more work performed by - the database itself). Outer join fetching allows a whole graph of objects connected - by many-to-one, one-to-many, many-to-many and one-to-one associations to be retrieved - in a single SQL SELECT. - - - - Outer join fetching may be disabled globally by setting - the property hibernate.max_fetch_depth to 0. - A setting of 1 or higher enables outer join fetching for - one-to-one and many-to-one associations which have been mapped with - fetch="join". - - - - See for more information. - - - - - - Binary Streams - - - Oracle limits the size of byte arrays that may - be passed to/from its JDBC driver. If you wish to use large instances of - binary or serializable type, you should - enable hibernate.jdbc.use_streams_for_binary. - This is a system-level setting only. - - - - - - Second-level and query cache - - - The properties prefixed by hibernate.cache - allow you to use a process or cluster scoped second-level cache system - with Hibernate. See the for - more details. - - - - - - Query Language Substitution - - - You may define new Hibernate query tokens using hibernate.query.substitutions. - For example: - - - hibernate.query.substitutions true=1, false=0 - - - would cause the tokens true and false to be translated to - integer literals in the generated SQL. - - - hibernate.query.substitutions toLowercase=LOWER - - - would allow you to rename the SQL LOWER function. - - - - - - Hibernate statistics - - - If you enable hibernate.generate_statistics, Hibernate will - expose a number of metrics that are useful when tuning a running system via - SessionFactory.getStatistics(). Hibernate can even be configured - to expose these statistics via JMX. Read the Javadoc of the interfaces in - org.hibernate.stats for more information. - - - - - - - Logging - - - Hibernate utilizes Simple Logging Facade for Java - (SLF4J) in order to log various system events. SLF4J can direct your logging output to - several logging frameworks (NOP, Simple, log4j version 1.2, JDK 1.4 logging, JCL or logback) depending on your - chosen binding. In order to setup logging properly you will need slf4j-api.jar in - your classpath together with the jar file for your preferred binding - slf4j-log4j12.jar - in the case of Log4J. See the SLF4J documentation for more detail. - To use Log4j you will also need to place a log4j.properties file in your classpath, - an example properties file is distributed with Hibernate in the src/ directory. - - - - We strongly recommend that you familiarize yourself with Hibernate's log - messages. A lot of work has been put into making the Hibernate log as - detailed as possible, without making it unreadable. It is an essential - troubleshooting device. The most interesting log categories are the - following: - - - - Hibernate Log Categories - - - - - - Category - Function - - - - - org.hibernate.SQL - Log all SQL DML statements as they are executed - - - org.hibernate.type - Log all JDBC parameters - - - org.hibernate.tool.hbm2ddl - Log all SQL DDL statements as they are executed - - - org.hibernate.pretty - - Log the state of all entities (max 20 entities) associated - with the session at flush time - - - - org.hibernate.cache - Log all second-level cache activity - - - org.hibernate.transaction - Log transaction related activity - - - org.hibernate.jdbc - Log all JDBC resource acquisition - - - org.hibernate.hql.ast.AST - - Log HQL and SQL ASTs during query parsing - - - - org.hibernate.secure - Log all JAAS authorization requests - - - org.hibernate - - Log everything (a lot of information, but very useful for - troubleshooting) - - - - -
- - - When developing applications with Hibernate, you should almost always work with - debug enabled for the category org.hibernate.SQL, - or, alternatively, the property hibernate.show_sql enabled. - - - - - - - Implementing a <literal>NamingStrategy</literal> - - - The interface org.hibernate.cfg.NamingStrategy allows you - to specify a "naming standard" for database objects and schema elements. - - - - You may provide rules for automatically generating database identifiers from - Java identifiers or for processing "logical" column and table names given in - the mapping file into "physical" table and column names. This feature helps - reduce the verbosity of the mapping document, eliminating repetitive noise - (TBL_ prefixes, for example). The default strategy used by - Hibernate is quite minimal. - - - - You may specify a different strategy by calling - Configuration.setNamingStrategy() before adding mappings: - - - - - - org.hibernate.cfg.ImprovedNamingStrategy is a built-in - strategy that might be a useful starting point for some applications. - - - - - - XML configuration file - - - An alternative approach to configuration is to specify a full configuration in - a file named hibernate.cfg.xml. This file can be used as a - replacement for the hibernate.properties file or, if both - are present, to override properties. - - - - The XML configuration file is by default expected to be in the root o - your CLASSPATH. Here is an example: - - - - - - - - - - - - java:/comp/env/jdbc/MyDB - org.hibernate.dialect.MySQLDialect - false - - org.hibernate.transaction.JTATransactionFactory - - java:comp/UserTransaction - - - - - - - - - - - - -]]> - - - As you can see, the advantage of this approach is the externalization of the - mapping file names to configuration. The hibernate.cfg.xml - is also more convenient once you have to tune the Hibernate cache. Note that is - your choice to use either hibernate.properties or - hibernate.cfg.xml, both are equivalent, except for the above - mentioned benefits of using the XML syntax. - - - - With the XML configuration, starting Hibernate is then as simple as - - - - - - You can pick a different XML configuration file using - - - - - - - - J2EE Application Server integration - - - Hibernate has the following integration points for J2EE infrastructure: - - - - - - Container-managed datasources: Hibernate can use - JDBC connections managed by the container and provided through JNDI. Usually, - a JTA compatible TransactionManager and a - ResourceManager take care of transaction management (CMT), - esp. distributed transaction handling across several datasources. You may - of course also demarcate transaction boundaries programmatically (BMT) or - you might want to use the optional Hibernate Transaction - API for this to keep your code portable. - - - - - - - - Automatic JNDI binding: Hibernate can bind its - SessionFactory to JNDI after startup. - - - - - - - - JTA Session binding: The Hibernate Session - may be automatically bound to the scope of JTA transactions. Simply - lookup the SessionFactory from JNDI and get the current - Session. Let Hibernate take care of flushing and closing the - Session when your JTA transaction completes. Transaction - demarcation is either declarative (CMT) or programmatic (BMT/UserTransaction). - - - - - - - - JMX deployment: If you have a JMX capable application server - (e.g. JBoss AS), you can chose to deploy Hibernate as a managed MBean. This saves - you the one line startup code to build your SessionFactory from - a Configuration. The container will startup your - HibernateService, and ideally also take care of service - dependencies (Datasource has to be available before Hibernate starts, etc). - - - - - - Depending on your environment, you might have to set the configuration option - hibernate.connection.aggressive_release to true if your - application server shows "connection containment" exceptions. - - - - Transaction strategy configuration - - - The Hibernate Session API is independent of any transaction - demarcation system in your architecture. If you let Hibernate use JDBC directly, - through a connection pool, you may begin and end your transactions by calling - the JDBC API. If you run in a J2EE application server, you might want to use bean-managed - transactions and call the JTA API and UserTransaction when needed. - - - - To keep your code portable between these two (and other) environments we recommend the optional - Hibernate Transaction API, which wraps and hides the underlying system. - You have to specify a factory class for Transaction instances by setting the - Hibernate configuration property hibernate.transaction.factory_class. - - - - There are three standard (built-in) choices: - - - - - org.hibernate.transaction.JDBCTransactionFactory - - delegates to database (JDBC) transactions (default) - - - - org.hibernate.transaction.JTATransactionFactory - - - delegates to container-managed transaction if an existing transaction is - underway in this context (e.g. EJB session bean method), otherwise - a new transaction is started and bean-managed transaction are used. - - - - - org.hibernate.transaction.CMTTransactionFactory - - delegates to container-managed JTA transactions - - - - - - You may also define your own transaction strategies (for a CORBA transaction service, - for example). - - - - Some features in Hibernate (i.e. the second level cache, Contextual Sessions with JTA, etc.) - require access to the JTA TransactionManager in a managed environment. - In an application server you have to specify how Hibernate should obtain a reference to the - TransactionManager, since J2EE does not standardize a single mechanism: - - - - JTA TransactionManagers - - - - - - Transaction Factory - Application Server - - - - - org.hibernate.transaction.JBossTransactionManagerLookup - JBoss - - - org.hibernate.transaction.WeblogicTransactionManagerLookup - Weblogic - - - org.hibernate.transaction.WebSphereTransactionManagerLookup - WebSphere - - - org.hibernate.transaction.WebSphereExtendedJTATransactionLookup - WebSphere 6 - - - org.hibernate.transaction.OrionTransactionManagerLookup - Orion - - - org.hibernate.transaction.ResinTransactionManagerLookup - Resin - - - org.hibernate.transaction.JOTMTransactionManagerLookup - JOTM - - - org.hibernate.transaction.JOnASTransactionManagerLookup - JOnAS - - - org.hibernate.transaction.JRun4TransactionManagerLookup - JRun4 - - - org.hibernate.transaction.BESTransactionManagerLookup - Borland ES - - - -
- - - - - JNDI-bound <literal>SessionFactory</literal> - - - A JNDI bound Hibernate SessionFactory can simplify the lookup - of the factory and the creation of new Sessions. Note that this - is not related to a JNDI bound Datasource, both simply use the - same registry! - - - - If you wish to have the SessionFactory bound to a JNDI namespace, specify - a name (eg. java:hibernate/SessionFactory) using the property - hibernate.session_factory_name. If this property is omitted, the - SessionFactory will not be bound to JNDI. (This is especially useful in - environments with a read-only JNDI default implementation, e.g. Tomcat.) - - - - When binding the SessionFactory to JNDI, Hibernate will use the values of - hibernate.jndi.url, hibernate.jndi.class to instantiate - an initial context. If they are not specified, the default InitialContext - will be used. - - - - Hibernate will automatically place the SessionFactory in JNDI after - you call cfg.buildSessionFactory(). This means you will at least have - this call in some startup code (or utility class) in your application, unless you use - JMX deployment with the HibernateService (discussed later). - - - - If you use a JNDI SessionFactory, an EJB or any other class may - obtain the SessionFactory using a JNDI lookup. - - - - We recommend that you bind the SessionFactory to JNDI in - a managed environment and use a static singleton otherwise. - To shield your application code from these details, we also recommend to hide the - actual lookup code for a SessionFactory in a helper class, - such as HibernateUtil.getSessionFactory(). Note that such a - class is also a convenient way to startup Hibernate—see chapter 1. - - - - - - Current Session context management with JTA - - - The easiest way to handle Sessions and transactions is - Hibernates automatic "current" Session management. - See the discussion of current sessions. - Using the "jta" session context, if there is no Hibernate - Session associated with the current JTA transaction, one will - be started and associated with that JTA transaction the first time you call - sessionFactory.getCurrentSession(). The Sessions - retrieved via getCurrentSession() in "jta" context - will be set to automatically flush before the transaction completes, close - after the transaction completes, and aggressively release JDBC connections - after each statement. This allows the Sessions to - be managed by the life cycle of the JTA transaction to which it is associated, - keeping user code clean of such management concerns. Your code can either use - JTA programmatically through UserTransaction, or (recommended - for portable code) use the Hibernate Transaction API to set - transaction boundaries. If you run in an EJB container, declarative transaction - demarcation with CMT is preferred. - - - - - - JMX deployment - - - The line cfg.buildSessionFactory() still has to be executed - somewhere to get a SessionFactory into JNDI. You can do this - either in a static initializer block (like the one in - HibernateUtil) or you deploy Hibernate as a managed - service. - - - - Hibernate is distributed with org.hibernate.jmx.HibernateService - for deployment on an application server with JMX capabilities, such as JBoss AS. - The actual deployment and configuration is vendor specific. Here is an example - jboss-service.xml for JBoss 4.0.x: - - - - - - - - - jboss.jca:service=RARDeployer - jboss.jca:service=LocalTxCM,name=HsqlDS - - - java:/hibernate/SessionFactory - - - java:HsqlDS - org.hibernate.dialect.HSQLDialect - - - - org.hibernate.transaction.JTATransactionFactory - - org.hibernate.transaction.JBossTransactionManagerLookup - true - true - - - 5 - - - true - org.hibernate.cache.EhCacheProvider - true - - - true - - - auction/Item.hbm.xml,auction/Category.hbm.xml - - - -]]> - - - This file is deployed in a directory called META-INF and packaged - in a JAR file with the extension .sar (service archive). You also need - to package Hibernate, its required third-party libraries, your compiled persistent classes, - as well as your mapping files in the same archive. Your enterprise beans (usually session - beans) may be kept in their own JAR file, but you may include this EJB JAR file in the - main service archive to get a single (hot-)deployable unit. Consult the JBoss AS - documentation for more information about JMX service and EJB deployment. - - - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/events.xml b/documentation/envers/src/main/docbook/en-US/content/events.xml deleted file mode 100755 index b7855ae1c1..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/events.xml +++ /dev/null @@ -1,292 +0,0 @@ - - - - - - - Interceptors and events - - - It is often useful for the application to react to certain events that occur - inside Hibernate. This allows implementation of certain kinds of generic - functionality, and extension of Hibernate functionality. - - - - Interceptors - - - The Interceptor interface provides callbacks from the session to the - application allowing the application to inspect and/or manipulate properties of a - persistent object before it is saved, updated, deleted or loaded. One - possible use for this is to track auditing information. For example, the following - Interceptor automatically sets the createTimestamp - when an Auditable is created and updates the - lastUpdateTimestamp property when an Auditable is - updated. - - - - You may either implement Interceptor directly or (better) extend - EmptyInterceptor. - - - - - - Interceptors come in two flavors: Session-scoped and - SessionFactory-scoped. - - - - A Session-scoped interceptor is specified - when a session is opened using one of the overloaded SessionFactory.openSession() - methods accepting an Interceptor. - - - - - - A SessionFactory-scoped interceptor is registered with the Configuration - object prior to building the SessionFactory. In this case, the supplied interceptor - will be applied to all sessions opened from that SessionFactory; this is true unless - a session is opened explicitly specifying the interceptor to use. SessionFactory-scoped - interceptors must be thread safe, taking care to not store session-specific state since multiple - sessions will use this interceptor (potentially) concurrently. - - - - - - - - Event system - - - If you have to react to particular events in your persistence layer, you may - also use the Hibernate3 event architecture. The event - system can be used in addition or as a replacement for interceptors. - - - - Essentially all of the methods of the Session interface correlate - to an event. You have a LoadEvent, a FlushEvent, etc - (consult the XML configuration-file DTD or the org.hibernate.event - package for the full list of defined event types). When a request is made of one of - these methods, the Hibernate Session generates an appropriate - event and passes it to the configured event listeners for that type. Out-of-the-box, - these listeners implement the same processing in which those methods always resulted. - However, you are free to implement a customization of one of the listener interfaces - (i.e., the LoadEvent is processed by the registered implemenation - of the LoadEventListener interface), in which case their - implementation would be responsible for processing any load() requests - made of the Session. - - - - The listeners should be considered effectively singletons; meaning, they are shared between - requests, and thus should not save any state as instance variables. - - - - A custom listener should implement the appropriate interface for the event it wants to - process and/or extend one of the convenience base classes (or even the default event - listeners used by Hibernate out-of-the-box as these are declared non-final for this - purpose). Custom listeners can either be registered programmatically through the - Configuration object, or specified in the Hibernate configuration - XML (declarative configuration through the properties file is not supported). Here's an - example of a custom load event listener: - - - - - - You also need a configuration entry telling Hibernate to use the listener in addition - to the default listener: - - - - - ... - - - - - -]]> - - - Instead, you may register it programmatically: - - - - - - Listeners registered declaratively cannot share instances. If the same class name is - used in multiple <listener/> elements, each reference will - result in a separate instance of that class. If you need the capability to share - listener instances between listener types you must use the programmatic registration - approach. - - - - Why implement an interface and define the specific type during configuration? Well, a - listener implementation could implement multiple event listener interfaces. Having the - type additionally defined during registration makes it easier to turn custom listeners on - or off during configuration. - - - - - - Hibernate declarative security - - Usually, declarative security in Hibernate applications is managed in a session facade - layer. Now, Hibernate3 allows certain actions to be permissioned via JACC, and authorized - via JAAS. This is optional functionality built on top of the event architecture. - - - - First, you must configure the appropriate event listeners, to enable the use of JAAS - authorization. - - - - - -]]> - - - Note that <listener type="..." class="..."/> is just a shorthand - for <event type="..."><listener class="..."/></event> - when there is exactly one listener for a particular event type. - - - - Next, still in hibernate.cfg.xml, bind the permissions to roles: - - - -]]> - - - The role names are the roles understood by your JACC provider. - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/example_mappings.xml b/documentation/envers/src/main/docbook/en-US/content/example_mappings.xml deleted file mode 100644 index 14f899c499..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/example_mappings.xml +++ /dev/null @@ -1,685 +0,0 @@ - - - - - - - Example: Various Mappings - - - This chapters shows off some more complex association mappings. - - - - Employer/Employee - - - The following model of the relationship between Employer and - Employee uses an actual entity class (Employment) - to represent the association. This is done because there might be more than one - period of employment for the same two parties. Components are used to model monetary - values and employee names. - - - - - - - - - - - - - Heres a possible mapping document: - - - - - - - - employer_id_seq - - - - - - - - - - employment_id_seq - - - - - - - - - - - - - - - - - - - - - employee_id_seq - - - - - - - - - - -]]> - - - And heres the table schema generated by SchemaExport. - - - - - - - - Author/Work - - - Consider the following model of the relationships between Work, - Author and Person. We represent the relationship - between Work and Author as a many-to-many - association. We choose to represent the relationship between Author - and Person as one-to-one association. Another possibility would be to - have Author extend Person. - - - - - - - - - - - - - The following mapping document correctly represents these relationships: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - There are four tables in this mapping. works, - authors and persons hold work, author - and person data respectively. author_work is an association - table linking authors to works. Heres the table schema, as generated by - SchemaExport. - - - - - - - - Customer/Order/Product - - - Now consider a model of the relationships between Customer, - Order and LineItem and Product. - There is a one-to-many association between Customer and - Order, but how should we represent Order / - LineItem / Product? I've chosen to map - LineItem as an association class representing the many-to-many - association between Order and Product. In - Hibernate, this is called a composite element. - - - - - - - - - - - - - The mapping document: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - customers, orders, line_items and - products hold customer, order, order line item and product data - respectively. line_items also acts as an association table linking - orders with products. - - - - - - - - Miscellaneous example mappings - - - These examples are all taken from the Hibernate test suite. You - will find many other useful example mappings there. Look in the - test folder of the Hibernate distribution. - - - TODO: put words around this stuff - - - "Typed" one-to-one association - - - - name - 'HOME' - - - name - 'MAILING' - - - - - - - - - - - -]]> - - - - Composite key example - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ( select sum(li.quantity*p.price) - from LineItem li, Product p - where li.productId = p.productId - and li.customerId = customerId - and li.orderNumber = orderNumber ) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ( select sum(li.quantity) - from LineItem li - where li.productId = productId ) - - - -]]> - - - - Many-to-many with shared composite key attribute - - - - - - - - - - - - - org - - - - - - - - - - - - - - - - - - org - - - -]]> - - - - Content based discrimination - - - - - - - - - - case - when title is not null then 'E' - when salesperson is not null then 'C' - else 'P' - end - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - - Associations on alternate keys - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/example_parentchild.xml b/documentation/envers/src/main/docbook/en-US/content/example_parentchild.xml deleted file mode 100644 index 14779d97cb..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/example_parentchild.xml +++ /dev/null @@ -1,388 +0,0 @@ - - - - - - - Example: Parent/Child - - - One of the very first things that new users try to do with Hibernate is to model a parent / child type - relationship. There are two different approaches to this. For various reasons the most convenient - approach, especially for new users, is to model both Parent and Child - as entity classes with a <one-to-many> association from Parent - to Child. (The alternative approach is to declare the Child as a - <composite-element>.) Now, it turns out that default semantics of a one to many - association (in Hibernate) are much less close to the usual semantics of a parent / child relationship than - those of a composite element mapping. We will explain how to use a bidirectional one to many - association with cascades to model a parent / child relationship efficiently and elegantly. - It's not at all difficult! - - - - A note about collections - - - Hibernate collections are considered to be a logical part of their owning entity; never of the - contained entities. This is a crucial distinction! It has the following consequences: - - - - - - When we remove / add an object from / to a collection, the version number of the collection owner - is incremented. - - - - - If an object that was removed from a collection is an instance of a value type (eg, a composite - element), that object will cease to be persistent and its state will be completely removed from - the database. Likewise, adding a value type instance to the collection will cause its state to be - immediately persistent. - - - - - On the other hand, if an entity is removed from a collection (a one-to-many or many-to-many - association), it will not be deleted, by default. This behaviour is completely consistent - a - change to the internal state of another entity should not cause the associated entity to vanish! - Likewise, adding an entity to a collection does not cause that entity to become persistent, by - default. - - - - - - Instead, the default behaviour is that adding an entity to a collection merely creates a link between - the two entities, while removing it removes the link. This is very appropriate for all sorts of cases. - Where it is not appropriate at all is the case of a parent / child relationship, where the life of the - child is bound to the life cycle of the parent. - - - - - - Bidirectional one-to-many - - - Suppose we start with a simple <one-to-many> association from - Parent to Child. - - - - - -]]> - - - If we were to execute the following code - - - - - - Hibernate would issue two SQL statements: - - - - - an INSERT to create the record for c - - - - an UPDATE to create the link from p to - c - - - - - - This is not only inefficient, but also violates any NOT NULL constraint on the - parent_id column. We can fix the nullability constraint violation by specifying - not-null="true" in the collection mapping: - - - - - -]]> - - - However, this is not the recommended solution. - - - The underlying cause of this behaviour is that the link (the foreign key parent_id) - from p to c is not considered part of the state of the - Child object and is therefore not created in the INSERT. So the - solution is to make the link part of the Child mapping. - - - ]]> - - - (We also need to add the parent property to the Child class.) - - - - Now that the Child entity is managing the state of the link, we tell the collection - not to update the link. We use the inverse attribute. - - - - - -]]> - - - The following code would be used to add a new Child - - - - - - And now, only one SQL INSERT would be issued! - - - - To tighten things up a bit, we could create an addChild() method of - Parent. - - - - - - Now, the code to add a Child looks like - - - - - - - - Cascading life cycle - - - The explicit call to save() is still annoying. We will address this by - using cascades. - - - - - -]]> - - - This simplifies the code above to - - - - - - Similarly, we don't need to iterate over the children when saving or deleting a Parent. - The following removes p and all its children from the database. - - - - - - However, this code - - - - - - will not remove c from the database; it will ony remove the link to p - (and cause a NOT NULL constraint violation, in this case). You need to explicitly - delete() the Child. - - - - - - Now, in our case, a Child can't really exist without its parent. So if we remove - a Child from the collection, we really do want it to be deleted. For this, we must - use cascade="all-delete-orphan". - - - - - -]]> - - - Note: even though the collection mapping specifies inverse="true", cascades are - still processed by iterating the collection elements. So if you require that an object be saved, - deleted or updated by cascade, you must add it to the collection. It is not enough to simply call - setParent(). - - - - - - Cascades and <literal>unsaved-value</literal> - - - Suppose we loaded up a Parent in one Session, made some changes - in a UI action and wish to persist these changes in a new session by calling update(). - The Parent will contain a collection of childen and, since cascading update is enabled, - Hibernate needs to know which children are newly instantiated and which represent existing rows in the - database. Lets assume that both Parent and Child have genenerated - identifier properties of type Long. Hibernate will use the identifier and - version/timestamp property value to determine which of the children are new. (See - .) In Hibernate3, it is no longer necessary to specify - an unsaved-value explicitly. - - - - The following code will update parent and child and insert - newChild. - - - - - - Well, that's all very well for the case of a generated identifier, but what about assigned identifiers - and composite identifiers? This is more difficult, since Hibernate can't use the identifier property to - distinguish between a newly instantiated object (with an identifier assigned by the user) and an - object loaded in a previous session. In this case, Hibernate will either use the timestamp or version - property, or will actually query the second-level cache or, worst case, the database, to see if the - row exists. - - - - - - - Conclusion - - - There is quite a bit to digest here and it might look confusing first time around. However, in practice, - it all works out very nicely. Most Hibernate applications use the parent / child pattern in many places. - - - - We mentioned an alternative in the first paragraph. None of the above issues exist in the case of - <composite-element> mappings, which have exactly the semantics of a parent / child - relationship. Unfortunately, there are two big limitations to composite element classes: composite elements - may not own collections, and they should not be the child of any entity other than the unique parent. - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/example_weblog.xml b/documentation/envers/src/main/docbook/en-US/content/example_weblog.xml deleted file mode 100644 index 78ac629c25..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/example_weblog.xml +++ /dev/null @@ -1,457 +0,0 @@ - - - - - - - Example: Weblog Application - - - Persistent Classes - - - The persistent classes represent a weblog, and an item posted - in a weblog. They are to be modelled as a standard parent/child - relationship, but we will use an ordered bag, instead of a set. - - - - - - - - - - Hibernate Mappings - - - The XML mappings should now be quite straightforward. - - - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - - - Hibernate Code - - - The following class demonstrates some of the kinds of things - we can do with these classes, using Hibernate. - - - :minDate" - ); - - Calendar cal = Calendar.getInstance(); - cal.roll(Calendar.MONTH, false); - q.setCalendar("minDate", cal); - - result = q.list(); - tx.commit(); - } - catch (HibernateException he) { - if (tx!=null) tx.rollback(); - throw he; - } - finally { - session.close(); - } - return result; - } -}]]> - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/filters.xml b/documentation/envers/src/main/docbook/en-US/content/filters.xml deleted file mode 100755 index 5892ee26c7..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/filters.xml +++ /dev/null @@ -1,173 +0,0 @@ - - - - - - - Filtering data - - - Hibernate3 provides an innovative new approach to handling data with "visibility" rules. - A Hibernate filter is a global, named, parameterized filter that may be - enabled or disabled for a particular Hibernate session. - - - - Hibernate filters - - - Hibernate3 adds the ability to pre-define filter criteria and attach those filters at both - a class and a collection level. A filter criteria is the ability to define a restriction clause - very similiar to the existing "where" attribute available on the class and various collection - elements. Except these filter conditions can be parameterized. The application can then make - the decision at runtime whether given filters should be enabled and what their parameter - values should be. Filters can be used like database views, but parameterized inside the - application. - - - - In order to use filters, they must first be defined and then attached to the appropriate - mapping elements. To define a filter, use the <filter-def/> element - within a <hibernate-mapping/> element: - - - - -]]> - - - Then, this filter can be attached to a class: - - - - ... - -]]> - - - or, to a collection: - - - - -]]> - - - or, even to both (or multiples of each) at the same time. - - - - The methods on Session are: enableFilter(String filterName), - getEnabledFilter(String filterName), and disableFilter(String filterName). - By default, filters are not enabled for a given session; they must be explcitly - enabled through use of the Session.enableFilter() method, which returns an - instance of the Filter interface. Using the simple filter defined above, this - would look like: - - - - - - Note that methods on the org.hibernate.Filter interface do allow the method-chaining common to much of Hibernate. - - - - A full example, using temporal data with an effective record date pattern: - - - - - - - -... - - - -... - - - - - -... - - - - - -]]> - - - Then, in order to ensure that you always get back currently effective records, simply - enable the filter on the session prior to retrieving employee data: - - - :targetSalary") - .setLong("targetSalary", new Long(1000000)) - .list(); -]]> - - - In the HQL above, even though we only explicitly mentioned a salary constraint on the results, - because of the enabled filter the query will return only currently active employees who have - a salary greater than a million dollars. - - - - Note: if you plan on using filters with outer joining (either through HQL or load fetching) be - careful of the direction of the condition expression. Its safest to set this up for left - outer joining; in general, place the parameter first followed by the column name(s) after - the operator. - - - - After being defined a filter might be attached to multiple entities and/or - collections each with its own condition. That can be tedious when the - conditions are the same each time. Thus <filter-def/> - allows defining a default condition, either as an attribute or CDATA: - - - xyz">... -abc=xyz]]> - - - This default condition will then be used whenever the filter is attached to something - without specifying a condition. Note that this means you can give a specific condition - as part of the attachment of the filter which overrides the default condition in that - particular case. - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/inheritance_mapping.xml b/documentation/envers/src/main/docbook/en-US/content/inheritance_mapping.xml deleted file mode 100644 index 4fda14b97c..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/inheritance_mapping.xml +++ /dev/null @@ -1,518 +0,0 @@ - - - - - - - Inheritance Mapping - - - The Three Strategies - - - Hibernate supports the three basic inheritance mapping strategies: - - - - - - table per class hierarchy - - - - - table per subclass - - - - - table per concrete class - - - - - - In addition, Hibernate supports a fourth, slightly different kind of - polymorphism: - - - - - - implicit polymorphism - - - - - - It is possible to use different mapping strategies for different - branches of the same inheritance hierarchy, and then make use of implicit - polymorphism to achieve polymorphism across the whole hierarchy. However, - Hibernate does not support mixing <subclass>, - and <joined-subclass> and - <union-subclass> mappings under the same root - <class> element. It is possible to mix together - the table per hierarchy and table per subclass strategies, under the - the same <class> element, by combining the - <subclass> and <join> - elements (see below). - - - - It is possible to define subclass, union-subclass, - and joined-subclass mappings in separate mapping documents, directly beneath - hibernate-mapping. This allows you to extend a class hierachy just by adding - a new mapping file. You must specify an extends attribute in the subclass mapping, - naming a previously mapped superclass. Note: Previously this feature made the ordering of the mapping - documents important. Since Hibernate3, the ordering of mapping files does not matter when using the - extends keyword. The ordering inside a single mapping file still needs to be defined as superclasses - before subclasses. - - - - - - - ]]> - - - - Table per class hierarchy - - - Suppose we have an interface Payment, with implementors - CreditCardPayment, CashPayment, - ChequePayment. The table per hierarchy mapping would - look like: - - - - - - - - - ... - - - ... - - - ... - - - ... - -]]> - - - Exactly one table is required. There is one big limitation of this mapping - strategy: columns declared by the subclasses, such as CCTYPE, - may not have NOT NULL constraints. - - - - - - Table per subclass - - - A table per subclass mapping would look like: - - - - - - - - ... - - - - ... - - - - ... - - - - ... - -]]> - - - Four tables are required. The three subclass tables have primary - key associations to the superclass table (so the relational model - is actually a one-to-one association). - - - - - - Table per subclass, using a discriminator - - - Note that Hibernate's implementation of table per subclass requires - no discriminator column. Other object/relational mappers use a - different implementation of table per subclass which requires a type - discriminator column in the superclass table. The approach taken by - Hibernate is much more difficult to implement but arguably more - correct from a relational point of view. If you would like to use - a discriminator column with the table per subclass strategy, you - may combine the use of <subclass> and - <join>, as follow: - - - - - - - - - ... - - - - - ... - - - - - - ... - - - - - - ... - - -]]> - - - The optional fetch="select" declaration tells Hibernate - not to fetch the ChequePayment subclass data using an - outer join when querying the superclass. - - - - - - Mixing table per class hierarchy with table per subclass - - - You may even mix the table per hierarchy and table per subclass strategies - using this approach: - - - - - - - - - ... - - - - ... - - - - ... - - - ... - -]]> - - - For any of these mapping strategies, a polymorphic association to the root - Payment class is mapped using - <many-to-one>. - - - ]]> - - - - - Table per concrete class - - - There are two ways we could go about mapping the table per concrete class - strategy. The first is to use <union-subclass>. - - - - - - - - ... - - - ... - - - ... - - - ... - -]]> - - - Three tables are involved for the subclasses. Each table defines columns for - all properties of the class, including inherited properties. - - - - The limitation of this approach is that if a property is mapped on the - superclass, the column name must be the same on all subclass tables. - (We might relax this in a future release of Hibernate.) The identity - generator strategy is not allowed in union subclass inheritance, indeed - the primary key seed has to be shared accross all unioned subclasses - of a hierarchy. - - - - If your superclass is abstract, map it with abstract="true". - Of course, if it is not abstract, an additional table (defaults to - PAYMENT in the example above) is needed to hold instances - of the superclass. - - - - - - Table per concrete class, using implicit polymorphism - - - An alternative approach is to make use of implicit polymorphism: - - - - - - - - ... - - - - - - - - ... - - - - - - - - ... -]]> - - - Notice that nowhere do we mention the Payment interface - explicitly. Also notice that properties of Payment are - mapped in each of the subclasses. If you want to avoid duplication, consider - using XML entities - (e.g. [ <!ENTITY allproperties SYSTEM "allproperties.xml"> ] - in the DOCTYPE declartion and - &allproperties; in the mapping). - - - - The disadvantage of this approach is that Hibernate does not generate SQL - UNIONs when performing polymorphic queries. - - - - For this mapping strategy, a polymorphic association to Payment - is usually mapped using <any>. - - - - - - - - -]]> - - - - - Mixing implicit polymorphism with other inheritance mappings - - - There is one further thing to notice about this mapping. Since the subclasses - are each mapped in their own <class> element (and since - Payment is just an interface), each of the subclasses could - easily be part of another inheritance hierarchy! (And you can still use polymorphic - queries against the Payment interface.) - - - - - - - - - ... - - - - - - - - - ... - - - - ... - - - - - ... - -]]> - - - Once again, we don't mention Payment explicitly. If we - execute a query against the Payment interface - for - example, from Payment - Hibernate - automatically returns instances of CreditCardPayment - (and its subclasses, since they also implement Payment), - CashPayment and ChequePayment but - not instances of NonelectronicTransaction. - - - - - - - - Limitations - - - There are certain limitations to the "implicit polymorphism" approach to - the table per concrete-class mapping strategy. There are somewhat less - restrictive limitations to <union-subclass> - mappings. - - - - The following table shows the limitations of table per concrete-class - mappings, and of implicit polymorphism, in Hibernate. - - - - Features of inheritance mappings - - - - - - - - - - - - Inheritance strategy - Polymorphic many-to-one - Polymorphic one-to-one - Polymorphic one-to-many - Polymorphic many-to-many - Polymorphic load()/get() - Polymorphic queries - Polymorphic joins - Outer join fetching - - - - - table per class-hierarchy - <many-to-one> - <one-to-one> - <one-to-many> - <many-to-many> - s.get(Payment.class, id) - from Payment p - from Order o join o.payment p - supported - - - table per subclass - <many-to-one> - <one-to-one> - <one-to-many> - <many-to-many> - s.get(Payment.class, id) - from Payment p - from Order o join o.payment p - supported - - - table per concrete-class (union-subclass) - <many-to-one> - <one-to-one> - <one-to-many> (for inverse="true" only) - <many-to-many> - s.get(Payment.class, id) - from Payment p - from Order o join o.payment p - supported - - - table per concrete class (implicit polymorphism) - <any> - not supported - not supported - <many-to-any> - s.createCriteria(Payment.class).add( Restrictions.idEq(id) ).uniqueResult() - from Payment p - not supported - not supported - - - -
- - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/performance.xml b/documentation/envers/src/main/docbook/en-US/content/performance.xml deleted file mode 100644 index fd9771239f..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/performance.xml +++ /dev/null @@ -1,1439 +0,0 @@ - - - - - - - Improving performance - - - Fetching strategies - - - A fetching strategy is the strategy Hibernate will use for - retrieving associated objects if the application needs to navigate the association. - Fetch strategies may be declared in the O/R mapping metadata, or over-ridden by a - particular HQL or Criteria query. - - - - Hibernate3 defines the following fetching strategies: - - - - - - Join fetching - Hibernate retrieves the - associated instance or collection in the same SELECT, - using an OUTER JOIN. - - - - - Select fetching - a second SELECT - is used to retrieve the associated entity or collection. Unless - you explicitly disable lazy fetching by specifying lazy="false", - this second select will only be executed when you actually access the - association. - - - - - Subselect fetching - a second SELECT - is used to retrieve the associated collections for all entities retrieved in a - previous query or fetch. Unless you explicitly disable lazy fetching by specifying - lazy="false", this second select will only be executed when you - actually access the association. - - - - - Batch fetching - an optimization strategy - for select fetching - Hibernate retrieves a batch of entity instances - or collections in a single SELECT, by specifying - a list of primary keys or foreign keys. - - - - - - Hibernate also distinguishes between: - - - - - - Immediate fetching - an association, collection or - attribute is fetched immediately, when the owner is loaded. - - - - - Lazy collection fetching - a collection is fetched - when the application invokes an operation upon that collection. (This - is the default for collections.) - - - - - "Extra-lazy" collection fetching - individual - elements of the collection are accessed from the database as needed. - Hibernate tries not to fetch the whole collection into memory unless - absolutely needed (suitable for very large collections) - - - - - Proxy fetching - a single-valued association is - fetched when a method other than the identifier getter is invoked - upon the associated object. - - - - - "No-proxy" fetching - a single-valued association is - fetched when the instance variable is accessed. Compared to proxy fetching, - this approach is less lazy (the association is fetched even when only the - identifier is accessed) but more transparent, since no proxy is visible to - the application. This approach requires buildtime bytecode instrumentation - and is rarely necessary. - - - - - Lazy attribute fetching - an attribute or single - valued association is fetched when the instance variable is accessed. - This approach requires buildtime bytecode instrumentation and is rarely - necessary. - - - - - - We have two orthogonal notions here: when is the association - fetched, and how is it fetched (what SQL is used). Don't - confuse them! We use fetch to tune performance. We may use - lazy to define a contract for what data is always available - in any detached instance of a particular class. - - - - Working with lazy associations - - - By default, Hibernate3 uses lazy select fetching for collections and lazy proxy - fetching for single-valued associations. These defaults make sense for almost - all associations in almost all applications. - - - - Note: if you set - hibernate.default_batch_fetch_size, Hibernate will use the - batch fetch optimization for lazy fetching (this optimization may also be enabled - at a more granular level). - - - - However, lazy fetching poses one problem that you must be aware of. Access to a - lazy association outside of the context of an open Hibernate session will result - in an exception. For example: - - - - - - Since the permissions collection was not initialized when the - Session was closed, the collection will not be able to - load its state. Hibernate does not support lazy initialization - for detached objects. The fix is to move the code that reads - from the collection to just before the transaction is committed. - - - - Alternatively, we could use a non-lazy collection or association, - by specifying lazy="false" for the association mapping. - However, it is intended that lazy initialization be used for almost all - collections and associations. If you define too many non-lazy associations - in your object model, Hibernate will end up needing to fetch the entire - database into memory in every transaction! - - - - On the other hand, we often want to choose join fetching (which is non-lazy by - nature) instead of select fetching in a particular transaction. We'll now see - how to customize the fetching strategy. In Hibernate3, the mechanisms for - choosing a fetch strategy are identical for single-valued associations and - collections. - - - - - - Tuning fetch strategies - - - Select fetching (the default) is extremely vulnerable to N+1 selects problems, - so we might want to enable join fetching in the mapping document: - - - - - - - - ]]> - - - The fetch strategy defined in the mapping document affects: - - - - - - retrieval via get() or load() - - - - - retrieval that happens implicitly when an association is navigated - - - - - Criteria queries - - - - - HQL queries if subselect fetching is used - - - - - - No matter what fetching strategy you use, the defined non-lazy graph is guaranteed - to be loaded into memory. Note that this might result in several immediate selects - being used to execute a particular HQL query. - - - - Usually, we don't use the mapping document to customize fetching. Instead, we - keep the default behavior, and override it for a particular transaction, using - left join fetch in HQL. This tells Hibernate to fetch - the association eagerly in the first select, using an outer join. In the - Criteria query API, you would use - setFetchMode(FetchMode.JOIN). - - - - If you ever feel like you wish you could change the fetching strategy used by - get() or load(), simply use a - Criteria query, for example: - - - - - - (This is Hibernate's equivalent of what some ORM solutions call a "fetch plan".) - - - - A completely different way to avoid problems with N+1 selects is to use the - second-level cache. - - - - - - Single-ended association proxies - - - Lazy fetching for collections is implemented using Hibernate's own implementation - of persistent collections. However, a different mechanism is needed for lazy - behavior in single-ended associations. The target entity of the association must - be proxied. Hibernate implements lazy initializing proxies for persistent objects - using runtime bytecode enhancement (via the excellent CGLIB library). - - - - By default, Hibernate3 generates proxies (at startup) for all persistent classes - and uses them to enable lazy fetching of many-to-one and - one-to-one associations. - - - - The mapping file may declare an interface to use as the proxy interface for that - class, with the proxy attribute. By default, Hibernate uses a subclass - of the class. Note that the proxied class must implement a default constructor - with at least package visibility. We recommend this constructor for all persistent classes! - - - - There are some gotchas to be aware of when extending this approach to polymorphic - classes, eg. - - - - ...... - - ..... - -]]> - - - Firstly, instances of Cat will never be castable to - DomesticCat, even if the underlying instance is an - instance of DomesticCat: - - - - - - Secondly, it is possible to break proxy ==. - - - - - - However, the situation is not quite as bad as it looks. Even though we now have two references - to different proxy objects, the underlying instance will still be the same object: - - - - - - Third, you may not use a CGLIB proxy for a final class or a class - with any final methods. - - - - Finally, if your persistent object acquires any resources upon instantiation (eg. in - initializers or default constructor), then those resources will also be acquired by - the proxy. The proxy class is an actual subclass of the persistent class. - - - - These problems are all due to fundamental limitations in Java's single inheritance model. - If you wish to avoid these problems your persistent classes must each implement an interface - that declares its business methods. You should specify these interfaces in the mapping file. eg. - - - - ...... - - ..... - -]]> - - - where CatImpl implements the interface Cat and - DomesticCatImpl implements the interface DomesticCat. Then - proxies for instances of Cat and DomesticCat may be returned - by load() or iterate(). (Note that list() - does not usually return proxies.) - - - - - - Relationships are also lazily initialized. This means you must declare any properties to be of - type Cat, not CatImpl. - - - - Certain operations do not require proxy initialization - - - - - - equals(), if the persistent class does not override - equals() - - - - - hashCode(), if the persistent class does not override - hashCode() - - - - - The identifier getter method - - - - - - Hibernate will detect persistent classes that override equals() or - hashCode(). - - - - By choosing lazy="no-proxy" instead of the default - lazy="proxy", we can avoid the problems associated with typecasting. - However, we will require buildtime bytecode instrumentation, and all operations - will result in immediate proxy initialization. - - - - - - Initializing collections and proxies - - - A LazyInitializationException will be thrown by Hibernate if an uninitialized - collection or proxy is accessed outside of the scope of the Session, ie. when - the entity owning the collection or having the reference to the proxy is in the detached state. - - - - Sometimes we need to ensure that a proxy or collection is initialized before closing the - Session. Of course, we can alway force initialization by calling - cat.getSex() or cat.getKittens().size(), for example. - But that is confusing to readers of the code and is not convenient for generic code. - - - - The static methods Hibernate.initialize() and Hibernate.isInitialized() - provide the application with a convenient way of working with lazily initialized collections or - proxies. Hibernate.initialize(cat) will force the initialization of a proxy, - cat, as long as its Session is still open. - Hibernate.initialize( cat.getKittens() ) has a similar effect for the collection - of kittens. - - - - Another option is to keep the Session open until all needed - collections and proxies have been loaded. In some application architectures, - particularly where the code that accesses data using Hibernate, and the code that - uses it are in different application layers or different physical processes, it - can be a problem to ensure that the Session is open when a - collection is initialized. There are two basic ways to deal with this issue: - - - - - - In a web-based application, a servlet filter can be used to close the - Session only at the very end of a user request, once - the rendering of the view is complete (the Open Session in - View pattern). Of course, this places heavy demands on the - correctness of the exception handling of your application infrastructure. - It is vitally important that the Session is closed and the - transaction ended before returning to the user, even when an exception occurs - during rendering of the view. See the Hibernate Wiki for examples of this - "Open Session in View" pattern. - - - - - In an application with a separate business tier, the business logic must - "prepare" all collections that will be needed by the web tier before - returning. This means that the business tier should load all the data and - return all the data already initialized to the presentation/web tier that - is required for a particular use case. Usually, the application calls - Hibernate.initialize() for each collection that will - be needed in the web tier (this call must occur before the session is closed) - or retrieves the collection eagerly using a Hibernate query with a - FETCH clause or a FetchMode.JOIN in - Criteria. This is usually easier if you adopt the - Command pattern instead of a Session Facade. - - - - - You may also attach a previously loaded object to a new Session - with merge() or lock() before - accessing uninitialized collections (or other proxies). No, Hibernate does not, - and certainly should not do this automatically, since it - would introduce ad hoc transaction semantics! - - - - - - Sometimes you don't want to initialize a large collection, but still need some - information about it (like its size) or a subset of the data. - - - - You can use a collection filter to get the size of a collection without initializing it: - - - - - - The createFilter() method is also used to efficiently retrieve subsets - of a collection without needing to initialize the whole collection: - - - - - - - - Using batch fetching - - - Hibernate can make efficient use of batch fetching, that is, Hibernate can load several uninitialized - proxies if one proxy is accessed (or collections. Batch fetching is an optimization of the lazy select - fetching strategy. There are two ways you can tune batch fetching: on the class and the collection level. - - - - Batch fetching for classes/entities is easier to understand. Imagine you have the following situation - at runtime: You have 25 Cat instances loaded in a Session, each - Cat has a reference to its owner, a Person. - The Person class is mapped with a proxy, lazy="true". If you now - iterate through all cats and call getOwner() on each, Hibernate will by default - execute 25 SELECT statements, to retrieve the proxied owners. You can tune this - behavior by specifying a batch-size in the mapping of Person: - - - ...]]> - - - Hibernate will now execute only three queries, the pattern is 10, 10, 5. - - - - You may also enable batch fetching of collections. For example, if each Person has - a lazy collection of Cats, and 10 persons are currently loaded in the - Session, iterating through all persons will generate 10 SELECTs, - one for every call to getCats(). If you enable batch fetching for the - cats collection in the mapping of Person, Hibernate can pre-fetch - collections: - - - - - ... - -]]> - - - With a batch-size of 3, Hibernate will load 3, 3, 3, 1 collections in four - SELECTs. Again, the value of the attribute depends on the expected number of - uninitialized collections in a particular Session. - - - - Batch fetching of collections is particularly useful if you have a nested tree of items, ie. - the typical bill-of-materials pattern. (Although a nested set or a - materialized path might be a better option for read-mostly trees.) - - - - - - Using subselect fetching - - - If one lazy collection or single-valued proxy has to be fetched, Hibernate loads all of - them, re-running the original query in a subselect. This works in the same way as - batch-fetching, without the piecemeal loading. - - - - - - - - Using lazy property fetching - - - Hibernate3 supports the lazy fetching of individual properties. This optimization technique - is also known as fetch groups. Please note that this is mostly a - marketing feature, as in practice, optimizing row reads is much more important than - optimization of column reads. However, only loading some properties of a class might - be useful in extreme cases, when legacy tables have hundreds of columns and the data model - can not be improved. - - - - To enable lazy property loading, set the lazy attribute on your - particular property mappings: - - - - - - - - - -]]> - - - Lazy property loading requires buildtime bytecode instrumentation! If your persistent - classes are not enhanced, Hibernate will silently ignore lazy property settings and - fall back to immediate fetching. - - - - For bytecode instrumentation, use the following Ant task: - - - - - - - - - - - - - - -]]> - - - A different (better?) way to avoid unnecessary column reads, at least for - read-only transactions is to use the projection features of HQL or Criteria - queries. This avoids the need for buildtime bytecode processing and is - certainly a preferred solution. - - - - You may force the usual eager fetching of properties using fetch all - properties in HQL. - - - - - - - - The Second Level Cache - - - A Hibernate Session is a transaction-level cache of persistent data. It is - possible to configure a cluster or JVM-level (SessionFactory-level) cache on - a class-by-class and collection-by-collection basis. You may even plug in a clustered cache. Be - careful. Caches are never aware of changes made to the persistent store by another application - (though they may be configured to regularly expire cached data). - - - - You have the option to tell Hibernate which caching implementation to use by - specifying the name of a class that implements org.hibernate.cache.CacheProvider - using the property hibernate.cache.provider_class. Hibernate - comes bundled with a number of built-in integrations with open-source cache providers - (listed below); additionally, you could implement your own and plug it in as - outlined above. Note that versions prior to 3.2 defaulted to use EhCache as the - default cache provider; that is no longer the case as of 3.2. - - - - Cache Providers - - - - - - - - - Cache - Provider class - Type - Cluster Safe - Query Cache Supported - - - - - Hashtable (not intended for production use) - org.hibernate.cache.HashtableCacheProvider - memory - - yes - - - EHCache - org.hibernate.cache.EhCacheProvider - memory, disk - - yes - - - OSCache - org.hibernate.cache.OSCacheProvider - memory, disk - - yes - - - SwarmCache - org.hibernate.cache.SwarmCacheProvider - clustered (ip multicast) - yes (clustered invalidation) - - - - JBoss Cache 1.x - org.hibernate.cache.TreeCacheProvider - clustered (ip multicast), transactional - yes (replication) - yes (clock sync req.) - - - JBoss Cache 2 - org.hibernate.cache.jbc2.JBossCacheRegionFactory - clustered (ip multicast), transactional - yes (replication or invalidation) - yes (clock sync req.) - - - -
- - - Cache mappings - - - The <cache> element of a class or collection mapping has the - following form: - - - - - - - - - ]]> - - - - usage (required) specifies the caching strategy: - transactional, - read-write, - nonstrict-read-write or - read-only - - - - - region (optional, defaults to the class or - collection role name) specifies the name of the second level cache - region - - - - - include (optional, defaults to all) - non-lazy specifies that properties of the entity mapped - with lazy="true" may not be cached when attribute-level - lazy fetching is enabled - - - - - - - Alternatively (preferably?), you may specify <class-cache> and - <collection-cache> elements in hibernate.cfg.xml. - - - - The usage attribute specifies a cache concurrency strategy. - - - - - - Strategy: read only - - - If your application needs to read but never modify instances of a persistent class, a - read-only cache may be used. This is the simplest and best performing - strategy. It's even perfectly safe for use in a cluster. - - - - - .... -]]> - - - - - - Strategy: read/write - - - If the application needs to update data, a read-write cache might be appropriate. - This cache strategy should never be used if serializable transaction isolation level is required. - If the cache is used in a JTA environment, you must specify the property - hibernate.transaction.manager_lookup_class, naming a strategy for obtaining the - JTA TransactionManager. In other environments, you should ensure that the transaction - is completed when Session.close() or Session.disconnect() is called. - If you wish to use this strategy in a cluster, you should ensure that the underlying cache implementation - supports locking. The built-in cache providers do not. - - - - - .... - - - .... - -]]> - - - - - Strategy: nonstrict read/write - - - If the application only occasionally needs to update data (ie. if it is extremely unlikely that two - transactions would try to update the same item simultaneously) and strict transaction isolation is - not required, a nonstrict-read-write cache might be appropriate. If the cache is - used in a JTA environment, you must specify hibernate.transaction.manager_lookup_class. - In other environments, you should ensure that the transaction is completed when - Session.close() or Session.disconnect() is called. - - - - - - Strategy: transactional - - - The transactional cache strategy provides support for fully transactional cache - providers such as JBoss TreeCache. Such a cache may only be used in a JTA environment and you must - specify hibernate.transaction.manager_lookup_class. - - - - - - Cache-provider/concurrency-strategy compatibility - - - - None of the cache providers support all of the cache concurrency strategies. - - - - - The following table shows which providers are compatible with which concurrency strategies. - - - - Cache Concurrency Strategy Support - - - - - - - - - Cache - read-only - nonstrict-read-write - read-write - transactional - - - - - Hashtable (not intended for production use) - yes - yes - yes - - - - EHCache - yes - yes - yes - - - - OSCache - yes - yes - yes - - - - SwarmCache - yes - yes - - - - - JBoss Cache 1.x - yes - - - yes - - - JBoss Cache 2 - yes - - - yes - - - -
- - - - - - - Managing the caches - - - Whenever you pass an object to save(), update() - or saveOrUpdate() and whenever you retrieve an object using - load(), get(), list(), - iterate() or scroll(), that object is added - to the internal cache of the Session. - - - When flush() is subsequently called, the state of that object will - be synchronized with the database. If you do not want this synchronization to occur or - if you are processing a huge number of objects and need to manage memory efficiently, - the evict() method may be used to remove the object and its collections - from the first-level cache. - - - - - - The Session also provides a contains() method to determine - if an instance belongs to the session cache. - - - - To completely evict all objects from the session cache, call Session.clear() - - - - For the second-level cache, there are methods defined on SessionFactory for - evicting the cached state of an instance, entire class, collection instance or entire collection - role. - - - - - - The CacheMode controls how a particular session interacts with the second-level - cache. - - - - - - CacheMode.NORMAL - read items from and write items to the second-level cache - - - - - CacheMode.GET - read items from the second-level cache, but don't write to - the second-level cache except when updating data - - - - - CacheMode.PUT - write items to the second-level cache, but don't read from - the second-level cache - - - - - CacheMode.REFRESH - write items to the second-level cache, but don't read from - the second-level cache, bypass the effect of hibernate.cache.use_minimal_puts, forcing - a refresh of the second-level cache for all items read from the database - - - - - - To browse the contents of a second-level or query cache region, use the Statistics - API: - - - - - - You'll need to enable statistics, and, optionally, force Hibernate to keep the cache entries in a - more human-understandable format: - - - - - - - - The Query Cache - - - Query result sets may also be cached. This is only useful for queries that are run - frequently with the same parameters. To use the query cache you must first enable it: - - - - - - This setting causes the creation of two new cache regions - one holding cached query - result sets (org.hibernate.cache.StandardQueryCache), the other - holding timestamps of the most recent updates to queryable tables - (org.hibernate.cache.UpdateTimestampsCache). Note that the query - cache does not cache the state of the actual entities in the result set; it caches - only identifier values and results of value type. So the query cache should always be - used in conjunction with the second-level cache. - - - - Most queries do not benefit from caching, so by default queries are not cached. To - enable caching, call Query.setCacheable(true). This call allows - the query to look for existing cache results or add its results to the cache when - it is executed. - - - - If you require fine-grained control over query cache expiration policies, you may - specify a named cache region for a particular query by calling - Query.setCacheRegion(). - - - - - - If the query should force a refresh of its query cache region, you should call - Query.setCacheMode(CacheMode.REFRESH). This is particularly useful - in cases where underlying data may have been updated via a separate process (i.e., - not modified through Hibernate) and allows the application to selectively refresh - particular query result sets. This is a more efficient alternative to eviction of - a query cache region via SessionFactory.evictQueries(). - - - - - - Understanding Collection performance - - - We've already spent quite some time talking about collections. - In this section we will highlight a couple more issues about - how collections behave at runtime. - - - - Taxonomy - - Hibernate defines three basic kinds of collections: - - - - collections of values - - - one to many associations - - - many to many associations - - - - - This classification distinguishes the various table and foreign key - relationships but does not tell us quite everything we need to know - about the relational model. To fully understand the relational structure - and performance characteristics, we must also consider the structure of - the primary key that is used by Hibernate to update or delete collection - rows. This suggests the following classification: - - - - - indexed collections - - - sets - - - bags - - - - - All indexed collections (maps, lists, arrays) have a primary key consisting - of the <key> and <index> - columns. In this case collection updates are usually extremely efficient - - the primary key may be efficiently indexed and a particular row may be efficiently - located when Hibernate tries to update or delete it. - - - - Sets have a primary key consisting of <key> and element - columns. This may be less efficient for some types of collection element, particularly - composite elements or large text or binary fields; the database may not be able to index - a complex primary key as efficiently. On the other hand, for one to many or many to many - associations, particularly in the case of synthetic identifiers, it is likely to be just - as efficient. (Side-note: if you want SchemaExport to actually create - the primary key of a <set> for you, you must declare all columns - as not-null="true".) - - - - <idbag> mappings define a surrogate key, so they are - always very efficient to update. In fact, they are the best case. - - - - Bags are the worst case. Since a bag permits duplicate element values and has no - index column, no primary key may be defined. Hibernate has no way of distinguishing - between duplicate rows. Hibernate resolves this problem by completely removing - (in a single DELETE) and recreating the collection whenever it - changes. This might be very inefficient. - - - - Note that for a one-to-many association, the "primary key" may not be the physical - primary key of the database table - but even in this case, the above classification - is still useful. (It still reflects how Hibernate "locates" individual rows of the - collection.) - - - - - - Lists, maps, idbags and sets are the most efficient collections to update - - - From the discussion above, it should be clear that indexed collections - and (usually) sets allow the most efficient operation in terms of adding, - removing and updating elements. - - - - There is, arguably, one more advantage that indexed collections have over sets for - many to many associations or collections of values. Because of the structure of a - Set, Hibernate doesn't ever UPDATE a row when - an element is "changed". Changes to a Set always work via - INSERT and DELETE (of individual rows). Once - again, this consideration does not apply to one to many associations. - - - - After observing that arrays cannot be lazy, we would conclude that lists, maps and - idbags are the most performant (non-inverse) collection types, with sets not far - behind. Sets are expected to be the most common kind of collection in Hibernate - applications. This is because the "set" semantics are most natural in the relational - model. - - - - However, in well-designed Hibernate domain models, we usually see that most collections - are in fact one-to-many associations with inverse="true". For these - associations, the update is handled by the many-to-one end of the association, and so - considerations of collection update performance simply do not apply. - - - - - - Bags and lists are the most efficient inverse collections - - - Just before you ditch bags forever, there is a particular case in which bags (and also lists) - are much more performant than sets. For a collection with inverse="true" - (the standard bidirectional one-to-many relationship idiom, for example) we can add elements - to a bag or list without needing to initialize (fetch) the bag elements! This is because - Collection.add() or Collection.addAll() must always - return true for a bag or List (unlike a Set). This can - make the following common code much faster. - - - - - - - - One shot delete - - - Occasionally, deleting collection elements one by one can be extremely inefficient. Hibernate - isn't completely stupid, so it knows not to do that in the case of an newly-empty collection - (if you called list.clear(), for example). In this case, Hibernate will - issue a single DELETE and we are done! - - - - Suppose we add a single element to a collection of size twenty and then remove two elements. - Hibernate will issue one INSERT statement and two DELETE - statements (unless the collection is a bag). This is certainly desirable. - - - - However, suppose that we remove eighteen elements, leaving two and then add thee new elements. - There are two possible ways to proceed - - - - - delete eighteen rows one by one and then insert three rows - - - remove the whole collection (in one SQL DELETE) and insert - all five current elements (one by one) - - - - - Hibernate isn't smart enough to know that the second option is probably quicker in this case. - (And it would probably be undesirable for Hibernate to be that smart; such behaviour might - confuse database triggers, etc.) - - - - Fortunately, you can force this behaviour (ie. the second strategy) at any time by discarding - (ie. dereferencing) the original collection and returning a newly instantiated collection with - all the current elements. This can be very useful and powerful from time to time. - - - - Of course, one-shot-delete does not apply to collections mapped inverse="true". - - - - - - - - Monitoring performance - - - Optimization is not much use without monitoring and access to performance numbers. - Hibernate provides a full range of figures about its internal operations. - Statistics in Hibernate are available per SessionFactory. - - - - Monitoring a SessionFactory - - - You can access SessionFactory metrics in two ways. - Your first option is to call sessionFactory.getStatistics() and - read or display the Statistics yourself. - - - - Hibernate can also use JMX to publish metrics if you enable the - StatisticsService MBean. You may enable a single MBean for all your - SessionFactory or one per factory. See the following code for - minimalistic configuration examples: - - - - - - - - - TODO: This doesn't make sense: In the first case, we retrieve and use the MBean directly. In the second one, we must give - the JNDI name in which the session factory is held before using it. Use - hibernateStatsBean.setSessionFactoryJNDIName("my/JNDI/Name") - - - You can (de)activate the monitoring for a SessionFactory - - - - - at configuration time, set hibernate.generate_statistics to false - - - - - - - at runtime: sf.getStatistics().setStatisticsEnabled(true) - or hibernateStatsBean.setStatisticsEnabled(true) - - - - - - Statistics can be reset programmatically using the clear() method. - A summary can be sent to a logger (info level) using the logSummary() - method. - - - - - - Metrics - - - Hibernate provides a number of metrics, from very basic to the specialized information - only relevant in certain scenarios. All available counters are described in the - Statistics interface API, in three categories: - - - - - Metrics related to the general Session usage, such as - number of open sessions, retrieved JDBC connections, etc. - - - - - Metrics related to he entities, collections, queries, and caches as a - whole (aka global metrics), - - - - - Detailed metrics related to a particular entity, collection, query or - cache region. - - - - - - For example, you can check the cache hit, miss, and put ratio of entities, collections - and queries, and the average time a query needs. Beware that the number of milliseconds - is subject to approximation in Java. Hibernate is tied to the JVM precision, on some - platforms this might even only be accurate to 10 seconds. - - - - Simple getters are used to access the global metrics (i.e. not tied to a particular entity, - collection, cache region, etc.). You can access the metrics of a particular entity, collection - or cache region through its name, and through its HQL or SQL representation for queries. Please - refer to the Statistics, EntityStatistics, - CollectionStatistics, SecondLevelCacheStatistics, - and QueryStatistics API Javadoc for more information. The following - code shows a simple example: - - - - - - To work on all entities, collections, queries and region caches, you can retrieve - the list of names of entities, collections, queries and region caches with the - following methods: getQueries(), getEntityNames(), - getCollectionRoleNames(), and - getSecondLevelCacheRegionNames(). - - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/persistent_classes.xml b/documentation/envers/src/main/docbook/en-US/content/persistent_classes.xml deleted file mode 100644 index b7d601cb4f..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/persistent_classes.xml +++ /dev/null @@ -1,561 +0,0 @@ - - - - - - - Persistent Classes - - - Persistent classes are classes in an application that implement the entities - of the business problem (e.g. Customer and Order in an E-commerce application). - Not all instances of a persistent class are considered to be in the persistent - state - an instance may instead be transient or detached. - - - - Hibernate works best if these classes follow some simple rules, also known - as the Plain Old Java Object (POJO) programming model. However, none of these - rules are hard requirements. Indeed, Hibernate3 assumes very little about - the nature of your persistent objects. You may express a domain model in other - ways: using trees of Map instances, for example. - - - - A simple POJO example - - - Most Java applications require a persistent class representing felines. - - - - - - There are four main rules to follow here: - - - - - Implement a no-argument constructor - - - Cat has a no-argument constructor. All persistent classes must - have a default constructor (which may be non-public) so that Hibernate can instantiate - them using Constructor.newInstance(). We strongly recommend having a - default constructor with at least package visibility for runtime proxy - generation in Hibernate. - - - - - Provide an identifier property (optional) - - - Cat has a property called id. This property - maps to the primary key column of a database table. The property might have been called - anything, and its type might have been any primitive type, any primitive "wrapper" - type, java.lang.String or java.util.Date. (If - your legacy database table has composite keys, you can even use a user-defined class - with properties of these types - see the section on composite identifiers later.) - - - - The identifier property is strictly optional. You can leave them off and let Hibernate - keep track of object identifiers internally. We do not recommend this, however. - - - - In fact, some functionality is available only to classes which declare an - identifier property: - - - - - - Transitive reattachment for detached objects (cascade update or cascade - merge) - see - - - - - Session.saveOrUpdate() - - - - - Session.merge() - - - - - - We recommend you declare consistently-named identifier properties on persistent - classes. We further recommend that you use a nullable (ie. non-primitive) type. - - - - - Prefer non-final classes (optional) - - A central feature of Hibernate, proxies, depends upon the - persistent class being either non-final, or the implementation of an interface - that declares all public methods. - - - You can persist final classes that do not implement an interface - with Hibernate, but you won't be able to use proxies for lazy association fetching - - which will limit your options for performance tuning. - - - You should also avoid declaring public final methods on the - non-final classes. If you want to use a class with a public final - method, you must explicitly disable proxying by setting lazy="false". - - - - - Declare accessors and mutators for persistent fields (optional) - - - Cat declares accessor methods for all its persistent fields. - Many other ORM tools directly persist instance variables. We believe it is - better to provide an indirection between the relational schema and internal - data structures of the class. By default, Hibernate persists JavaBeans style - properties, and recognizes method names of the form getFoo, - isFoo and setFoo. You may switch to direct - field access for particular properties, if needed. - - - - Properties need not be declared public - Hibernate can - persist a property with a default, protected or - private get / set pair. - - - - - - - - Implementing inheritance - - - A subclass must also observe the first and second rules. It inherits its - identifier property from the superclass, Cat. - - - - - - - Implementing <literal>equals()</literal> and <literal>hashCode()</literal> - - - You have to override the equals() and hashCode() - methods if you - - - - - intend to put instances of persistent classes in a Set - (the recommended way to represent many-valued associations) - and - - - - - intend to use reattachment of detached instances - - - - - - Hibernate guarantees equivalence of persistent identity (database row) and Java identity - only inside a particular session scope. So as soon as we mix instances retrieved in - different sessions, we must implement equals() and - hashCode() if we wish to have meaningful semantics for - Sets. - - - - The most obvious way is to implement equals()/hashCode() - by comparing the identifier value of both objects. If the value is the same, both must - be the same database row, they are therefore equal (if both are added to a Set, - we will only have one element in the Set). Unfortunately, we can't use that - approach with generated identifiers! Hibernate will only assign identifier values to objects - that are persistent, a newly created instance will not have any identifier value! Furthermore, - if an instance is unsaved and currently in a Set, saving it will assign - an identifier value to the object. If equals() and hashCode() - are based on the identifier value, the hash code would change, breaking the contract of the - Set. See the Hibernate website for a full discussion of this problem. Note - that this is not a Hibernate issue, but normal Java semantics of object identity and equality. - - - - We recommend implementing equals() and hashCode() - using Business key equality. Business key equality means that the - equals() method compares only the properties that form the business - key, a key that would identify our instance in the real world (a - natural candidate key): - - - - - - Note that a business key does not have to be as solid as a database - primary key candidate (see ). - Immutable or unique properties are usually good - candidates for a business key. - - - - - - Dynamic models - - - Note that the following features are currently considered - experimental and may change in the near future. - - - - Persistent entities don't necessarily have to be represented as POJO classes - or as JavaBean objects at runtime. Hibernate also supports dynamic models - (using Maps of Maps at runtime) and the - representation of entities as DOM4J trees. With this approach, you don't - write persistent classes, only mapping files. - - - - By default, Hibernate works in normal POJO mode. You may set a default entity - representation mode for a particular SessionFactory using the - default_entity_mode configuration option (see - . - - - - The following examples demonstrates the representation using Maps. - First, in the mapping file, an entity-name has to be declared - instead of (or in addition to) a class name: - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - - Note that even though associations are declared using target class names, - the target type of an associations may also be a dynamic entity instead - of a POJO. - - - - After setting the default entity mode to dynamic-map - for the SessionFactory, we can at runtime work with - Maps of Maps: - - - - - - The advantages of a dynamic mapping are quick turnaround time for prototyping - without the need for entity class implementation. However, you lose compile-time - type checking and will very likely deal with many exceptions at runtime. Thanks - to the Hibernate mapping, the database schema can easily be normalized and sound, - allowing to add a proper domain model implementation on top later on. - - - - Entity representation modes can also be set on a per Session - basis: - - - - - - - Please note that the call to getSession() using an - EntityMode is on the Session API, not the - SessionFactory. That way, the new Session - shares the underlying JDBC connection, transaction, and other context - information. This means you don't have tocall flush() - and close() on the secondary Session, and - also leave the transaction and connection handling to the primary unit of work. - - - - More information about the XML representation capabilities can be found - in . - - - - - - Tuplizers - - - org.hibernate.tuple.Tuplizer, and its sub-interfaces, are responsible - for managing a particular representation of a piece of data, given that representation's - org.hibernate.EntityMode. If a given piece of data is thought of as - a data structure, then a tuplizer is the thing which knows how to create such a data structure - and how to extract values from and inject values into such a data structure. For example, - for the POJO entity mode, the correpsonding tuplizer knows how create the POJO through its - constructor and how to access the POJO properties using the defined property accessors. - There are two high-level types of Tuplizers, represented by the - org.hibernate.tuple.entity.EntityTuplizer and org.hibernate.tuple.component.ComponentTuplizer - interfaces. EntityTuplizers are responsible for managing the above mentioned - contracts in regards to entities, while ComponentTuplizers do the same for - components. - - - - Users may also plug in their own tuplizers. Perhaps you require that a java.util.Map - implementation other than java.util.HashMap be used while in the - dynamic-map entity-mode; or perhaps you need to define a different proxy generation strategy - than the one used by default. Both would be achieved by defining a custom tuplizer - implementation. Tuplizers definitions are attached to the entity or component mapping they - are meant to manage. Going back to the example of our customer entity: - - - - - - - - - - - - - ... - - - - -public class CustomMapTuplizerImpl - extends org.hibernate.tuple.entity.DynamicMapEntityTuplizer { - // override the buildInstantiator() method to plug in our custom map... - protected final Instantiator buildInstantiator( - org.hibernate.mapping.PersistentClass mappingInfo) { - return new CustomMapInstantiator( mappingInfo ); - } - - private static final class CustomMapInstantiator - extends org.hibernate.tuple.DynamicMapInstantitor { - // override the generateMap() method to return our custom map... - protected final Map generateMap() { - return new CustomMap(); - } - } -}]]> - - - - - - Extentsions - - TODO: Document user-extension framework in the property and proxy packages - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/preface.xml b/documentation/envers/src/main/docbook/en-US/content/preface.xml deleted file mode 100644 index cf4c3aa350..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/preface.xml +++ /dev/null @@ -1,132 +0,0 @@ - - - - - - - Preface - - - Working with object-oriented software and a relational database can be cumbersome - and time consuming in today's enterprise environments. Hibernate is an object/relational - mapping tool for Java environments. The term object/relational mapping (ORM) refers to - the technique of mapping a data representation from an object model to a relational - data model with a SQL-based schema. - - - - Hibernate not only takes care of the mapping from Java classes to - database tables (and from Java data types to SQL data types), but also provides data - query and retrieval facilities and can significantly reduce development time otherwise - spent with manual data handling in SQL and JDBC. - - - - Hibernates goal is to relieve the developer from 95 percent of common data persistence - related programming tasks. Hibernate may not be the best solution for data-centric - applications that only use stored-procedures to implement the business logic in the - database, it is most useful with object-oriented domain models and business logic in - the Java-based middle-tier. However, Hibernate can certainly help you to remove or - encapsulate vendor-specific SQL code and will help with the common task of result set - translation from a tabular representation to a graph of objects. - - - - If you are new to Hibernate and Object/Relational Mapping or even Java, - please follow these steps: - - - - - - Read for a tutorial with step-by-step - instructions. The source code for the tutorial is included in the - distribution in the doc/reference/tutorial/ - directory. - - - - - Read to understand the environments where - Hibernate can be used. - - - - - Have a look at the eg/ directory in the Hibernate - distribution, it contains a simple standalone application. Copy your - JDBC driver to the lib/ directory and edit - etc/hibernate.properties, specifying correct values for - your database. From a command prompt in the distribution directory, - type ant eg (using Ant), or under Windows, type - build eg. - - - - - Use this reference documentation as your primary source of information. - Consider reading Java Persistence with Hibernate - (http://www.manning.com/bauer2) if you need more help with application - design or if you prefer a step-by-step tutorial. Also visit - http://caveatemptor.hibernate.org and download the example application - for Java Persistence with Hibernate. - - - - - FAQs are answered on the Hibernate website. - - - - - Third party demos, examples, and tutorials are linked on the Hibernate - website. - - - - - The Community Area on the Hibernate website is a good resource for - design patterns and various integration solutions (Tomcat, JBoss AS, - Struts, EJB, etc.). - - - - - - If you have questions, use the user forum linked on the Hibernate website. We also - provide a JIRA issue trackings system for bug reports and feature requests. If you - are interested in the development of Hibernate, join the developer mailing list. If - you are interested in translating this documentation into your language, contact us - on the developer mailing list. - - - - Commercial development support, production support, and training for Hibernate is - available through JBoss Inc. (see http://www.hibernate.org/SupportTraining/). - Hibernate is a Professional Open Source project and a critical component of the - JBoss Enterprise Middleware System (JEMS) suite of products. - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/query_criteria.xml b/documentation/envers/src/main/docbook/en-US/content/query_criteria.xml deleted file mode 100644 index ea8bb85465..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/query_criteria.xml +++ /dev/null @@ -1,463 +0,0 @@ - - - - - - - Criteria Queries - - - Hibernate features an intuitive, extensible criteria query API. - - - - Creating a <literal>Criteria</literal> instance - - - The interface org.hibernate.Criteria represents a query against - a particular persistent class. The Session is a factory for - Criteria instances. - - - - - - - - Narrowing the result set - - - An individual query criterion is an instance of the interface - org.hibernate.criterion.Criterion. The class - org.hibernate.criterion.Restrictions defines - factory methods for obtaining certain built-in - Criterion types. - - - - - - Restrictions may be grouped logically. - - - - - - - - There are quite a range of built-in criterion types (Restrictions - subclasses), but one that is especially useful lets you specify SQL directly. - - - - - - The {alias} placeholder with be replaced by the row alias - of the queried entity. - - - - An alternative approach to obtaining a criterion is to get it from a - Property instance. You can create a Property - by calling Property.forName(). - - - - - - - - Ordering the results - - - You may order the results using org.hibernate.criterion.Order. - - - - - - - - - - Associations - - - You may easily specify constraints upon related entities by navigating - associations using createCriteria(). - - - - - - note that the second createCriteria() returns a new - instance of Criteria, which refers to the elements of - the kittens collection. - - - - The following, alternate form is useful in certain circumstances. - - - - - - (createAlias() does not create a new instance of - Criteria.) - - - - Note that the kittens collections held by the Cat instances - returned by the previous two queries are not pre-filtered - by the criteria! If you wish to retrieve just the kittens that match the - criteria, you must use a ResultTransformer. - - - - - - - - Dynamic association fetching - - - You may specify association fetching semantics at runtime using - setFetchMode(). - - - - - - This query will fetch both mate and kittens - by outer join. See for more information. - - - - - - Example queries - - - The class org.hibernate.criterion.Example allows - you to construct a query criterion from a given instance. - - - - - - Version properties, identifiers and associations are ignored. By default, - null valued properties are excluded. - - - - You can adjust how the Example is applied. - - - - - - You can even use examples to place criteria upon associated objects. - - - - - - - - Projections, aggregation and grouping - - The class org.hibernate.criterion.Projections is a - factory for Projection instances. We apply a - projection to a query by calling setProjection(). - - - - - - - - There is no explicit "group by" necessary in a criteria query. Certain - projection types are defined to be grouping projections, - which also appear in the SQL group by clause. - - - - An alias may optionally be assigned to a projection, so that the projected value - may be referred to in restrictions or orderings. Here are two different ways to - do this: - - - - - - - - The alias() and as() methods simply wrap a - projection instance in another, aliased, instance of Projection. - As a shortcut, you can assign an alias when you add the projection to a - projection list: - - - - - - - - You can also use Property.forName() to express projections: - - - - - - - - - - Detached queries and subqueries - - The DetachedCriteria class lets you create a query outside the scope - of a session, and then later execute it using some arbitrary Session. - - - - - - A DetachedCriteria may also be used to express a subquery. Criterion - instances involving subqueries may be obtained via Subqueries or - Property. - - - - - - - - Even correlated subqueries are possible: - - - - - - - - - - Queries by natural identifier - - - For most queries, including criteria queries, the query cache is not very efficient, - because query cache invalidation occurs too frequently. However, there is one special - kind of query where we can optimize the cache invalidation algorithm: lookups by a - constant natural key. In some applications, this kind of query occurs frequently. - The criteria API provides special provision for this use case. - - - - First, you should map the natural key of your entity using - <natural-id>, and enable use of the second-level cache. - - - - - - - - - - - - -]]> - - - Note that this functionality is not intended for use with entities with - mutable natural keys. - - - - Next, enable the Hibernate query cache. - - - - Now, Restrictions.naturalId() allows us to make use of - the more efficient cache algorithm. - - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/query_hql.xml b/documentation/envers/src/main/docbook/en-US/content/query_hql.xml deleted file mode 100644 index 051585a16e..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/query_hql.xml +++ /dev/null @@ -1,1261 +0,0 @@ - - - - - - - HQL: The Hibernate Query Language - - - Hibernate is equipped with an extremely powerful query language that (quite intentionally) - looks very much like SQL. But don't be fooled by the syntax; HQL is fully object-oriented, - understanding notions like inheritence, polymorphism and association. - - - - Case Sensitivity - - - Queries are case-insensitive, except for names of Java classes and properties. - So SeLeCT is the same as - sELEct is the same as - SELECT but - org.hibernate.eg.FOO is not - org.hibernate.eg.Foo and - foo.barSet is not - foo.BARSET. - - - - This manual uses lowercase HQL keywords. Some users find queries with uppercase keywords - more readable, but we find this convention ugly when embedded in Java code. - - - - - - The from clause - - - The simplest possible Hibernate query is of the form: - - - - - - which simply returns all instances of the class eg.Cat. - We don't usually need to qualify the class name, since auto-import - is the default. So we almost always just write: - - - - - - Most of the time, you will need to assign an alias, since - you will want to refer to the Cat in other parts of the - query. - - - - - - This query assigns the alias cat to Cat - instances, so we could use that alias later in the query. The as - keyword is optional; we could also write: - - - - - - Multiple classes may appear, resulting in a cartesian product or "cross" join. - - - - - - - It is considered good practice to name query aliases using an initial lowercase, - consistent with Java naming standards for local variables - (eg. domesticCat). - - - - - - Associations and joins - - - We may also assign aliases to associated entities, or even to elements of a - collection of values, using a join. - - - - - - - - - - The supported join types are borrowed from ANSI SQL - - - - - - inner join - - - - - left outer join - - - - - right outer join - - - - - full join (not usually useful) - - - - - - The inner join, left outer join and - right outer join constructs may be abbreviated. - - - - - - You may supply extra join conditions using the HQL with - keyword. - - - 10.0]]> - - - In addition, a "fetch" join allows associations or collections of values to be - initialized along with their parent objects, using a single select. This is particularly - useful in the case of a collection. It effectively overrides the outer join and - lazy declarations of the mapping file for associations and collections. See - for more information. - - - - - - A fetch join does not usually need to assign an alias, because the associated objects - should not be used in the where clause (or any other clause). Also, - the associated objects are not returned directly in the query results. Instead, they may - be accessed via the parent object. The only reason we might need an alias is if we are - recursively join fetching a further collection: - - - - - - Note that the fetch construct may not be used in queries called using - iterate() (though scroll() can be used). Nor should - fetch be used together with setMaxResults() or - setFirstResult() as these operations are based on the result rows, which - usually contain duplicates for eager collection fetching, hence, the number of rows is not what - you'd expect. - Nor may fetch be used together with an ad hoc with condition. - It is possible to create a cartesian product by join fetching more than one collection in a - query, so take care in this case. Join fetching multiple collection roles also sometimes gives - unexpected results for bag mappings, so be careful about how you formulate your queries in this - case. Finally, note that full join fetch and right join fetch - are not meaningful. - - - - If you are using property-level lazy fetching (with bytecode instrumentation), it is - possible to force Hibernate to fetch the lazy properties immediately (in the first - query) using fetch all properties. - - - - - - - - - Forms of join syntax - - - HQL supports two forms of association joining: implicit and explicit. - - - - The queries shown in the previous section all use the explicit form where - the join keyword is explicitly used in the from clause. This is the recommended form. - - - - The implicit form does not use the join keyword. Instead, the - associations are "dereferenced" using dot-notation. implicit joins - can appear in any of the HQL clauses. implicit join result - in inner joins in the resulting SQL statement. - - - - - - - Refering to identifier property - - - There are, generally speaking, 2 ways to refer to an entity's identifier property: - - - - - The special property (lowercase) id may be used to reference the identifier - property of an entity provided that entity does not define a non-identifier property - named id. - - - - - If the entity defines a named identifier property, you may use that property name. - - - - - - References to composite identifier properties follow the same naming rules. If the - entity has a non-identifier property named id, the composite identifier property can only - be referenced by its defined named; otherwise, the special id property - can be used to rerference the identifier property. - - - - Note: this has changed significantly starting in version 3.2.2. In previous versions, - id always referred to the identifier property no - matter what its actual name. A ramification of that decision was that non-identifier - properties named id could never be referenced in Hibernate queries. - - - - - The select clause - - - The select clause picks which objects and properties to return in - the query result set. Consider: - - - - - - The query will select mates of other Cats. - Actually, you may express this query more compactly as: - - - - - - Queries may return properties of any value type including properties of component type: - - - - - - - - Queries may return multiple objects and/or properties as an array of type - Object[], - - - - - - or as a List, - - - - - - or as an actual typesafe Java object, - - - - - - assuming that the class Family has an appropriate constructor. - - - - You may assign aliases to selected expressions using as: - - - - - - This is most useful when used together with select new map: - - - - - - This query returns a Map from aliases to selected values. - - - - - - Aggregate functions - - - HQL queries may even return the results of aggregate functions on properties: - - - - - - - - The supported aggregate functions are - - - - - - avg(...), sum(...), min(...), max(...) - - - - - count(*) - - - - - count(...), count(distinct ...), count(all...) - - - - - - You may use arithmetic operators, concatenation, and recognized SQL functions - in the select clause: - - - - - - - - The distinct and all keywords may be used and - have the same semantics as in SQL. - - - - - - - - Polymorphic queries - - - A query like: - - - - - - returns instances not only of Cat, but also of subclasses like - DomesticCat. Hibernate queries may name any Java - class or interface in the from clause. The query will return instances - of all persistent classes that extend that class or implement the interface. The following - query would return all persistent objects: - - - - - - The interface Named might be implemented by various persistent - classes: - - - - - - Note that these last two queries will require more than one SQL SELECT. This - means that the order by clause does not correctly order the whole result set. - (It also means you can't call these queries using Query.scroll().) - - - - - - The where clause - - - The where clause allows you to narrow the list of instances returned. - If no alias exists, you may refer to properties by name: - - - - - - If there is an alias, use a qualified property name: - - - - - - returns instances of Cat named 'Fritz'. - - - - - - will return all instances of Foo for which - there exists an instance of bar with a - date property equal to the - startDate property of the - Foo. Compound path expressions make the - where clause extremely powerful. Consider: - - - - - - This query translates to an SQL query with a table (inner) join. If you were to write - something like - - - - - - you would end up with a query that would require four table joins in SQL. - - - - The = operator may be used to compare not only properties, but also - instances: - - - - - - - - The special property (lowercase) id may be used to reference the - unique identifier of an object. See - for more information. - - - - - - The second query is efficient. No table join is required! - - - - Properties of composite identifiers may also be used. Suppose Person - has a composite identifier consisting of country and - medicareNumber. Again, see - for more information regarding referencing identifier properties. - - - - - - - - Once again, the second query requires no table join. - - - - Likewise, the special property class accesses the discriminator value - of an instance in the case of polymorphic persistence. A Java class name embedded in the - where clause will be translated to its discriminator value. - - - - - - You may also use components or composite user types, or properties of said - component types. See for more details. - - - - An "any" type has the special properties id and class, - allowing us to express a join in the following way (where AuditLog.item - is a property mapped with <any>). - - - - - - Notice that log.item.class and payment.class - would refer to the values of completely different database columns in the above query. - - - - - - Expressions - - - Expressions allowed in the where clause include - most of the kind of things you could write in SQL: - - - - - - mathematical operators +, -, *, / - - - - - binary comparison operators =, >=, <=, <>, !=, like - - - - - logical operations and, or, not - - - - - Parentheses ( ), indicating grouping - - - - - in, - not in, - between, - is null, - is not null, - is empty, - is not empty, - member of and - not member of - - - - - "Simple" case, case ... when ... then ... else ... end, and - "searched" case, case when ... then ... else ... end - - - - - string concatenation ...||... or concat(...,...) - - - - - current_date(), current_time(), - current_timestamp() - - - - - second(...), minute(...), - hour(...), day(...), - month(...), year(...), - - - - - Any function or operator defined by EJB-QL 3.0: substring(), trim(), - lower(), upper(), length(), locate(), abs(), sqrt(), bit_length(), mod() - - - - - coalesce() and nullif() - - - - - str() for converting numeric or temporal values to a - readable string - - - - - cast(... as ...), where the second argument is the name of - a Hibernate type, and extract(... from ...) if ANSI - cast() and extract() is supported by - the underlying database - - - - - the HQL index() function, that applies to aliases of - a joined indexed collection - - - - - HQL functions that take collection-valued path expressions: size(), - minelement(), maxelement(), minindex(), maxindex(), along with the - special elements() and indices functions - which may be quantified using some, all, exists, any, in. - - - - - Any database-supported SQL scalar function like sign(), - trunc(), rtrim(), sin() - - - - - JDBC-style positional parameters ? - - - - - named parameters :name, :start_date, :x1 - - - - - SQL literals 'foo', 69, 6.66E+2, - '1970-01-01 10:00:01.0' - - - - - Java public static final constants eg.Color.TABBY - - - - - - in and between may be used as follows: - - - - - - - - and the negated forms may be written - - - - - - - - Likewise, is null and is not null may be used to test - for null values. - - - - Booleans may be easily used in expressions by declaring HQL query substitutions in Hibernate - configuration: - - - true 1, false 0]]> - - - This will replace the keywords true and false with the - literals 1 and 0 in the translated SQL from this HQL: - - - - - - You may test the size of a collection with the special property size, or - the special size() function. - - - 0]]> - - 0]]> - - - For indexed collections, you may refer to the minimum and maximum indices using - minindex and maxindex functions. Similarly, - you may refer to the minimum and maximum elements of a collection of basic type - using the minelement and maxelement - functions. - - - current_date]]> - - 100]]> - - 10000]]> - - - The SQL functions any, some, all, exists, in are supported when passed the element - or index set of a collection (elements and indices functions) - or the result of a subquery (see below). - - - - - - - - - all elements(p.scores)]]> - - - - - Note that these constructs - size, elements, - indices, minindex, maxindex, - minelement, maxelement - may only be used in - the where clause in Hibernate3. - - - - Elements of indexed collections (arrays, lists, maps) may be referred to by - index (in a where clause only): - - - - - - - - - - - - The expression inside [] may even be an arithmetic expression. - - - - - - HQL also provides the built-in index() function, for elements - of a one-to-many association or collection of values. - - - - - - Scalar SQL functions supported by the underlying database may be used - - - - - - If you are not yet convinced by all this, think how much longer and less readable the - following query would be in SQL: - - - - - - Hint: something like - - - - - - - - The order by clause - - - The list returned by a query may be ordered by any property of a returned class or components: - - - - - - The optional asc or desc indicate ascending or descending order - respectively. - - - - - The group by clause - - - A query that returns aggregate values may be grouped by any property of a returned class or components: - - - - - - - - A having clause is also allowed. - - - - - - SQL functions and aggregate functions are allowed in the having - and order by clauses, if supported by the underlying database - (eg. not in MySQL). - - - 100 -order by count(kitten) asc, sum(kitten.weight) desc]]> - - - Note that neither the group by clause nor the - order by clause may contain arithmetic expressions. - Also note that Hibernate currently does not expand a grouped entity, - so you can't write group by cat if all properties - of cat are non-aggregated. You have to list all - non-aggregated properties explicitly. - - - - - - Subqueries - - - For databases that support subselects, Hibernate supports subqueries within queries. A subquery must - be surrounded by parentheses (often by an SQL aggregate function call). Even correlated subqueries - (subqueries that refer to an alias in the outer query) are allowed. - - - ( - select avg(cat.weight) from DomesticCat cat -)]]> - - - - - - - - - - - Note that HQL subqueries may occur only in the select or where clauses. - - - - Note that subqueries can also utilize row value constructor syntax. See - for more details. - - - - - - HQL examples - - - Hibernate queries can be quite powerful and complex. In fact, the power of the query language - is one of Hibernate's main selling points. Here are some example queries very similar to queries - that I used on a recent project. Note that most queries you will write are much simpler than these! - - - - The following query returns the order id, number of items and total value of the order for all - unpaid orders for a particular customer and given minimum total value, ordering the results by - total value. In determining the prices, it uses the current catalog. The resulting SQL query, - against the ORDER, ORDER_LINE, PRODUCT, - CATALOG and PRICE tables has four inner joins and an - (uncorrelated) subselect. - - - = all ( - select cat.effectiveDate - from Catalog as cat - where cat.effectiveDate < sysdate - ) -group by order -having sum(price.amount) > :minAmount -order by sum(price.amount) desc]]> - - - What a monster! Actually, in real life, I'm not very keen on subqueries, so my query was - really more like this: - - - :minAmount -order by sum(price.amount) desc]]> - - - The next query counts the number of payments in each status, excluding all payments in the - AWAITING_APPROVAL status where the most recent status change was made by the - current user. It translates to an SQL query with two inner joins and a correlated subselect - against the PAYMENT, PAYMENT_STATUS and - PAYMENT_STATUS_CHANGE tables. - - - PaymentStatus.AWAITING_APPROVAL - or ( - statusChange.timeStamp = ( - select max(change.timeStamp) - from PaymentStatusChange change - where change.payment = payment - ) - and statusChange.user <> :currentUser - ) -group by status.name, status.sortOrder -order by status.sortOrder]]> - - - If I would have mapped the statusChanges collection as a list, instead of a set, - the query would have been much simpler to write. - - - PaymentStatus.AWAITING_APPROVAL - or payment.statusChanges[ maxIndex(payment.statusChanges) ].user <> :currentUser -group by status.name, status.sortOrder -order by status.sortOrder]]> - - - The next query uses the MS SQL Server isNull() function to return all - the accounts and unpaid payments for the organization to which the current user belongs. - It translates to an SQL query with three inner joins, an outer join and a subselect against - the ACCOUNT, PAYMENT, PAYMENT_STATUS, - ACCOUNT_TYPE, ORGANIZATION and - ORG_USER tables. - - - - - - For some databases, we would need to do away with the (correlated) subselect. - - - - - - - - Bulk update and delete - - - HQL now supports update, delete and - insert ... select ... statements. - See for details. - - - - - Tips & Tricks - - - You can count the number of query results without actually returning them: - - - - - - To order a result by the size of a collection, use the following query: - - - - - - If your database supports subselects, you can place a condition upon selection - size in the where clause of your query: - - - = 1]]> - - - If your database doesn't support subselects, use the following query: - - - = 1]]> - - - As this solution can't return a User with zero messages - because of the inner join, the following form is also useful: - - - - - - Properties of a JavaBean can be bound to named query parameters: - - - - - - Collections are pageable by using the Query interface with a filter: - - - - - - Collection elements may be ordered or grouped using a query filter: - - - - - - You can find the size of a collection without initializing it: - - - - - - - - Components - - - Components might be used in just about every way that simple value types can be used in HQL - queries. They can appear in the select clause: - - - - - - - where the Person's name property is a component. Components can also be used - in the where clause: - - - - - - - Components can also be used in the order by clause: - - - - - - - Another common use of components is in row value constructors. - - - - - Row value constructor syntax - - - HQL supports the use of ANSI SQL row value constructor syntax (sometimes - called tuple syntax), even though the underlying database may not support - that notion. Here we are generally referring to multi-valued comparisons, typically associated - with components. Consider an entity Person which defines a name component: - - - - - - That's valid syntax, although a little verbose. It be nice to make this a bit more concise and use - row value constructor syntax: - - - - - - It can also be useful to specify this in the select clause: - - - - - - Another time using row value constructor syntax can be beneficial - is when using subqueries needing to compare against multiple values: - - - - - - One thing to consider when deciding if you want to use this syntax is that the query will - be dependent upon the ordering of the component sub-properties in the metadata. - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/query_sql.xml b/documentation/envers/src/main/docbook/en-US/content/query_sql.xml deleted file mode 100644 index e36876d9f1..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/query_sql.xml +++ /dev/null @@ -1,784 +0,0 @@ - - - - - - - Native SQL - - You may also express queries in the native SQL dialect of your - database. This is useful if you want to utilize database specific features - such as query hints or the CONNECT keyword in Oracle. It - also provides a clean migration path from a direct SQL/JDBC based - application to Hibernate. - - Hibernate3 allows you to specify handwritten SQL (including stored - procedures) for all create, update, delete, and load operations. - - - Using a <literal>SQLQuery</literal> - - Execution of native SQL queries is controlled via the - SQLQuery interface, which is obtained by calling - Session.createSQLQuery(). The following describes how - to use this API for querying. - - - Scalar queries - - The most basic SQL query is to get a list of scalars - (values). - - - - These will both return a List of Object arrays (Object[]) with - scalar values for each column in the CATS table. Hibernate will use - ResultSetMetadata to deduce the actual order and types of the returned - scalar values. - - To avoid the overhead of using - ResultSetMetadata or simply to be more explicit in - what is returned one can use addScalar(). - - - - This query specified: - - - - the SQL query string - - - - the columns and types to return - - - - This will still return Object arrays, but now it will not use - ResultSetMetadata but will instead explicitly get the - ID, NAME and BIRTHDATE column as respectively a Long, String and a Short - from the underlying resultset. This also means that only these three - columns will be returned, even though the query is using - * and could return more than the three listed - columns. - - It is possible to leave out the type information for all or some - of the scalars. - - - - This is essentially the same query as before, but now - ResultSetMetaData is used to decide the type of NAME - and BIRTHDATE where as the type of ID is explicitly specified. - - How the java.sql.Types returned from ResultSetMetaData is mapped - to Hibernate types is controlled by the Dialect. If a specific type is - not mapped or does not result in the expected type it is possible to - customize it via calls to registerHibernateType in - the Dialect. - - - - Entity queries - - The above queries were all about returning scalar values, - basically returning the "raw" values from the resultset. The following - shows how to get entity objects from a native sql query via - addEntity(). - - - - This query specified: - - - - the SQL query string - - - - the entity returned by the query - - - - Assuming that Cat is mapped as a class with the columns ID, NAME - and BIRTHDATE the above queries will both return a List where each - element is a Cat entity. - - If the entity is mapped with a many-to-one to - another entity it is required to also return this when performing the - native query, otherwise a database specific "column not found" error - will occur. The additional columns will automatically be returned when - using the * notation, but we prefer to be explicit as in the following - example for a many-to-one to a - Dog: - - - - This will allow cat.getDog() to function properly. - - - - Handling associations and collections - - It is possible to eagerly join in the Dog to - avoid the possible extra roundtrip for initializing the proxy. This is - done via the addJoin() method, which allows you to - join in an association or collection. - - - - In this example the returned Cat's will have - their dog property fully initialized without any - extra roundtrip to the database. Notice that we added a alias name - ("cat") to be able to specify the target property path of the join. It - is possible to do the same eager joining for collections, e.g. if the - Cat had a one-to-many to Dog - instead. - - - - - At this stage we are reaching the limits of what is possible with native queries without starting to - enhance the sql queries to make them usable in Hibernate; the problems starts to arise when returning - multiple entities of the same type or when the default alias/column names are not enough. - - - - - Returning multiple entities - - Until now the result set column names are assumed to be the same - as the column names specified in the mapping document. This can be - problematic for SQL queries which join multiple tables, since the same - column names may appear in more than one table. - - Column alias injection is needed in the following query (which - most likely will fail): - - - - The intention for this query is to return two Cat instances per - row, a cat and its mother. This will fail since there is a conflict of - names since they are mapped to the same column names and on some - databases the returned column aliases will most likely be on the form - "c.ID", "c.NAME", etc. which are not equal to the columns specified in - the mappings ("ID" and "NAME"). - - The following form is not vulnerable to column name - duplication: - - - - This query specified: - - - - the SQL query string, with placeholders for Hibernate to - inject column aliases - - - - the entities returned by the query - - - - The {cat.*} and {mother.*} notation used above is a shorthand for - "all properties". Alternatively, you may list the columns explicitly, but - even in this case we let Hibernate inject the SQL column aliases for - each property. The placeholder for a column alias is just the property - name qualified by the table alias. In the following example, we retrieve - Cats and their mothers from a different table (cat_log) to the one - declared in the mapping metadata. Notice that we may even use the - property aliases in the where clause if we like. - - - - - Alias and property references - - For most cases the above alias injection is needed, but for - queries relating to more complex mappings like composite properties, - inheritance discriminators, collections etc. there are some specific - aliases to use to allow Hibernate to inject the proper aliases. - - The following table shows the different possibilities of using - the alias injection. Note: the alias names in the result are examples, - each alias will have a unique and probably different name when - used. - - - Alias injection names - - - - - - - - - - - Description - - Syntax - - Example - - - - - - A simple property - - {[aliasname].[propertyname] - - A_NAME as {item.name} - - - - A composite property - - {[aliasname].[componentname].[propertyname]} - - CURRENCY as {item.amount.currency}, VALUE as - {item.amount.value} - - - - Discriminator of an entity - - {[aliasname].class} - - DISC as {item.class} - - - - All properties of an entity - - {[aliasname].*} - - {item.*} - - - - A collection key - - {[aliasname].key} - - ORGID as {coll.key} - - - - The id of an collection - - {[aliasname].id} - - EMPID as {coll.id} - - - - The element of an collection - - {[aliasname].element} - - XID as {coll.element} - - - - roperty of the element in the collection - - {[aliasname].element.[propertyname]} - - NAME as {coll.element.name} - - - - All properties of the element in the collection - - {[aliasname].element.*} - - {coll.element.*} - - - - All properties of the the collection - - {[aliasname].*} - - {coll.*} - - - -
- - - - - Returning non-managed entities - - It is possible to apply a ResultTransformer to native sql queries. Allowing it to e.g. return non-managed entities. - - - - This query specified: - - - - the SQL query string - - - - a result transformer - - - - - The above query will return a list of CatDTO which has been instantiated and injected the values of NAME and BIRTHNAME into its corresponding - properties or fields. - - - - - Handling inheritance - - Native sql queries which query for entities that is mapped as part - of an inheritance must include all properties for the baseclass and all - it subclasses. - - - - Parameters - - Native sql queries support positional as well as named - parameters: - - - - - - - - - - Named SQL queries - - Named SQL queries may be defined in the mapping document and called - in exactly the same way as a named HQL query. In this case, we do - not need to call - addEntity(). - - - - SELECT person.NAME AS {person.name}, - person.AGE AS {person.age}, - person.SEX AS {person.sex} - FROM PERSON person - WHERE person.NAME LIKE :namePattern -]]> - - - - The <return-join> and - <load-collection> elements are used to join - associations and define queries which initialize collections, - respectively. - - - - - SELECT person.NAME AS {person.name}, - person.AGE AS {person.age}, - person.SEX AS {person.sex}, - address.STREET AS {address.street}, - address.CITY AS {address.city}, - address.STATE AS {address.state}, - address.ZIP AS {address.zip} - FROM PERSON person - JOIN ADDRESS address - ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' - WHERE person.NAME LIKE :namePattern -]]> - - A named SQL query may return a scalar value. You must declare the - column alias and Hibernate type using the - <return-scalar> element: - - - - - SELECT p.NAME AS name, - p.AGE AS age, - FROM PERSON p WHERE p.NAME LIKE 'Hiber%' -]]> - - You can externalize the resultset mapping informations in a - <resultset> element to either reuse them across - several named queries or through the - setResultSetMapping() API. - - - - - - - - SELECT person.NAME AS {person.name}, - person.AGE AS {person.age}, - person.SEX AS {person.sex}, - address.STREET AS {address.street}, - address.CITY AS {address.city}, - address.STATE AS {address.state}, - address.ZIP AS {address.zip} - FROM PERSON person - JOIN ADDRESS address - ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' - WHERE person.NAME LIKE :namePattern -]]> - - You can alternatively use the resultset mapping information in your - hbm files directly in java code. - - - - - Using return-property to explicitly specify column/alias - names - - With <return-property> you can explicitly - tell Hibernate what column aliases to use, instead of using the - {}-syntax to let Hibernate inject its own - aliases. - - - - - - - - SELECT person.NAME AS myName, - person.AGE AS myAge, - person.SEX AS mySex, - FROM PERSON person WHERE person.NAME LIKE :name - -]]> - - <return-property> also works with - multiple columns. This solves a limitation with the - {}-syntax which can not allow fine grained control of - multi-column properties. - - - - - - - - - - SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer}, - STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate}, - REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VALUE, CURRENCY - FROM EMPLOYMENT - WHERE EMPLOYER = :id AND ENDDATE IS NULL - ORDER BY STARTDATE ASC -]]> - - Notice that in this example we used - <return-property> in combination with the - {}-syntax for injection. Allowing users to choose how - they want to refer column and properties. - - If your mapping has a discriminator you must use - <return-discriminator> to specify the - discriminator column. - - - - Using stored procedures for querying - - Hibernate 3 introduces support for queries via stored procedures - and functions. Most of the following documentation is equivalent for - both. The stored procedure/function must return a resultset as the first - out-parameter to be able to work with Hibernate. An example of such a - stored function in Oracle 9 and higher is as follows: - - - - To use this query in Hibernate you need to map it via a named - query. - - - - - - - - - - - - - - - { ? = call selectAllEmployments() } -]]> - - Notice stored procedures currently only return scalars and - entities. <return-join> and - <load-collection> are not supported. - - - Rules/limitations for using stored procedures - - To use stored procedures with Hibernate the procedures/functions - have to follow some rules. If they do not follow those rules they are - not usable with Hibernate. If you still want to use these procedures - you have to execute them via session.connection(). - The rules are different for each database, since database vendors have - different stored procedure semantics/syntax. - - Stored procedure queries can't be paged with - setFirstResult()/setMaxResults(). - - Recommended call form is standard SQL92: { ? = call - functionName(<parameters>) } or { ? = call - procedureName(<parameters>}. Native call syntax is not - supported. - - For Oracle the following rules apply: - - - - A function must return a result set. The first parameter of - a procedure must be an OUT that returns a - result set. This is done by using a - SYS_REFCURSOR type in Oracle 9 or 10. In Oracle - you need to define a REF CURSOR type, see - Oracle literature. - - - - For Sybase or MS SQL server the following rules apply: - - - - The procedure must return a result set. Note that since - these servers can/will return multiple result sets and update - counts, Hibernate will iterate the results and take the first - result that is a result set as its return value. Everything else - will be discarded. - - - - If you can enable SET NOCOUNT ON in your - procedure it will probably be more efficient, but this is not a - requirement. - - - - - - - - Custom SQL for create, update and delete - - Hibernate3 can use custom SQL statements for create, update, and - delete operations. The class and collection persisters in Hibernate - already contain a set of configuration time generated strings (insertsql, - deletesql, updatesql etc.). The mapping tags - <sql-insert>, - <sql-delete>, and - <sql-update> override these strings: - - - - - - - INSERT INTO PERSON (NAME, ID) VALUES ( UPPER(?), ? ) - UPDATE PERSON SET NAME=UPPER(?) WHERE ID=? - DELETE FROM PERSON WHERE ID=? -]]> - - The SQL is directly executed in your database, so you are free to - use any dialect you like. This will of course reduce the portability of - your mapping if you use database specific SQL. - - Stored procedures are supported if the callable - attribute is set: - - - - - - - {call createPerson (?, ?)} - {? = call deletePerson (?)} - {? = call updatePerson (?, ?)} -]]> - - The order of the positional parameters are currently vital, as they - must be in the same sequence as Hibernate expects them. - - You can see the expected order by enabling debug logging for the - org.hibernate.persister.entity level. With this level - enabled Hibernate will print out the static SQL that is used to create, - update, delete etc. entities. (To see the expected sequence, remember to - not include your custom SQL in the mapping files as that will override the - Hibernate generated static sql.) - - The stored procedures are in most cases (read: better do it than - not) required to return the number of rows inserted/updated/deleted, as - Hibernate has some runtime checks for the success of the statement. - Hibernate always registers the first statement parameter as a numeric - output parameter for the CUD operations: - - - - - - Custom SQL for loading - - You may also declare your own SQL (or HQL) queries for entity - loading: - - - - SELECT NAME AS {pers.name}, ID AS {pers.id} - FROM PERSON - WHERE ID=? - FOR UPDATE -]]> - - This is just a named query declaration, as discussed earlier. You - may reference this named query in a class mapping: - - - - - - - -]]> - - This even works with stored procedures. - - You may even define a query for collection loading: - - - - - -]]> - - - - SELECT {emp.*} - FROM EMPLOYMENT emp - WHERE EMPLOYER = :id - ORDER BY STARTDATE ASC, EMPLOYEE ASC -]]> - - You could even define an entity loader that loads a collection by - join fetching: - - - - - SELECT NAME AS {pers.*}, {emp.*} - FROM PERSON pers - LEFT OUTER JOIN EMPLOYMENT emp - ON pers.ID = emp.PERSON_ID - WHERE ID=? -]]> - - diff --git a/documentation/envers/src/main/docbook/en-US/content/session_api.xml b/documentation/envers/src/main/docbook/en-US/content/session_api.xml deleted file mode 100644 index a1fa6374fe..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/session_api.xml +++ /dev/null @@ -1,1287 +0,0 @@ - - - - - - - Working with objects - - - Hibernate is a full object/relational mapping solution that not only shields - the developer from the details of the underlying database management - system, but also offers state management of objects. This is, - contrary to the management of SQL statements in common JDBC/SQL - persistence layers, a very natural object-oriented view of persistence in Java - applications. - - - - In other words, Hibernate application developers should always think about the - state of their objects, and not necessarily about the - execution of SQL statements. This part is taken care of by Hibernate and is only - relevant for the application developer when tuning the performance of the system. - - - - Hibernate object states - - - Hibernate defines and supports the following object states: - - - - - - Transient - an object is transient if it has just - been instantiated using the new operator, and it - is not associated with a Hibernate Session. It has no - persistent representation in the database and no identifier value has been - assigned. Transient instances will be destroyed by the garbage collector if - the application doesn't hold a reference anymore. Use the Hibernate - Session to make an object persistent (and let Hibernate - take care of the SQL statements that need to be executed for this transition). - - - - - Persistent - a persistent instance has a representation - in the database and an identifier value. It might just have been saved or loaded, - however, it is by definition in the scope of a Session. - Hibernate will detect any changes made to an object in persistent state and - synchronize the state with the database when the unit of work completes. - Developers don't execute manual UPDATE statements, or - DELETE statements when an object should be made transient. - - - - - Detached - a detached instance is an object that has been - persistent, but its Session has been closed. The reference - to the object is still valid, of course, and the detached instance might even - be modified in this state. A detached instance can be reattached to a new - Session at a later point in time, making it (and all the - modifications) persistent again. This feature enables a programming model for - long running units of work that require user think-time. We call them - application transactions, i.e. a unit of work from the - point of view of the user. - - - - - - We'll now discuss the states and state transitions (and the Hibernate methods that - trigger a transition) in more detail. - - - - - - Making objects persistent - - - Newly instantiated instances of a a persistent class are considered - transient by Hibernate. We can make a transient - instance persistent by associating it with a - session: - - - - - - If Cat has a generated identifier, the identifier is - generated and assigned to the cat when save() - is called. If Cat has an assigned - identifier, or a composite key, the identifier should be assigned to - the cat instance before calling save(). - You may also use persist() instead of save(), - with the semantics defined in the EJB3 early draft. - - - - - - persist() makes a transient instance persistent. - However, it doesn't guarantee that the identifier value will be assigned to - the persistent instance immediately, the assignment might happen at flush time. - persist() also guarantees that it will not execute an - INSERT statement if it is called outside of transaction - boundaries. This is useful in long-running conversations with an extended - Session/persistence context. - - - - - save() does guarantee to return an identifier. If an INSERT - has to be executed to get the identifier ( e.g. "identity" generator, not - "sequence"), this INSERT happens immediately, no matter if you are inside or - outside of a transaction. This is problematic in a long-running conversation - with an extended Session/persistence context. - - - - - - Alternatively, you may assign the identifier using an overloaded version - of save(). - - - - - - If the object you make persistent has associated objects (e.g. the - kittens collection in the previous example), - these objects may be made persistent in any order you like unless you - have a NOT NULL constraint upon a foreign key column. - There is never a risk of violating foreign key constraints. However, you - might violate a NOT NULL constraint if you - save() the objects in the wrong order. - - - - Usually you don't bother with this detail, as you'll very likely use Hibernate's - transitive persistence feature to save the associated - objects automatically. Then, even NOT NULL - constraint violations don't occur - Hibernate will take care of everything. - Transitive persistence is discussed later in this chapter. - - - - - - Loading an object - - - The load() methods of Session gives you - a way to retrieve a persistent instance if you already know its identifier. - load() takes a class object and will load the state into - a newly instantiated instance of that class, in persistent state. - - - - - - - - Alternatively, you can load state into a given instance: - - - - - - Note that load() will throw an unrecoverable exception if - there is no matching database row. If the class is mapped with a proxy, - load() just returns an uninitialized proxy and does not - actually hit the database until you invoke a method of the proxy. This - behaviour is very useful if you wish to create an association to an object - without actually loading it from the database. It also allows multiple - instances to be loaded as a batch if batch-size is - defined for the class mapping. - - - - If you are not certain that a matching row exists, you should use the - get() method, which hits the database immediately and - returns null if there is no matching row. - - - - - - You may even load an object using an SQL SELECT ... FOR UPDATE, - using a LockMode. See the API documentation for more information. - - - - - - Note that any associated instances or contained collections are - not selected FOR UPDATE, unless you decide - to specify lock or all as a - cascade style for the association. - - - - It is possible to re-load an object and all its collections at any time, using the - refresh() method. This is useful when database triggers are used to - initialize some of the properties of the object. - - - - - - An important question usually appears at this point: How much does Hibernate load - from the database and how many SQL SELECTs will it use? This - depends on the fetching strategy and is explained in - . - - - - - - Querying - - - If you don't know the identifiers of the objects you are looking for, - you need a query. Hibernate supports an easy-to-use but powerful object - oriented query language (HQL). For programmatic query creation, Hibernate - supports a sophisticated Criteria and Example query feature (QBC and QBE). - You may also express your query in the native SQL of your database, with - optional support from Hibernate for result set conversion into objects. - - - - Executing queries - - - HQL and native SQL queries are represented with an instance of org.hibernate.Query. - This interface offers methods for parameter binding, result set handling, and for the execution - of the actual query. You always obtain a Query using the current - Session: - - - - - - A query is usually executed by invoking list(), the - result of the query will be loaded completely into a collection in memory. - Entity instances retrieved by a query are in persistent state. The - uniqueResult() method offers a shortcut if you - know your query will only return a single object. Note that queries that - make use of eager fetching of collections usually return duplicates of - the root objects (but with their collections initialized). You can filter - these duplicates simply through a Set. - - - - Iterating results - - - Occasionally, you might be able to achieve better performance by - executing the query using the iterate() method. - This will only usually be the case if you expect that the actual - entity instances returned by the query will already be in the session - or second-level cache. If they are not already cached, - iterate() will be slower than list() - and might require many database hits for a simple query, usually - 1 for the initial select which only returns identifiers, - and n additional selects to initialize the actual instances. - - - - - - - Queries that return tuples - - - Hibernate queries sometimes return tuples of objects, in which case each tuple - is returned as an array: - - - - - - - - Scalar results - - - Queries may specify a property of a class in the select clause. - They may even call SQL aggregate functions. Properties or aggregates are considered - "scalar" results (and not entities in persistent state). - - - - - - - - Bind parameters - - - Methods on Query are provided for binding values to - named parameters or JDBC-style ? parameters. - Contrary to JDBC, Hibernate numbers parameters from zero. - Named parameters are identifiers of the form :name in - the query string. The advantages of named parameters are: - - - - - - named parameters are insensitive to the order they occur in the - query string - - - - - they may occur multiple times in the same query - - - - - they are self-documenting - - - - - - - - - - - - - - Pagination - - - If you need to specify bounds upon your result set (the maximum number of rows - you want to retrieve and / or the first row you want to retrieve) you should - use methods of the Query interface: - - - - - - Hibernate knows how to translate this limit query into the native - SQL of your DBMS. - - - - - - Scrollable iteration - - - If your JDBC driver supports scrollable ResultSets, the - Query interface may be used to obtain a - ScrollableResults object, which allows flexible - navigation of the query results. - - - i++ ) && cats.next() ) pageOfCats.add( cats.get(1) ); - -} -cats.close()]]> - - - Note that an open database connection (and cursor) is required for this - functionality, use setMaxResult()/setFirstResult() - if you need offline pagination functionality. - - - - - - Externalizing named queries - - - You may also define named queries in the mapping document. (Remember to use a - CDATA section if your query contains characters that could - be interpreted as markup.) - - - ? -] ]>]]> - - - Parameter binding and executing is done programatically: - - - - - - Note that the actual program code is independent of the query language that - is used, you may also define native SQL queries in metadata, or migrate - existing queries to Hibernate by placing them in mapping files. - - - - Also note that a query declaration inside a <hibernate-mapping> - element requires a global unique name for the query, while a query declaration inside a - <class> element is made unique automatically by prepending the - fully qualified name of the class, for example - eg.Cat.ByNameAndMaximumWeight. - - - - - - - - Filtering collections - - A collection filter is a special type of query that may be applied to - a persistent collection or array. The query string may refer to this, - meaning the current collection element. - - - - - - The returned collection is considered a bag, and it's a copy of the given - collection. The original collection is not modified (this is contrary to - the implication of the name "filter", but consistent with expected behavior). - - - - Observe that filters do not require a from clause (though they may have - one if required). Filters are not limited to returning the collection elements themselves. - - - - - - Even an empty filter query is useful, e.g. to load a subset of elements in a - huge collection: - - - - - - - - Criteria queries - - - HQL is extremely powerful but some developers prefer to build queries dynamically, - using an object-oriented API, rather than building query strings. Hibernate provides - an intuitive Criteria query API for these cases: - - - - - - The Criteria and the associated Example - API are discussed in more detail in . - - - - - - Queries in native SQL - - - You may express a query in SQL, using createSQLQuery() and - let Hibernate take care of the mapping from result sets to objects. Note - that you may at any time call session.connection() and - use the JDBC Connection directly. If you chose to use the - Hibernate API, you must enclose SQL aliases in braces: - - - - - - - - SQL queries may contain named and positional parameters, just like Hibernate queries. - More information about native SQL queries in Hibernate can be found in - . - - - - - - - - Modifying persistent objects - - - Transactional persistent instances (ie. objects loaded, saved, created or - queried by the Session) may be manipulated by the application - and any changes to persistent state will be persisted when the Session - is flushed (discussed later in this chapter). There is no need - to call a particular method (like update(), which has a different - purpose) to make your modifications persistent. So the most straightforward way to update - the state of an object is to load() it, - and then manipulate it directly, while the Session is open: - - - - - - Sometimes this programming model is inefficient since it would require both an SQL - SELECT (to load an object) and an SQL UPDATE - (to persist its updated state) in the same session. Therefore Hibernate offers an - alternate approach, using detached instances. - - - - Note that Hibernate does not offer its own API for direct execution of - UPDATE or DELETE statements. Hibernate is a - state management service, you don't have to think in - statements to use it. JDBC is a perfect API for executing - SQL statements, you can get a JDBC Connection at any time - by calling session.connection(). Furthermore, the notion - of mass operations conflicts with object/relational mapping for online - transaction processing-oriented applications. Future versions of Hibernate - may however provide special mass operation functions. See - for some possible batch operation tricks. - - - - - - Modifying detached objects - - - Many applications need to retrieve an object in one transaction, send it to the - UI layer for manipulation, then save the changes in a new transaction. - Applications that use this kind of approach in a high-concurrency environment - usually use versioned data to ensure isolation for the "long" unit of work. - - - - Hibernate supports this model by providing for reattachment of detached instances - using the Session.update() or Session.merge() - methods: - - - - - - If the Cat with identifier catId had already - been loaded by secondSession when the application tried to - reattach it, an exception would have been thrown. - - - - Use update() if you are sure that the session does - not contain an already persistent instance with the same identifier, and - merge() if you want to merge your modifications at any time - without consideration of the state of the session. In other words, update() - is usually the first method you would call in a fresh session, ensuring that - reattachment of your detached instances is the first operation that is executed. - - - - The application should individually update() detached instances - reachable from the given detached instance if and only if it wants - their state also updated. This can be automated of course, using transitive - persistence, see . - - - - The lock() method also allows an application to reassociate - an object with a new session. However, the detached instance has to be unmodified! - - - - - - Note that lock() can be used with various - LockModes, see the API documentation and the - chapter on transaction handling for more information. Reattachment is not - the only usecase for lock(). - - - - Other models for long units of work are discussed in . - - - - - - Automatic state detection - - - Hibernate users have requested a general purpose method that either saves a - transient instance by generating a new identifier or updates/reattaches - the detached instances associated with its current identifier. - The saveOrUpdate() method implements this functionality. - - - - - - The usage and semantics of saveOrUpdate() seems to be confusing - for new users. Firstly, so long as you are not trying to use instances from one session - in another new session, you should not need to use update(), - saveOrUpdate(), or merge(). Some whole - applications will never use either of these methods. - - - - Usually update() or saveOrUpdate() are used in - the following scenario: - - - - - - the application loads an object in the first session - - - - - the object is passed up to the UI tier - - - - - some modifications are made to the object - - - - - the object is passed back down to the business logic tier - - - - - the application persists these modifications by calling - update() in a second session - - - - - - saveOrUpdate() does the following: - - - - - - if the object is already persistent in this session, do nothing - - - - - if another object associated with the session has the same identifier, - throw an exception - - - - - if the object has no identifier property, save() it - - - - - if the object's identifier has the value assigned to a newly instantiated - object, save() it - - - - - if the object is versioned (by a <version> or - <timestamp>), and the version property value - is the same value assigned to a newly instantiated object, - save() it - - - - - otherwise update() the object - - - - - - and merge() is very different: - - - - - - if there is a persistent instance with the same identifier currently - associated with the session, copy the state of the given object onto - the persistent instance - - - - - if there is no persistent instance currently associated with the session, - try to load it from the database, or create a new persistent instance - - - - - the persistent instance is returned - - - - - the given instance does not become associated with the session, it - remains detached - - - - - - - - Deleting persistent objects - - - Session.delete() will remove an object's state from the database. - Of course, your application might still hold a reference to a deleted object. - It's best to think of delete() as making a persistent instance - transient. - - - - - - You may delete objects in any order you like, without risk of foreign key - constraint violations. It is still possible to violate a NOT - NULL constraint on a foreign key column by deleting objects in - the wrong order, e.g. if you delete the parent, but forget to delete the - children. - - - - - - Replicating object between two different datastores - - - It is occasionally useful to be able to take a graph of persistent instances - and make them persistent in a different datastore, without regenerating identifier - values. - - - - - - The ReplicationMode determines how replicate() - will deal with conflicts with existing rows in the database. - - - - - - ReplicationMode.IGNORE - ignore the object when there is - an existing database row with the same identifier - - - - - ReplicationMode.OVERWRITE - overwrite any existing database - row with the same identifier - - - - - ReplicationMode.EXCEPTION - throw an exception if there is - an existing database row with the same identifier - - - - - ReplicationMode.LATEST_VERSION - overwrite the row if its - version number is earlier than the version number of the object, or ignore - the object otherwise - - - - - - Usecases for this feature include reconciling data entered into different database - instances, upgrading system configuration information during product upgrades, - rolling back changes made during non-ACID transactions and more. - - - - - - Flushing the Session - - - From time to time the Session will execute the SQL statements - needed to synchronize the JDBC connection's state with the state of objects held in - memory. This process, flush, occurs by default at the following - points - - - - - - before some query executions - - - - - from org.hibernate.Transaction.commit() - - - - - from Session.flush() - - - - - - The SQL statements are issued in the following order - - - - - - all entity insertions, in the same order the corresponding objects - were saved using Session.save() - - - - - all entity updates - - - - - all collection deletions - - - - - all collection element deletions, updates and insertions - - - - - all collection insertions - - - - - all entity deletions, in the same order the corresponding objects - were deleted using Session.delete() - - - - - - (An exception is that objects using native ID generation are - inserted when they are saved.) - - - - Except when you explicity flush(), there are absolutely no - guarantees about when the Session executes - the JDBC calls, only the order in which they are executed. - However, Hibernate does guarantee that the Query.list(..) - will never return stale data; nor will they return the wrong data. - - - - It is possible to change the default behavior so that flush occurs less frequently. - The FlushMode class defines three different modes: only flush - at commit time (and only when the Hibernate Transaction API - is used), flush automatically using the explained routine, or never flush unless - flush() is called explicitly. The last mode is useful for long running - units of work, where a Session is kept open and disconnected for - a long time (see ). - - - - - - During flush, an exception might occur (e.g. if a DML operation violates a constraint). - Since handling exceptions involves some understanding of Hibernate's transactional - behavior, we discuss it in . - - - - - - Transitive persistence - - - It is quite cumbersome to save, delete, or reattach individual objects, - especially if you deal with a graph of associated objects. A common case is - a parent/child relationship. Consider the following example: - - - - If the children in a parent/child relationship would be value typed (e.g. a collection - of addresses or strings), their life cycle would depend on the parent and no - further action would be required for convenient "cascading" of state changes. - When the parent is saved, the value-typed child objects are saved as - well, when the parent is deleted, the children will be deleted, etc. This - even works for operations such as the removal of a child from the collection; - Hibernate will detect this and, since value-typed objects can't have shared - references, delete the child from the database. - - - - Now consider the same scenario with parent and child objects being entities, - not value-types (e.g. categories and items, or parent and child cats). Entities - have their own life cycle, support shared references (so removing an entity from - the collection does not mean it can be deleted), and there is by default no - cascading of state from one entity to any other associated entities. Hibernate - does not implement persistence by reachability by default. - - - - For each basic operation of the Hibernate session - including persist(), merge(), - saveOrUpdate(), delete(), lock(), refresh(), evict(), replicate() - there is a - corresponding cascade style. Respectively, the cascade styles are named create, - merge, save-update, delete, lock, refresh, evict, replicate. If you want an - operation to be cascaded along an association, you must indicate that in the mapping - document. For example: - - - ]]> - - - Cascade styles my be combined: - - - ]]> - - - You may even use cascade="all" to specify that all - operations should be cascaded along the association. The default cascade="none" - specifies that no operations are to be cascaded. - - - - A special cascade style, delete-orphan, applies only to one-to-many - associations, and indicates that the delete() operation should - be applied to any child object that is removed from the association. - - - - - Recommendations: - - - - - - It doesn't usually make sense to enable cascade on a <many-to-one> - or <many-to-many> association. Cascade is often useful for - <one-to-one> and <one-to-many> - associations. - - - - - If the child object's lifespan is bounded by the lifespan of the parent - object, make it a life cycle object by specifying - cascade="all,delete-orphan". - - - - - Otherwise, you might not need cascade at all. But if you think that you will often be - working with the parent and children together in the same transaction, and you want to save - yourself some typing, consider using cascade="persist,merge,save-update". - - - - - - Mapping an association (either a single valued association, or a collection) with - cascade="all" marks the association as a - parent/child style relationship where save/update/delete of the - parent results in save/update/delete of the child or children. - - - Futhermore, a mere reference to a child from a persistent parent will result in - save/update of the child. This metaphor is incomplete, however. A child which becomes - unreferenced by its parent is not automatically deleted, except - in the case of a <one-to-many> association mapped with - cascade="delete-orphan". The precise semantics of cascading - operations for a parent/child relationship are as follows: - - - - - - If a parent is passed to persist(), all children are passed to - persist() - - - - - If a parent is passed to merge(), all children are passed to - merge() - - - - - If a parent is passed to save(), update() or - saveOrUpdate(), all children are passed to saveOrUpdate() - - - - - If a transient or detached child becomes referenced by a persistent parent, - it is passed to saveOrUpdate() - - - - - If a parent is deleted, all children are passed to delete() - - - - - If a child is dereferenced by a persistent parent, nothing - special happens - the application should explicitly delete - the child if necessary - unless cascade="delete-orphan", - in which case the "orphaned" child is deleted. - - - - - - Finally, note that cascading of operations can be applied to an object graph at - call time or at flush time. All operations, - if enabled, are cascaded to associated entities reachable when the operation is - executed. However, save-upate and delete-orphan - are transitive for all associated entities reachable during flush of the - Session. - - - - - - Using metadata - - - Hibernate requires a very rich meta-level model of all entity and value types. From time - to time, this model is very useful to the application itself. For example, the application - might use Hibernate's metadata to implement a "smart" deep-copy algorithm that understands - which objects should be copied (eg. mutable value types) and which should not (eg. - immutable value types and, possibly, associated entities). - - - Hibernate exposes metadata via the ClassMetadata and - CollectionMetadata interfaces and the Type - hierarchy. Instances of the metadata interfaces may be obtained from the - SessionFactory. - - - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/toolset_guide.xml b/documentation/envers/src/main/docbook/en-US/content/toolset_guide.xml deleted file mode 100644 index b47abeb1c1..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/toolset_guide.xml +++ /dev/null @@ -1,631 +0,0 @@ - - - - - - - Toolset Guide - - - Roundtrip engineering with Hibernate is possible using a set of Eclipse plugins, - commandline tools, as well as Ant tasks. - - - - The Hibernate Tools currently include plugins for the Eclipse - IDE as well as Ant tasks for reverse engineering of existing databases: - - - - - Mapping Editor: An editor for Hibernate XML mapping files, - supporting auto-completion and syntax highlighting. It also supports semantic - auto-completion for class names and property/field names, making it much more versatile than a normal XML editor. - - - Console: The console is a new view in Eclipse. In addition to - a tree overview of your console configurations, you also get an interactive view - of your persistent classes and their relationships. The console allows you to - execute HQL queries against your database and browse the result directly in - Eclipse. - - - Development Wizards: Several wizards are provided with the - Hibernate Eclipse tools; you can use a wizard to quickly generate Hibernate configuration - (cfg.xml) files, or you may even completely reverse engineer an existing database schema - into POJO source files and Hibernate mapping files. The reverse engineering wizard - supports customizable templates. - - - Ant Tasks: - - - - - - Please refer to the Hibernate Tools package and it's documentation - for more information. - - - - However, the Hibernate main package comes bundled with an integrated tool (it can even - be used from "inside" Hibernate on-the-fly): SchemaExport aka - hbm2ddl. - - - - Automatic schema generation - - - DDL may be generated from your mapping files by a Hibernate utility. The generated - schema includes referential integrity constraints (primary and foreign keys) for - entity and collection tables. Tables and sequences are also created for mapped - identifier generators. - - - - You must specify a SQL Dialect via the - hibernate.dialect property when using this tool, as DDL - is highly vendor specific. - - - - First, customize your mapping files to improve the generated schema. - - - - Customizing the schema - - - Many Hibernate mapping elements define optional attributes named length, - precision and scale. You may set the length, precision - and scale of a column with this attribute. - - - - ]]> - ]]> - - - Some tags also accept a not-null attribute (for generating a - NOT NULL constraint on table columns) and a unique - attribute (for generating UNIQUE constraint on table columns). - - - ]]> - - ]]> - - - A unique-key attribute may be used to group columns in - a single unique key constraint. Currently, the specified value of the - unique-key attribute is not used - to name the constraint in the generated DDL, only to group the columns in - the mapping file. - - - -]]> - - - An index attribute specifies the name of an index that - will be created using the mapped column or columns. Multiple columns may be - grouped into the same index, simply by specifying the same index name. - - - -]]> - - - A foreign-key attribute may be used to override the name - of any generated foreign key constraint. - - - ]]> - - - Many mapping elements also accept a child <column> element. - This is particularly useful for mapping multi-column types: - - - - - - -]]> - - - The default attribute lets you specify a default value for - a column (you should assign the same value to the mapped property before - saving a new instance of the mapped class). - - - - -]]> - - - -]]> - - - The sql-type attribute allows the user to override the default - mapping of a Hibernate type to SQL datatype. - - - - -]]> - - - The check attribute allows you to specify a check constraint. - - - - -]]> - - - ... - -]]> - - - - Summary - - - - - - - Attribute - Values - Interpretation - - - - - length - number - column length - - - precision - number - column decimal precision - - - scale - number - column decimal scale - - - not-null - true|false - specfies that the column should be non-nullable - - - unique - true|false - specifies that the column should have a unique constraint - - - index - index_name - specifies the name of a (multi-column) index - - - unique-key - unique_key_name - specifies the name of a multi-column unique constraint - - - foreign-key - foreign_key_name - - specifies the name of the foreign key constraint generated - for an association, for a <one-to-one>, - <many-to-one>, <key>, - or <many-to-many> mapping element. Note that - inverse="true" sides will not be considered - by SchemaExport. - - - - sql-type - SQL column type - - overrides the default column type (attribute of - <column> element only) - - - - default - SQL expression - - specify a default value for the column - - - - check - SQL expression - - create an SQL check constraint on either column or table - - - - -
- - - The <comment> element allows you to specify comments - for the generated schema. - - - - Current customers only - ... -]]> - - - - Balance in USD - -]]> - - - This results in a comment on table or - comment on column statement in the generated - DDL (where supported). - - - - - - Running the tool - - - The SchemaExport tool writes a DDL script to standard out and/or - executes the DDL statements. - - - - java -cp hibernate_classpaths - org.hibernate.tool.hbm2ddl.SchemaExport options mapping_files - - - - <literal>SchemaExport</literal> Command Line Options - - - - - - Option - Description - - - - - --quiet - don't output the script to stdout - - - --drop - only drop the tables - - - --create - only create the tables - - - --text - don't export to the database - - - --output=my_schema.ddl - output the ddl script to a file - - - --naming=eg.MyNamingStrategy - select a NamingStrategy - - - --config=hibernate.cfg.xml - read Hibernate configuration from an XML file - - - --properties=hibernate.properties - read database properties from a file - - - --format - format the generated SQL nicely in the script - - - --delimiter=; - set an end of line delimiter for the script - - - -
- - - You may even embed SchemaExport in your application: - - - - - - - - Properties - - - Database properties may be specified - - - - - as system properties with -D<property> - - - in hibernate.properties - - - in a named properties file with --properties - - - - - The needed properties are: - - - - SchemaExport Connection Properties - - - - - - Property Name - Description - - - - - hibernate.connection.driver_class - jdbc driver class - - - hibernate.connection.url - jdbc url - - - hibernate.connection.username - database user - - - hibernate.connection.password - user password - - - hibernate.dialect - dialect - - - -
- - - - - Using Ant - - - You can call SchemaExport from your Ant build script: - - - - - - - - - - -]]> - - - - - Incremental schema updates - - - The SchemaUpdate tool will update an existing schema with "incremental" changes. - Note that SchemaUpdate depends heavily upon the JDBC metadata API, so it will - not work with all JDBC drivers. - - - - java -cp hibernate_classpaths - org.hibernate.tool.hbm2ddl.SchemaUpdate options mapping_files - - - - <literal>SchemaUpdate</literal> Command Line Options - - - - - - Option - Description - - - - - --quiet - don't output the script to stdout - - - --text - don't export the script to the database - - - --naming=eg.MyNamingStrategy - select a NamingStrategy - - - --properties=hibernate.properties - read database properties from a file - - - --config=hibernate.cfg.xml - specify a .cfg.xml file - - - -
- - - You may embed SchemaUpdate in your application: - - - - - - - - Using Ant for incremental schema updates - - - You can call SchemaUpdate from the Ant script: - - - - - - - - - - -]]> - - - - - Schema validation - - - The SchemaValidator tool will validate that the existing database schema "matches" - your mapping documents. Note that SchemaValidator depends heavily upon the JDBC - metadata API, so it will not work with all JDBC drivers. This tool is extremely useful for testing. - - - - java -cp hibernate_classpaths - org.hibernate.tool.hbm2ddl.SchemaValidator options mapping_files - - - - <literal>SchemaValidator</literal> Command Line Options - - - - - - Option - Description - - - - - --naming=eg.MyNamingStrategy - select a NamingStrategy - - - --properties=hibernate.properties - read database properties from a file - - - --config=hibernate.cfg.xml - specify a .cfg.xml file - - - -
- - - You may embed SchemaValidator in your application: - - - - - - - - Using Ant for schema validation - - - You can call SchemaValidator from the Ant script: - - - - - - - - - - -]]> - - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/transactions.xml b/documentation/envers/src/main/docbook/en-US/content/transactions.xml deleted file mode 100644 index 25e80f4237..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/transactions.xml +++ /dev/null @@ -1,1136 +0,0 @@ - - - - - - - Transactions And Concurrency - - - The most important point about Hibernate and concurrency control is that it is very - easy to understand. Hibernate directly uses JDBC connections and JTA resources without - adding any additional locking behavior. We highly recommend you spend some time with the - JDBC, ANSI, and transaction isolation specification of your database management system. - - - - Hibernate does not lock objects in memory. Your application can expect the behavior as - defined by the isolation level of your database transactions. Note that thanks to the - Session, which is also a transaction-scoped cache, Hibernate - provides repeatable reads for lookup by identifier and entity queries (not - reporting queries that return scalar values). - - - - In addition to versioning for automatic optimistic concurrency control, Hibernate also - offers a (minor) API for pessimistic locking of rows, using the - SELECT FOR UPDATE syntax. Optimistic concurrency control and - this API are discussed later in this chapter. - - - - We start the discussion of concurrency control in Hibernate with the granularity of - Configuration, SessionFactory, and - Session, as well as database transactions and long conversations. - - - - Session and transaction scopes - - - A SessionFactory is an expensive-to-create, threadsafe object - intended to be shared by all application threads. It is created once, usually on - application startup, from a Configuration instance. - - - - A Session is an inexpensive, non-threadsafe object that should be - used once, for a single request, a conversation, single unit of work, and then discarded. - A Session will not obtain a JDBC Connection - (or a Datasource) unless it is needed, hence consume no - resources until used. - - - - To complete this picture you also have to think about database transactions. A - database transaction has to be as short as possible, to reduce lock contention in - the database. Long database transactions will prevent your application from scaling - to highly concurrent load. Hence, it is almost never good design to hold a - database transaction open during user think time, until the unit of work is - complete. - - - - What is the scope of a unit of work? Can a single Hibernate Session - span several database transactions or is this a one-to-one relationship of scopes? When - should you open and close a Session and how do you demarcate the - database transaction boundaries? - - - - Unit of work - - - First, don't use the session-per-operation antipattern, that is, - don't open and close a Session for every simple database call in - a single thread! Of course, the same is true for database transactions. Database calls - in an application are made using a planned sequence, they are grouped into atomic - units of work. (Note that this also means that auto-commit after every single - SQL statement is useless in an application, this mode is intended for ad-hoc SQL - console work. Hibernate disables, or expects the application server to do so, - auto-commit mode immediately.) Database transactions are never optional, all - communication with a database has to occur inside a transaction, no matter if - you read or write data. As explained, auto-commit behavior for reading data - should be avoided, as many small transactions are unlikely to perform better than - one clearly defined unit of work. The latter is also much more maintainable - and extensible. - - - - The most common pattern in a multi-user client/server application is - session-per-request. In this model, a request from the client - is sent to the server (where the Hibernate persistence layer runs), a new Hibernate - Session is opened, and all database operations are executed in this unit - of work. Once the work has been completed (and the response for the client has been prepared), - the session is flushed and closed. You would also use a single database transaction to - serve the clients request, starting and committing it when you open and close the - Session. The relationship between the two is one-to-one and this - model is a perfect fit for many applications. - - - - The challenge lies in the implementation. Hibernate provides built-in management of - the "current session" to simplify this pattern. All you have to do is start a - transaction when a server request has to be processed, and end the transaction - before the response is sent to the client. You can do this in any way you - like, common solutions are ServletFilter, AOP interceptor with a - pointcut on the service methods, or a proxy/interception container. An EJB container - is a standardized way to implement cross-cutting aspects such as transaction - demarcation on EJB session beans, declaratively with CMT. If you decide to - use programmatic transaction demarcation, prefer the Hibernate Transaction - API shown later in this chapter, for ease of use and code portability. - - - - Your application code can access a "current session" to process the request - by simply calling sessionFactory.getCurrentSession() anywhere - and as often as needed. You will always get a Session scoped - to the current database transaction. This has to be configured for either - resource-local or JTA environments, see . - - - - Sometimes it is convenient to extend the scope of a Session and - database transaction until the "view has been rendered". This is especially useful - in servlet applications that utilize a separate rendering phase after the request - has been processed. Extending the database transaction until view rendering is - complete is easy to do if you implement your own interceptor. However, it is not - easily doable if you rely on EJBs with container-managed transactions, as a - transaction will be completed when an EJB method returns, before rendering of any - view can start. See the Hibernate website and forum for tips and examples around - this Open Session in View pattern. - - - - - - Long conversations - - - The session-per-request pattern is not the only useful concept you can use to design - units of work. Many business processes require a whole series of interactions with the user - interleaved with database accesses. In web and enterprise applications it is - not acceptable for a database transaction to span a user interaction. Consider the following - example: - - - - - - The first screen of a dialog opens, the data seen by the user has been loaded in - a particular Session and database transaction. The user is free to - modify the objects. - - - - - The user clicks "Save" after 5 minutes and expects his modifications to be made - persistent; he also expects that he was the only person editing this information and - that no conflicting modification can occur. - - - - - - We call this unit of work, from the point of view of the user, a long running - conversation (or application transaction). - There are many ways how you can implement this in your application. - - - - A first naive implementation might keep the Session and database - transaction open during user think time, with locks held in the database to prevent - concurrent modification, and to guarantee isolation and atomicity. This is of course - an anti-pattern, since lock contention would not allow the application to scale with - the number of concurrent users. - - - - Clearly, we have to use several database transactions to implement the conversation. - In this case, maintaining isolation of business processes becomes the - partial responsibility of the application tier. A single conversation - usually spans several database transactions. It will be atomic if only one of - these database transactions (the last one) stores the updated data, all others - simply read data (e.g. in a wizard-style dialog spanning several request/response - cycles). This is easier to implement than it might sound, especially if - you use Hibernate's features: - - - - - - Automatic Versioning - Hibernate can do automatic - optimistic concurrency control for you, it can automatically detect - if a concurrent modification occurred during user think time. Usually - we only check at the end of the conversation. - - - - - Detached Objects - If you decide to use the already - discussed session-per-request pattern, all loaded instances - will be in detached state during user think time. Hibernate allows you to - reattach the objects and persist the modifications, the pattern is called - session-per-request-with-detached-objects. Automatic - versioning is used to isolate concurrent modifications. - - - - - Extended (or Long) Session - The Hibernate - Session may be disconnected from the underlying JDBC - connection after the database transaction has been committed, and reconnected - when a new client request occurs. This pattern is known as - session-per-conversation and makes - even reattachment unnecessary. Automatic versioning is used to isolate - concurrent modifications and the Session is usually - not allowed to be flushed automatically, but explicitly. - - - - - - Both session-per-request-with-detached-objects and - session-per-conversation have advantages and disadvantages, - we discuss them later in this chapter in the context of optimistic concurrency control. - - - - - - Considering object identity - - - An application may concurrently access the same persistent state in two - different Sessions. However, an instance of a persistent class - is never shared between two Session instances. Hence there are - two different notions of identity: - - - - - Database Identity - - - foo.getId().equals( bar.getId() ) - - - - - JVM Identity - - - foo==bar - - - - - - - Then for objects attached to a particular Session - (i.e. in the scope of a Session) the two notions are equivalent, and - JVM identity for database identity is guaranteed by Hibernate. However, while the application - might concurrently access the "same" (persistent identity) business object in two different - sessions, the two instances will actually be "different" (JVM identity). Conflicts are - resolved using (automatic versioning) at flush/commit time, using an optimistic approach. - - - - This approach leaves Hibernate and the database to worry about concurrency; it also provides - the best scalability, since guaranteeing identity in single-threaded units of work only doesn't - need expensive locking or other means of synchronization. The application never needs to - synchronize on any business object, as long as it sticks to a single thread per - Session. Within a Session the application may safely use - == to compare objects. - - - - However, an application that uses == outside of a Session, - might see unexpected results. This might occur even in some unexpected places, for example, - if you put two detached instances into the same Set. Both might have the same - database identity (i.e. they represent the same row), but JVM identity is by definition not - guaranteed for instances in detached state. The developer has to override the equals() - and hashCode() methods in persistent classes and implement - his own notion of object equality. There is one caveat: Never use the database - identifier to implement equality, use a business key, a combination of unique, usually - immutable, attributes. The database identifier will change if a transient object is made - persistent. If the transient instance (usually together with detached instances) is held in a - Set, changing the hashcode breaks the contract of the Set. - Attributes for business keys don't have to be as stable as database primary keys, you only - have to guarantee stability as long as the objects are in the same Set. See - the Hibernate website for a more thorough discussion of this issue. Also note that this is not - a Hibernate issue, but simply how Java object identity and equality has to be implemented. - - - - - - Common issues - - - Never use the anti-patterns session-per-user-session or - session-per-application (of course, there are rare exceptions to - this rule). Note that some of the following issues might also appear with the recommended - patterns, make sure you understand the implications before making a design decision: - - - - - - A Session is not thread-safe. Things which are supposed to work - concurrently, like HTTP requests, session beans, or Swing workers, will cause race - conditions if a Session instance would be shared. If you keep your - Hibernate Session in your HttpSession (discussed - later), you should consider synchronizing access to your Http session. Otherwise, - a user that clicks reload fast enough may use the same Session in - two concurrently running threads. - - - - - An exception thrown by Hibernate means you have to rollback your database transaction - and close the Session immediately (discussed later in more detail). - If your Session is bound to the application, you have to stop - the application. Rolling back the database transaction doesn't put your business - objects back into the state they were at the start of the transaction. This means the - database state and the business objects do get out of sync. Usually this is not a - problem, because exceptions are not recoverable and you have to start over after - rollback anyway. - - - - - The Session caches every object that is in persistent state (watched - and checked for dirty state by Hibernate). This means it grows endlessly until you - get an OutOfMemoryException, if you keep it open for a long time or simply load too - much data. One solution for this is to call clear() and evict() - to manage the Session cache, but you most likely should consider a - Stored Procedure if you need mass data operations. Some solutions are shown in - . Keeping a Session open for the duration - of a user session also means a high probability of stale data. - - - - - - - - - - Database transaction demarcation - - - Database (or system) transaction boundaries are always necessary. No communication with - the database can occur outside of a database transaction (this seems to confuse many developers - who are used to the auto-commit mode). Always use clear transaction boundaries, even for - read-only operations. Depending on your isolation level and database capabilities this might not - be required but there is no downside if you always demarcate transactions explicitly. Certainly, - a single database transaction is going to perform better than many small transactions, even - for reading data. - - - - A Hibernate application can run in non-managed (i.e. standalone, simple Web- or Swing applications) - and managed J2EE environments. In a non-managed environment, Hibernate is usually responsible for - its own database connection pool. The application developer has to manually set transaction - boundaries, in other words, begin, commit, or rollback database transactions himself. A managed environment - usually provides container-managed transactions (CMT), with the transaction assembly defined declaratively - in deployment descriptors of EJB session beans, for example. Programmatic transaction demarcation is - then no longer necessary. - - - - However, it is often desirable to keep your persistence layer portable between non-managed - resource-local environments, and systems that can rely on JTA but use BMT instead of CMT. - In both cases you'd use programmatic transaction demarcation. Hibernate offers a wrapper - API called Transaction that translates into the native transaction system of - your deployment environment. This API is actually optional, but we strongly encourage its use - unless you are in a CMT session bean. - - - - Usually, ending a Session involves four distinct phases: - - - - - - flush the session - - - - - commit the transaction - - - - - close the session - - - - - handle exceptions - - - - - - Flushing the session has been discussed earlier, we'll now have a closer look at transaction - demarcation and exception handling in both managed- and non-managed environments. - - - - - Non-managed environment - - - If a Hibernate persistence layer runs in a non-managed environment, database connections - are usually handled by simple (i.e. non-DataSource) connection pools from which - Hibernate obtains connections as needed. The session/transaction handling idiom looks - like this: - - - - - - You don't have to flush() the Session explicitly - - the call to commit() automatically triggers the synchronization (depending - upon the FlushMode for the session. - A call to close() marks the end of a session. The main implication - of close() is that the JDBC connection will be relinquished by the - session. This Java code is portable and runs in both non-managed and JTA environments. - - - - A much more flexible solution is Hibernate's built-in "current session" context - management, as described earlier: - - - - - - You will very likely never see these code snippets in a regular application; - fatal (system) exceptions should always be caught at the "top". In other words, the - code that executes Hibernate calls (in the persistence layer) and the code that handles - RuntimeException (and usually can only clean up and exit) are in - different layers. The current context management by Hibernate can significantly - simplify this design, as all you need is access to a SessionFactory. - Exception handling is discussed later in this chapter. - - - - Note that you should select org.hibernate.transaction.JDBCTransactionFactory - (which is the default), and for the second example "thread" as your - hibernate.current_session_context_class. - - - - - - Using JTA - - - If your persistence layer runs in an application server (e.g. behind EJB session beans), - every datasource connection obtained by Hibernate will automatically be part of the global - JTA transaction. You can also install a standalone JTA implementation and use it without - EJB. Hibernate offers two strategies for JTA integration. - - - - If you use bean-managed transactions (BMT) Hibernate will tell the application server to start - and end a BMT transaction if you use the Transaction API. So, the - transaction management code is identical to the non-managed environment. - - - - - - If you want to use a transaction-bound Session, that is, the - getCurrentSession() functionality for easy context propagation, - you will have to use the JTA UserTransaction API directly: - - - - - - With CMT, transaction demarcation is done in session bean deployment descriptors, not programmatically, - hence, the code is reduced to: - - - - - - In a CMT/EJB even rollback happens automatically, since an unhandled RuntimeException - thrown by a session bean method tells the container to set the global transaction to rollback. - This means you do not need to use the Hibernate Transaction API at - all with BMT or CMT, and you get automatic propagation of the "current" Session bound to the - transaction. - - - - Note that you should choose org.hibernate.transaction.JTATransactionFactory - if you use JTA directly (BMT), and org.hibernate.transaction.CMTTransactionFactory - in a CMT session bean, when you configure Hibernate's transaction factory. Remember to also set - hibernate.transaction.manager_lookup_class. Furthermore, make sure - that your hibernate.current_session_context_class is either unset (backwards - compatibility), or set to "jta". - - - - The getCurrentSession() operation has one downside in a JTA environment. - There is one caveat to the use of after_statement connection release - mode, which is then used by default. Due to a silly limitation of the JTA spec, it is not - possible for Hibernate to automatically clean up any unclosed ScrollableResults or - Iterator instances returned by scroll() or - iterate(). You must release the underlying database - cursor by calling ScrollableResults.close() or - Hibernate.close(Iterator) explicitly from a finally - block. (Of course, most applications can easily avoid using scroll() or - iterate() at all from the JTA or CMT code.) - - - - - - Exception handling - - - If the Session throws an exception (including any - SQLException), you should immediately rollback the database - transaction, call Session.close() and discard the - Session instance. Certain methods of Session - will not leave the session in a consistent state. No - exception thrown by Hibernate can be treated as recoverable. Ensure that the - Session will be closed by calling close() - in a finally block. - - - - The HibernateException, which wraps most of the errors that - can occur in a Hibernate persistence layer, is an unchecked exception (it wasn't - in older versions of Hibernate). In our opinion, we shouldn't force the application - developer to catch an unrecoverable exception at a low layer. In most systems, unchecked - and fatal exceptions are handled in one of the first frames of the method call - stack (i.e. in higher layers) and an error message is presented to the application - user (or some other appropriate action is taken). Note that Hibernate might also throw - other unchecked exceptions which are not a HibernateException. These - are, again, not recoverable and appropriate action should be taken. - - - - Hibernate wraps SQLExceptions thrown while interacting with the database - in a JDBCException. In fact, Hibernate will attempt to convert the exception - into a more meaningful subclass of JDBCException. The underlying - SQLException is always available via JDBCException.getCause(). - Hibernate converts the SQLException into an appropriate - JDBCException subclass using the SQLExceptionConverter - attached to the SessionFactory. By default, the - SQLExceptionConverter is defined by the configured dialect; however, it is - also possible to plug in a custom implementation (see the javadocs for the - SQLExceptionConverterFactory class for details). The standard - JDBCException subtypes are: - - - - - - JDBCConnectionException - indicates an error - with the underlying JDBC communication. - - - - - SQLGrammarException - indicates a grammar - or syntax problem with the issued SQL. - - - - - ConstraintViolationException - indicates some - form of integrity constraint violation. - - - - - LockAcquisitionException - indicates an error - acquiring a lock level necessary to perform the requested operation. - - - - - GenericJDBCException - a generic exception - which did not fall into any of the other categories. - - - - - - - - Transaction timeout - - - One extremely important feature provided by a managed environment like EJB - that is never provided for non-managed code is transaction timeout. Transaction - timeouts ensure that no misbehaving transaction can indefinitely tie up - resources while returning no response to the user. Outside a managed (JTA) - environment, Hibernate cannot fully provide this functionality. However, - Hibernate can at least control data access operations, ensuring that database - level deadlocks and queries with huge result sets are limited by a defined - timeout. In a managed environment, Hibernate can delegate transaction timeout - to JTA. This functionality is abstracted by the Hibernate - Transaction object. - - - - - - Note that setTimeout() may not be called in a CMT bean, - where transaction timeouts must be defined declaratively. - - - - - - - - Optimistic concurrency control - - - The only approach that is consistent with high concurrency and high - scalability is optimistic concurrency control with versioning. Version - checking uses version numbers, or timestamps, to detect conflicting updates - (and to prevent lost updates). Hibernate provides for three possible approaches - to writing application code that uses optimistic concurrency. The use cases - we show are in the context of long conversations, but version checking - also has the benefit of preventing lost updates in single database transactions. - - - - Application version checking - - - In an implementation without much help from Hibernate, each interaction with the - database occurs in a new Session and the developer is responsible - for reloading all persistent instances from the database before manipulating them. - This approach forces the application to carry out its own version checking to ensure - conversation transaction isolation. This approach is the least efficient in terms of - database access. It is the approach most similar to entity EJBs. - - - - - - The version property is mapped using <version>, - and Hibernate will automatically increment it during flush if the entity is - dirty. - - - - Of course, if you are operating in a low-data-concurrency environment and don't - require version checking, you may use this approach and just skip the version - check. In that case, last commit wins will be the default - strategy for your long conversations. Keep in mind that this might - confuse the users of the application, as they might experience lost updates without - error messages or a chance to merge conflicting changes. - - - - Clearly, manual version checking is only feasible in very trivial circumstances - and not practical for most applications. Often not only single instances, but - complete graphs of modified objects have to be checked. Hibernate offers automatic - version checking with either an extended Session or detached instances - as the design paradigm. - - - - - - Extended session and automatic versioning - - - A single Session instance and its persistent instances are - used for the whole conversation, known as session-per-conversation. - Hibernate checks instance versions at flush time, throwing an exception if concurrent - modification is detected. It's up to the developer to catch and handle this exception - (common options are the opportunity for the user to merge changes or to restart the - business conversation with non-stale data). - - - - The Session is disconnected from any underlying JDBC connection - when waiting for user interaction. This approach is the most efficient in terms - of database access. The application need not concern itself with version checking or - with reattaching detached instances, nor does it have to reload instances in every - database transaction. - - - - - The foo object still knows which Session it was - loaded in. Beginning a new database transaction on an old session obtains a new connection - and resumes the session. Committing a database transaction disconnects a session - from the JDBC connection and returns the connection to the pool. After reconnection, to - force a version check on data you aren't updating, you may call Session.lock() - with LockMode.READ on any objects that might have been updated by another - transaction. You don't need to lock any data that you are updating. - Usually you would set FlushMode.MANUAL on an extended Session, - so that only the last database transaction cycle is allowed to actually persist all - modifications made in this conversation. Hence, only this last database transaction - would include the flush() operation, and then also - close() the session to end the conversation. - - - - This pattern is problematic if the Session is too big to - be stored during user think time, e.g. an HttpSession should - be kept as small as possible. As the Session is also the - (mandatory) first-level cache and contains all loaded objects, we can probably - use this strategy only for a few request/response cycles. You should use a - Session only for a single conversation, as it will soon also - have stale data. - - - - (Note that earlier Hibernate versions required explicit disconnection and reconnection - of a Session. These methods are deprecated, as beginning and - ending a transaction has the same effect.) - - - - Also note that you should keep the disconnected Session close - to the persistence layer. In other words, use an EJB stateful session bean to - hold the Session in a three-tier environment, and don't transfer - it to the web layer (or even serialize it to a separate tier) to store it in the - HttpSession. - - - - The extended session pattern, or session-per-conversation, is - more difficult to implement with automatic current session context management. - You need to supply your own implementation of the CurrentSessionContext - for this, see the Hibernate Wiki for examples. - - - - - - Detached objects and automatic versioning - - - Each interaction with the persistent store occurs in a new Session. - However, the same persistent instances are reused for each interaction with the database. - The application manipulates the state of detached instances originally loaded in another - Session and then reattaches them using Session.update(), - Session.saveOrUpdate(), or Session.merge(). - - - - - - Again, Hibernate will check instance versions during flush, throwing an - exception if conflicting updates occurred. - - - - You may also call lock() instead of update() - and use LockMode.READ (performing a version check, bypassing all - caches) if you are sure that the object has not been modified. - - - - - - Customizing automatic versioning - - - You may disable Hibernate's automatic version increment for particular properties and - collections by setting the optimistic-lock mapping attribute to - false. Hibernate will then no longer increment versions if the - property is dirty. - - - - Legacy database schemas are often static and can't be modified. Or, other applications - might also access the same database and don't know how to handle version numbers or - even timestamps. In both cases, versioning can't rely on a particular column in a table. - To force a version check without a version or timestamp property mapping, with a - comparison of the state of all fields in a row, turn on optimistic-lock="all" - in the <class> mapping. Note that this conceptually only works - if Hibernate can compare the old and new state, i.e. if you use a single long - Session and not session-per-request-with-detached-objects. - - - - Sometimes concurrent modification can be permitted as long as the changes that have been - made don't overlap. If you set optimistic-lock="dirty" when mapping the - <class>, Hibernate will only compare dirty fields during flush. - - - - In both cases, with dedicated version/timestamp columns or with full/dirty field - comparison, Hibernate uses a single UPDATE statement (with an - appropriate WHERE clause) per entity to execute the version check - and update the information. If you use transitive persistence to cascade reattachment - to associated entities, Hibernate might execute unnecessary updates. This is usually - not a problem, but on update triggers in the database might be - executed even when no changes have been made to detached instances. You can customize - this behavior by setting select-before-update="true" in the - <class> mapping, forcing Hibernate to SELECT - the instance to ensure that changes did actually occur, before updating the row. - - - - - - - - Pessimistic Locking - - - It is not intended that users spend much time worrying about locking strategies. It's usually - enough to specify an isolation level for the JDBC connections and then simply let the - database do all the work. However, advanced users may sometimes wish to obtain - exclusive pessimistic locks, or re-obtain locks at the start of a new transaction. - - - - Hibernate will always use the locking mechanism of the database, never lock objects - in memory! - - - - The LockMode class defines the different lock levels that may be acquired - by Hibernate. A lock is obtained by the following mechanisms: - - - - - - LockMode.WRITE is acquired automatically when Hibernate updates or inserts - a row. - - - - - LockMode.UPGRADE may be acquired upon explicit user request using - SELECT ... FOR UPDATE on databases which support that syntax. - - - - - LockMode.UPGRADE_NOWAIT may be acquired upon explicit user request using a - SELECT ... FOR UPDATE NOWAIT under Oracle. - - - - - LockMode.READ is acquired automatically when Hibernate reads data - under Repeatable Read or Serializable isolation level. May be re-acquired by explicit user - request. - - - - - LockMode.NONE represents the absence of a lock. All objects switch to this - lock mode at the end of a Transaction. Objects associated with the session - via a call to update() or saveOrUpdate() also start out - in this lock mode. - - - - - - The "explicit user request" is expressed in one of the following ways: - - - - - - A call to Session.load(), specifying a LockMode. - - - - - A call to Session.lock(). - - - - - A call to Query.setLockMode(). - - - - - - If Session.load() is called with UPGRADE or - UPGRADE_NOWAIT, and the requested object was not yet loaded by - the session, the object is loaded using SELECT ... FOR UPDATE. - If load() is called for an object that is already loaded with - a less restrictive lock than the one requested, Hibernate calls - lock() for that object. - - - - Session.lock() performs a version number check if the specified lock - mode is READ, UPGRADE or - UPGRADE_NOWAIT. (In the case of UPGRADE or - UPGRADE_NOWAIT, SELECT ... FOR UPDATE is used.) - - - - If the database does not support the requested lock mode, Hibernate will use an appropriate - alternate mode (instead of throwing an exception). This ensures that applications will - be portable. - - - - - - Connection Release Modes - - - The legacy (2.x) behavior of Hibernate in regards to JDBC connection management - was that a Session would obtain a connection when it was first - needed and then hold unto that connection until the session was closed. - Hibernate 3.x introduced the notion of connection release modes to tell a session - how to handle its JDBC connections. Note that the following discussion is pertinent - only to connections provided through a configured ConnectionProvider; - user-supplied connections are outside the breadth of this discussion. The different - release modes are identified by the enumerated values of - org.hibernate.ConnectionReleaseMode: - - - - - - ON_CLOSE - is essentially the legacy behavior described above. The - Hibernate session obtains a connection when it first needs to perform some JDBC access - and holds unto that connection until the session is closed. - - - - - AFTER_TRANSACTION - says to release connections after a - org.hibernate.Transaction has completed. - - - - - AFTER_STATEMENT (also referred to as aggressive release) - says to - release connections after each and every statement execution. This aggressive releasing - is skipped if that statement leaves open resources associated with the given session; - currently the only situation where this occurs is through the use of - org.hibernate.ScrollableResults. - - - - - - The configuration parameter hibernate.connection.release_mode is used - to specify which release mode to use. The possible values: - - - - - - auto (the default) - this choice delegates to the release mode - returned by the org.hibernate.transaction.TransactionFactory.getDefaultReleaseMode() - method. For JTATransactionFactory, this returns ConnectionReleaseMode.AFTER_STATEMENT; for - JDBCTransactionFactory, this returns ConnectionReleaseMode.AFTER_TRANSACTION. It is rarely - a good idea to change this default behavior as failures due to the value of this setting - tend to indicate bugs and/or invalid assumptions in user code. - - - - - on_close - says to use ConnectionReleaseMode.ON_CLOSE. This setting - is left for backwards compatibility, but its use is highly discouraged. - - - - - after_transaction - says to use ConnectionReleaseMode.AFTER_TRANSACTION. - This setting should not be used in JTA environments. Also note that with - ConnectionReleaseMode.AFTER_TRANSACTION, if a session is considered to be in auto-commit - mode connections will be released as if the release mode were AFTER_STATEMENT. - - - - - after_statement - says to use ConnectionReleaseMode.AFTER_STATEMENT. Additionally, - the configured ConnectionProvider is consulted to see if it supports this - setting (supportsAggressiveRelease()). If not, the release mode is reset - to ConnectionReleaseMode.AFTER_TRANSACTION. This setting is only safe in environments where - we can either re-acquire the same underlying JDBC connection each time we make a call into - ConnectionProvider.getConnection() or in auto-commit environments where - it does not matter whether we get back the same connection. - - - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/tutorial.xml b/documentation/envers/src/main/docbook/en-US/content/tutorial.xml deleted file mode 100644 index e2dfa9c05a..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/tutorial.xml +++ /dev/null @@ -1,1617 +0,0 @@ - - - - -]> - - - - - Introduction to Hibernate - - - Preface - - - This chapter is an introduction to Hibernate by way of a tutorial, - intended for new users of Hibernate. We start with a simple - application using an in-memory database. We build the - application in small, easy to understand steps. The tutorial is - based on another, earlier one developed by Michael Gloegl. All - code is contained in the tutorials/web directory - of the project source. - - - - - - - This tutorial expects the user have knowledge of both Java and - SQL. If you are new or uncomfortable with either, it is advised - that you start with a good introduction to that technology prior - to attempting to learn Hibernate. It will save time and effort - in the long run. - - - - - - There is another tutorial/example application in the - /tutorials/eg directory of the project source. - That example is console based and as such would not have the - dependency on a servlet container to execute. The basic setup is - the same as the instructions below. - - - - - Part 1 - The first Hibernate Application - - - Let's assume we need a small database application that can store - events we want to attend, and information about the host(s) of - these events. We will use an in-memory, Java database named HSQLDB - to avoid describing installation/setup of any particular database - servers. Feel free to tweak this tutorial to use whatever database - you feel comfortable using. - - - - The first thing we need to do is set up our development environment, - and specifically to setup all the required dependencies to Hibernate - as well as other libraries. Hibernate is built using Maven which - amongst other features provides dependecy management; - moreover it provides transitive - dependecy management which simply means that to use - Hibernate we can simply define our dependency on Hibernate, Hibernate - itself defines the dependencies it needs which then become transitive - dependencies of our project. - - - - - ... - - - - ${groupId} - hibernate-core - - - - - javax.servlet - servlet-api - - - -]]> - - - - Essentially we are describing here the - /tutorials/web/pom.xml file. See the - Maven site for more information. - - - - - - While not strictly necessary, most IDEs have integration with Maven - to read these POM files and automatically set up a project for you - which can save lots of time and effort. - - - - - Next we create a class that represents the event we want to store in database. - - - - The first class - - - Our first persistent class is a simple JavaBean class with some properties: - - - - - - You can see that this class uses standard JavaBean naming conventions for property - getter and setter methods, as well as private visibility for the fields. This is - a recommended design - but not required. Hibernate can also access fields directly, - the benefit of accessor methods is robustness for refactoring. The no-argument - constructor is required to instantiate an object of this class through reflection. - - - - The id property holds a unique identifier value for a particular event. - All persistent entity classes (there are less important dependent classes as well) will need - such an identifier property if we want to use the full feature set of Hibernate. In fact, - most applications (esp. web applications) need to distinguish objects by identifier, so you - should consider this a feature rather than a limitation. However, we usually don't manipulate - the identity of an object, hence the setter method should be private. Only Hibernate will assign - identifiers when an object is saved. You can see that Hibernate can access public, private, - and protected accessor methods, as well as (public, private, protected) fields directly. The - choice is up to you and you can match it to fit your application design. - - - - The no-argument constructor is a requirement for all persistent classes; Hibernate - has to create objects for you, using Java Reflection. The constructor can be - private, however, package visibility is required for runtime proxy generation and - efficient data retrieval without bytecode instrumentation. - - - - Place this Java source file in a directory called src in the - development folder, and in its correct package. The directory should now look like this: - - - -+src - +events - Event.java]]> - - - In the next step, we tell Hibernate about this persistent class. - - - - - - The mapping file - - - Hibernate needs to know how to load and store objects of the persistent class. - This is where the Hibernate mapping file comes into play. The mapping file - tells Hibernate what table in the database it has to access, and what columns - in that table it should use. - - - - The basic structure of a mapping file looks like this: - - - - - - -[...] -]]> - - - Note that the Hibernate DTD is very sophisticated. You can use it for - auto-completion of XML mapping elements and attributes in your editor or - IDE. You also should open up the DTD file in your text editor - it's the - easiest way to get an overview of all elements and attributes and to see - the defaults, as well as some comments. Note that Hibernate will not - load the DTD file from the web, but first look it up from the classpath - of the application. The DTD file is included in hibernate3.jar - as well as in the src/ directory of the Hibernate distribution. - - - - We will omit the DTD declaration in future examples to shorten the code. It is - of course not optional. - - - - Between the two hibernate-mapping tags, include a - class element. All persistent entity classes (again, there - might be dependent classes later on, which are not first-class entities) need - such a mapping, to a table in the SQL database: - - - - - - - - -]]> - - - So far we told Hibernate how to persist and load object of class Event - to the table EVENTS, each instance represented by a row in that table. - Now we continue with a mapping of the unique identifier property to the tables primary key. - In addition, as we don't want to care about handling this identifier, we configure Hibernate's - identifier generation strategy for a surrogate primary key column: - - - - - - - - - - -]]> - - - The id element is the declaration of the identifier property, - name="id" declares the name of the Java property - - Hibernate will use the getter and setter methods to access the property. - The column attribute tells Hibernate which column of the - EVENTS table we use for this primary key. The nested - generator element specifies the identifier generation strategy, - in this case we used native, which picks the best strategy depending - on the configured database (dialect). Hibernate supports database generated, globally - unique, as well as application assigned identifiers (or any strategy you have written - an extension for). - - - - Finally we include declarations for the persistent properties of the class in - the mapping file. By default, no properties of the class are considered - persistent: - - - - - - - - - - - - -]]> - - - Just as with the id element, the name - attribute of the property element tells Hibernate which getter - and setter methods to use. So, in this case, Hibernate will look for - getDate()/setDate(), as well as getTitle()/setTitle(). - - - - Why does the date property mapping include the - column attribute, but the title - doesn't? Without the column attribute Hibernate - by default uses the property name as the column name. This works fine for - title. However, date is a reserved - keyword in most database, so we better map it to a different name. - - - - The next interesting thing is that the title mapping also lacks - a type attribute. The types we declare and use in the mapping - files are not, as you might expect, Java data types. They are also not SQL - database types. These types are so called Hibernate mapping types, - converters which can translate from Java to SQL data types and vice versa. Again, - Hibernate will try to determine the correct conversion and mapping type itself if - the type attribute is not present in the mapping. In some cases this - automatic detection (using Reflection on the Java class) might not have the default you - expect or need. This is the case with the date property. Hibernate can't - know if the property (which is of java.util.Date) should map to a - SQL date, timestamp, or time column. - We preserve full date and time information by mapping the property with a - timestamp converter. - - - - This mapping file should be saved as Event.hbm.xml, right in - the directory next to the Event Java class source file. - The naming of mapping files can be arbitrary, however the hbm.xml - suffix is a convention in the Hibernate developer community. The directory structure - should now look like this: - - - -+src - +events - Event.java - Event.hbm.xml]]> - - - We continue with the main configuration of Hibernate. - - - - - - Hibernate configuration - - - We now have a persistent class and its mapping file in place. It is time to configure - Hibernate. Before we do this, we will need a database. HSQL DB, a java-based SQL DBMS, - can be downloaded from the HSQL DB website(http://hsqldb.org/). Actually, you only need the hsqldb.jar - from this download. Place this file in the lib/ directory of the - development folder. - - - - Create a directory called data in the root of the development directory - - this is where HSQL DB will store its data files. Now start the database by running - java -classpath ../lib/hsqldb.jar org.hsqldb.Server in this data directory. - You can see it start up and bind to a TCP/IP socket, this is where our application - will connect later. If you want to start with a fresh database during this tutorial, - shutdown HSQL DB (press CTRL + C in the window), delete all files in the - data/ directory, and start HSQL DB again. - - - - Hibernate is the layer in your application which connects to this database, so it needs - connection information. The connections are made through a JDBC connection pool, which we - also have to configure. The Hibernate distribution contains several open source JDBC connection - pooling tools, but will use the Hibernate built-in connection pool for this tutorial. Note that - you have to copy the required library into your classpath and use different - connection pooling settings if you want to use a production-quality third party - JDBC pooling software. - - - - For Hibernate's configuration, we can use a simple hibernate.properties file, a - slightly more sophisticated hibernate.cfg.xml file, or even complete - programmatic setup. Most users prefer the XML configuration file: - - - - - - - - - - - org.hsqldb.jdbcDriver - jdbc:hsqldb:hsql://localhost - sa - - - - 1 - - - org.hibernate.dialect.HSQLDialect - - - thread - - - org.hibernate.cache.NoCacheProvider - - - true - - - create - - - - - -]]> - - - Note that this XML configuration uses a different DTD. We configure - Hibernate's SessionFactory - a global factory responsible - for a particular database. If you have several databases, use several - <session-factory> configurations, usually in - several configuration files (for easier startup). - - - - The first four property elements contain the necessary - configuration for the JDBC connection. The dialect property - element specifies the particular SQL variant Hibernate generates. - Hibernate's automatic session management for persistence contexts will - come in handy as you will soon see. - The hbm2ddl.auto option turns on automatic generation of - database schemas - directly into the database. This can of course also be turned - off (by removing the config option) or redirected to a file with the help of - the SchemaExport Ant task. Finally, we add the mapping file(s) - for persistent classes to the configuration. - - - - Copy this file into the source directory, so it will end up in the - root of the classpath. Hibernate automatically looks for a file called - hibernate.cfg.xml in the root of the classpath, on startup. - - - - - - Building with Ant - - - We'll now build the tutorial with Ant. You will need to have Ant installed - get - it from the Ant download page. - How to install Ant will not be covered here. Please refer to the - Ant manual. After you - have installed Ant, we can start to create the buildfile. It will be called - build.xml and placed directly in the development directory. - - - - A basic build file looks like this: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - This will tell Ant to add all files in the lib directory ending with .jar - to the classpath used for compilation. It will also copy all non-Java source files to the - target directory, e.g. configuration and Hibernate mapping files. If you now run Ant, you - should get this output: - - - ant -Buildfile: build.xml - -copy-resources: - [copy] Copying 2 files to C:\hibernateTutorial\bin - -compile: - [javac] Compiling 1 source file to C:\hibernateTutorial\bin - -BUILD SUCCESSFUL -Total time: 1 second ]]> - - - - - Startup and helpers - - - It's time to load and store some Event objects, but first - we have to complete the setup with some infrastructure code. We have to startup - Hibernate. This startup includes building a global SessionFactory - object and to store it somewhere for easy access in application code. - A SessionFactory can open up new Session's. - A Session represents a single-threaded unit of work, the - SessionFactory is a thread-safe global object, instantiated once. - - - - We'll create a HibernateUtil helper class which takes care - of startup and makes accessing a SessionFactory convenient. - Let's have a look at the implementation: - - - - - - This class does not only produce the global SessionFactory in - its static initializer (called once by the JVM when the class is loaded), but also - hides the fact that it uses a static singleton. It might as well lookup the - SessionFactory from JNDI in an application server. - - - - If you give the SessionFactory a name in your configuration - file, Hibernate will in fact try to bind it to JNDI after it has been built. - To avoid this code completely you could also use JMX deployment and let the - JMX-capable container instantiate and bind a HibernateService - to JNDI. These advanced options are discussed in the Hibernate reference - documentation. - - - - Place HibernateUtil.java in the development source directory, in - a package next to events: - - - -+src - +events - Event.java - Event.hbm.xml - +util - HibernateUtil.java - hibernate.cfg.xml -+data -build.xml]]> - - - This should again compile without problems. We finally need to configure a logging - system - Hibernate uses commons logging and leaves you the choice between Log4j and - JDK 1.4 logging. Most developers prefer Log4j: copy log4j.properties - from the Hibernate distribution (it's in the etc/ directory) to - your src directory, next to hibernate.cfg.xml. - Have a look at the example configuration and change the settings if you like to have - more verbose output. By default, only Hibernate startup message are shown on stdout. - - - - The tutorial infrastructure is complete - and we are ready to do some real work with - Hibernate. - - - - - - Loading and storing objects - - - Finally, we can use Hibernate to load and store objects. We write an - EventManager class with a main() method: - - - - - - We create a new Event object, and hand it over to Hibernate. - Hibernate now takes care of the SQL and executes INSERTs - on the database. Let's have a look at the Session and - Transaction-handling code before we run this. - - - - A Session is a single unit of work. For now we'll keep things - simple and assume a one-to-one granularity between a Hibernate Session - and a database transaction. To shield our code from the actual underlying transaction - system (in this case plain JDBC, but it could also run with JTA) we use the - Transaction API that is available on the Hibernate Session. - - - - What does sessionFactory.getCurrentSession() do? First, you can call it - as many times and anywhere you like, once you get hold of your SessionFactory - (easy thanks to HibernateUtil). The getCurrentSession() - method always returns the "current" unit of work. Remember that we switched the configuration - option for this mechanism to "thread" in hibernate.cfg.xml? Hence, - the current unit of work is bound to the current Java thread that executes our application. - However, this is not the full picture, you also have to consider scope, when a unit of work - begins and when it ends. - - - - A Session begins when it is first needed, when the first call to - getCurrentSession() is made. It is then bound by Hibernate to the current - thread. When the transaction ends, either through commit or rollback, Hibernate automatically - unbinds the Session from the thread and closes it for you. If you call - getCurrentSession() again, you get a new Session and can - start a new unit of work. This thread-bound programming model is the most - popular way of using Hibernate, as it allows flexible layering of your code (transaction - demarcation code can be separated from data access code, we'll do this later in this tutorial). - - - - Related to the unit of work scope, should the Hibernate Session be used to - execute one or several database operations? The above example uses one Session - for one operation. This is pure coincidence, the example is just not complex enough to show any - other approach. The scope of a Hibernate Session is flexible but you should - never design your application to use a new Hibernate Session for - every database operation. So even if you see it a few more times in - the following (very trivial) examples, consider session-per-operation - an anti-pattern. A real (web) application is shown later in this tutorial. - - - - Have a look at for more information - about transaction handling and demarcation. We also skipped any error handling and - rollback in the previous example. - - - - To run this first routine we have to add a callable target to the Ant build file: - - - - - - - -]]> - - - The value of the action argument is set on the command line when - calling the target: - - - ant run -Daction=store]]> - - - You should see, after compilation, Hibernate starting up and, depending on your - configuration, lots of log output. At the end you will find the following line: - - - - - - This is the INSERT executed by Hibernate, the question marks - represent JDBC bind parameters. To see the values bound as arguments, or to reduce - the verbosity of the log, check your log4j.properties. - - - - Now we'd like to list stored events as well, so we add an option to the main method: - - - - - - We also add a new listEvents() method: - - - - - - What we do here is use an HQL (Hibernate Query Language) query to load all existing - Event objects from the database. Hibernate will generate the - appropriate SQL, send it to the database and populate Event objects - with the data. You can create more complex queries with HQL, of course. - - - - Now, to execute and test all of this, follow these steps: - - - - - - Run ant run -Daction=store to store something into the database - and, of course, to generate the database schema before through hbm2ddl. - - - - - Now disable hbm2ddl by commenting out the property in your hibernate.cfg.xml - file. Usually you only leave it turned on in continuous unit testing, but another - run of hbm2ddl would drop everything you have stored - the - create configuration setting actually translates into "drop all - tables from the schema, then re-create all tables, when the SessionFactory is build". - - - - - - If you now call Ant with -Daction=list, you should see the events - you have stored so far. You can of course also call the store action a few - times more. - - - - Note: Most new Hibernate users fail at this point and we see questions about - Table not found error messages regularly. However, if you follow the - steps outlined above you will not have this problem, as hbm2ddl creates the database - schema on the first run, and subsequent application restarts will use this schema. If - you change the mapping and/or database schema, you have to re-enable hbm2ddl once again. - - - - - - - - Part 2 - Mapping associations - - - We mapped a persistent entity class to a table. Let's build on this and add some class associations. - First we'll add people to our application, and store a list of events they participate in. - - - - Mapping the Person class - - - The first cut of the Person class is simple: - - - - - - Create a new mapping file called Person.hbm.xml (don't forget the - DTD reference at the top): - - - - - - - - - - - - - -]]> - - - Finally, add the new mapping to Hibernate's configuration: - - - -]]> - - - We'll now create an association between these two entities. Obviously, persons - can participate in events, and events have participants. The design questions - we have to deal with are: directionality, multiplicity, and collection - behavior. - - - - - - A unidirectional Set-based association - - - We'll add a collection of events to the Person class. That way we can - easily navigate to the events for a particular person, without executing an explicit query - - by calling aPerson.getEvents(). We use a Java collection, a Set, - because the collection will not contain duplicate elements and the ordering is not relevant for us. - - - - We need a unidirectional, many-valued associations, implemented with a Set. - Let's write the code for this in the Java classes and then map it: - - - - - - Before we map this association, think about the other side. Clearly, we could just keep this - unidirectional. Or, we could create another collection on the Event, if we - want to be able to navigate it bi-directional, i.e. anEvent.getParticipants(). - This is not necessary, from a functional perspective. You could always execute an explicit query - to retrieve the participants for a particular event. This is a design choice left to you, but what - is clear from this discussion is the multiplicity of the association: "many" valued on both sides, - we call this a many-to-many association. Hence, we use Hibernate's - many-to-many mapping: - - - - - - - - - - - - - - - -]]> - - - Hibernate supports all kinds of collection mappings, a <set> being most - common. For a many-to-many association (or n:m entity relationship), an - association table is needed. Each row in this table represents a link between a person and an event. - The table name is configured with the table attribute of the set - element. The identifier column name in the association, for the person's side, is defined with the - <key> element, the column name for the event's side with the - column attribute of the <many-to-many>. You also - have to tell Hibernate the class of the objects in your collection (correct: the class on the - other side of the collection of references). - - - - The database schema for this mapping is therefore: - - - | *EVENT_ID | | | - | EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID | - | TITLE | |__________________| | AGE | - |_____________| | FIRSTNAME | - | LASTNAME | - |_____________| - ]]> - - - - - Working the association - - - Let's bring some people and events together in a new method in EventManager: - - - - - - After loading a Person and an Event, simply - modify the collection using the normal collection methods. As you can see, there is no explicit call - to update() or save(), Hibernate automatically - detects that the collection has been modified and needs to be updated. This is called automatic - dirty checking, and you can also try it by modifying the name or the date property of - any of your objects. As long as they are in persistent state, that is, bound - to a particular Hibernate Session (i.e. they have been just loaded or saved in - a unit of work), Hibernate monitors any changes and executes SQL in a write-behind fashion. The - process of synchronizing the memory state with the database, usually only at the end of a unit of - work, is called flushing. In our code, the unit of work ends with a commit - (or rollback) of the database transaction - as defined by the thread configuration - option for the CurrentSessionContext class. - - - - You might of course load person and event in different units of work. Or you modify an object - outside of a Session, when it is not in persistent state (if it was persistent - before, we call this state detached). You can even modify a collection when - it is detached: - - - - - - The call to update makes a detached object persistent again, you could - say it binds it to a new unit of work, so any modifications you made to it while detached - can be saved to the database. This includes any modifications (additions/deletions) you - made to a collection of that entity object. - - - - Well, this is not much use in our current situation, but it's an important concept you can - design into your own application. For now, complete this exercise by adding a new action - to the EventManager's main method and call it from the command line. If - you need the identifiers of a person and an event - the save() method - returns it (you might have to modify some of the previous methods to return that identifier): - - - - - - This was an example of an association between two equally important classes, two entities. - As mentioned earlier, there are other classes and types in a typical model, usually "less - important". Some you have already seen, like an int or a String. - We call these classes value types, and their instances depend - on a particular entity. Instances of these types don't have their own identity, nor are they - shared between entities (two persons don't reference the same firstname - object, even if they have the same first name). Of course, value types can not only be found in - the JDK (in fact, in a Hibernate application all JDK classes are considered value types), but - you can also write dependent classes yourself, Address or MonetaryAmount, - for example. - - - - You can also design a collection of value types. This is conceptually very different from a - collection of references to other entities, but looks almost the same in Java. - - - - - - Collection of values - - - We add a collection of value typed objects to the Person entity. We want to - store email addresses, so the type we use is String, and the collection is - again a Set: - - - - - The mapping of this Set: - - - - - -]]> - - - The difference compared with the earlier mapping is the element part, which tells Hibernate that the collection - does not contain references to another entity, but a collection of elements of type - String (the lowercase name tells you it's a Hibernate mapping type/converter). - Once again, the table attribute of the set element determines - the table name for the collection. The key element defines the foreign-key column - name in the collection table. The column attribute in the element - element defines the column name where the String values will actually be stored. - - - - Have a look at the updated schema: - - - | *EVENT_ID | | | |___________________| - | EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID | <--> | *PERSON_ID | - | TITLE | |__________________| | AGE | | *EMAIL_ADDR | - |_____________| | FIRSTNAME | |___________________| - | LASTNAME | - |_____________| - ]]> - - - You can see that the primary key of the collection table is in fact a composite key, - using both columns. This also implies that there can't be duplicate email addresses - per person, which is exactly the semantics we need for a set in Java. - - - - You can now try and add elements to this collection, just like we did before by - linking persons and events. It's the same code in Java: - - - - - - This time we didn't use a fetch query to initialize the collection. - Hence, the call to its getter method will trigger an additional select to initialize - it, so we can add an element to it. Monitor the SQL log and try to optimize this with - an eager fetch. - - - - - - Bi-directional associations - - - Next we are going to map a bi-directional association - making the association between - person and event work from both sides in Java. Of course, the database schema doesn't - change, we still have many-to-many multiplicity. A relational database is more flexible - than a network programming language, so it doesn't need anything like a navigation - direction - data can be viewed and retrieved in any possible way. - - - - First, add a collection of participants to the Event Event class: - - - - - - Now map this side of the association too, in Event.hbm.xml. - - - - - -]]> - - - As you see, these are normal set mappings in both mapping documents. - Notice that the column names in key and many-to-many are - swapped in both mapping documents. The most important addition here is the - inverse="true" attribute in the set element of the - Event's collection mapping. - - - - What this means is that Hibernate should take the other side - the Person class - - when it needs to find out information about the link between the two. This will be a lot easier to - understand once you see how the bi-directional link between our two entities is created . - - - - - - Working bi-directional links - - - First, keep in mind that Hibernate does not affect normal Java semantics. How did we create a - link between a Person and an Event in the unidirectional - example? We added an instance of Event to the collection of event references, - of an instance of Person. So, obviously, if we want to make this link working - bi-directional, we have to do the same on the other side - adding a Person - reference to the collection in an Event. This "setting the link on both sides" - is absolutely necessary and you should never forget doing it. - - - - Many developers program defensively and create link management methods to - correctly set both sides, e.g. in Person: - - - - - - Notice that the get and set methods for the collection are now protected - this allows classes in the - same package and subclasses to still access the methods, but prevents everybody else from messing - with the collections directly (well, almost). You should probably do the same with the collection - on the other side. - - - - What about the inverse mapping attribute? For you, and for Java, a bi-directional - link is simply a matter of setting the references on both sides correctly. Hibernate however doesn't - have enough information to correctly arrange SQL INSERT and UPDATE - statements (to avoid constraint violations), and needs some help to handle bi-directional associations - properly. Making one side of the association inverse tells Hibernate to basically - ignore it, to consider it a mirror of the other side. That's all that is necessary - for Hibernate to work out all of the issues when transformation a directional navigation model to - a SQL database schema. The rules you have to remember are straightforward: All bi-directional associations - need one side as inverse. In a one-to-many association it has to be the many-side, - in many-to-many association you can pick either side, there is no difference. - - - - - - - - Part 3 - The EventManager web application - - - Let's turn the following discussion into a small web application... - - - - A Hibernate web application uses Session and Transaction - almost like a standalone application. However, some common patterns are useful. We now write - an EventManagerServlet. This servlet can list all events stored in the - database, and it provides an HTML form to enter new events. - - - - Writing the basic servlet - - - Create a new class in your source directory, in the events - package: - - - - - - The servlet handles HTTP GET requests only, hence, the method - we implement is doGet(): - - - - - - The pattern we are applying here is called session-per-request. - When a request hits the servlet, a new Hibernate Session is - opened through the first call to getCurrentSession() on the - SessionFactory. Then a database transaction is started—all - data access as to occur inside a transaction, no matter if data is read or written - (we don't use the auto-commit mode in applications). - - - - Do not use a new Hibernate Session for - every database operation. Use one Hibernate Session that is - scoped to the whole request. Use getCurrentSession(), so that - it is automatically bound to the current Java thread. - - - - Next, the possible actions of the request are processed and the response HTML - is rendered. We'll get to that part soon. - - - - Finally, the unit of work ends when processing and rendering is complete. If any - problem occurred during processing or rendering, an exception will be thrown - and the database transaction rolled back. This completes the - session-per-request pattern. Instead of the transaction - demarcation code in every servlet you could also write a servlet filter. - See the Hibernate website and Wiki for more information about this pattern, - called Open Session in View—you'll need it as soon - as you consider rendering your view in JSP, not in a servlet. - - - - - - Processing and rendering - - - Let's implement the processing of the request and rendering of the page. - - -Event Manager"); - -// Handle actions -if ( "store".equals(request.getParameter("action")) ) { - - String eventTitle = request.getParameter("eventTitle"); - String eventDate = request.getParameter("eventDate"); - - if ( "".equals(eventTitle) || "".equals(eventDate) ) { - out.println("Please enter event title and date."); - } else { - createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate)); - out.println("Added event."); - } -} - -// Print page -printEventForm(out); -listEvents(out, dateFormatter); - -// Write HTML footer -out.println(""); -out.flush(); -out.close();]]> - - - Granted, this coding style with a mix of Java and HTML would not scale - in a more complex application—keep in mind that we are only illustrating - basic Hibernate concepts in this tutorial. The code prints an HTML - header and a footer. Inside this page, an HTML form for event entry and - a list of all events in the database are printed. The first method is - trivial and only outputs HTML: - - - Add new event:"); - out.println("
"); - out.println("Title:
"); - out.println("Date (e.g. 24.12.2009):
"); - out.println(""); - out.println("
"); -}]]> - - - The listEvents() method uses the Hibernate - Session bound to the current thread to execute - a query: - - - 0) { - out.println("

Events in database:

"); - out.println(""); - out.println(""); - out.println(""); - out.println(""); - out.println(""); - for (Iterator it = result.iterator(); it.hasNext();) { - Event event = (Event) it.next(); - out.println(""); - out.println(""); - out.println(""); - out.println(""); - } - out.println("
Event titleEvent date
" + event.getTitle() + "" + dateFormatter.format(event.getDate()) + "
"); - } -}]]> - - - Finally, the store action is dispatched to the - createAndStoreEvent() method, which also uses - the Session of the current thread: - - - - - - That's it, the servlet is complete. A request to the servlet will be processed - in a single Session and Transaction. As - earlier in the standalone application, Hibernate can automatically bind these - objects to the current thread of execution. This gives you the freedom to layer - your code and access the SessionFactory in any way you like. - Usually you'd use a more sophisticated design and move the data access code - into data access objects (the DAO pattern). See the Hibernate Wiki for more - examples. - - - - - - Deploying and testing - - - To deploy this application you have to create a web archive, a WAR. Add the - following Ant target to your build.xml: - - - - - - - - - - -]]> - - - This target creates a file called hibernate-tutorial.war - in your project directory. It packages all libraries and the web.xml - descriptor, which is expected in the base directory of your project: - - - - - - - Event Manager - events.EventManagerServlet - - - - Event Manager - /eventmanager - -]]> - - - Before you compile and deploy the web application, note that an additional library - is required: jsdk.jar. This is the Java servlet development kit, - if you don't have this library already, get it from the Sun website and copy it to - your library directory. However, it will be only used for compilation and excluded - from the WAR package. - - - - To build and deploy call ant war in your project directory - and copy the hibernate-tutorial.war file into your Tomcat - webapp directory. If you don't have Tomcat installed, download - it and follow the installation instructions. You don't have to change any Tomcat - configuration to deploy this application though. - - - - Once deployed and Tomcat is running, access the application at - http://localhost:8080/hibernate-tutorial/eventmanager. Make - sure you watch the Tomcat log to see Hibernate initialize when the first - request hits your servlet (the static initializer in HibernateUtil - is called) and to get the detailed output if any exceptions occurs. - - - - - - - - Summary - - - This tutorial covered the basics of writing a simple standalone Hibernate application - and a small web application. - - - - If you already feel confident with Hibernate, continue browsing through the reference - documentation table of contents for topics you find interesting - most asked are - transactional processing (), fetch - performance (), or the usage of the API () - and the query features (). - - - - Don't forget to check the Hibernate website for more (specialized) tutorials. - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/content/xml.xml b/documentation/envers/src/main/docbook/en-US/content/xml.xml deleted file mode 100755 index 3bd340a4a0..0000000000 --- a/documentation/envers/src/main/docbook/en-US/content/xml.xml +++ /dev/null @@ -1,313 +0,0 @@ - - - - - - - XML Mapping - - - Note that this is an experimental feature in Hibernate 3.0 and is under - extremely active development. - - - - Working with XML data - - - Hibernate lets you work with persistent XML data in much the same way - you work with persistent POJOs. A parsed XML tree can be thought of - as just another way to represent the relational data at the object level, - instead of POJOs. - - - - Hibernate supports dom4j as API for manipulating XML trees. You can write - queries that retrieve dom4j trees from the database and have any - modification you make to the tree automatically synchronized to the - database. You can even take an XML document, parse it using dom4j, and - write it to the database with any of Hibernate's basic operations: - persist(), saveOrUpdate(), merge(), delete(), replicate() - (merging is not yet supported). - - - - This feature has many applications including data import/export, - externalization of entity data via JMS or SOAP and XSLT-based reporting. - - - - A single mapping may be used to simultaneously map properties of a class - and nodes of an XML document to the database, or, if there is no class to map, - it may be used to map just the XML. - - - - Specifying XML and class mapping together - - - Here is an example of mapping a POJO and XML simultaneously: - - - - - - - - - - - ... - -]]> - - - - Specifying only an XML mapping - - - Here is an example where there is no POJO class: - - - - - - - - - - - ... - -]]> - - - This mapping allows you to access the data as a dom4j tree, or as a graph of - property name/value pairs (java Maps). The property names - are purely logical constructs that may be referred to in HQL queries. - - - - - - - - XML mapping metadata - - - Many Hibernate mapping elements accept the node attribute. - This let's you specify the name of an XML attribute or element that holds the - property or entity data. The format of the node attribute - must be one of the following: - - - - - "element-name" - map to the named XML element - - - "@attribute-name" - map to the named XML attribute - - - "." - map to the parent element - - - - "element-name/@attribute-name" - - map to the named attribute of the named element - - - - - - For collections and single valued associations, there is an additional - embed-xml attribute. If embed-xml="true", - the default, the XML tree for the associated entity (or collection of value type) - will be embedded directly in the XML tree for the entity that owns the association. - Otherwise, if embed-xml="false", then only the referenced - identifier value will appear in the XML for single point associations and - collections will simply not appear at all. - - - - You should be careful not to leave embed-xml="true" for - too many associations, since XML does not deal well with circularity! - - - - - - - - - - - - - - - - - - - ... - -]]> - - - in this case, we have decided to embed the collection of account ids, but not - the actual account data. The following HQL query: - - - - - - Would return datasets such as this: - - - - 987632567 - 985612323 - - Gavin - A - King - - ... -]]> - - - If you set embed-xml="true" on the <one-to-many> - mapping, the data might look more like this: - - - - - - 100.29 - - - - -2370.34 - - - Gavin - A - King - - ... -]]> - - - - - - Manipulating XML data - - - Let's rearead and update XML documents in the application. We do this by - obtaining a dom4j session: - - - - - - - - It is extremely useful to combine this feature with Hibernate's replicate() - operation to implement XML-based data import/export. - - - - - - diff --git a/documentation/envers/src/main/docbook/en-US/images/AuthorWork.png b/documentation/envers/src/main/docbook/en-US/images/AuthorWork.png deleted file mode 100644 index ef4ab7227a..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/AuthorWork.png and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/AuthorWork.zargo b/documentation/envers/src/main/docbook/en-US/images/AuthorWork.zargo deleted file mode 100644 index f249b22951..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/AuthorWork.zargo and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/CustomerOrderProduct.png b/documentation/envers/src/main/docbook/en-US/images/CustomerOrderProduct.png deleted file mode 100644 index 7034cbe8cd..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/CustomerOrderProduct.png and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/CustomerOrderProduct.zargo b/documentation/envers/src/main/docbook/en-US/images/CustomerOrderProduct.zargo deleted file mode 100644 index 016c559eee..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/CustomerOrderProduct.zargo and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/EmployerEmployee.png b/documentation/envers/src/main/docbook/en-US/images/EmployerEmployee.png deleted file mode 100644 index a7ecff483f..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/EmployerEmployee.png and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/EmployerEmployee.zargo b/documentation/envers/src/main/docbook/en-US/images/EmployerEmployee.zargo deleted file mode 100644 index 487368e8c7..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/EmployerEmployee.zargo and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/full_cream.png b/documentation/envers/src/main/docbook/en-US/images/full_cream.png deleted file mode 100644 index 4f174a0b05..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/full_cream.png and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/full_cream.svg b/documentation/envers/src/main/docbook/en-US/images/full_cream.svg deleted file mode 100644 index d62b66e893..0000000000 --- a/documentation/envers/src/main/docbook/en-US/images/full_cream.svg +++ /dev/null @@ -1,429 +0,0 @@ - - -]> - - - - - - - - - - - - - - - - - - - - - - -Application - - - -Database - - - -SessionFactory - - - - - -Session - - - - - -Transaction - - - - - - - -TransactionFactory - - - - - - - -ConnectionProvider - - - - - - - - - -JNDI - - - - - -JTA - - - - - -JDBC - - - - - - - - -Transient Objects - - - - - - - - - -Persistent - -Objects - - - diff --git a/documentation/envers/src/main/docbook/en-US/images/hibernate_logo_a.png b/documentation/envers/src/main/docbook/en-US/images/hibernate_logo_a.png deleted file mode 100644 index 0a343c4bca..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/hibernate_logo_a.png and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/lite.png b/documentation/envers/src/main/docbook/en-US/images/lite.png deleted file mode 100644 index 8db5dcb5e1..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/lite.png and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/lite.svg b/documentation/envers/src/main/docbook/en-US/images/lite.svg deleted file mode 100644 index 747d34e185..0000000000 --- a/documentation/envers/src/main/docbook/en-US/images/lite.svg +++ /dev/null @@ -1,334 +0,0 @@ - - -]> - - - - - - - - - - - - - - - - - - - - - - - - - - -Application - - - -Transient Objects - - - -Database - - - -SessionFactory - - - - - - - - - - - -Persistent - -Objects - - - -Session - - - - - - - -JDBC - - - - - - - -JNDI - - - - - - - -JTA - - diff --git a/documentation/envers/src/main/docbook/en-US/images/overview.png b/documentation/envers/src/main/docbook/en-US/images/overview.png deleted file mode 100644 index 1593a9522d..0000000000 Binary files a/documentation/envers/src/main/docbook/en-US/images/overview.png and /dev/null differ diff --git a/documentation/envers/src/main/docbook/en-US/images/overview.svg b/documentation/envers/src/main/docbook/en-US/images/overview.svg deleted file mode 100644 index 7ec1c26be7..0000000000 --- a/documentation/envers/src/main/docbook/en-US/images/overview.svg +++ /dev/null @@ -1,250 +0,0 @@ - - -]> - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Application - - - -Persistent Objects - - - -Database - - - -HIBERNATE - - - - - - - - - - - - - - -hibernate. - -properties - - - -XML Mapping - - -