JBoss Enterprise Web Platform 5

Hibernate Core Reference Guide

for use with JBoss Enterprise Web Platform 5

Edition 5.1.1

Red Hat Documentation Group

Legal Notice

Copyright © 2011 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
June, 2011

Abstract

The Hibernate Core Reference Guide for JBoss Enterprise Web Platform 5 and its patch releases.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. Give us Feedback
1. Introduction
2. Tutorial
2.1. Part 1 - The first Hibernate Application
2.1.1. Setup
2.1.2. The first class
2.1.3. The mapping file
2.1.4. Hibernate configuration
2.1.5. Building with Maven
2.1.6. Startup and helpers
2.1.7. Loading and storing objects
2.2. Part 2 - Mapping associations
2.2.1. Mapping the Person class
2.2.2. A unidirectional Set-based association
2.2.3. Working the association
2.2.4. Collection of values
2.2.5. Bi-directional associations
2.2.6. Working bi-directional links
2.3. Part 3 - The EventManager web application
2.3.1. Writing the basic servlet
2.3.2. Processing and rendering
2.3.3. Deploying and testing
2.4. Summary
3. Architecture
3.1. Overview
3.2. Instance states
3.3. JMX Integration
3.4. JCA Support
3.5. Contextual sessions
4. Configuration
4.1. Programmatic configuration
4.2. Obtaining a SessionFactory
4.3. JDBC connections
4.4. Optional configuration properties
4.4.1. SQL Dialects
4.4.2. Outer Join Fetching
4.4.3. Binary Streams
4.4.4. Second-level and query cache
4.4.5. Query Language Substitution
4.4.6. Hibernate statistics
4.5. Logging
4.6. Implementing a NamingStrategy
4.7. XML configuration file
4.8. J2EE Application Server integration
4.8.1. Transaction strategy configuration
4.8.2. JNDI-bound SessionFactory
4.8.3. Current Session context management with JTA
4.8.4. JMX deployment
5. Persistent Classes
5.1. A simple POJO example
5.1.1. Implement a no-argument constructor
5.1.2. Provide an identifier property (optional)
5.1.3. Prefer non-final classes (optional)
5.1.4. Declare accessors and mutators for persistent fields (optional)
5.2. Implementing inheritance
5.3. Implementing equals() and hashCode()
5.4. Dynamic models
5.5. Tuplizers
5.6. EntityNameResolvers
6. Basic O/R Mapping
6.1. Mapping declaration
6.1.1. Doctype
6.1.2. Hibernate-mapping
6.1.3. Class
6.1.4. id
6.1.5. Enhanced identifier generators
6.1.6. Identifier generator optimization
6.1.7. composite-id
6.1.8. Discriminator
6.1.9. Version (optional)
6.1.10. Timestamp (optional)
6.1.11. Property
6.1.12. Many-to-one
6.1.13. One-to-one
6.1.14. Natural-id
6.1.15. Component and dynamic-component
6.1.16. Properties
6.1.17. Subclass
6.1.18. Joined-subclass
6.1.19. Union-subclass
6.1.20. Join
6.1.21. Key
6.1.22. Column and formula elements
6.1.23. Import
6.1.24. Any
6.2. Hibernate types
6.2.1. Entities and values
6.2.2. Basic value types
6.2.3. Custom value types
6.3. Mapping a class more than once
6.4. SQL quoted identifiers
6.5. Metadata alternatives
6.5.1. Using XDoclet markup
6.5.2. Using JDK 5.0 Annotations
6.6. Generated properties
6.7. Auxiliary database objects
7. Collection mapping
7.1. Persistent collections
7.2. Collection mappings
7.2.1. Collection foreign keys
7.2.2. Collection elements
7.2.3. Indexed collections
7.2.4. Collections of values and many-to-many associations
7.2.5. One-to-many associations
7.3. Advanced collection mappings
7.3.1. Sorted collections
7.3.2. Bidirectional associations
7.3.3. Bidirectional associations with indexed collections
7.3.4. Ternary associations
7.3.5. Using an <idbag>
7.4. Collection examples
8. Association Mappings
8.1. Introduction
8.2. Unidirectional associations
8.2.1. Many-to-one
8.2.2. One-to-one
8.2.3. One-to-many
8.3. Unidirectional associations with join tables
8.3.1. One-to-many
8.3.2. Many-to-one
8.3.3. One-to-one
8.3.4. Many-to-many
8.4. Bidirectional associations
8.4.1. one-to-many / many-to-one
8.4.2. One-to-one
8.5. Bidirectional associations with join tables
8.5.1. one-to-many / many-to-one
8.5.2. one to one
8.5.3. Many-to-many
8.6. More complex association mappings
9. Component Mapping
9.1. Dependent objects
9.2. Collections of dependent objects
9.3. Components as Map indices
9.4. Components as composite identifiers
9.5. Dynamic components
10. Inheritance mapping
10.1. The three strategies
10.1.1. Table per class hierarchy
10.1.2. Table per subclass
10.1.3. Table per subclass: using a discriminator
10.1.4. Mixing table per class hierarchy with table per subclass
10.1.5. Table per concrete class
10.1.6. Table per concrete class using implicit polymorphism
10.1.7. Mixing implicit polymorphism with other inheritance mappings
10.2. Limitations
11. Working with objects
11.1. Hibernate object states
11.2. Making objects persistent
11.3. Loading an object
11.4. Querying
11.4.1. Executing queries
11.4.2. Filtering collections
11.4.3. Criteria queries
11.4.4. Queries in native SQL
11.5. Modifying persistent objects
11.6. Modifying detached objects
11.7. Automatic state detection
11.8. Deleting persistent objects
11.9. Replicating object between two different datastores
11.10. Flushing the Session
11.11. Transitive persistence
11.12. Using metadata
12. Transactions and Concurrency
12.1. Session and transaction scopes
12.1.1. Unit of work
12.1.2. Long conversations
12.1.3. Considering object identity
12.1.4. Common issues
12.2. Database transaction demarcation
12.2.1. Non-managed environment
12.2.2. Using JTA
12.2.3. Exception handling
12.2.4. Transaction timeout
12.3. Optimistic concurrency control
12.3.1. Application version checking
12.3.2. Extended session and automatic versioning
12.3.3. Detached objects and automatic versioning
12.3.4. Customizing automatic versioning
12.4. Pessimistic locking
12.5. Connection release modes
13. Interceptors and events
13.1. Interceptors
13.2. Event system
13.3. Hibernate declarative security
14. Batch processing
14.1. Batch inserts
14.2. Batch updates
14.3. The StatelessSession interface
14.4. DML-style operations
15. HQL: The Hibernate Query Language
15.1. Case Sensitivity
15.2. The from clause
15.3. Associations and joins
15.4. Forms of join syntax
15.5. Referring to identifier property
15.6. The select clause
15.7. Aggregate functions
15.8. Polymorphic queries
15.9. The where clause
15.10. Expressions
15.11. The order by clause
15.12. The group by clause
15.13. Subqueries
15.14. HQL examples
15.15. Bulk update and delete
15.16. Tips & Tricks
15.17. Components
15.18. Row value constructor syntax
16. Criteria Queries
16.1. Creating a Criteria instance
16.2. Narrowing the result set
16.3. Ordering the results
16.4. Associations
16.5. Dynamic association fetching
16.6. Example queries
16.7. Projections, aggregation and grouping
16.8. Detached queries and subqueries
16.9. Queries by natural identifier
17. Native SQL
17.1. Using a SQLQuery
17.1.1. Scalar queries
17.1.2. Entity queries
17.1.3. Handling associations and collections
17.1.4. Returning multiple entities
17.1.5. Returning non-managed entities
17.1.6. Handling inheritance
17.1.7. Parameters
17.2. Named SQL queries
17.2.1. Using return-property to explicitly specify column/alias names
17.2.2. Using stored procedures for querying
17.3. Custom SQL for create, update and delete
17.4. Custom SQL for loading
18. Filtering data
18.1. Hibernate filters
19. XML Mapping
19.1. Working with XML data
19.1.1. Specifying XML and class mapping together
19.1.2. Specifying only an XML mapping
19.2. XML mapping metadata
19.3. Manipulating XML data
20. Improving performance
20.1. Fetching strategies
20.1.1. Working with lazy associations
20.1.2. Tuning fetch strategies
20.1.3. Single-ended association proxies
20.1.4. Initializing collections and proxies
20.1.5. Using batch fetching
20.1.6. Using subselect fetching
20.1.7. Using lazy property fetching
20.2. The Second Level Cache
20.2.1. Cache mappings
20.2.2. Strategy: read only
20.2.3. Strategy: read/write
20.2.4. Strategy: nonstrict read/write
20.2.5. Strategy: transactional
20.2.6. Cache-provider/concurrency-strategy compatibility
20.3. Managing the caches
20.4. The Query Cache
20.5. Understanding Collection performance
20.5.1. Taxonomy
20.5.2. Lists, maps, idbags and sets are the most efficient collections to update
20.5.3. Bags and lists are the most efficient inverse collections
20.5.4. One shot delete
20.6. Monitoring performance
20.6.1. Monitoring a SessionFactory
20.6.2. Metrics
21. Toolset Guide
21.1. Automatic schema generation
21.1.1. Customizing the schema
21.1.2. Running the tool
21.1.3. Properties
21.1.4. Using Ant
21.1.5. Incremental schema updates
21.1.6. Using Ant for incremental schema updates
21.1.7. Schema validation
21.1.8. Using Ant for schema validation
22. Example: Parent/Child
22.1. A note about collections
22.2. Bidirectional one-to-many
22.3. Cascading life cycle
22.4. Cascades and unsaved-value
22.5. Conclusion
23. Example: Weblog Application
23.1. Persistent Classes
23.2. Hibernate Mappings
23.3. Hibernate Code
24. Example: Various Mappings
24.1. Employer/Employee
24.2. Author/Work
24.3. Customer/Order/Product
24.4. Miscellaneous example mappings
24.4.1. "Typed" one-to-one association
24.4.2. Composite key example
24.4.3. Many-to-many with shared composite key attribute
24.4.4. Content based discrimination
24.4.5. Associations on alternate keys
25. Best Practices
26. Database Portability Considerations
26.1. Portability Basics
26.2. Dialect
26.3. Dialect resolution
26.4. Identifier generation
26.5. Database functions
A. Revision History