Hibernate User Guide

Table of Contents

• Preface
• 1. Architecture
  • 1.1. Overview
• 2. Domain Model
  • 2.1. Mapping types
    • 2.1.1. Value types
    • 2.1.2. Entity types
  • 2.2. Naming strategies
    • 2.2.1. ImplicitNamingStrategy
    • 2.2.2. PhysicalNamingStrategy
  • 2.3. Basic Types
    • 2.3.1. Hibernate-provided BasicTypes
    • 2.3.2. The @Basic annotation
    • 2.3.3. The @Column annotation
    • 2.3.4. BasicTypeRegistry
    • 2.3.5. Explicit BasicTypes
    • 2.3.6. Custom BasicTypes
    • 2.3.7. Mapping enums
    • 2.3.8. @Enumerated
    • 2.3.9. AttributeConverter
    • 2.3.10. Custom type
    • 2.3.11. Mapping LOBs
    • 2.3.12. Mapping Nationalized Character Data
    • 2.3.13. Mapping UUID Values
    • 2.3.14. UUID as binary
    • 2.3.15. UUID as (var)char
    • 2.3.16. PostgeSQL-specific UUID
    • 2.3.17. UUID as identifier
    • 2.3.18. Mapping Date/Time Values
    • 2.3.19. JPA 2.1 AttributeConverters
    • 2.3.20. SQL quoted identifiers
    • 2.3.21. Generated properties
    • 2.3.22. Column transformers: read and write expressions
    • 2.3.23. Formula
    • 2.3.24. Any
  • 2.4. Embeddable types
    • 2.4.1. Component / Embedded
    • 2.4.2. Multiple embeddable types
    • 2.4.3. JPA’s AttributeOverride
    • 2.4.4. ImplicitNamingStrategy
    • 2.4.5. Collections of embeddable types
    • 2.4.6. Embeddable types as Map key
    • 2.4.7. Embeddable types as identifiers
  • 2.5. Entity types
    • 2.5.1. POJO Models
    • 2.5.2. Prefer non-final classes
    • 2.5.3. Implement a no-argument constructor
    • 2.5.4. Declare getters and setters for persistent attributes
    • 2.5.5. Provide identifier attribute(s)
    • 2.5.6. Mapping the entity
    • 2.5.7. Implementing equals() and hashCode()
    • 2.5.8. Mapping optimistic locking
    • 2.5.9. Access strategies
  • 2.6. Identifiers
    • 2.6.1. Simple identifiers
    • 2.6.2. Composite identifiers
    • 2.6.3. Composite identifiers - aggregated (EmbeddedId)
    • 2.6.4. Composite identifiers - non-aggregated (IdClass)
    • 2.6.5. Composite identifiers - associations
    • 2.6.6. Generated identifier values
    • 2.6.7. Interpreting AUTO
    • 2.6.8. Using sequences
    • 2.6.9. Using IDENTITY columns
    • 2.6.10. Using identifier table
    • 2.6.11. Using UUID generation
    • 2.6.12. Using @GenericGenerator
    • 2.6.13. Optimizers
    • 2.6.14. Derived Identifiers
  • 2.7. Associations
    • 2.7.1. @ManyToOne
    • 2.7.2. @OneToMany
    • 2.7.3. @OneToOne
    • 2.7.4. @ManyToMany
  • 2.8. Collections
    • 2.8.1. Collections as a value type
    • 2.8.2. Collections of value types
    • 2.8.3. Collections of entities
    • 2.8.4. Bags
    • 2.8.5. Ordered Lists
    • 2.8.6. Sets
    • 2.8.7. Sorted sets
    • 2.8.8. Maps
    • 2.8.9. Arrays
    • 2.8.10. Arrays as binary
    • 2.8.11. Collections as basic value type
  • 2.9. Natural Ids
    • 2.9.1. Natural Id Mapping
    • 2.9.2. Natural Id API
    • 2.9.3. Natural Id - Mutability and Caching
  • 2.10. Dynamic Model
    • 2.10.1. Dynamic mapping models
  • 2.11. Inheritance
    • 2.11.1. MappedSuperclass
    • 2.11.2. Single table
    • 2.11.3. Joined table
    • 2.11.4. Table per class
• 3. Bootstrap
  • 3.1. Native Bootstrapping
    • 3.1.1. Building the ServiceRegistry
    • 3.1.2. Event Listener registration
    • 3.1.3. Building the Metadata
    • 3.1.4. Building the SessionFactory
  • 3.2. JPA Bootstrapping
    • 3.2.1. JPA-compliant bootstrapping
    • 3.2.2. Proprietary JPA bootstrapping
