java persistence with hibernate, 2007

Praise for the First Edition
“2005 Best Java Book!”
—Java Developer’s Journal
Hibernate In Action has to be considered the definitive tome on Hibernate. As
the authors are intimately involved with the project, the insight on Hibernate
that they provide can’t be easily duplicated.
—JavaRanch.com
“Not only gets you up to speed with Hibernate and its features…It also intro-
duces you to the right way of developing and tuning an industrial-quality Hiber-
nate application. …albeit very technical, it reads astonishingly
easy…unfortunately very rare nowadays…[an] excellent piece of work…”
—JavaLobby.com
“The first and only full tutorial, reference, and authoritative guide, and one of
the most anticipated books of the year for Hibernate users.”
—Dr. Dobb’s Journal
“…the book was beyond my expectations…this book is the ultimate
solution.”
—Javalobby.org, (second review, fall 2005)
“…from none others than the lead developer and the lead documenter, this
book is a great introduction and reference documentation to using Hibernate.
It is organized in such a way that the concepts are explained in progressive
order from very simple to more complex, and the authors take good care of
explaining every detail with good examples. …The book not only gets you up
to speed with Hibernate and its features (which the documentation does quite
well). It also introduces you to the right way of developing and tuning an indus-
trial-quality Hibernate application.”
—Slashdot.org
“Strongly recommended, because a contemporary and state-of-the-art topic is
very well explained, and especially, because the voices come literally from the
horses’ mouths.”

—C Vu, the Journal of the ACCU
“The ultimate guide to the Hibernate open source project. It provides in-depth
information on architecture of Hibernate, configuring Hibernate and develop-
ment using Hibernate…It also explains essential concepts like, object/rela-
tional mapping (
ORM), persistence, caching, queries and describes how they
are taken care with respect to Hibernate…written by the creators of Hibernate
and they have made best effort to introduce and leverage Hibernate. I recom-
mend this book to everyone who is interested in getting familiar with
Hibernate.”
—JavaReference.com
“Well worth the cost…While the on-line documentation is good, (Mr. Bauer,
one of the authors is in charge of the on-line documentation) the book is bet-
ter. It begins with a description of what you are trying to do (often left out in
computer books) and leads you on in a consistent manner through the entire
Hibernate system. Excellent Book!”
—Books-on-Line
“A compact (408 pages), focused, no nonsense read and an essential resource
for anyone venturing into the
ORM landscape. The first three chapters of this
book alone are indispensable for developers that want to quickly build an
application leveraging Hibernate, but more importantly really want to under-
stand Hibernate concepts, framework, methodology and the reasons that
shaped the framework design. The remaining chapters continue the compre-
hensive overview of Hibernate that include how to map to and persist objects,
inheritance, transactions, concurrency, caching, retrieving objects efficiently
using
HQL, configuring Hibernate for managed and unmanaged environ-
ments, and the Hibernate Toolset that can be leveraged for several different
development scenarios.”

—Columbia Java Users Group
“The authors show their knowledge of relational databases and the paradigm
of mapping this world with the object-oriented world of Java. This is why the
book is so good at explaining Hibernate in the context of solving or providing
a solution to the very complex problem of object/relational mapping.”
—Denver JUG
Java Persistence
with Hibernate
REVISED EDITION OF
HIBERNATE IN ACTION
CHRISTIAN BAUER
AND GAVIN KING
MANNING
Greenwich
(74° w. long.)
For online information and ordering of this and other Manning books, please visit
www.manning.com. The publisher offers discounts on this book when ordered in quantity.
For more information, please contact:
Special Sales Department
Manning Publications Co.
Cherokee Station
PO Box 20386 Fax: (609) 877-8256
New York, NY 10021 email:
©2007 by Manning Publications Co. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in
any form or by means electronic, mechanical, photocopying, or otherwise, without prior written
permission of the publisher.
Many of the designations used by manufacturers and sellers to distinguish their products are
claimed as trademarks. Where those designations appear in the book, and Manning
Publications was aware of a trademark claim, the designations have been printed in initial caps

