Hibernate.orgCommunity Documentation

Hibernate User Guide

Hibernate - Relational Persistence for Idiomatic Java

5.0.10.Final

2016-07-31


Table of Contents

Preface
1. Architecture
1.1. Overview
1.2. Contextual sessions
2. Domain Model
2.1. POJO Domain Models
2.1.1. Implement a no-argument constructor
2.1.2. Provide identifier attribute(s)
2.1.3. Prefer non-final classes
2.1.4. Declare getters and setters for persistent attributes
2.1.5. Implementing equals() and hashCode()
2.2. Dynamic models
3. Bootstrap
3.1. Native Bootstrapping
3.1.1. Building the ServiceRegistry
3.1.2. Building the Metadata
3.1.3. Building the SessionFactory
3.2. JPA Bootstrapping
3.2.1. JPA-compliant bootstrapping
3.2.2. Proprietary 2-phase bootstrapping
4. Persistence Contexts
4.1. Making entities persistent
4.2. Deleting entities
4.3. Obtain an entity reference without initializing its data
4.4. Obtain an entity with its data initialized
4.5. Obtain an entity by natural-id
4.6. Refresh entity state
4.7. Modifying managed/persistent state
4.8. Working with detached data
4.8.1. Reattaching detached data
4.8.2. Merging detached data
4.9. Checking persistent state
4.10. Accessing Hibernate APIs from JPA
5. Database access
5.1. ConnectionProvider
5.1.1. Using DataSources
5.1.2. Using c3p0
5.1.3. Using Proxool
5.1.4. Using Hikari
5.1.5. Using Hibernate's built-in (and unsupported) pooling
5.1.6. User-provided Connections
5.1.7. ConnectionProvider support for transaction isolation setting
5.2. Database Dialect
6. Transactions and concurrency control
6.1. Physical Transactions
6.1.1. JTA configuration
6.2. Hibernate Transaction API
6.3. Transactional patterns (and anti-patterns)
6.3.1. Session-per-operation anti-pattern
6.3.2. Session-per-request pattern
6.3.3. Conversations
6.3.4. Session-per-application
6.4. Common issues
7. JNDI
8. Locking
8.1. Optimistic
8.1.1. Dedicated version number
8.1.2. Timestamp
8.2. Pessimistic
8.2.1. The LockMode class
9. Fetching
9.1. The basics
9.2. Applying fetch strategies
9.2.1. No fetching
9.2.2. Dynamic fetching via queries
9.2.3. Dynamic fetching via profiles
10. Batching
10.1. JDBC batching
11. Caching
11.1. Configuring second-level caching
11.1.1. RegionFactory
11.1.2. Caching behavior
11.2. Managing the Cached Data
12. Interceptors and events
12.1. Interceptors
12.2. Native Event system
12.2.1. Hibernate declarative security
12.3. JPA Callbacks
13. HQL and JPQL
13.1. Case Sensitivity
13.2. Statement types
13.2.1. Select statements
13.2.2. Update statements
13.2.3. Delete statements
13.2.4. Insert statements
13.3. The FROM clause
13.3.1. Identification variables
13.3.2. Root entity references
13.3.3. Explicit joins
13.3.4. Implicit joins (path expressions)
13.3.5. Collection member references
13.3.6. Polymorphism
13.4. Expressions
13.4.1. Identification variable
13.4.2. Path expressions
13.4.3. Literals
13.4.4. Parameters
13.4.5. Arithmetic
13.4.6. Concatenation (operation)
13.4.7. Aggregate functions
13.4.8. Scalar functions
13.4.9. Collection-related expressions
13.4.10. Entity type
13.4.11. CASE expressions
13.5. The SELECT clause
13.6. Predicates
13.6.1. Relational comparisons
13.6.2. Nullness predicate
13.6.3. Like predicate
13.6.4. Between predicate
13.6.5. In predicate
13.6.6. Exists predicate
13.6.7. Empty collection predicate
13.6.8. Member-of collection predicate
13.6.9. NOT predicate operator
13.6.10. AND predicate operator
13.6.11. OR predicate operator
13.7. The WHERE clause
13.8. Grouping
13.9. Ordering
13.10. Query API
13.10.1. Hibernate Query API
13.10.2. JPA Query API
14. Criteria
14.1. Typed criteria queries
14.1.1. Selecting an entity
14.1.2. Selecting an expression
14.1.3. Selecting multiple values
14.1.4. Selecting a wrapper
14.2. Tuple criteria queries
14.3. FROM clause
14.3.1. Roots
14.3.2. Joins
14.3.3. Fetches
14.4. Path expressions
14.5. Using parameters
15. Native SQL Queries
15.1. Using a SQLQuery
15.1.1. Scalar queries
15.1.2. Entity queries
15.1.3. Handling associations and collections
15.1.4. Returning multiple entities
15.1.5. Returning non-managed entities
15.1.6. Handling inheritance
15.1.7. Parameters
15.2. Named SQL queries
15.2.1. Using return-property to explicitly specify column/alias names
15.2.2. Using stored procedures for querying
15.3. Custom SQL for create, update and delete
15.4. Custom SQL for loading
16. Multi-tenancy
16.1. What is multi-tenancy?
16.2. Multi-tenant data approaches
16.2.1. Separate database
16.2.2. Separate schema
16.2.3. Partitioned (discriminator) data
16.3. Multi-tenancy in Hibernate
16.3.1. MultiTenantConnectionProvider
16.3.2. CurrentTenantIdentifierResolver
16.3.3. Caching
16.3.4. Odds and ends
16.4. Strategies for MultiTenantConnectionProvider implementors
17. OSGi
17.1. OSGi Specification and Environment
17.2. hibernate-osgi
17.3. features.xml
17.4. QuickStarts/Demos
17.5. Container-Managed JPA
17.5.1. Enterprise OSGi JPA Container
17.5.2. persistence.xml
17.5.3. DataSource
17.5.4. Bundle Package Imports
17.5.5. Obtaining an EntityManger
17.6. Unmanaged JPA
17.6.1. persistence.xml
17.6.2. Bundle Package Imports
17.6.3. Obtaining an EntityMangerFactory
17.7. Unmanaged Native
17.7.1. Bundle Package Imports
17.7.2. Obtaining an SessionFactory
17.8. Optional Modules
17.9. Extension Points
17.10. Caveats
18. Envers
18.1. Basics
18.2. Configuration
18.3. Additional mapping annotations
18.4. Choosing an audit strategy
18.5. Revision Log
18.5.1. Tracking entity names modified during revisions
18.6. Tracking entity changes at property level
18.7. Queries
18.7.1. Querying for entities of a class at a given revision
18.7.2. Querying for revisions, at which entities of a given class changed
18.7.3. Querying for revisions of entity that modified given property
18.7.4. Querying for entities modified in a given revision
18.8. Conditional auditing
18.9. Understanding the Envers Schema
18.10. Generating schema with Ant
18.11. Mapping exceptions
18.11.1. What isn't and will not be supported
18.11.2. What isn't and will be supported
18.11.3. @OneToMany+@JoinColumn
18.12. Advanced: Audit table partitioning
18.12.1. Benefits of audit table partitioning
18.12.2. Suitable columns for audit table partitioning
18.12.3. Audit table partitioning example
18.13. Envers links
19. Database Portability Considerations
19.1. Portability Basics
19.2. Dialect
19.3. Dialect resolution
19.4. Identifier generation
19.5. Database functions
19.6. Type mappings
A. Legacy Bootstrapping
A.1. Migration
B. Legacy Hibernate Criteria Queries
B.1. Creating a Criteria instance
B.2. Narrowing the result set
B.3. Ordering the results
B.4. Associations
B.5. Dynamic association fetching
B.6. Components
B.7. Collections
B.8. Example queries
B.9. Projections, aggregation and grouping
B.10. Detached queries and subqueries
B.11. Queries by natural identifier
References