• 4. Persistence Contexts
  • 4.1. Accessing Hibernate APIs from JPA
  • 4.2. Bytecode Enhancement
    • 4.2.1. Capabilities
    • 4.2.2. Performing enhancement
  • 4.3. Making entities persistent
  • 4.4. Deleting (removing) entities
  • 4.5. Obtain an entity reference without initializing its data
  • 4.6. Obtain an entity with its data initialized
  • 4.7. Obtain an entity by natural-id
  • 4.8. Modifying managed/persistent state
  • 4.9. Refresh entity state
  • 4.10. Working with detached data
    • 4.10.1. Reattaching detached data
    • 4.10.2. Merging detached data
  • 4.11. Checking persistent state
  • 4.12. Evicting entities
• 5. Flushing
  • 5.1. AUTO flush
    • 5.1.1. AUTO flush on commit
    • 5.1.2. AUTO flush on JPQL/HQL query
    • 5.1.3. AUTO flush on native SQL query
  • 5.2. COMMIT flush
  • 5.3. ALWAYS flush
  • 5.4. MANUAL flush
• 6. Database access
  • 6.1. ConnectionProvider
  • 6.2. Using DataSources
  • 6.3. Using c3p0
  • 6.4. Using Proxool
  • 6.5. Using existing Proxool pools
  • 6.6. Configuring Proxool via XML
  • 6.7. Configuring Proxool via Properties
  • 6.8. Using Hikari
  • 6.9. Using Hibernate’s built-in (and unsupported) pooling
  • 6.10. User-provided Connections
  • 6.11. ConnectionProvider support for transaction isolation setting
  • 6.12. Database Dialect
• 7. Transactions and concurrency control
  • 7.1. Physical Transactions
  • 7.2. JTA configuration
  • 7.3. Hibernate Transaction API
  • 7.4. Contextual sessions
  • 7.5. Transactional patterns (and anti-patterns)
  • 7.6. Session-per-operation anti-pattern
  • 7.7. Session-per-request pattern
  • 7.8. Conversations
  • 7.9. Session-per-application
• 8. JNDI
• 9. Locking
  • 9.1. Optimistic
  • 9.2. Dedicated version number
  • 9.3. Timestamp
  • 9.4. Pessimistic
  • 9.5. The LockMode class
  • 9.6. JPA locking query hints
  • 9.7. The buildLockRequest API
• 10. Fetching
  • 10.1. The basics
  • 10.2. Applying fetch strategies
  • 10.3. No fetching
  • 10.4. Dynamic fetching via queries
  • 10.5. Dynamic fetching via JPA entity graph
  • 10.6. Dynamic fetching via Hibernate profiles
• 11. Batching
  • 11.1. JDBC batching
  • 11.2. Session batching
    • 11.2.1. Batch inserts
    • 11.2.2. Session scroll
    • 11.2.3. StatelessSession
  • 11.3. Hibernate Query Language for DML
    • 11.3.1. HQL/JPQL for UPDATE and DELETE
    • 11.3.2. HQL syntax for INSERT
• 12. Caching
  • 12.1. Configuring second-level caching
    • 12.1.1. RegionFactory
    • 12.1.2. Caching configuration properties
  • 12.2. Configuring second-level cache mappings
  • 12.3. Entity cache
  • 12.4. Collection cache
  • 12.5. Query cache
    • 12.5.1. Query cache regions
  • 12.6. Managing the cached data
    • 12.6.1. Evicting cache entries
  • 12.7. Caching statistics
  • 12.8. Ehcache
    • 12.8.1. RegionFactory
  • 12.9. Infinispan
    • 12.9.1. RegionFactory
    • 12.9.2. Configuration properties
• 13. Interceptors and events
  • 13.1. Interceptors
  • 13.2. Native Event system
  • 13.3. Hibernate declarative security
  • 13.4. JPA Callbacks
• 14. HQL and JPQL
  • 14.1. Query API
  • 14.2. Examples domain model
  • 14.3. JPA Query API
  • 14.4. Hibernate Query API
  • 14.5. Case Sensitivity
  • 14.6. Statement types
  • 14.7. Select statements
  • 14.8. Update statements
  • 14.9. Delete statements
  • 14.10. Insert statements
  • 14.11. The FROM clause
  • 14.12. Identification variables
  • 14.13. Root entity references
  • 14.14. Explicit joins
  • 14.15. Implicit joins (path expressions)
  • 14.16. Collection member references
  • 14.17. Special case - qualified path expressions
  • 14.18. Polymorphism
  • 14.19. Expressions
  • 14.20. Identification variable
  • 14.21. Path expressions
  • 14.22. Literals
  • 14.23. Arithmetic
  • 14.24. Concatenation (operation)
  • 14.25. Aggregate functions
  • 14.26. Scalar functions
  • 14.27. JPQL standardized functions
  • 14.28. HQL functions
  • 14.29. Non-standardized functions
  • 14.30. Collection-related expressions
  • 14.31. Entity type
  • 14.32. CASE expressions
  • 14.33. Simple CASE expressions
  • 14.34. Searched CASE expressions
  • 14.35. NULLIF expressions
  • 14.36. COALESCE expressions
  • 14.37. The SELECT clause
  • 14.38. Predicates
  • 14.39. Relational comparisons
  • 14.40. Nullness predicate
  • 14.41. Like predicate
  • 14.42. Between predicate
  • 14.43. In predicate
  • 14.44. Exists predicate
  • 14.45. Empty collection predicate
  • 14.46. Member-of collection predicate
  • 14.47. NOT predicate operator
  • 14.48. AND predicate operator
  • 14.49. OR predicate operator
  • 14.50. The WHERE clause
  • 14.51. Group by
  • 14.52. Order by