or all caps.
Recognizing the importance of preserving what has been written, it is Manning’s policy to have
the books we publish printed on acid-free paper, and we exert our best efforts to that end.
Manning Publications Co. Copyeditor: Tiffany Taylor
209 Bruce Park Avenue Typesetters: Dottie Marsico
Greenwich, CT 06830 Cover designer: Leslie Haimes
ISBN 1-932394-88-5
Printed in the United States of America
12345678910–VHG–1009080706
v
brief contents
PART 1GETTING STARTED WITH HIBERNATE AND EJB 3.0 1
1 ■ Understanding object/relational persistence 3
2
■ Starting a project 37
3
■ Domain models and metadata 105
PART 2MAPPING CONCEPTS AND STRATEGIES 155
4 ■ Mapping persistent classes 157
5
■ Inheritance and custom types 191
6
■ Mapping collections and entity associations 240
7
■ Advanced entity association mappings 277
8
■ Legacy databases and custom SQL 322
PART 3CONVERSATIONAL OBJECT PROCESSING 381
9 ■ Working with objects 383
10

■ Transactions and concurrency 433
11
■ Implementing conversations 476
12
■ Modifying objects efficiently 517
vi BRIEF CONTENTS
13 ■ Optimizing fetching and caching 559
14
■ Querying with HQL and JPA QL 614
15
■ Advanced query options 663
16
■ Creating and testing layered applications 697
17
■ Introducing JBoss Seam 747
appendix A SQL fundamentals 818
appendix B Mapping quick reference 822
vii
contents
foreword to the revised edition xix
foreword to the first edition xxi
preface to the revised edition xxiii
preface to the first edition xxv
acknowledgments xxviii
about this book xxix
about the cover illustration xxxiii
PART 1GETTING STARTED WITH HIBERNATE
AND EJB 3.0 1
1
Understanding object/relational persistence 3

1.1 What is persistence? 5
Relational databases 5
■
Understanding SQL 6
■
Using SQL
in Java 7
■
Persistence in object-oriented applications 8
1.2 The paradigm mismatch 10
The problem of granularity 12
■
The problem of subtypes 13
The problem of identity 14
■
Problems relating to
associations 16
■
The problem of data navigation 18
The cost of the mismatch 19
viii CONTENTS
1.3 Persistence layers and alternatives 20
Layered architecture 20
■
Hand-coding a persistence
layer with SQL/JDBC 22
■
Using serialization 23
Object-oriented database systems 23
■

Other options 24
1.4 Object/relational mapping 24
What is ORM? 25
■
Generic ORM problems 27
Why ORM? 28
■
Introducing Hibernate, EJB3,
and JPA 31
1.5 Summary 35
2
Starting a project 37
2.1 Starting a Hibernate project 38
Selecting a development process 39
■
Setting up
the project 41
■
Hibernate configuration and
startup 49
■
Running and testing the application 60
2.2 Starting a Java Persistence project 68
Using Hibernate Annotations 68
■
Using Hibernate
EntityManager 72
■
Introducing EJB components 79
Switching to Hibernate interfaces 86

2.3 Reverse engineering a legacy database 88
Creating a database configuration 89
■
Customizing
reverse engineering 90
■
Generating Java source code 92
2.4 Integration with Java EE services 96
Integration with JTA 97
■
JNDI-bound SessionFactory 101
JMX service deployment 103
2.5 Summary 104
3
Domain models and metadata 105
3.1 The CaveatEmptor application 106
Analyzing the business domain 107
■
The CaveatEmptor
domain model 108
CONTENTS ix
3.2 Implementing the domain model 110
Addressing leakage of concerns 111
■
Transparent and
automated persistence 112
■
Writing POJOs and persistent
entity classes 113
■

Implementing POJO associations 116
Adding logic to accessor methods 120
3.3 Object/relational mapping metadata 123
Metadata in XML 123
■
Annotation-based metadata 125
Using XDoclet 131
■
Handling global metadata 133
Manipulating metadata at runtime 138
3.4 Alternative entity representation 140
Creating dynamic applications 141
■
Representing data
in XML 148
3.5 Summary 152
PART 2MAPPING CONCEPTS AND STRATEGIES 155
4
Mapping persistent classes 157
4.1 Understanding entities and value types 158
Fine-grained domain models 158
■
Defining the concept 159
Identifying entities and value types 160
4.2 Mapping entities with identity 161
Understanding Java identity and equality 162
■
Handling
database identity 162
■

