Hibernate User Guide

Hibernate - Relational Persistence for Idiomatic Java

The Hibernate Team

The JBoss Visual Design Team

5.1.0.Final

2016-02-10

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. Bytecode Enhancement

3.1. Capabilities

3.1.1. Lazy attribute loading
3.1.2. In-line dirty tracking
3.1.3. Bi-directional association management
3.1.4. Internal performance optimizations

3.2. Performing enhancement

3.2.1. Run-time enhancement
3.2.2. Build-time enhancement

4. Bootstrap

4.1. Native Bootstrapping

4.1.1. Building the ServiceRegistry
4.1.2. Building the Metadata
4.1.3. Building the SessionFactory

4.2. JPA Bootstrapping

4.2.1. JPA-compliant bootstrapping
4.2.2. Proprietary 2-phase bootstrapping

5. Persistence Contexts

5.1. Making entities persistent

5.2. Deleting entities

5.3. Obtain an entity reference without initializing its data

5.4. Obtain an entity with its data initialized

5.5. Obtain an entity by natural-id

5.6. Refresh entity state

5.7. Modifying managed/persistent state

5.8. Working with detached data

5.8.1. Reattaching detached data
5.8.2. Merging detached data

5.9. Checking persistent state

5.10. Accessing Hibernate APIs from JPA

6. Database access

6.1. ConnectionProvider

6.1.1. Using DataSources
6.1.2. Using c3p0
6.1.3. Using Proxool
6.1.4. Using Hikari
6.1.5. Using Hibernate's built-in (and unsupported) pooling
6.1.6. User-provided Connections
6.1.7. ConnectionProvider support for transaction isolation setting

6.2. Database Dialect

7. Transactions and concurrency control

7.1. Physical Transactions

7.1.1. JTA configuration

7.2. Hibernate Transaction API

7.3. Transactional patterns (and anti-patterns)

7.3.1. Session-per-operation anti-pattern
7.3.2. Session-per-request pattern
7.3.3. Conversations
7.3.4. Session-per-application

7.4. Common issues

8. JNDI

9. Locking

9.1. Optimistic

9.1.1. Dedicated version number
9.1.2. Timestamp

9.2. Pessimistic

9.2.1. The LockMode class

10. Fetching

10.1. The basics

10.2. Applying fetch strategies

10.2.1. No fetching
10.2.2. Dynamic fetching via queries
10.2.3. Dynamic fetching via profiles

11. Batching

11.1. JDBC batching

12. Caching

12.1. Configuring second-level caching

12.1.1. RegionFactory
12.1.2. Caching behavior

12.2. Managing the Cached Data

13. Interceptors and events

13.1. Interceptors

13.2. Native Event system

13.2.1. Hibernate declarative security

13.3. JPA Callbacks

14. HQL and JPQL

14.1. Case Sensitivity

14.2. Statement types

14.2.1. Select statements
14.2.2. Update statements
14.2.3. Delete statements
14.2.4. Insert statements

14.3. The FROM clause

14.3.1. Identification variables
14.3.2. Root entity references
14.3.3. Explicit joins
14.3.4. Implicit joins (path expressions)
14.3.5. Collection member references
14.3.6. Polymorphism

14.4. Expressions

14.4.1. Identification variable
14.4.2. Path expressions
14.4.3. Literals
14.4.4. Parameters
14.4.5. Arithmetic
14.4.6. Concatenation (operation)
14.4.7. Aggregate functions
14.4.8. Scalar functions
14.4.9. Collection-related expressions
14.4.10. Entity type
14.4.11. CASE expressions

14.5. The SELECT clause

14.6. Predicates

14.6.1. Relational comparisons
14.6.2. Nullness predicate
14.6.3. Like predicate
14.6.4. Between predicate
14.6.5. In predicate
14.6.6. Exists predicate
14.6.7. Empty collection predicate
14.6.8. Member-of collection predicate
14.6.9. NOT predicate operator
14.6.10. AND predicate operator
14.6.11. OR predicate operator

14.7. The WHERE clause

14.8. Grouping

14.9. Ordering

14.10. Query API

14.10.1. Hibernate Query API
14.10.2. JPA Query API

15. Criteria

15.1. Typed criteria queries

15.1.1. Selecting an entity
15.1.2. Selecting an expression
15.1.3. Selecting multiple values
15.1.4. Selecting a wrapper