• 15. Criteria
  • 15.1. Typed criteria queries
  • 15.2. Selecting an entity
  • 15.3. Selecting an expression
  • 15.4. Selecting multiple values
  • 15.5. Selecting a wrapper
  • 15.6. Tuple criteria queries
  • 15.7. FROM clause
  • 15.8. Roots
  • 15.9. Joins
  • 15.10. Fetches
  • 15.11. Path expressions
  • 15.12. Using parameters
  • 15.13. Using group by
• 16. Native SQL Queries
  • 16.1. Creating a native query using JPA
  • 16.2. Scalar queries
  • 16.3. Entity queries
  • 16.4. Handling associations and collections
  • 16.5. Returning multiple entities
  • 16.6. Alias and property references
  • 16.7. Returning DTOs (Data Transfer Objects)
  • 16.8. Handling inheritance
  • 16.9. Parameters
  • 16.10. Named SQL queries
    • 16.10.1. Named SQL queries selecting scalar values
    • 16.10.2. Named SQL queries selecting entities
  • 16.11. Using stored procedures for querying
  • 16.12. Rules/limitations for using stored procedures
  • 16.13. Custom SQL for create, update and delete
  • 16.14. Custom SQL for loading
• 17. Multi-tenancy
  • 17.1. What is multi-tenancy?
  • 17.2. Multi-tenant data approaches
  • 17.3. Separate database
  • 17.4. Separate schema
  • 17.5. Partitioned (discriminator) data
  • 17.6. Multi-tenancy in Hibernate
  • 17.7. MultiTenantConnectionProvider
  • 17.8. CurrentTenantIdentifierResolver
  • 17.9. Caching
  • 17.10. Odds and ends
  • 17.11. 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.6. Enterprise OSGi JPA Container
  • 18.7. persistence.xml
  • 18.8. DataSource
  • 18.9. Bundle Package Imports
  • 18.10. Obtaining an EntityManger
  • 18.11. Unmanaged JPA
  • 18.12. persistence.xml
  • 18.13. Bundle Package Imports
  • 18.14. Obtaining an EntityMangerFactory
  • 18.15. Unmanaged Native
  • 18.16. Bundle Package Imports
  • 18.17. Obtaining an SessionFactory
  • 18.18. Optional Modules
  • 18.19. Extension Points
  • 18.20. 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.6. Tracking entity names modified during revisions
  • 19.7. Tracking entity changes at property level
  • 19.8. Queries
  • 19.9. Querying for entities of a class at a given revision
  • 19.10. Querying for revisions, at which entities of a given class changed
  • 19.11. Querying for revisions of entity that modified given property
  • 19.12. Querying for entities modified in a given revision
  • 19.13. Conditional auditing
  • 19.14. Understanding the Envers Schema
  • 19.15. Generating schema with Ant
  • 19.16. Mapping exceptions
  • 19.17. What isn’t and will not be supported
  • 19.18. What isn’t and will be supported
  • 19.19. @OneToMany with @JoinColumn
  • 19.20. Advanced: Audit table partitioning
  • 19.21. Benefits of audit table partitioning
  • 19.22. Suitable columns for audit table partitioning
  • 19.23. Audit table partitioning example
  • 19.24. Determining a suitable partitioning column
  • 19.25. Determining a suitable partitioning scheme
  • 19.26. 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
    • 20.6.1. BLOB/CLOB mappings
    • 20.6.2. Boolean mappings
• 21. Legacy Bootstrapping
• 22. Migration
• 23. Legacy Domain Model
• 24. Legacy Hibernate Criteria Queries
  • 24.1. Creating a Criteria instance
  • 24.2. Narrowing the result set
  • 24.3. Ordering the results
  • 24.4. Associations
  • 24.5. Dynamic association fetching
  • 24.6. Components
  • 24.7. Collections
  • 24.8. Example queries
  • 24.9. Projections, aggregation and grouping
  • 24.10. Detached queries and subqueries
  • 24.11. Queries by natural identifier
• 25. Legacy Hibernate Native Queries
  • 25.1. Legacy Named SQL queries
  • 25.2. Legacy return-property to explicitly specify column/alias names
  • 25.3. Legacy stored procedures for querying
  • 25.4. Legacy rules/limitations for using stored procedures
  • 25.5. Legacy custom SQL for create, update and delete
  • 25.6. Legacy custom SQL for loading
• 26. References