Database primary keys 166
4.3 Class mapping options 171
Dynamic SQL generation 172
■
Making an entity
immutable 173
■
Naming entities for querying 173
Declaring a package name 174
■
Quoting SQL identifiers 175
Implementing naming conventions 175
4.4 Fine-grained models and mappings 177
Mapping basic properties 177
■
Mapping components 184
4.5 Summary 189
x CONTENTS
5
Inheritance and custom types 191
5.1 Mapping class inheritance 192
Table per concrete class with implicit polymorphism 192
Table per concrete class with unions 195
■
Table per
class hierarchy 199
■
Table per subclass 203
Mixing inheritance strategies 207
■

Choosing a
strategy 210
5.2 The Hibernate type system 212
Recapitulating entity and value types 212
Built-in mapping types 214
■
Using mapping
types 219
5.3 Creating custom mapping types 220
Considering custom mapping types 221
■
The
extension points 222
■
The case for custom
mapping types 223
■
Creating a UserType 224
Creating a CompositeUserType 228
■
Parameterizing
custom types 230
■
Mapping enumerations 233
5.4 Summary 239
6
Mapping collections and entity associations 240
6.1 Sets, bags, lists, and maps of value types 241
Selecting a collection interface 241
■

Mapping a
set 243
■
Mapping an identifier bag 244
Mapping a list 246
■
Mapping a map 247
Sorted and ordered collections 248
6.2 Collections of components 251
Writing the component class 252
■
Mapping the
collection 252
■
Enabling bidirectional navigation 253
Avoiding not-null columns 254
6.3 Mapping collections with annotations 256
Basic collection mapping 256
■
Sorted and ordered
collections 257
■
Mapping a collection of embedded objects 258
CONTENTS xi
6.4 Mapping a parent/children relationship 260
Multiplicity 261
■
The simplest possible association 261
Making the association bidirectional 264
■

Cascading object
state 267
6.5 Summary 275
7
Advanced entity association mappings 277
7.1 Single-valued entity associations 278
Shared primary key associations 279
■
One-to-one foreign
key associations 282
■
Mapping with a join table 285
7.2 Many-valued entity associations 290
One-to-many associations 290
■
Many-to-many
associations 297
■
Adding columns to join tables 303
Mapping maps 310
7.3 Polymorphic associations 313
Polymorphic many-to-one associations 313
■
Polymorphic
collections 315
■
Polymorphic associations to unions 316
Polymorphic table per concrete class 319
7.4 Summary 321
8

Legacy databases and custom SQL 322
8.1 Integrating legacy databases 323
Handling primary keys 324
■
Arbitrary join conditions
with formulas 337
■
Joining arbitrary tables 342
■
Working
with triggers 346
8.2 Customizing SQL 350
Writing custom CRUD statements 351
Integrating stored procedures and functions 356
8.3 Improving schema DDL 364
Custom SQL names and datatypes 365
■
Ensuring data
consistency 367
■
Adding domains and column
xii CONTENTS
constraints 369
■
Table-level constraints 370
Database constraints 373
■
Creating indexes 375
Adding auxiliary DDL 376
8.4 Summary 378

PART 3CONVERSATIONAL OBJECT PROCESSING 381
9
Working with objects 383
9.1 The persistence lifecycle 384
Object states 385
■
The persistence context 388
9.2 Object identity and equality 391
Introducing conversations 391
■
The scope of object
identity 393
■
The identity of detached objects 394
Extending a persistence context 400
9.3 The Hibernate interfaces 401
Storing and loading objects 402
■
Working with detached
objects 408
■
Managing the persistence context 414
9.4 The Java Persistence API 417
Storing and loading objects 417
■
Working with detached
entity instances 423
9.5 Using Java Persistence in EJB components 426
Injecting an EntityManager 426
■

Looking up an
EntityManager 429
■
Accessing an
EntityManagerFactory 429
9.6 Summary 431
10
Transactions and concurrency 433
10.1 Transaction essentials 434
Database and system transactions 435
■
Transactions in
a Hibernate application 437
■
Transactions with Java
Persistence 449
CONTENTS xiii
10.2 Controlling concurrent access 453
Understanding database-level concurrency 453
■
Optimistic
concurrency control 458
■
Obtaining additional isolation
guarantees 465
10.3 Nontransactional data access 469
Debunking autocommit myths 470
■
Working
nontransactionally with Hibernate 471