15.2. Tuple criteria queries

15.3. FROM clause

15.3.1. Roots
15.3.2. Joins
15.3.3. Fetches

15.4. Path expressions

15.5. Using parameters

16. Native SQL Queries

16.1. Using a SQLQuery

16.1.1. Scalar queries
16.1.2. Entity queries
16.1.3. Handling associations and collections
16.1.4. Returning multiple entities
16.1.5. Returning non-managed entities
16.1.6. Handling inheritance
16.1.7. Parameters

16.2. Named SQL queries

16.2.1. Using return-property to explicitly specify column/alias names
16.2.2. Using stored procedures for querying

16.3. Custom SQL for create, update and delete

16.4. Custom SQL for loading

17. Multi-tenancy

17.1. What is multi-tenancy?

17.2. Multi-tenant data approaches

17.2.1. Separate database
17.2.2. Separate schema
17.2.3. Partitioned (discriminator) data

17.3. Multi-tenancy in Hibernate

17.3.1. MultiTenantConnectionProvider
17.3.2. CurrentTenantIdentifierResolver
17.3.3. Caching
17.3.4. Odds and ends

17.4. Strategies for MultiTenantConnectionProvider implementors

18. OSGi

18.1. OSGi Specification and Environment

18.2. hibernate-osgi

18.3. features.xml

18.4. QuickStarts/Demos

18.5. Container-Managed JPA

18.5.1. Enterprise OSGi JPA Container
18.5.2. persistence.xml
18.5.3. DataSource
18.5.4. Bundle Package Imports
18.5.5. Obtaining an EntityManger

18.6. Unmanaged JPA

18.6.1. persistence.xml
18.6.2. Bundle Package Imports
18.6.3. Obtaining an EntityMangerFactory

18.7. Unmanaged Native

18.7.1. Bundle Package Imports
18.7.2. Obtaining an SessionFactory

18.8. Optional Modules

18.9. Extension Points

18.10. Caveats

19. Envers

19.1. Basics

19.2. Configuration

19.3. Additional mapping annotations

19.4. Choosing an audit strategy

19.5. Revision Log

19.5.1. Tracking entity names modified during revisions

19.6. Tracking entity changes at property level

19.7. Queries

19.7.1. Querying for entities of a class at a given revision
19.7.2. Querying for revisions, at which entities of a given class changed
19.7.3. Querying for revisions of entity that modified given property
19.7.4. Querying for entities modified in a given revision

19.8. Conditional auditing

19.9. Understanding the Envers Schema

19.10. Generating schema with Ant

19.11. Mapping exceptions

19.11.1. What isn't and will not be supported
19.11.2. What isn't and will be supported
19.11.3. @OneToMany+@JoinColumn

19.12. Advanced: Audit table partitioning

19.12.1. Benefits of audit table partitioning
19.12.2. Suitable columns for audit table partitioning
19.12.3. Audit table partitioning example

19.13. Envers links

20. Database Portability Considerations

20.1. Portability Basics
20.2. Dialect
20.3. Dialect resolution
20.4. Identifier generation
20.5. Database functions
20.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

