Hibernate Reference Documentation3.1

Table of Contents Preface 1. Introduction to Hibernate 1.1. Preface 1.2. Part 1 - The first Hibernate Application 1.2.1. The first class 1.2.2. The mapping file 1.2.3. Hibernate configuration 1.2.4. Building with Ant 1.2.5. Startup and helpers 1.2.6. Loading and storing objects 1.3. Part 2 - Mapping associations 1.3.1. Mapping the Person class 1.3.2. A unidirectional Set-based association 1.3.3. Working the association 1.3.4. Collection of values 1.3.5. Bi-directional associations 1.3.6. Working bi-directional links 1.4. Part 3 - The EventManager web application 1.4.1. Writing the basic servlet 1.4.2. Processing and rendering 1.4.3. Deploying and testing 1.5. Summary 2. Architecture 2.1. Overview 2.2. Instance states 2.3. JMX Integration 2.4. JCA Support 2.5. Contextual Sessions 3. Configuration 3.1. Programmatic configuration 3.2. Obtaining a SessionFactory 3.3. JDBC connections 3.4. Optional configuration properties 3.4.1. SQL Dialects 3.4.2. Outer Join Fetching 3.4.3. Binary Streams 3.4.4. Second-level and query cache 3.4.5. Query Language Substitution 3.4.6. Hibernate statistics 3.5. Logging 3.6. Implementing a NamingStrategy 3.7. XML configuration file 3.8. J2EE Application Server integration 3.8.1. Transaction strategy configuration 3.8.2. JNDI-bound SessionFactory 3.8.3. Current Session context management with JTA 3.8.4. JMX deployment 4. Persistent Classes 4.1. A simple POJO example 4.1.1. Implement a no-argument constructor 4.1.2. Provide an identifier property (optional) 4.1.3. Prefer non-final classes (optional) 4.1.4. Declare accessors and mutators for persistent fields (optional) 4.2. Implementing inheritance 4.3. Implementing equals() and hashCode() 4.4. Dynamic models 4.5. Tuplizers 5. Basic O/R Mapping 5.1. Mapping declaration 5.1.1. Doctype 5.1.2. hibernate-mapping 5.1.3. class 5.1.4. id 5.1.4.1. Generator 5.1.4.2. Hi/lo algorithm 5.1.4.3. UUID algorithm 5.1.4.4. Identity columns and sequences 5.1.4.5. Assigned identifiers 5.1.4.6. Primary keys assigned by triggers 5.1.5. composite-id 5.1.6. discriminator 5.1.7. version (optional) 5.1.8. timestamp (optional) 5.1.9. property 5.1.10. many-to-one 5.1.11. one-to-one 5.1.12. natural-id 5.1.13. component, dynamic-component 5.1.14. properties 5.1.15. subclass 5.1.16. joined-subclass 5.1.17. union-subclass 5.1.18. join 5.1.19. key 5.1.20. column and formula elements 5.1.21. import 5.1.22. any 5.2. Hibernate Types 5.2.1. Entities and values 5.2.2. Basic value types 5.2.3. Custom value types 5.3. Mapping a class more than once 5.4. SQL quoted identifiers 5.5. Metadata alternatives 5.5.1. Using XDoclet markup 5.5.2. Using JDK 5.0 Annotations 5.6. Generated Properties 5.7. Auxiliary Database Objects 6. Collection Mapping 6.1. Persistent collections 6.2. Collection mappings 6.2.1. Collection foreign keys 6.2.2. Collection elements 6.2.3. Indexed collections 6.2.4. Collections of values and many-to-many associations 6.2.5. One-to-many associations 6.3. Advanced collection mappings 6.3.1. Sorted collections 6.3.2. Bidirectional associations 6.3.3. Bidirectional associations with indexed collections 6.3.4. Ternary associations 6.3.5. Using an <idbag> 6.4. Collection examples 7. Association Mappings 7.1. Introduction 7.2. Unidirectional associations 7.2.1. many to one 7.2.2. one to one 7.2.3. one to many 7.3. Unidirectional associations with join tables 7.3.1. one to many 7.3.2. many to one 7.3.3. one to one 7.3.4. many to many 7.4. Bidirectional associations 7.4.1. one to many / many to one 7.4.2. one to one 7.5. Bidirectional associations with join tables 7.5.1. one to many / many to one 7.5.2. one to one 7.5.3. many to many 7.6. More complex association mappings 8. Component Mapping 8.1. Dependent objects 8.2. Collections of dependent objects 8.3. Components as Map indices 8.4. Components as composite identifiers 8.5. Dynamic components 9. Inheritance Mapping 9.1. The Three Strategies 9.1.1. Table per class hierarchy 9.1.2. Table per subclass 9.1.3. Table per subclass, using a discriminator 9.1.4. Mixing table per class hierarchy with table per subclass 9.1.5. Table per concrete class 9.1.6. Table per concrete class, using implicit polymorphism 9.1.7. Mixing implicit polymorphism with other inheritance mappings 9.2. Limitations 10. Working with objects 10.1. Hibernate object states 10.2. Making objects persistent 10.3. Loading an object 10.4. Querying 10.4.1. Executing queries 10.4.1.1. Iterating results 10.4.1.2. Queries that return tuples 10.4.1.3. Scalar results 10.4.1.4. Bind parameters 10.4.1.5. Pagination 10.4.1.6. Scrollable iteration 10.4.1.7. Externalizing named queries 10.4.2. Filtering collections 10.4.3. Criteria queries 10.4.4. Queries in native SQL 10.5. Modifying persistent objects 10.6. Modifying detached objects 10.7. Automatic state detection 10.8. Deleting persistent objects 10.9. Replicating object between two different datastores 10.10. Flushing the Session 10.11. Transitive persistence 10.12. Using metadata 11. Transactions And Concurrency 11.1. Session and transaction scopes 11.1.1. Unit of work 11.1.2. Long conversations 11.1.3. Considering object identity 11.1.4. Common issues 11.2. Database transaction demarcation 11.2.1. Non-managed environment 11.2.2. Using JTA 11.2.3. Exception handling 11.2.4. Transaction timeout 11.3. Optimistic concurrency control 11.3.1. Application version checking 11.3.2. Extended session and automatic versioning 11.3.3. Detached objects and automatic versioning 11.3.4. Customizing automatic versioning 11.4. Pessimistic Locking 11.5. Connection Release Modes 12. Interceptors and events 12.1. Interceptors 12.2. Event system 12.3. Hibernate declarative security 13. Batch processing 13.1. Batch inserts 13.2. Batch updates 13.3. The StatelessSession interface 13.4. DML-style operations 14. HQL: The Hibernate Query Language 14.1. Case Sensitivity 14.2. The from clause 14.3. Associations and joins 14.4. Forms of join syntax 14.5. The select clause 14.6. Aggregate functions 14.7. Polymorphic queries 14.8. The where clause 14.9. Expressions 14.10. The order by clause 14.11. The group by clause 14.12. Subqueries 14.13. HQL examples 14.14. Bulk update and delete 14.15. Tips & Tricks 15. Criteria Queries 15.1. Creating a Criteria instance 15.2. Narrowing the result set 15.3. Ordering the results 15.4. Associations 15.5. Dynamic association fetching 15.6. Example queries 15.7. Projections, aggregation and grouping 15.8. Detached queries and subqueries 15.9. Queries by natural identifier 16. Native SQL 16.1. Using a SQLQuery 16.2. Alias and property references 16.3. Named SQL queries 16.3.1. Using return-property to explicitly specify column/alias names 16.3.2. Using stored procedures for querying 16.3.2.1. Rules/limitations for using stored procedures 16.4. Custom SQL for create, update and delete 16.5. Custom SQL for loading 17. Filtering data 17.1. Hibernate filters 18. XML Mapping 18.1. Working with XML data 18.1.1. Specifying XML and class mapping together 18.1.2. Specifying only an XML mapping 18.2. XML mapping metadata 18.3. Manipulating XML data 19. Improving performance 19.1. Fetching strategies 19.1.1. Working with lazy associations 19.1.2. Tuning fetch strategies 19.1.3. Single-ended association proxies 19.1.4. Initializing collections and proxies 19.1.5. Using batch fetching 19.1.6. Using subselect fetching 19.1.7. Using lazy property fetching 19.2. The Second Level Cache 19.2.1. Cache mappings 19.2.2. Strategy: read only 19.2.3. Strategy: read/write 19.2.4. Strategy: nonstrict read/write 19.2.5. Strategy: transactional 19.3. Managing the caches 19.4. The Query Cache 19.5. Understanding Collection performance 19.5.1. Taxonomy 19.5.2. Lists, maps, idbags and sets are the most efficient collections to update 19.5.3. Bags and lists are the most efficient inverse collections 19.5.4. One shot delete 19.6. Monitoring performance 19.6.1. Monitoring a SessionFactory 19.6.2. Metrics 20. Toolset Guide 20.1. Automatic schema generation 20.1.1. Customizing the schema 20.1.2. Running the tool 20.1.3. Properties 20.1.4. Using Ant 20.1.5. Incremental schema updates 20.1.6. Using Ant for incremental schema updates 20.1.7. Schema validation 20.1.8. Using Ant for schema validation 21. Example: Parent/Child 21.1. A note about collections 21.2. Bidirectional one-to-many 21.3. Cascading lifecycle 21.4. Cascades and unsaved-value 21.5. Conclusion 22. Example: Weblog Application 22.1. Persistent Classes 22.2. Hibernate Mappings 22.3. Hibernate Code 23. Example: Various Mappings 23.1. Employer/Employee 23.2. Author/Work 23.3. Customer/Order/Product 23.4. Miscellaneous example mappings 23.4.1. "Typed" one-to-one association 23.4.2. Composite key example 23.4.3. Many-to-many with shared composite key attribute 23.4.4. Content based discrimination 23.4.5. Associations on alternate keys 24. Best Practices