■
Optional
transactions with JTA 473
10.4 Summary 474
11
Implementing conversations 476
11.1 Propagating the Hibernate Session 477
The use case for Session propagation 478
■
Propagation
through thread-local 480
■
Propagation with
JTA 482
■
Propagation with EJBs 483
11.2 Conversations with Hibernate 485
Providing conversational guarantees 485
■
Conversations
with detached objects 486
■
Extending a Session for a
conversation 489
11.3 Conversations with JPA 497
Persistence context propagation in Java SE 498
Merging detached objects in conversations 499
Extending the persistence context in Java SE 501
11.4 Conversations with EJB 3.0 506
Context propagation with EJBs 506

Extended persistence contexts with EJBs 510
11.5 Summary 515
12
Modifying objects efficiently 517
12.1 Transitive persistence 518
Persistence by reachability 519
■
Applying cascading to
associations 520
■
Working with transitive state 524
Transitive associations with JPA 531
xiv CONTENTS
12.2 Bulk and batch operations 532
Bulk statements with HQL and JPA QL 533
■
Processing
with batches 537
■
Using a stateless Session 539
12.3 Data filtering and interception 540
Dynamic data filters 541
■
Intercepting Hibernate events 546
The core event system 553
■
Entity listeners and callbacks 556
12.4 Summary 558
13
Optimizing fetching and caching 559

13.1 Defining the global fetch plan 560
The object-retrieval options 560
■
The lazy default fetch
plan 564
■
Understanding proxies 564
■
Disabling proxy
generation 567
■
Eager loading of associations and
collections 568
■
Lazy loading with interception 571
13.2 Selecting a fetch strategy 573
Prefetching data in batches 574
■
Prefetching collections with
subselects 577
■
Eager fetching with joins 578
■
Optimizing
fetching for secondary tables 581
■
Optimization
guidelines 584
13.3 Caching fundamentals 592
Caching strategies and scopes 593

■
The Hibernate cache
architecture 597
13.4 Caching in practice 602
Selecting a concurrency control strategy 602
■
Understanding
cache regions 604
■
Setting up a local cache provider 605
Setting up a replicated cache 606
■
Controlling the second-level
cache 611
13.5 Summary 612
14
Querying with HQL and JPA QL 614
14.1 Creating and running queries 615
Preparing a query 616
■
Executing a query 625
Using named queries 629
CONTENTS xv
14.2 Basic HQL and JPA QL queries 633
Selection 633
■
Restriction 635
■
Projection 641
14.3 Joins, reporting queries, and subselects 643

Joining relations and associations 643
■
Reporting
queries 655
■
Using subselects 659
14.4 Summary 662
15
Advanced query options 663
15.1 Querying with criteria and example 664
Basic criteria queries 665
■
Joins and dynamic
fetching 670
■
Projection and report queries 676
Query by example 680
15.2 Using native SQL queries 683
Automatic resultset handling 683
■
Retrieving scalar
values 684
■
Native SQL in Java Persistence 686
15.3 Filtering collections 688
15.4 Caching query results 691
Enabling the query result cache 691
■
Understanding
the query cache 692

■
When to use the query cache 693
Natural identifier cache lookups 693
15.5 Summary 695
16
Creating and testing layered applications 697
16.1 Hibernate in a web application 698
Introducing the use case 698
■
Writing a controller 699
The Open Session in View pattern 701
■
Designing smart
domain models 705
16.2 Creating a persistence layer 708
A generic data-access object pattern 709
■
Implementing the
generic CRUD interface 711
■
Implementing entity DAOs 713
Using data-access objects 715
xvi CONTENTS
16.3 Introducing the Command pattern 718
The basic interfaces 719
■
Executing command objects 721
Variations of the Command pattern 723
16.4 Designing applications with EJB 3.0 725
Implementing a conversation with stateful beans 725