6.1. Provided Dialects
13.1. Callback annotations
16.1. Alias injection names
19.1. Envers Configuration Properties
19.2. Salaries table
19.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. @LazyGroup example
3.2. Incorrect normal Java usage
3.3. Correct normal Java usage
3.4. Example persistence.xml
3.5. Apply the Gradle plugin
3.6. Apply the Maven plugin
4.1. Controlling BootstrapServiceRegistry building
4.2. Building a BootstrapServiceRegistryBuilder
4.3. Controlling StandardServiceRegistry building
4.4. Configuring a MetadataSources
4.5. Configuring a MetadataSources with method chaining
4.6. Building Metadata via MetadataBuilder
4.7. Building SessionFactory via SessionFactoryBuilder
4.8. Native Bootstrapping - Putting it all together
4.9. Injecting a EntityManagerFactory
4.10. Application bootstrapped EntityManagerFactory
5.1. Example of making an entity persistent
5.2. Example of deleting an entity
5.3. Example of obtaining an entity reference without initializing its data
5.4. Example of obtaining an entity reference with its data initialized
5.5. Example of simple natural-id access
5.6. Example of natural-id access
5.7. Example of refreshing entity state
5.8. Example of modifying managed state
5.9. Example of reattaching a detached entity
5.10. Visualizing merge
5.11. Example of merging a detached entity
5.12. Examples of verifying managed state
5.13. Examples of verifying laziness
5.14. Alternative JPA means to verify laziness
5.15. Usage of EntityManager.unwrap
7.1. Using Transaction API in JDBC
7.2. Using Transaction API in JTA (CMT)
7.3. Using Transaction API in JTA (BMT)
9.1. The @Version annotation
9.2. Declaring a version property in hbm.xml
9.3. Using timestamps for optimistic locking
9.4. The timestamp element in hbm.xml
10.1. Sample domain model
10.2. No fetching example
10.3. No fetching (scalar) example
10.4. Dynamic query fetching example
10.5. Fetch profile example
13.1. Custom LoadListener example
13.2. JACC listener registration example
13.3. Example of specifying JPA callbacks
14.1. Example UPDATE query statements
14.2. Example INSERT query statements
14.3. Simple query example
14.4. Simple query using entity name for root entity reference
14.5. Simple query using multiple root entity references
14.6. Explicit inner join examples
14.7. Explicit left (outer) join examples
14.8. Fetch join example
14.9. with-clause join example
14.10. Simple implicit join example
14.11. Reused implicit join
14.12. Collection references example
14.13. Qualified collection references example
14.14. String literal examples
14.15. Numeric literal examples
14.16. Named parameter examples
14.17. Positional (JPQL) parameter examples
14.18. Numeric arithmetic examples
14.19. Concatenation operation example
14.20. Aggregate function examples
14.21. Collection-related expressions examples
14.22. Index operator examples
14.23. Entity type expression examples
14.24. Simple case expression example
14.25. Searched case expression example
14.26. NULLIF example
14.27. Dynamic instantiation example - constructor
14.28. Dynamic instantiation example - list
14.29. Dynamic instantiation example - map
14.30. Relational comparison examples
14.31. ALL subquery comparison qualifier example
14.32. Nullness checking examples
14.33. Like predicate examples
14.34. Between predicate examples
14.35. In predicate examples
14.36. Empty collection expression examples
14.37. Member-of collection expression examples
14.38. Group-by illustration
14.39. Having illustration
14.40. Order-by examples
14.41. Obtaining a Query reference - Hibernate
14.42. Basic Query usage - Hibernate
14.43. Parameter binding - Hibernate
14.44. Parameter binding (inferred type) - Hibernate
14.45. Parameter binding (short forms) - Hibernate
14.46. list() and uniqueResult()
14.47. Obtaining a Query reference - JPA
14.48. Basic Query usage - JPA
14.49. Parameter binding - JPA
15.1. Selecting the root entity
15.2. Selecting an attribute
15.3. Selecting an array
15.4. Selecting an array (2)
15.5. Selecting an wrapper
15.6. Selecting a tuple
15.7. Adding a root
15.8. Adding multiple roots
15.9. Example with Embedded and ManyToOne
15.10. Example with Collections
15.11. Example with Embedded and ManyToOne
15.12. Example with Collections
15.13. Using parameters
16.1. Named sql query using the <sql-query> maping element
16.2. Execution of a named query
16.3. Named sql query with association
16.4. Named query returning a scalar
16.5. <resultset> mapping used to externalize mapping information
16.6. Programmatically specifying the result mapping information
16.7. Named SQL query using @NamedNativeQuery together with @SqlResultSetMapping
16.8. Implicit result set mapping
16.9. Using dot notation in @FieldResult for specifying associations
16.10. Scalar values via @ColumnResult
16.11. Custom CRUD via annotations
16.12. Custom CRUD XML
16.13. Overriding SQL statements for collections using annotations
16.14. Overriding SQL statements for secondary tables
16.15. Stored procedures and their return value
17.1. Specifying tenant identifier from SessionFactory
17.2. Implementing MultiTenantConnectionProvider using different connection pools
17.3. Implementing MultiTenantConnectionProvider using single connection pool
18.1. datasource-h2.xml
18.2. META-INF/persistence.xml
18.3. OSGI-INF/blueprint/blueprint.xml
18.4. Discover/Use EntityManagerFactory
18.5. Discover/Use EntityManagerFactory
18.6. Example extension point registrations in blueprint.xml
19.1. Example of storing username with revision
19.2. Custom implementation of tracking entity classes modified during revisions
A.1. Configuration usage