List of Tables

5.1. Provided Dialects
12.1. Callback annotations
15.1. Alias injection names
18.1. Envers Configuration Properties
18.2. Salaries table
18.3. Salaries - audit table

List of Examples

2.1. Scope of identity
2.2. Set usage with Session-scoped identity
2.3. Mixed Sessions
2.4. Sets with transient entities
2.5. Naive equals/hashCode implementation
2.6. Still trouble
2.7. Forcing identifier generation
2.8. Better equals/hashCode with natural-id
2.9. Working with Dynamic Domain Models
3.1. Controlling BootstrapServiceRegistry building
3.2. Building a BootstrapServiceRegistryBuilder
3.3. Controlling StandardServiceRegistry building
3.4. Configuring a MetadataSources
3.5. Configuring a MetadataSources with method chaining
3.6. Building Metadata via MetadataBuilder
3.7. Building SessionFactory via SessionFactoryBuilder
3.8. Native Bootstrapping - Putting it all together
3.9. Injecting a EntityManagerFactory
3.10. Application bootstrapped EntityManagerFactory
4.1. Example of making an entity persistent
4.2. Example of deleting an entity
4.3. Example of obtaining an entity reference without initializing its data
4.4. Example of obtaining an entity reference with its data initialized
4.5. Example of simple natural-id access
4.6. Example of natural-id access
4.7. Example of refreshing entity state
4.8. Example of modifying managed state
4.9. Example of reattaching a detached entity
4.10. Visualizing merge
4.11. Example of merging a detached entity
4.12. Examples of verifying managed state
4.13. Examples of verifying laziness
4.14. Alternative JPA means to verify laziness
4.15. Usage of EntityManager.unwrap
6.1. Using Transaction API in JDBC
6.2. Using Transaction API in JTA (CMT)
6.3. Using Transaction API in JTA (BMT)
8.1. The @Version annotation
8.2. Declaring a version property in hbm.xml
8.3. Using timestamps for optimistic locking
8.4. The timestamp element in hbm.xml
9.1. Sample domain model
9.2. No fetching example
9.3. No fetching (scalar) example
9.4. Dynamic query fetching example
9.5. Fetch profile example
12.1. Custom LoadListener example
12.2. JACC listener registration example
12.3. Example of specifying JPA callbacks
13.1. Example UPDATE query statements
13.2. Example INSERT query statements
13.3. Simple query example
13.4. Simple query using entity name for root entity reference
13.5. Simple query using multiple root entity references
13.6. Explicit inner join examples
13.7. Explicit left (outer) join examples
13.8. Fetch join example
13.9. with-clause join example
13.10. Simple implicit join example
13.11. Reused implicit join
13.12. Collection references example
13.13. Qualified collection references example
13.14. String literal examples
13.15. Numeric literal examples
13.16. Named parameter examples
13.17. Positional (JPQL) parameter examples
13.18. Numeric arithmetic examples
13.19. Concatenation operation example
13.20. Aggregate function examples
13.21. Collection-related expressions examples
13.22. Index operator examples
13.23. Entity type expression examples
13.24. Simple case expression example
13.25. Searched case expression example
13.26. NULLIF example
13.27. Dynamic instantiation example - constructor
13.28. Dynamic instantiation example - list
13.29. Dynamic instantiation example - map
13.30. Relational comparison examples
13.31. ALL subquery comparison qualifier example
13.32. Nullness checking examples
13.33. Like predicate examples
13.34. Between predicate examples
13.35. In predicate examples
13.36. Empty collection expression examples
13.37. Member-of collection expression examples
13.38. Group-by illustration
13.39. Having illustration
13.40. Order-by examples
13.41. Obtaining a Query reference - Hibernate
13.42. Basic Query usage - Hibernate
13.43. Parameter binding - Hibernate
13.44. Parameter binding (inferred type) - Hibernate
13.45. Parameter binding (short forms) - Hibernate
13.46. list() and uniqueResult()
13.47. Obtaining a Query reference - JPA
13.48. Basic Query usage - JPA
13.49. Parameter binding - JPA
14.1. Selecting the root entity
14.2. Selecting an attribute
14.3. Selecting an array
14.4. Selecting an array (2)
14.5. Selecting an wrapper
14.6. Selecting a tuple
14.7. Adding a root
14.8. Adding multiple roots
14.9. Example with Embedded and ManyToOne
14.10. Example with Collections
14.11. Example with Embedded and ManyToOne
14.12. Example with Collections
14.13. Using parameters
15.1. Named sql query using the <sql-query> maping element
15.2. Execution of a named query
15.3. Named sql query with association
15.4. Named query returning a scalar
15.5. <resultset> mapping used to externalize mapping information
15.6. Programmatically specifying the result mapping information
15.7. Named SQL query using @NamedNativeQuery together with @SqlResultSetMapping
15.8. Implicit result set mapping
15.9. Using dot notation in @FieldResult for specifying associations
15.10. Scalar values via @ColumnResult
15.11. Custom CRUD via annotations
15.12. Custom CRUD XML
15.13. Overriding SQL statements for collections using annotations
15.14. Overriding SQL statements for secondary tables
15.15. Stored procedures and their return value
16.1. Specifying tenant identifier from SessionFactory
16.2. Implementing MultiTenantConnectionProvider using different connection pools
16.3. Implementing MultiTenantConnectionProvider using single connection pool
17.1. datasource-h2.xml
17.2. META-INF/persistence.xml
17.3. OSGI-INF/blueprint/blueprint.xml
17.4. Discover/Use EntityManagerFactory
17.5. Discover/Use EntityManagerFactory
17.6. Example extension point registrations in blueprint.xml
18.1. Example of storing username with revision
18.2. Custom implementation of tracking entity classes modified during revisions
A.1. Configuration usage