■
Writing
DAOs with EJBs 727
■
Utilizing dependency injection 728
16.5 Testing 730
Understanding different kinds of tests 731
■
Introducing
TestNG 732
■
Testing the persistence layer 736
Considering performance benchmarks 744
16.6 Summary 746
17
Introducing JBoss Seam 747
17.1 The Java EE 5.0 programming model 748
Considering JavaServer Faces 749
■
Considering EJB 3.0 751
Writing a web application with JSF and EJB 3.0 752
Analyzing the application 762
17.2 Improving the application with Seam 765
Configuring Seam 766
■
Binding pages to stateful Seam
components 767
■
Analyzing the Seam application 773
17.3 Understanding contextual components 779

Writing the login page 779
■
Creating the components 781
Aliasing contextual variables 784
■
Completing the login/logout
feature 786
17.4 Validating user input 789
Introducing Hibernate Validator 790
■
Creating the registration
page 791
■
Internationalization with Seam 799
CONTENTS xvii
17.5 Simplifying persistence with Seam 803
Implementing a conversation 804
■
Letting Seam manage the
persistence context 811
17.6 Summary 816
appendix A SQL fundamentals 818
appendix B Mapping quick reference 822
references 824
index 825

xix
foreword to the revised edition
When Hibernate in Action was published two years ago, it was immediately recog-
nized not only as the definitive book on Hibernate, but also as the definitive work

on object/relational mapping.
In the intervening time, the persistence landscape has changed with the
release of the Java Persistence
API, the new standard for object/relational map-
ping for Java EE and Java SE which was developed under the Java Community Pro-
cess as part of the Enterprise JavaBeans 3.0 Specification.
In developing the Java Persistence
API, the EJB 3.0 Expert Group benefitted
heavily from the experience of the
O/R mapping frameworks already in use in
the Java community. As one of the leaders among these, Hibernate has had a very
significant influence on the technical direction of Java Persistence. This was due
not only to the participation of Gavin King and other members of the Hibernate
team in the
EJB 3.0 standardization effort, but was also due in large part to the
direct and pragmatic approach that Hibernate has taken towards
O/R mapping
and to the simplicity, clarity, and power of its
APIs and their resulting appeal to
the Java community.
In addition to their contributions to Java Persistence, the Hibernate develop-
ers also have taken major steps forward for Hibernate with the Hibernate 3
release described in this book. Among these are support for operations over large
datasets; additional and more sophisticated mapping options, especially for han-
dling legacy databases; data filters; strategies for managing conversations; and
xx FOREWORD TO THE REVISED EDITION
integration with Seam, the new framework for web application development with
JSF and EJB 3.0.
Java Persistence with Hibernate is therefore considerably more than simply a sec-
ond edition to Hibernate in Action. It provides a comprehensive overview of all the

capabilities of the Java Persistence
API in addition to those of Hibernate 3, as well
as a detailed comparative analysis of the two. It describes how Hibernate has been
used to implement the Java Persistence standard, and how to leverage the Hiber-
nate extensions to Java Persistence.
More important, throughout the presentation of Hibernate and Java Persis-
tence, Christian Bauer and Gavin King illustrate and explain the fundamental
principles and decisions that need to be taken into account in both the design
and use of an object/relational mapping framework. The insights they provide
into the underlying issues of
ORM give the reader a deep understanding into the
effective application of
ORM as an enterprise technology.
Java Persistence with Hibernate thus reaches out to a wide range of developers—
from newcomers to object/relational mapping to experienced developers—seek-
ing to learn more about cutting-edge technological innovations in the Java com-
munity that have occurred and are continuing to emerge as a result of this work.
L
INDA DEMICHIEL
Specification Lead
Enterprise JavaBeans 3.0 and Java Persistence
Sun Microsystems
xxi
foreword to the first edition
Relational databases are indisputably at the core of the modern enterprise.
While modern programming languages, including Java
TM
, provide an intuitive,
object-oriented view of application-level business entities, the enterprise data
underlying these entities is heavily relational in nature. Further, the main strength

of the relational model—over earlier navigational models as well as over later
OODB models—is that by design it is intrinsically agnostic to the programmatic
manipulation and application-level view of the data that it serves up.
Many attempts have been made to bridge relational and object-oriented tech-
nologies, or to replace one with the other, but the gap between the two is one of
the hard facts of enterprise computing today. It is this challenge—to provide a
bridge between relational data and Java
TM
objects—that Hibernate takes on
through its object/relational mapping (
ORM) approach. Hibernate meets this
challenge in a very pragmatic, direct, and realistic way.
As Christian Bauer and Gavin King demonstrate in this book, the effective use
of
ORM technology in all but the simplest of enterprise environments requires
understanding and configuring how the mediation between relational data and
objects is performed. This demands that the developer be aware and knowledge-
able both of the application and its data requirements, and of the
SQL query lan-
guage, relational storage structures, and the potential for optimization that
relational technology offers.
xxii FOREWORD TO THE FIRST EDITION
Not only does Hibernate provide a full-function solution that meets these
requirements head on, it is also a flexible and configurable architecture. Hiber-
nate’s developers designed it with modularity, pluggability, extensibility, and user
customization in mind. As a result, in the few years since its initial release,
Hibernate has rapidly become one of the leading
ORM technologies for enter-
prise developers—and deservedly so.
This book provides a comprehensive overview of Hibernate. It covers how to

use its type mapping capabilities and facilities for modeling associations and
inheritance; how to retrieve objects efficiently using the Hibernate query lan-
guage; how to configure Hibernate for use in both managed and unmanaged
environments; and how to use its tools. In addition, throughout the book the
authors provide insight into the underlying issues of
ORM and into the design
choices behind Hibernate. These insights give the reader a deep understanding
of the effective use of
ORM as an enterprise technology.
Hibernate in Action is the definitive guide to using Hibernate and to object/rela-
tional mapping in enterprise computing today.
L
INDA DEMICHIEL
Lead Architect, Enterprise JavaBeans
Sun Microsystems
xxiii
preface to the revised edition
The predecessor of this book, Hibernate in Action, started with a quote from
Anthony Berglas: “Just because it is possible to push twigs along the ground with
one’s nose does not necessarily mean that that is the best way to collect firewood.”
Since then, the Hibernate project and the strategies and concepts software devel-
opers rely on to manage information have evolved. However, the fundamental
issues are still the same—every company we work with every day still uses
SQL data-
bases, and Java is entrenched in the industry as the first choice for enterprise
application development.
The tabular representation of data in a relational system is still fundamentally
different than the networks of objects used in object-oriented Java applications.
We still see the object/relational impedance mismatch, and we frequently see that
the importance and cost of this mismatch is underestimated.

On the other hand, we now have a range of tools and solutions available to
deal with this problem. We’re done collecting firewood, and the pocket lighter
has been replaced with a flame thrower.
Hibernate is now available in its third major release; Hibernate 3.2 is the ver-
sion we describe in this book. Compared to older Hibernate versions, this new
major release has twice as many features—and this book is almost double the size
of Hibernate in Action. Most of these features are ones that you, the developers
working with Hibernate every day, have asked for. We’ve sometimes said that
Hibernate is a 90 percent solution for all the problems a Java application devel-
xxiv PREFACE TO THE REVISED EDITION
oper has to deal with when creating a database application. With the latest Hiber-
nate version, this number is more likely 99 percent.
As Hibernate matured and its user base and community kept growing, the Java
standards for data management and database application development were
found lacking by many developers. We even told you not to use
EJB 2.x entity
beans in Hibernate in Action.
Enter
EJB 3.0 and the new Java Persistence standard. This new industry stan-
dard is a major step forward for the Java developer community. It defines a light-
weight and simplified programming model and powerful object/relational
persistence. Many of the key concepts of the new standard were modeled after
Hibernate and other successful object/relational persistence solutions. The latest
Hibernate version implements the Java Persistence standard.
So, in addition to the new all-in-one Hibernate for every purpose, you can now
use Hibernate like any Java Persistence provider, with or without other
EJB 3.0
components and Java EE 5.0 services. This deep integration of Hibernate with
such a rich programming model enables you to design and implement applica-
tion functionality that was difficult to create by hand before.

We wrote this book to give you a complete and accurate guide to both Hiber-
nate and Java Persistence (and also all relevant
EJB 3.0 concepts). We hope that
you’ll enjoy learning Hibernate and that you'll keep this reference bible on your
desk for your daily work.