Hibernate Complete

HIBERNATE - Relational Persistence for Idiomatic Java h ttp : / / docs. j b oss. org / h ib ernate/ core/ 3 .
: / / docs. j b oss. org / h ib ernate/ core/ 3 . 3 / reference/ en-U S / h tml_ sing le/
HIBERNATE - Relational Persistence for

Id iom atic J av a
Hibernate Reference Documentation

by G av i n K i n g, Ch ri sti an B au er, M ax R ydah l A n dersen , E m m an u el B ern ard, an d S tev e E berso l e
an d th an k s to J am es Co bb (G rap h i c D esi gn ) an d Ch eyen n e W eav er (G rap h i c D esi gn )
3.3.2.GA
Co p yri gh t © 20 0 4 R ed H at M i ddl ew are, L L C.
L egal N o ti c e
J u n e 24 , 20 0 9
P refac e
1 . F eedbac k
1 . T u to ri al
1 .1 . P art 1 - T h e fi rst H i bern ate A p p l i c ati o n
1 .1 .1 . S etu p
1 .1 .2. T h e fi rst c l ass
1 .1 .3 . T h e m ap p i n g fi l e
1 .1 .4 . H i bern ate c o n fi gu rati o n
1 .1 .5 . B u i l di n g w i th M av en
1 .1 .6 . S tartu p an d h el p ers
1 .1 .7 . L o adi n g an d sto ri n g o bj ec ts
1 .2. P art 2 - M ap p i n g asso c i ati o n s
1 .2.1 . M ap p i n g th e P erso n c l ass
1 .2.2. A u n i di rec ti o n al S et- based asso c i ati o n
1 .2.3 . W o rk i n g th e asso c i ati o n
1 .2.4 . Co l l ec ti o n o f v al u es
1 .2.5 . B i - di rec ti o n al asso c i ati o n s
1 .2.6 . W o rk i n g bi - di rec ti o n al l i n k s
1 .3 . P art 3 - T h e E v en tM an ager w eb ap p l i c ati o n
1 .3 .1 . W ri ti n g th e basi c serv l et
1 .3 .2. P ro c essi n g an d ren deri n g
1 .3 .3 . D ep l o yi n g an d testi n g
1 .4 . S u m m ary
2. A rc h i tec tu re
2.1 . O v erv i ew
2.2. I n stan c e states
2.3 . J M X I n tegrati o n
2.4 . J CA S u p p o rt
2.5 . Co n tex tu al sessi o n s
3 . Co n fi gu rati o n
1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
HIBERNATE - Relational Persistence for Idiomatic Java h ttp : / / docs. j b oss. org / h ib ernate/ core/ 3 . 3 / reference/ en-U S / h tml_ sing le/
3 .1 . P ro gram m ati c c o n fi gu rati o n

3 .2. O btai n i n g a S essi o n F ac to ry
3 .3 . J D B C c o n n ec ti o n s
3 .4 . O p ti o n al c o n fi gu rati o n p ro p erti es
3 .4 .1 . S Q L D i al ec ts
3 .4 .2. O u ter J o i n F etc h i n g
3 .4 .3 . B i n ary S tream s
3 .4 .4 . S ec o n d- l ev el an d q u ery c ac h e
3 .4 .5 . Q u ery L an gu age S u bsti tu ti o n
3 .4 .6 . H i bern ate stati sti c s
3 .5 . L o ggi n g
3 .6 . I m p l em en ti n g a NamingStrategy
3 .7 . X M L c o n fi gu rati o n fi l e
3 .8 . J 2E E A p p l i c ati o n S erv er i n tegrati o n
3 .8 .1 . T ran sac ti o n strategy c o n fi gu rati o n
3 .8 .2. J N D I - bo u n d Ses s io nF acto ry
3 .8 .3 . Cu rren t S essi o n c o n tex t m an agem en t w i th J T A
3 .8 .4 . J M X dep l o ym en t
4 . P ersi sten t Cl asses
4 .1 . A si m p l e P O J O ex am p l e
4 .1 .1 . I m p l em en t a n o - argu m en t c o n stru c to r
4 .1 .2. P ro v i de an i den ti fi er p ro p erty (o p ti o n al )
4 .1 .3 . P refer n o n - fi n al c l asses (o p ti o n al )
4 .1 .4 . D ec l are ac c esso rs an d m u tato rs fo r p ersi sten t fi el ds (o p ti o n al )
4 .2. I m p l em en ti n g i n h eri tan c e
4 .3 . I m p l em en ti n g eq u al s ( ) an d h as h C o de( )
4 .4 . D yn am i c m o del s
4 .5 . T u p l i z ers
4 .6 . E n ti tyN am eR eso l v ers
5 . B asi c O /R M ap p i n g
5 .1 . M ap p i n g dec l arati o n
5 .1 .1 . D o c typ e
5 .1 .2. H i bern ate- m ap p i n g
5 .1 .3 . Cl ass
5 .1 .4 . i d
5 .1 .5 . E n h an c ed i den ti fi er gen erato rs
5 .1 .6 . I den ti fi er gen erato r o p ti m i z ati o n
5 .1 .7 . c o m p o si te- i d
5 .1 .8 . D i sc ri m i n ato r
5 .1 .9 . V ersi o n (o p ti o n al )
5 .1 .1 0 . T i m estam p (o p ti o n al )
5 .1 .1 1 . P ro p erty
5 .1 .1 2. M an y- to - o n e
5 .1 .1 3 . O n e- to - o n e
5 .1 .1 4 . N atu ral - i d
5 .1 .1 5 . Co m p o n en t an d dyn am i c - c o m p o n en t
5 .1 .1 6 . P ro p erti es
5 .1 .1 7 . S u bc l ass
5 .1 .1 8 . J o i n ed- su bc l ass
5 .1 .1 9 . U n i o n - su bc l ass
5 .1 .20 . J o i n
5 .1 .21 . K ey
5 .1 .22. Co l u m n an d fo rm u l a el em en ts
5 .1 .23 . I m p o rt
5 .1 .24 . A n y
5 .2. H i bern ate typ es
5 .2.1 . E n ti ti es an d v al u es
5 .2.2. B asi c v al u e typ es
5 .2.3 . Cu sto m v al u e typ es
5 .3 . M ap p i n g a c l ass m o re th an o n c e
2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
5 .4 . S Q L q u o ted i den ti fi ers

5 .5 . M etadata al tern ati v es
5 .5 .1 . U si n g X D o c l et m ark u p
5 .5 .2. U si n g J D K 5 .0 A n n o tati o n s
5 .6 . G en erated p ro p erti es
5 .7 . A u x i l i ary database o bj ec ts
6 . Co l l ec ti o n m ap p i n g
6 .1 . P ersi sten t c o l l ec ti o n s
6 .2. Co l l ec ti o n m ap p i n gs
6 .2.1 . Co l l ec ti o n fo rei gn k eys
6 .2.2. Co l l ec ti o n el em en ts
6 .2.3 . I n dex ed c o l l ec ti o n s
6 .2.4 . Co l l ec ti o n s o f v al u es an d m an y- to - m an y asso c i ati o n s
6 .2.5 . O n e- to - m an y asso c i ati o n s
6 .3 . A dv an c ed c o l l ec ti o n m ap p i n gs
6 .3 .1 . S o rted c o l l ec ti o n s
6 .3 .2. B i di rec ti o n al asso c i ati o n s
6 .3 .3 . B i di rec ti o n al asso c i ati o n s w i th i n dex ed c o l l ec ti o n s
6 .3 .4 . T ern ary asso c i ati o n s
6 .3 .5 . U s ing an < idb ag>
6 .4 . Co l l ec ti o n ex am p l es
7 . A sso c i ati o n M ap p i n gs
7 .1 . I n tro du c ti o n
7 .2. U n i di rec ti o n al asso c i ati o n s
7 .2.1 . M an y- to - o n e
7 .2.2. O n e- to - o n e
7 .2.3 . O n e- to - m an y
7 .3 . U n i di rec ti o n al asso c i ati o n s w i th j o i n tabl es
7 .3 .1 . O n e- to - m an y
7 .3 .2. M an y- to - o n e
7 .3 .3 . O n e- to - o n e
7 .3 .4 . M an y- to - m an y
7 .4 . B i di rec ti o n al asso c i ati o n s
7 .4 .1 . o n e- to - m an y / m an y- to - o n e
7 .4 .2. O n e- to - o n e
7 .5 . B i di rec ti o n al asso c i ati o n s w i th j o i n tabl es
7 .5 .2. o n e to o n e
7 .5 .3 . M an y- to - m an y
7 .6 . M o re c o m p l ex asso c i ati o n m ap p i n gs
8 . Co m p o n en t M ap p i n g
8 .1 . D ep en den t o bj ec ts
8 .2. Co l l ec ti o n s o f dep en den t o bj ec ts
8 .3 . Co m p o n en ts as M ap i n di c es
8 .4 . Co m p o n en ts as c o m p o si te i den ti fi ers
8 .5 . D yn am i c c o m p o n en ts
9 . I n h eri tan c e m ap p i n g
9 .1 . T h e th ree strategi es
9 .1 .1 . T abl e p er c l ass h i erarc h y
9 .1 .2. T abl e p er su bc l ass
9 .1 .3 . T abl e p er su bc l ass: u si n g a di sc ri m i n ato r
9 .1 .4 . M i x i n g tabl e p er c l ass h i erarc h y w i th tabl e p er su bc l ass
9 .1 .5 . T abl e p er c o n c rete c l ass
9 .1 .6 . T abl e p er c o n c rete c l ass u si n g i m p l i c i t p o l ym o rp h i sm
9 .1 .7 . M i x i n g i m p l i c i t p o l ym o rp h i sm w i th o th er i n h eri tan c e m ap p i n gs
9 .2. L i m i tati o n s
1 0 . W o rk i n g w i th o bj ec ts
1 0 .1 . H i bern ate o bj ec t states
1 0 .2. M ak i n g o bj ec ts p ersi sten t
3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 0 .3 . L o adi n g an o bj ec t
1 0 .4 . Q u eryi n g
1 0 .4 .1 . E x ec u ti n g q u eri es
1 0 .4 .2. F i l teri n g c o l l ec ti o n s
1 0 .4 .3 . Cri teri a q u eri es
1 0 .4 .4 . Q u eri es i n n ati v e S Q L
1 0 .5 . M o di fyi n g p ersi sten t o bj ec ts
1 0 .6 . M o di fyi n g detac h ed o bj ec ts
1 0 .7 . A u to m ati c state detec ti o n
1 0 .8 . D el eti n g p ersi sten t o bj ec ts
1 0 .9 . R ep l i c ati n g o bj ec t betw een tw o di fferen t datasto res
1 0 .1 0 . F l u sh i n g th e S essi o n
1 0 .1 1 . T ran si ti v e p ersi sten c e
1 0 .1 2. U si n g m etadata
1 1 . T ran sac ti o n s an d Co n c u rren c y
1 1 .1 . S essi o n an d tran sac ti o n sc o p es
1 1 .1 .1 . U n i t o f w o rk
1 1 .1 .2. L o n g c o n v ersati o n s
1 1 .1 .3 . Co n si deri n g o bj ec t i den ti ty
1 1 .1 .4 . Co m m o n i ssu es
1 1 .2. D atabase tran sac ti o n dem arc ati o n
1 1 .2.1 . N o n - m an aged en v i ro n m en t
1 1 .2.2. U si n g J T A
1 1 .2.3 . E x c ep ti o n h an dl i n g
1 1 .2.4 . T ran sac ti o n ti m eo u t
1 1 .3 . O p ti m i sti c c o n c u rren c y c o n tro l
1 1 .3 .1 . A p p l i c ati o n v ersi o n c h ec k i n g
1 1 .3 .2. E x ten ded sessi o n an d au to m ati c v ersi o n i n g
1 1 .3 .3 . D etac h ed o bj ec ts an d au to m ati c v ersi o n i n g
1 1 .3 .4 . Cu sto m i z i n g au to m ati c v ersi o n i n g
1 1 .4 . P essi m i sti c l o c k i n g
1 1 .5 . Co n n ec ti o n rel ease m o des
1 2. I n terc ep to rs an d ev en ts
1 2.1 . I n terc ep to rs
1 2.2. E v en t system
1 2.3 . H i bern ate dec l arati v e sec u ri ty
1 3 . B atc h p ro c essi n g
1 3 .1 . B atc h i n serts
1 3 .2. B atc h u p dates
1 3 .3 . T h e S tatel essS essi o n i n terfac e
1 3 .4 . D M L - styl e o p erati o n s
1 4 .H Q L : T h e H i bern ate Q u ery L an gu age
1 4 .1 . Case S en si ti v i ty
1 4 .2. T h e fro m c l au se
1 4 .3 . A sso c i ati o n s an d j o i n s
1 4 .4 . F o rm s o f j o i n syn tax
1 4 .5 . R eferri n g to i den ti fi er p ro p erty
1 4 .6 . T h e sel ec t c l au se
1 4 .7 . A ggregate fu n c ti o n s
1 4 .8 . P o l ym o rp h i c q u eri es
1 4 .9 . T h e w h ere c l au se
1 4 .1 0 . E x p ressi o n s
1 4 .1 1 . T h e o rder by c l au se
1 4 .1 2. T h e gro u p by c l au se
1 4 .1 3 . S u bq u eri es
1 4 .1 4 . H Q L ex am p l es
1 4 .1 5 . B u l k u p date an d del ete
1 4 .1 6 . T i p s & T ri c k s
1 4 .1 7 . Co m p o n en ts
4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 4 .1 8 . R o w v al u e c o n stru c to r syn tax

1 5 . Cri teri a Q u eri es
1 5 .1 . Creati n g a C riteria i n stan c e
1 5 .2. N arro w i n g th e resu l t set
1 5 .3 . O rderi n g th e resu l ts
1 5 .4 . A sso c i ati o n s
1 5 .5 . D yn am i c asso c i ati o n fetc h i n g
1 5 .6 . E x am p l e q u eri es
1 5 .7 . P ro j ec ti o n s, aggregati o n an d gro u p i n g
1 5 .8 . D etac h ed q u eri es an d su bq u eri es
1 5 .9 . Q u eri es by n atu ral i den ti fi er
1 6 . N ati v e S Q L
1 6 .1 . U si n g a SQ L Q u ery
1 6 .1 .1 . S c al ar q u eri es
1 6 .1 .2. E n ti ty q u eri es
1 6 .1 .3 . H an dl i n g asso c i ati o n s an d c o l l ec ti o n s
1 6 .1 .4 . R etu rn i n g m u l ti p l e en ti ti es
1 6 .1 .5 . R etu rn i n g n o n - m an aged en ti ti es
1 6 .1 .6 . H an dl i n g i n h eri tan c e
1 6 .1 .7 . P aram eters
1 6 .2. N am ed S Q L q u eri es
1 6 .2.1 . U si n g retu rn - p ro p erty to ex p l i c i tl y sp ec i fy c o l u m n /al i as n am es
1 6 .2.2. U si n g sto red p ro c edu res fo r q u eryi n g
1 6 .3 . Cu sto m S Q L fo r c reate, u p date an d del ete
1 6 .4 . Cu sto m S Q L fo r l o adi n g
1 7 . F i l teri n g data
1 7 .1 . H i bern ate fi l ters
1 8 .X M L M ap p i n g
1 8 .1 . W o rk i n g w i th X M L data
1 8 .1 .1 . S p ec i fyi n g X M L an d c l ass m ap p i n g to geth er
1 8 .1 .2. S p ec i fyi n g o n l y an X M L m ap p i n g
1 8 .2. X M L m ap p i n g m etadata
1 8 .3 . M an i p u l ati n g X M L data
1 9 . I m p ro v i n g p erfo rm an c e
1 9 .1 . F etc h i n g strategi es
1 9 .1 .1 . W o rk i n g w i th l az y asso c i ati o n s
1 9 .1 .2. T u n i n g fetc h strategi es
1 9 .1 .3 . S i n gl e- en ded asso c i ati o n p ro x i es
1 9 .1 .4 . I n i ti al i z i n g c o l l ec ti o n s an d p ro x i es
1 9 .1 .5 . U si n g batc h fetc h i n g
1 9 .1 .6 . U si n g su bsel ec t fetc h i n g
1 9 .1 .7 . U si n g l az y p ro p erty fetc h i n g
1 9 .2. T h e S ec o n d L ev el Cac h e
1 9 .2.1 . Cac h e m ap p i n gs
1 9 .2.2. S trategy: read o n l y
1 9 .2.3 . S trategy: read/w ri te
1 9 .2.4 . S trategy: n o n stri c t read/w ri te
1 9 .2.5 . S trategy: tran sac ti o n al
1 9 .2.6 . Cac h e- p ro v i der/c o n c u rren c y- strategy c o m p ati bi l i ty
1 9 .3 . M an agi n g th e c ac h es
1 9 .4 . T h e Q u ery Cac h e
1 9 .5 . U n derstan di n g Co l l ec ti o n p erfo rm an c e
1 9 .5 .1 . T ax o n o m y
1 9 .5 .2. L i sts, m ap s, i dbags an d sets are th e m o st effi c i en t c o l l ec ti o n s to u p date
1 9 .5 .3 . B ags an d l i sts are th e m o st effi c i en t i n v erse c o l l ec ti o n s
1 9 .5 .4 . O n e sh o t del ete
1 9 .6 . M o n i to ri n g p erfo rm an c e
1 9 .6 .1 . M o n i to ri n g a S essi o n F ac to ry
1 9 .6 .2. M etri c s
5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
20 . T o o l set G u i de
20 .1 . A u to m ati c sc h em a gen erati o n
20 .1 .1 . Cu sto m i z i n g th e sc h em a
20 .1 .2. R u n n i n g th e to o l
20 .1 .3 . P ro p erti es
20 .1 .4 . U si n g A n t
20 .1 .5 . I n c rem en tal sc h em a u p dates
20 .1 .6 . U si n g A n t fo r i n c rem en tal sc h em a u p dates
20 .1 .7 . S c h em a v al i dati o n
20 .1 .8 . U si n g A n t fo r sc h em a v al i dati o n
21 . E x am p l e: P aren t/Ch i l d
21 .1 . A n o te abo u t c o l l ec ti o n s
21 .2. B i di rec ti o n al o n e- to - m an y
21 .3 . Casc adi n g l i fe c yc l e
21 .4 . Casc ades an d u ns av ed- v al u e
21 .5 . Co n c l u si o n
22. E x am p l e: W ebl o g A p p l i c ati o n
22.1 . P ersi sten t Cl asses
22.2. H i bern ate M ap p i n gs
22.3 . H i bern ate Co de
23 . E x am p l e: V ari o u s M ap p i n gs
23 .1 . E m p l o yer/E m p l o yee
23 .2. A u th o r/W o rk
23 .3 . Cu sto m er/O rder/P ro du c t
23 .4 . M i sc el l an eo u s ex am p l e m ap p i n gs
23 .4 .1 . " T yp ed" o n e- to - o n e asso c i ati o n
23 .4 .2. Co m p o si te k ey ex am p l e
23 .4 .3 . M an y- to - m an y w i th sh ared c o m p o si te k ey attri bu te
23 .4 .4 . Co n ten t based di sc ri m i n ati o n
23 .4 .5 . A sso c i ati o n s o n al tern ate k eys
24 . B est P rac ti c es
25 . D atabase P o rtabi l i ty Co n si derati o n s
25 .1 . P o rtabi l i ty B asi c s
25 .2. D i al ec t
25 .3 . D i al ec t reso l u ti o n
25 .4 . I den ti fi er gen erati o n
25 .5 . D atabase fu n c ti o n s
25 .6 . T yp e m ap p i n gs
R eferen c es
P reface
W o rk i n g w i th o bj ec t- o ri en ted so ftw are an d a rel ati o n al database c an be c u m berso m e an d ti m e c o n su m i n g i n
to day' s en terp ri se en v i ro n m en ts. H i bern ate i s an O bj ec t/R el ati o n al M ap p i n g to o l fo r J av a en v i ro n m en ts. T h e
term O bj ec t/R el ati o n al M ap p i n g (O R M ) refers to th e tec h n i q u e o f m ap p i n g a data rep resen tati o n fro m an
o bj ec t m o del to a rel ati o n al data m o del w i th a S Q L - based sc h em a.
H i bern ate n o t o n l y tak es c are o f th e m ap p i n g fro m J av a c l asses to database tabl es (an d fro m J av a data
typ es to S Q L data typ es), bu t al so p ro v i des data q u ery an d retri ev al fac i l i ti es. I t c an al so si gn i fi c an tl y redu c e
dev el o p m en t ti m e o th erw i se sp en t w i th m an u al data h an dl i n g i n S Q L an d J D B C.
H i bern ate' s go al i s to rel i ev e th e dev el o p er fro m 9 5 p erc en t o f c o m m o n data p ersi sten c e rel ated
p ro gram m i n g task s. H i bern ate m ay n o t be th e best so l u ti o n fo r data- c en tri c ap p l i c ati o n s th at o n l y u se
sto red- p ro c edu res to i m p l em en t th e bu si n ess l o gi c i n th e database, i t i s m o st u sefu l w i th o bj ec t- o ri en ted
do m ai n m o del s an d bu si n ess l o gi c i n th e J av a- based m i ddl e- ti er. H o w ev er, H i bern ate c an c ertai n l y h el p yo u
to rem o v e o r en c ap su l ate v en do r- sp ec i fi c S Q L c o de an d w i l l h el p w i th th e c o m m o n task o f resu l t set
tran sl ati o n fro m a tabu l ar rep resen tati o n to a grap h o f o bj ec ts.
I f yo u are n ew to H i bern ate an d O bj ec t/R el ati o n al M ap p i n g o r ev en J av a, p l ease fo l l o w th ese step s:
6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 . R ead Ch ap ter 1 , Tutorial fo r a tu to ri al w i th step - by- step i n stru c ti o n s. T h e so u rc e c o de fo r th e tu to ri al

i s i n c l u ded i n th e di stri bu ti o n i n th e do c/ ref erence/ tu to rial / di rec to ry.
2. R ead Ch ap ter 2, A rc h ite c ture to u n derstan d th e en v i ro n m en ts w h ere H i bern ate c an be u sed.

3 . V i ew th e eg/ di rec to ry i n th e H i bern ate di stri bu ti o n . I t c o n tai n s a si m p l e stan dal o n e ap p l i c ati o n . Co p y
yo u r J D B C dri v er to th e l ib / di rec to ry an d edi t etc/ h ib ernate. pro perties , sp ec i fyi n g c o rrec t v al u es fo r
yo u r database. F ro m a c o m m an d p ro m p t in th e di stri bu ti o n di rec to ry, typ e ant eg (u si n g A n t), o r
u n der W i n do w s, typ e b u il d eg .
4 . U se th i s referen c e do c u m en tati o n as yo u r p ri m ary so u rc e o f i n fo rm ati o n . Co n si der readi n g [J P w H ] i f

yo u n eed m o re h el p w i th ap p l i c ati o n desi gn , o r i f yo u p refer a step - by- step tu to ri al . A l so v i si t
h ttp ://c av eatem p to r.h i bern ate.o rg an d do w n l o ad th e ex am p l e ap p l i c ati o n fro m [J P w H ] .
5 . F A Q s are an sw ered o n th e H i bern ate w ebsi te.
6 . L i n k s to th i rd p arty dem o s, ex am p l es, an d tu to ri al s are m ai n tai n ed o n th e H i bern ate w ebsi te.
7 . T h e Co m m u n i ty A rea o n th e H i bern ate w ebsi te i s a go o d reso u rc e fo r desi gn p attern s an d v ari o u s
i n tegrati o n so l u ti o n s (T o m c at, J B o ss A S , S tru ts, E J B , etc .).
I f yo u h av e q u esti o n s, u se th e u ser fo ru m l i n k ed o n th e H i bern ate w ebsi te. W e al so p ro v i de a J I R A i ssu e

trac k i n g system fo r bu g rep o rts an d featu re req u ests. I f yo u are i n terested i n th e dev el o p m en t o f H i bern ate,
j o i n th e dev el o p er m ai l i n g l i st. I f yo u are i n terested i n tran sl ati n g th i s do c u m en tati o n i n to yo u r l an gu age,
c o n tac t u s o n th e dev el o p er m ai l i n g l i st.
Co m m erc i al dev el o p m en t su p p o rt, p ro du c ti o n su p p o rt, an d trai n i n g fo r H i bern ate i s av ai l abl e th ro u gh J B o ss

I n c . (see h ttp ://w w w .h i bern ate.o rg/S u p p o rtT rai n i n g/). H i bern ate i s a P ro fessi o n al O p en S o u rc e p ro j ec t an d a
c ri ti c al c o m p o n en t o f th e J B o ss E n terp ri se M i ddl ew are S ystem (J E M S ) su i te o f p ro du c ts.
1 . F eed back
U se H i bern ate J I R A to rep o rt erro rs o r req u est en h ac em en ts to th i s do c u m en tati o n .
C h ap ter 1 . T utorial
1 .1 . P art 1 - T h e fi rst H i bern ate A p p l i c ati o n
1 .1 .1 . S etu p
1 .1 .2. T h e fi rst c l ass
1 .1 .3 . T h e m ap p i n g fi l e
1 .1 .4 . H i bern ate c o n fi gu rati o n
1 .1 .5 . B u i l di n g w i th M av en
1 .1 .6 . S tartu p an d h el p ers
1 .1 .7 . L o adi n g an d sto ri n g o bj ec ts
1 .2. P art 2 - M ap p i n g asso c i ati o n s
1 .2.1 . M ap p i n g th e P erso n c l ass
1 .2.2. A u n i di rec ti o n al S et- based asso c i ati o n
1 .2.3 . W o rk i n g th e asso c i ati o n
1 .2.4 . Co l l ec ti o n o f v al u es
1 .2.5 . B i - di rec ti o n al asso c i ati o n s
1 .2.6 . W o rk i n g bi - di rec ti o n al l i n k s
1 .3 . P art 3 - T h e E v en tM an ager w eb ap p l i c ati o n
1 .3 .1 . W ri ti n g th e basi c serv l et
1 .3 .2. P ro c essi n g an d ren deri n g
1 .3 .3 . D ep l o yi n g an d testi n g
1 .4 . S u m m ary
I n ten ded fo r n ew u sers, th i s c h ap ter p ro v i des an step - by- step i n tro du c ti o n to H i bern ate, starti n g w i th a
si m p l e ap p l i c ati o n u si n g an i n - m em o ry database. T h e tu to ri al i s based o n an earl i er tu to ri al dev el o p ed by
7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
M i c h ael G l o egl . A l l c o de i s c o n tai n ed i n th e tutorials/web di rec to ry o f th e p ro j ec t so u rc e.
Important
T h i s tu to ri al ex p ec ts th e u ser h av e k n o w l edge o f bo th J av a an d S Q L . I f yo u h av e a l i m i ted
k n o w l edge o f J A V A o r S Q L , i t i s adv i sed th at yo u start w i th a go o d i n tro du c ti o n to th at
tec h n o l o gy p ri o r to attem p ti n g to l earn H i bern ate.
N ote
T h e di stri bu ti o n c o n tai n s an o th er ex am p l e ap p l i c ati o n u n der th e tutorial/eg p ro j ec t so u rc e
di rec to ry.
1 . 1 . P art 1 - T h e firs t Hibernate A p p l ication

F o r th i s ex am p l e, w e w i l l set u p a sm al l database ap p l i c ati o n th at c an sto re ev en ts w e w an t to atten d an d
i n fo rm ati o n abo u t th e h o st(s) o f th ese ev en ts.
N ote
A l th o u gh yo u c an u se w h atev er database yo u feel c o m fo rtabl e u si n g, w e w i l l u se H S Q L D B (an
i n - m em o ry, J av a database) to av o i d desc ri bi n g i n stal l ati o n /setu p o f an y p arti c u l ar database
serv ers.
1 . 1 . 1 . S e tu p
T h e fi rst th i n g w e n eed to do i s to set u p th e dev el o p m en t en v i ro n m en t. W e w i l l be u si n g th e " stan dard

l ayo u t" adv o c ated by al o t o f bu i l d to o l s su c h as M av en . M av en , i n p arti c u l ar, h as a go o d reso u rc e desc ri bi n g
th i s l ayo u t. A s th i s tu to ri al i s to be a w eb ap p l i c ati o n , w e w i l l be c reati n g an d m ak i n g u se o f src /m ain /j av a,
src /m ain /resourc es an d src /m ain /webap p di rec to ri es.
W e w i l l be u si n g M av en i n th i s tu to ri al , tak i n g adv an tage o f i ts tran si ti v e dep en den c y m an agem en t

c ap abi l i ti es as w el l as th e abi l i ty o f m an y I D E s to au to m ati c al l y set u p a p ro j ec t fo r u s based o n th e m av en
desc ri p to r.
8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< pro j ect x ml ns =" h ttp: / / mav en. apach e. o rg/ P O M / 4. 0. 0"
x ml ns : x s i=" h ttp: / / w w w . w 3. o rg/ 2 001/ X M L Sch ema- ins tance"
x s i: s ch emaL o catio n=" h ttp: / / mav en. apach e. o rg/ P O M / 4. 0. 0 h ttp: / / mav en. apach e. o rg/ x s d/ mav en- 4. 0. 0. x s d" >
< mo del V ers io n>4. 0. 0< / mo del V ers io n>
< gro u pI d>o rg. h ib ernate. tu to rial s < / gro u pI d>

< artif actI d>h ib ernate- tu to rial < / artif actI d>
< v ers io n>1. 0. 0- SNA P SH O T < / v ers io n>
< name>F irs t H ib ernate T u to rial < / name>

< ! - - w e do nt w ant th e v ers io n to b e part o f th e generated w ar f il e name - - >
< f inal Name>$ {artif actI d}< / f inal Name>

< dependencies >

< dependency>
< gro u pI d>o rg. h ib ernate< / gro u pI d>
< artif actI d>h ib ernate- co re< / artif actI d>
< / dependency>
< ! - - B ecau s e th is is a w eb app, w e al s o h av e a dependency o n th e s erv l et api. - - >

< dependency>
< gro u pI d>j av ax . s erv l et< / gro u pI d>
< artif actI d>s erv l et- api< / artif actI d>
< / dependency>
< ! - - H ib ernate u s es s l f 4j f o r l o gging, f o r o u r pu rpo s es h ere u s e th e s impl e b ack end - - >

< dependency>
< gro u pI d>o rg. s l f 4j < / gro u pI d>
< artif actI d>s l f 4j - s impl e< / artif actI d>
< / dependency>
< ! - - H ib ernate giv es yo u a ch o ice o f b yteco de pro v iders b etw een cgl ib and j av as s is t - - >
< dependency>
< gro u pI d>j av as s is t< / gro u pI d>
< artif actI d>j av as s is t< / artif actI d>
< / dependency>
< / dependencies >
< / pro j ect>
T ip
I t i s n o t a req u i rem en t to u se M av en . I f yo u w i sh to u se so m eth i n g el se to bu i l d th i s tu to i al
(su c h as A n t), th e l ayo u t w i l l rem ai n th e sam e. T h e o n l y c h an ge i s th at yo u w i l l n eed to
m an u al l y ac c o u n t fo r al l th e n eeded dep en den c i es. I f yo u u se so m eth i n g l i k e I v y p ro v i di n g
tran si ti v e dep en den c y m an agem en t yo u w o u l d sti l l u se th e dep en den c i es m en ti o n ed bel o w .
O th erw i se, yo u ' d n eed to grab all dep en den c i es, bo th ex p l i c i t an d tran si ti v e, an d add th em to
th e p ro j ec t' s c l assp ath . I f w o rk i n g fro m th e H i bern ate di stri bu ti o n bu n dl e, th i s w o u l d m ean
h ibern ate3 . j ar, al l arti fac ts i n th e lib/req uired di rec to ry an d al l fi l es fro m ei th er th e
lib/by tec od e/c g lib o r lib/by tec od e/j av assist di rec to ry; addi ti o n al l y yo u w i l l n eed bo th th e
serv l etap i j ar an d o n e o f th e sl f4 j l o ggi n g bac k en ds.
S av e th i s fi l e as p om . x m l i n th e p ro j ec t ro o t di rec to ry.
1 .1 .2 . T h e f i rs t c l as s
9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
N ex t, w e c reate a c l ass th at rep resen ts th e ev en t w e w an t to sto re i n th e database; i t i s a si m p l e J av aB ean

c l ass w i th so m e p ro p erti es:
pack age o rg. h ib ernate. tu to rial . do main;
impo rt j av a. u til . D ate;
pu b l ic cl as s E v ent {
priv ate L o ng id;
priv ate String titl e;

priv ate D ate date;
pu b l ic E v ent( ) {}
pu b l ic L o ng getI d( ) {
retu rn id;
}
priv ate v o id s etI d( L o ng id) {

th is . id = id;
}
pu b l ic D ate getD ate( ) {

retu rn date;
}
pu b l ic v o id s etD ate( D ate date) {

th is . date = date;
}
pu b l ic String getT itl e( ) {

retu rn titl e;
}
pu b l ic v o id s etT itl e( String titl e) {

th is . titl e = titl e;
}
}
T h i s c l ass u ses stan dard J av aB ean n am i n g c o n v en ti o n s fo r p ro p erty getter an d setter m eth o ds, as w el l as
p ri v ate v i si bi l i ty fo r th e fi el ds. A l th o u gh th i s i s th e rec o m m en ded desi gn , i t i s n o t req u i red. H i bern ate c an
al so ac c ess fi el ds di rec tl y, th e ben efi t o f ac c esso r m eth o ds i s ro bu stn ess fo r refac to ri n g.
T h e id p ro p erty h o l ds a u n i q u e i den ti fi er v al u e fo r a p arti c u l ar ev en t. A l l p ersi sten t en ti ty c l asses (th ere are

l ess i m p o rtan t dep en den t c l asses as w el l ) w i l l n eed su c h an i den ti fi er p ro p erty i f w e w an t to u se th e fu l l
featu re set o f H i bern ate. I n fac t, m o st ap p l i c ati o n s, esp ec i al l y w eb ap p l i c ati o n s, n eed to di sti n gu i sh o bj ec ts
by i den ti fi er, so yo u sh o u l d c o n si der th i s a featu re rath er th an a l i m i tati o n . H o w ev er, w e u su al l y do n o t
m an i p u l ate th e i den ti ty o f an o bj ec t, h en c e th e setter m eth o d sh o u l d be p ri v ate. O n l y H i bern ate w i l l assi gn
i den ti fi ers w h en an o bj ec t i s sav ed. H i bern ate c an ac c ess p u bl i c , p ri v ate, an d p ro tec ted ac c esso r m eth o ds, as
w el l as p u bl i c , p ri v ate an d p ro tec ted fi el ds di rec tl y. T h e c h o i c e i s u p to yo u an d yo u c an m atc h i t to fi t yo u r
ap p l i c ati o n desi gn .
T h e n o - argu m en t c o n stru c to r i s a req u i rem en t fo r al l p ersi sten t c l asses; H i bern ate h as to c reate o bj ec ts fo r
yo u , u si n g J av a R efl ec ti o n . T h e c o n stru c to r c an be p ri v ate, h o w ev er p ac k age o r p u bl i c v i si bi l i ty i s req u i red
fo r ru n ti m e p ro x y gen erati o n an d effi c i en t data retri ev al w i th o u t bytec o de i n stru m en tati o n .
S av e th i s fi l e to th e src /m ain /j av a/org /h ibern ate/tutorial/d om ain di rec to ry.
1 .1 .3 . T h e mappi ng f ile
1 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
H i bern ate n eeds to k n o w h o w to l o ad an d sto re o bj ec ts o f th e p ersi sten t c l ass. T h i s i s w h ere th e H i bern ate
m ap p i n g fi l e c o m es i n to p l ay. T h e m ap p i n g fi l e tel l s H i bern ate w h at tabl e i n th e database i t h as to ac c ess,
an d w h at c o l u m n s i n th at tabl e i t sh o u l d u se.
T h e basi c stru c tu re o f a m ap p i n g fi l e l o o k s l i k e th i s:
< ?x ml v ers io n=" 1. 0" ?>

< !D O C T Y P E h ib ernate- mapping P U B L I C
" - / / H ib ernate/ H ib ernate M apping D T D 3. 0/ / E N"
" h ttp: / / h ib ernate. s o u rcef o rge. net/ h ib ernate- mapping- 3. 0. dtd" >
< h ib ernate- mapping pack age=" o rg. h ib ernate. tu to rial . do main" >
[ ...]
< / h ib ernate- mapping>
H i bern ate D T D i s so p h i sti c ated. Y o u c an u se i t fo r au to - c o m p l eti o n o f X M L m ap p i n g el em en ts an d attri bu tes

i n yo u r edi to r o r I D E . O p en i n g u p th e D T D fi l e i n yo u r tex t edi to r i s th e easi est w ay to get an o v erv i ew o f al l
el em en ts an d attri bu tes, an d to v i ew th e defau l ts, as w el l as so m e c o m m en ts. H i bern ate w i l l n o t l o ad th e
D T D fi l e fro m th e w eb, bu t fi rst l o o k i t u p fro m th e c l assp ath o f th e ap p l i c ati o n . T h e D T D fi l e i s i n c l u ded i n
h ibern ate- c ore. j ar (i t i s al so i n c l u ded i n th e h ibern ate3 . j ar, i f u si n g th e di stri bu ti o n bu n dl e).
Important
W e w ill o m i t th e D T D dec l arati o n in fu tu re ex am p l es to sh o rten th e c o de. I t i s, o f c o u rse, n o t
o p ti o n al .
B etw een th e tw o h ib ernate- mapping tags, i n c l u de a cl as s el em en t. A l l p ersi sten t en ti ty c l asses (agai n , th ere
m i gh t be dep en den t c l asses l ater o n , w h i c h are n o t fi rst- c l ass en ti ti es) n eed a m ap p i n g to a tabl e i n th e S Q L
database:
< cl as s name=" E v ent" tab l e=" E V E NT S" >
< / cl as s >
S o far w e h av e to l d H i bern ate h o w to p ersi st an d l o ad o bj ec t o f c l ass E v ent to th e tabl e E V E NT S. E ac h i n stan c e

i s n o w rep resen ted by a ro w i n th at tabl e. N o w w e c an c o n ti n u e by m ap p i n g th e u n i q u e i den ti fi er p ro p erty to
th e tabl es p ri m ary k ey. A s w e do n o t w an t to c are abo u t h an dl i n g th i s i den ti fi er, w e c o n fi gu re H i bern ate' s
i den ti fi er gen erati o n strategy fo r a su rro gate p ri m ary k ey c o l u m n :

< id name=" id" co l u mn=" E V E NT _ I D " >
< generato r cl as s =" nativ e" / >
< / id>
< / cl as s >
T h e id el em en t i s th e dec l arati o n o f th e i den ti fi er p ro p erty. T h e name=" id" m ap p i n g attri bu te dec l ares th e

n am e o f th e J av aB ean p ro p erty an d tel l s H i bern ate to u se th e getI d( ) an d s etI d( ) m eth o ds to ac c ess th e
p ro p erty. T h e c o l u m n attri bu te tel l s H i bern ate w h i c h c o l u m n o f th e E V E NT S tabl e h o l ds th e p ri m ary k ey v al u e.
T h e n ested generato r el em en t sp ec i fi es th e i den ti fi er gen erati o n strategy (ak a h o w are i den ti fi er v al u es

gen erated?). I n th i s c ase w e c h o o se nativ e , w h i c h o ffers a l ev el o f p o rtabi l i ty dep en di n g o n th e c o n fi gu red
database di al ec t. H i bern ate su p p o rts database gen erated, gl o bal l y u n i q u e, as w el l as ap p l i c ati o n assi gn ed,
1 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
i den ti fi ers. I den ti fi er v al u e gen erati o n i s al so o n e o f H i bern ate' s m an y ex ten si o n p o i n ts an d yo u c an p l u gi n i n

yo u r o w n strategy.
T ip
nativ e i s n o l o n ger c o n si der th e best strategy i n term s o f p o rtabi l i ty. fo r fu rth er di sc u ssi o n , see
S ec ti o n 25 .4 , “ I den ti fi er gen erati o n ”
L astl y, w e n eed to tel l H i bern ate abo u t th e rem ai n i n g en ti ty c l ass p ro p erti es. B y defau l t, n o p ro p erti es o f th e
c l ass are c o n si dered p ersi sten t:

< id name=" id" co l u mn=" E V E NT _ I D " >
< / id>
< pro perty name=" date" type=" times tamp" co l u mn=" E V E NT _ D A T E " / >
< pro perty name=" titl e" / >
< / cl as s >
S im i l ar to th e id el em en t, th e name attri bu te o f th e pro perty el em en t tel l s H i bern ate w h i c h getter an d setter

m eth o ds to u se. I n th i s c ase, H i bern ate w i l l searc h fo r getD ate( ), s etD ate( ), getT itl e( ) an d s etT itl e( ) m eth o ds.
N ote
W h y do es th e date p ro p erty m ap p i n g i n c l u de th e co l u mn attri bu te, bu t th e titl e do es n o t?
W i th o u t th e co l u mn attri bu te, H i bern ate by defau l t u ses th e p ro p erty n am e as th e c o l u m n
n am e. T h i s w o rk s fo r titl e, h o w ev er, date i s a reserv ed k eyw o rd i n m o st databases so yo u w i l l
n eed to m ap i t to a di fferen t n am e.
T h e titl e m ap p i n g al so l ac k s a type attri bu te. T h e typ es dec l ared an d u sed i n th e m ap p i n g fi l es are n o t J av a

data typ es; th ey are n o t S Q L database typ es ei th er. T h ese typ es are c al l ed H ib e rnate m ap p ing ty p e s ,
c o n v erters w h i c h c an tran sl ate fro m J av a to S Q L data typ es an d v i c e v ersa. A gai n , H i bern ate w i l l try to
determ i n e th e c o rrec t c o n v ersi o n an d m ap p i n g typ e i tsel f i f th e type attri bu te i s n o t p resen t i n th e m ap p i n g.
I n so m e c ases th i s au to m ati c detec ti o n u si n g R efl ec ti o n o n th e J av a c l ass m i gh t n o t h av e th e defau l t yo u
ex p ec t o r n eed. T h i s i s th e c ase w i th th e date p ro p erty. H i bern ate c an n o t k n o w i f th e p ro p erty, w h i c h i s o f
j av a. u til . D ate, sh o u l d m ap to a S Q L date, times tamp , o r time c o l u m n . F u l l date an d ti m e i n fo rm ati o n is
p reserv ed by m ap p i n g th e p ro p erty w i th a times tamp c o n v erter.
T ip
H i bern ate m ak es th i s m ap p i n g typ e determ i n ati o n u si n g refl ec ti o n w h en th e m ap p i n g fi l es are
p ro c essed. T h i s c an tak e ti m e an d reso u rc es, so i f startu p p erfo rm an c e i s i m p o rtan t yo u sh o u l d
c o n si der ex p l i c i tl y defi n i n g th e typ e to u se.
S av e th i s m ap p i n g fi l e as src /m ain /resourc es/org /h ibern ate/tutorial/d om ain /E v en t. h bm . x m l.
1 . 1 . 4 . H i b e rnate c onf i g u rati on
A t th i s p o i n t, yo u sh o u l d h av e th e p ersi sten t c l ass an d i ts m ap p i n g fi l e i n p l ac e. I t i s n o w ti m e to c o n fi gu re

H i bern ate. F i rst l et' s set u p H S Q L D B to ru n i n " serv er m o de"
1 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
N ote
W e do th i s do th at th e data rem ai n s betw een ru n s.
W e w ill u ti l i z e th e M av en ex ec p l u gi n to l au n c h th e H S Q L D B serv er by ru n n i n g:
m v n ex ec : j av a - D ex ec . m ain C lass= " org . h sq ld b. S erv er" - D ex ec . arg s= " - d atabase. 0 f ile: targ et/d ata/tutorial" Y o u
w i l l see i t start u p an d bi n d to a T CP /I P so c k et; th i s i s w h ere o u r ap p l i c ati o n w i l l c o n n ec t l ater. I f yo u w an t to
start w i th a fresh database du ri n g th i s tu to ri al , sh u tdo w n H S Q L D B , del ete al l fi l es i n th e targ et/d ata
di rec to ry, an d start H S Q L D B agai n .
H i bern ate w i l l be c o n n ec ti n g to th e database o n beh al f o f yo u r ap p l i c ati o n , so i t n eeds to k n o w h o w to o btai n

c o n n ec ti o n s. F o r th i s tu to ri al w e w i l l be u si n g a stan dal o n e c o n n ec ti o n p o o l (as o p p o sed to a
j av ax . s q l . D ataSo u rce). H i bern ate c o m es w i th su p p o rt fo r tw o th i rd- p arty o p en so u rc e J D B C c o n n ec ti o n p o o l s:
c 3 p 0 an d p ro x o o l . H o w ev er, w e w i l l be u si n g th e H i bern ate bu i l t- i n c o n n ec ti o n p o o l fo r th i s tu to ri al .
C au ti on
T h e bu i l t- i n H i bern ate c o n n ec ti o n p o o l i s i n n o w ay i n ten ded fo r p ro du c ti o n u se. I t l ac k s sev eral
featu res fo u n d o n an y dec en t c o n n ec ti o n p o o l .
F o r H i bern ate' s c o n fi gu rati o n , w e c an u se a si m p l e h ib ernate. pro perties fi l e, a m o re so p h i sti c ated

h ib ernate. cf g. x ml fi l e, o r ev en c o m p l ete p ro gram m ati c setu p . M o st u sers p refer th e X M L c o n fi gu rati o n fi l e:
1 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< ?x ml v ers io n=' 1. 0' enco ding=' u tf - 8' ?>

< !D O C T Y P E h ib ernate- co nf igu ratio n P U B L I C
" - / / H ib ernate/ H ib ernate C o nf igu ratio n D T D 3. 0/ / E N"
" h ttp: / / h ib ernate. s o u rcef o rge. net/ h ib ernate- co nf igu ratio n- 3. 0. dtd" >
< h ib ernate- co nf igu ratio n>
< s es s io n- f acto ry>
< ! - - D atab as e co nnectio n s ettings - - >

< pro perty name=" co nnectio n. driv er_ cl as s " >o rg. h s q l db . j db cD riv er< / pro perty>
< pro perty name=" co nnectio n. u rl " >j db c: h s q l db : h s q l : / / l o cal h o s t< / pro perty>
< pro perty name=" co nnectio n. u s ername" >s a< / pro perty>
< pro perty name=" co nnectio n. pas s w o rd" >< / pro perty>
< !- - J D B C co nnectio n po o l ( u s e th e b u il t- in) - - >

< pro perty name=" co nnectio n. po o l _ s iz e" >1< / pro perty>
< ! - - SQ L dial ect - - >

< pro perty name=" dial ect" >o rg. h ib ernate. dial ect. H SQ L D ial ect< / pro perty>
< ! - - E nab l e H ib ernate' s au to matic s es s io n co ntex t management - - >

< pro perty name=" cu rrent_ s es s io n_ co ntex t_ cl as s " >th read< / pro perty>
< ! - - D is ab l e th e s eco nd- l ev el cach e - - >

< pro perty name=" cach e. pro v ider_ cl as s " >o rg. h ib ernate. cach e. No C ach eP ro v ider< / pro perty>
< ! - - E ch o al l ex ecu ted SQ L to s tdo u t - - >

< pro perty name=" s h o w _ s q l " >tru e< / pro perty>
< ! - - D ro p and re- create th e datab as e s ch ema o n s tartu p - - >

< pro perty name=" h b m2 ddl . au to " >u pdate< / pro perty>
< mapping res o u rce=" o rg/ h ib ernate/ tu to rial / do main/ E v ent. h b m. x ml " / >
< / s es s io n- f acto ry>
< / h ib ernate- co nf igu ratio n>
N ote
N o ti c e th at th i s c o n fi gu rati o n fi l e sp ec i fi es a di fferen t D T D
Y o u c o n fi gu re H i bern ate' s Ses s io nF acto ry. S essi o n F ac to ry i s a gl o bal fac to ry resp o n si bl e fo r a p arti c u l ar
database. I f yo u h av e sev eral databases, fo r easi er startu p yo u sh o u l d u se sev eral < s es s io n- f acto ry>
c o n fi gu rati o n s i n sev eral c o n fi gu rati o n fi l es.
T h e fi rst fo u r pro perty el em en ts c o n tai n th e n ec essary c o n fi gu rati o n fo r th e J D B C c o n n ec ti o n . T h e di al ec t

pro perty el em en t sp ec i fi es th e p arti c u l ar S Q L v ari an t H i bern ate gen erates.
T ip
I n m o st c ases, H i bern ate i s abl e to p ro p erl y determ i n e w h i c h di al ec t to u se. S ee S ec ti o n 25 .3 ,
“ D i al ec t reso l u ti o n ” fo r m o re i n fo rm ati o n .
H i bern ate' s au to m ati c sessi o n m an agem en t fo r p ersi sten c e c o n tex ts i s p arti c u l arl y u sefu l i n th i s c o n tex t. T h e
o p ti o n tu rn s o n au to m ati c gen erati o n o f database sc h em as di rec tl y i n to th e database. T h i s c an
h b m2 ddl . au to
1 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
al so be tu rn ed o ff by rem o v i n g th e c o n fi gu rati o n o p ti o n , o r redi rec ted to a fi l e w i th th e h el p o f th e

Sch emaE x po rt A n t task . F i n al l y, add th e m ap p i n g fi l e(s) fo r p ersi sten t c l asses to th e c o n fi gu rati o n .
S av e th i s fi l e as h ibern ate. c f g . x m l i n to th e src /m ain /resourc es di rec to ry.
1 . 1 . 5 . B u i l d i ng w i th M av e n
W e w i l l n o w bu i l d th e tu to ri al w i th M av en . Y o u w i l l n eed to h av e M av en i n stal l ed; i t i s av ai l abl e fro m th e

M av en do w n l o ad p age. M av en w i l l read th e /p om . x m l fi l e w e c reated earl i er an d k n o w h o w to p erfo rm so m e
basi c p ro j ec t task s. F i rst, l ets ru n th e co mpil e go al to m ak e su re w e c an c o m p i l e ev eryth i n g so far:
[ h ib ernateT u to rial ] $ mv n co mpil e

[ I NF O ] Scanning f o r pro j ects . . .
[ I NF O ] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[ I NF O ] B u il ding F irs t H ib ernate T u to rial
[ I NF O ] tas k - s egment: [ co mpil e]
[ I NF O ] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[ I NF O ] [ res o u rces : res o u rces ]
[ I NF O ] U s ing def au l t enco ding to co py f il tered res o u rces .
[ I NF O ] [ co mpil er: co mpil e]
[ I NF O ] C o mpil ing 1 s o u rce f il e to / h o me/ s tev e/ pro j ects / s andb o x / h ib ernateT u to rial / target/ cl as s es
[ I NF O ] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[ I NF O ] B U I L D SU C C E SSF U L
[ I NF O ] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[ I NF O ] T o tal time: 2 s eco nds
[ I NF O ] F inis h ed at: T u e J u n 09 12 : 2 5: 2 5 C D T 2 009
[ I NF O ] F inal M emo ry: 5M / 547 M
[ I NF O ] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1 . 1 . 6 . S tartu p and h e l pe rs
I t i s ti m e to l o ad an d sto re so m e E v ent o bj ec ts, bu t fi rst yo u h av e to c o m p l ete th e setu p w i th so m e

i n frastru c tu re c o de. Y o u h av e to startu p H i bern ate by bu i l di n g a gl o bal o rg. h ib ernate. Ses s io nF acto ry o bj ec t an d
sto ri n g i t so m ew h ere fo r easy ac c ess i n ap p l i c ati o n c o de. A o rg. h ib ernate. Ses s io nF acto ry i s u sed to o btai n
o rg. h ib ernate. Ses s io n i n stan c es. A o rg. h ib ernate. Ses s io n rep resen ts a si n gl e- th readed u n i t o f w o rk . T h e
o rg. h ib ernate. Ses s io nF acto ry i s a th readsafe gl o bal o bj ec t th at i s i n stan ti ated o n c e.
W e w ill c reate a H ib ernateU til h el p er c l ass th at tak es c are o f startu p an d m ak es ac c essi n g th e

o rg. h ib ernate. Ses s io nF acto ry m o re c o n v en i en t.
1 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
pack age o rg. h ib ernate. tu to rial . u til ;
impo rt o rg. h ib ernate. Ses s io nF acto ry;

impo rt o rg. h ib ernate. cf g. C o nf igu ratio n;
pu b l ic cl as s H ib ernateU til {
priv ate s tatic f inal Ses s io nF acto ry s es s io nF acto ry = b u il dSes s io nF acto ry( );
priv ate s tatic Ses s io nF acto ry b u il dSes s io nF acto ry( ) {

try {
/ / C reate th e Ses s io nF acto ry f ro m h ib ernate. cf g. x ml
retu rn new C o nf igu ratio n( ). co nf igu re( ). b u il dSes s io nF acto ry( );
}
catch ( T h ro w ab l e ex ) {
/ / M ak e s u re yo u l o g th e ex ceptio n, as it migh t b e s w al l o w ed
Sys tem. err. printl n( " I nitial Ses s io nF acto ry creatio n f ail ed. " + ex );
th ro w new E x ceptio nI nI nitial iz erE rro r( ex );
}
}
pu b l ic s tatic Ses s io nF acto ry getSes s io nF acto ry( ) {

retu rn s es s io nF acto ry;
}
S av e th i s c o de as src /m ain /j av a/org /h ibern ate/tutorial/util/H ibern ateU til. j av a
T h i s c l ass n o t o n l y p ro du c es th e gl o bal o rg. h ib ernate. Ses s io nF acto ry referen c e i n i ts stati c i n i ti al i z er; i t al so

h i des th e fac t th at it
u ses a stati c si n gl eto n . W e m i gh t j u st as w el l h av e l o o k ed u p th e
o rg. h ib ernate. Ses s io nF acto ry referen c e fro m J N D I i n an ap p l i c ati o n serv er o r an y o th er l o c ati o n fo r th at m atter.
I f yo u gi v e th e o rg. h ib ernate. Ses s io nF acto ry a n am e i n yo u r c o n fi gu rati o n , H i bern ate w i l l try to bi n d i t to J N D I

u n der th at n am e after i t h as been bu i l t. A n o th er, better o p ti o n i s to u se a J M X dep l o ym en t an d l et th e
J M X - c ap abl e c o n tai n er i n stan ti ate an d bi n d a H ib ernateServ ice to J N D I . S u c h adv an c ed o p ti o n s are di sc u ssed
l ater.
Y o u n o w n eed to c o n fi gu re a l o ggi n g system . H i bern ate u ses c o m m o n s l o ggi n g an d p ro v i des tw o c h o i c es:

L o g4 j an d J D K 1 .4 l o ggi n g. M o st dev el o p ers p refer L o g4 j : c o p y l o g4j . pro perties fro m th e H i bern ate di stri bu ti o n
i n th e etc/ di rec to ry to yo u r s rc di rec to ry, n ex t to h ib ernate. cf g. x ml . I f yo u p refer to h av e m o re v erbo se o u tp u t
th an th at p ro v i ded i n th e ex am p l e c o n fi gu rati o n , yo u c an c h an ge th e setti n gs. B y defau l t, o n l y th e H i bern ate
startu p m essage i s sh o w n o n stdo u t.
T h e tu to ri al i n frastru c tu re i s c o m p l ete an d yo u are n o w ready to do so m e real w o rk w i th H i bern ate.
1 . 1 . 7 . L oad i ng and s tori ng ob j e c ts
W e are n o w ready to start do i n g so m e real w o rj k w i th H i bern ate. L et' s start by w ri ti n g an E v entM anager c l ass
w i th a main( ) m eth o d:
1 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
pack age o rg. h ib ernate. tu to rial ;
impo rt o rg. h ib ernate. Ses s io n;
impo rt j av a. u til . *;
impo rt o rg. h ib ernate. tu to rial . do main. E v ent;

impo rt o rg. h ib ernate. tu to rial . u til . H ib ernateU til ;
pu b l ic cl as s E v entM anager {
pu b l ic s tatic v o id main( String[ ] args ) {

E v entM anager mgr = new E v entM anager( );
if ( args [ 0] . eq u al s ( " s to re" )) {

mgr. createA ndSto reE v ent( " M y E v ent" , new D ate( ));
}
H ib ernateU til . getSes s io nF acto ry( ). cl o s e( );

}
priv ate v o id createA ndSto reE v ent( String titl e, D ate th eD ate) {
Ses s io n s es s io n = H ib ernateU til . getSes s io nF acto ry( ). getC u rrentSes s io n( );
s es s io n. b eginT rans actio n( );
E v ent th eE v ent = new E v ent( );

th eE v ent. s etT itl e( titl e);
th eE v ent. s etD ate( th eD ate);
s es s io n. s av e( th eE v ent);
s es s io n. getT rans actio n( ). co mmit( );

}
I n createA ndSto reE v ent( ) w e c reated a n ew E v ent o bj ec t an d h an ded i t o v er to H i bern ate. A t th at p o i n t,

H i bern ate tak es c are o f th e S Q L an d ex ec u tes an I NSE R T o n th e database.
A
o rg.h i bern ate.S essi o n i s desi gn ed to rep resen t a si n gl e u n i t o f w o rk (a si n gl e atm o i c p i ec e o f w o rk to be
p erfo rm ed). F o r n o w w e w i l l k eep th i n gs si m p l e an d assu m e a o n e- to - o n e gran u l ari ty betw een a H i bern ate
o rg.h i bern ate.S essi o n an d a database tran sac ti o n . T o sh i el d o u r c o de fro m th e ac tu al u n derl yi n g tran sac ti o n
system w e u se th e H i bern ate o rg. h ib ernate. T rans actio n A P I . I n th i s p arti c u l ar c ase w e are u si n g J D B C- based
tran sac ti o n al sem an ti c s, bu t i t c o u l d al so ru n w i th J T A .
W h at do es s es s io nF acto ry. getC u rrentSes s io n( ) do ? F i rst, yo u c an c al l i t as m an y ti m es an d an yw h ere yo u lik e

o n c e yo u get h o l d o f yo u r o rg. h ib ernate. Ses s io nF acto ry. T h e getC u rrentSes s io n( ) m eth o d al w ays retu rn s th e
" c u rren t" u n i t o f w o rk . R em em ber th at w e sw i tc h ed th e c o n fi gu rati o n o p ti o n fo r th i s m ec h an i sm to " th read"
i n o u r src /m ain /resourc es/h ibern ate. c f g . x m l? D u e to th at setti n g, th e c o n tex t o f a c u rren t u n i t o f w o rk i s
bo u n d to th e c u rren t J av a th read th at ex ec u tes th e ap p l i c ati o n .
Important
H i bern ate o ffers th ree m eth o ds o f c u rren t sessi o n trac k i n g. T h e " th read" based m eth o d i s n o t
i n ten ded fo r p ro du c ti o n u se; i t i s m erel y u sefu l fo r p ro to typ i n g an d tu to ri al s su c h as th i s o n e.
Cu rren t sessi o n trac k i n g i s di sc u ssed i n m o re detai l l ater o n .
A o rg.h i bern ate.S essi o n begi n s w h en th e fi rst c al l to getC u rrentSes s io n( ) i s m ade fo r th e c u rren t th read. I t i s
th en bo u n d by H i bern ate to th e c u rren t th read. W h en th e tran sac ti o n en ds, ei th er th ro u gh c o m m i t o r
ro l l bac k , H i bern ate au to m ati c al l y u n bi n ds th e o rg.h i bern ate.S essi o n fro m th e th read an d c l o ses i t fo r yo u . I f
1 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
yo u c al l getC u rrentSes s io n( ) agai n , yo u get a n ew o rg.h i bern ate.S essi o n an d c an start a n ew u n i t o f w o rk .
R el ated to th e u n i t o f w o rk sc o p e, sh o u l d th e H i bern ate o rg.h i bern ate.S essi o n be u sed to ex ec u te o n e o r

sev eral database o p erati o n s? T h e abo v e ex am p l e u ses o n e o rg.h i bern ate.S essi o n fo r o n e o p erati o n .
H o w ev er th i s i s p u re c o i n c i den c e; th e ex am p l e i s j u st n o t c o m p l ex en o u gh to sh o w an y o th er ap p ro ac h . T h e
sc o p e o f a H i bern ate o rg.h i bern ate.S essi o n i s fl ex i bl e bu t yo u sh o u l d n ev er desi gn yo u r ap p l i c ati o n to u se a
n ew H i bern ate o rg.h i bern ate.S essi o n fo r e v e ry database o p erati o n . E v en th o u gh i t i s u sed i n th e fo l l o w i n g
ex am p l es, c o n si der s e s s ion- p e r- op e ration an an ti - p attern . A real w eb ap p l i c ati o n i s sh o w n l ater i n th e
tu to ri al w h i c h w i l l h el p i l l u strate th i s.
S ee Ch ap ter 1 1 , Trans ac tions and C onc urre nc y fo r m o re i n fo rm ati o n abo u t tran sac ti o n h an dl i n g an d
dem arc ati o n . T h e p rev i o u s ex am p l e al so sk i p p ed an y erro r h an dl i n g an d ro l l bac k .
T o ru n th i s, w e w i l l m ak e u se o f th e M av en ex ec p l u gi n to c al l o u r c l ass w i th th e n ec essary c l assp ath setu p :

m v n ex ec : j av a - D ex ec . m ain C lass= " org . h ibern ate. tutorial. E v en tM an ag er" - D ex ec . arg s= " store"
N ote
Y o u m ay n eed to p erfo rm m v n c om p ile fi rst.
Y o u sh o u l d see H i bern ate starti n g u p an d, dep en di n g o n yo u r c o n fi gu rati o n , l o ts o f l o g o u tp u t. T o w ards th e

en d, th e fo l l o w i n g l i n e w i l l be di sp l ayed:
[ j av a] H ib ernate: ins ert into E V E NT S ( E V E NT _ D A T E , titl e, E V E NT _ I D ) v al u es ( ?, ?, ?)
T h i s i s th e I NSE R T ex ec u ted by H i bern ate.
T o l i st sto red ev en ts an o p ti o n i s added to th e m ai n m eth o d:
if ( args [ 0] . eq u al s ( " s to re" )) {

mgr. createA ndSto reE v ent( " M y E v ent" , new D ate( ));
}
el s e if ( args [ 0] . eq u al s ( " l is t" )) {
L is t ev ents = mgr. l is tE v ents ( );
f o r ( int i = 0; i < ev ents . s iz e( ); i+ + ) {
E v ent th eE v ent = ( E v ent) ev ents . get( i);
Sys tem. o u t. printl n(
" E v ent: " + th eE v ent. getT itl e( ) + " T ime: " + th eE v ent. getD ate( )
);
}
}
A n ew l is tE v ents ( ) meth o d is al s o added :
priv ate L is t l is tE v ents ( ) {

L is t res u l t = s es s io n. createQ u ery( " f ro m E v ent" ). l is t( );
retu rn res u l t;
}
H ere, w e are u si n g a H i bern ate Q u ery L an gu age (H Q L ) q u ery to l o ad al l ex i sti n g E v ent o bj ec ts fro m th e
database. H i bern ate w i l l gen erate th e ap p ro p ri ate S Q L , sen d i t to th e database an d p o p u l ate E v ent o bj ec ts
w i th th e data. Y o u c an c reate m o re c o m p l ex q u eri es w i th H Q L . S ee Ch ap ter 1 4 , H Q L : Th e H ib e rnate Q ue ry
L ang uag e fo r m o re i n fo rm ati o n .
N o w w e c an c al l o u r n ew fu n c ti o n al i ty, agai n u si n g th e M av en ex ec p l u gi n :
m v n ex ec : j av a - D ex ec . m ain C lass= " org . h ibern ate. tutorial. E v en tM an ag er" - D ex ec . arg s= " list"
1 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 . 2 . P art 2 - M ap p ing as s ociations

S o far w e h av e m ap p ed a si n gl e p ersi sten t en ti ty c l ass to a tabl e i n i so l ati o n . L et' s ex p an d o n th at a bi t an d
add so m e c l ass asso c i ati o n s. W e w i l l add p eo p l e to th e ap p l i c ati o n an d sto re a l i st o f ev en ts i n w h i c h th ey
p arti c i p ate.
1 . 2 . 1 . M appi ng th e P e rs on c l as s
T h e fi rst c u t o f th e P ers o n c l ass l o o k s l i k e th i s:
pack age o rg. h ib ernate. tu to rial . do main;
pu b l ic cl as s P ers o n {
priv ate L o ng id;

priv ate int age;
priv ate String f irs tname;
priv ate String l as tname;
pu b l ic P ers o n( ) {}
/ / A cces s o r meth o ds f o r al l pro perties , priv ate s etter f o r ' id'
S av e th i s to a fi l e n am ed src /m ain /j av a/org /h ibern ate/tutorial/d om ain /P erson . j av a
N ex t, c reate th e n ew m ap p i n g fi l e as src /m ain /resourc es/org /h ibern ate/tutorial/d om ain /P erson . h bm . x m l
< cl as s name=" P ers o n" tab l e=" P E R SO N" >

< id name=" id" co l u mn=" P E R SO N_ I D " >
< / id>
< pro perty name=" age" / >
< pro perty name=" f irs tname" / >
< pro perty name=" l as tname" / >
< / cl as s >
F i n al l y, add th e n ew m ap p i n g to H i bern ate' s c o n fi gu rati o n :
< mapping res o u rce=" ev ents / E v ent. h b m. x ml " / >

< mapping res o u rce=" ev ents / P ers o n. h b m. x ml " / >
Create an asso c i ati o n betw een th ese tw o en ti ti es. P erso n s c an p arti c i p ate i n ev en ts, an d ev en ts h av e
p arti c i p an ts. T h e desi gn q u esti o n s yo u h av e to deal w i th are: di rec ti o n al i ty, m u l ti p l i c i ty, an d c o l l ec ti o n
beh av i o r.
1 .2 .2 . A u ni d i re c ti onal S e t- b as e d as s oc i ati on
B y addi n g a c o l l ec ti o n o f ev en ts to th e P ers o n c l ass, yo u c an easi l y n av i gate to th e ev en ts fo r a p arti c u l ar

p erso n , w i th o u t ex ec u ti n g an ex p l i c i t q u ery - by c al l i n g P ers o n# getE v ents . M u l ti - v al u ed asso c i ati o n s are
rep resen ted i n H i bern ate by o n e o f th e J av a Co l l ec ti o n F ram ew o rk c o n trac ts; h ere w e c h o o se a j av a. u til . Set
bec au se th e c o l l ec ti o n w i l l n o t c o n tai n du p l i c ate el em en ts an d th e o rderi n g i s n o t rel ev an t to o u r ex am p l es:
1 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
priv ate Set ev ents = new H as h Set( );
pu b l ic Set getE v ents ( ) {

retu rn ev ents ;
}
pu b l ic v o id s etE v ents ( Set ev ents ) {

th is . ev ents = ev ents ;
}
}
B efo re m ap p i n g th i s asso c i ati o n , l et' s c o n si der th e o th er si de. W e c o u l d j u st k eep th i s u n i di rec ti o n al o r c reate

an o th er c o l l ec ti o n o n th e E v ent , i f w e w an ted to be abl e to n av i gate i t fro m bo th di rec ti o n s. T h i s i s n o t
n ec essary, fro m a fu n c ti o n al p ersp ec ti v e. Y o u c an al w ays ex ec u te an ex p l i c i t q u ery to retri ev e th e
p arti c i p an ts fo r a p arti c u l ar ev en t. T h i s i s a desi gn c h o i c e l eft to yo u , bu t w h at i s c l ear fro m th i s di sc u ssi o n i s
th e m u l ti p l i c i ty o f th e asso c i ati o n : " m an y" v al u ed o n bo th si des i s c al l ed a m any - to- m any asso c i ati o n . H en c e,
w e u se H i bern ate' s m an y- to - m an y m ap p i n g:
< cl as s name=" P ers o n" tab l e=" P E R SO N" >

< / id>
< pro perty name=" age" / >
< pro perty name=" f irs tname" / >
< pro perty name=" l as tname" / >
< s et name=" ev ents " tab l e=" P E R SO N_ E V E NT " >

< k ey co l u mn=" P E R SO N_ I D " / >
< many- to - many co l u mn=" E V E NT _ I D " cl as s =" E v ent" / >
< / s et>
< / cl as s >
H i bern ate su p p o rts a bro ad ran ge o f c o l l ec ti o n m ap p i n gs, a s et bei n g m o st c o m m o n . F o r a m an y- to - m an y

asso c i ati o n , o r n: m en ti ty rel ati o n sh i p , an asso c i ati o n tabl e i s req u i red. E ac h ro w i n th i s tabl e rep resen ts a
l i n k betw een a p erso n an d an ev en t. T h e tabl e n am e i s dec al red u si n g th e tab l e attri bu te o f th e s et el em en t.
T h e i den ti fi er c o l u m n n am e in th e asso c i ati o n , fo r th e p erso n si de, i s defi n ed w i th th e k ey el em en t, th e
c o lu m n n am e fo r th e ev en t' s si de w i th th e co l u mn attri bu te o f th e many- to - many. Y o u al so h av e to tel l
H i bern ate th e c l ass o f th e o bj ec ts i n yo u r c o l l ec ti o n (th e c l ass o n th e o th er si de o f th e c o l l ec ti o n o f
referen c es).
T h e database sc h em a fo r th i s m ap p i n g i s th erefo re:
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
| | | | _ _ _ _ _ _ _ _ _ _ _ _ _
| E V E NT S | | P E R SO N_ E V E NT | | |
| _ _ _ _ _ _ _ _ _ _ _ _ _ | | _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | | P E R SO N |
| | | | | _ _ _ _ _ _ _ _ _ _ _ _ _ |
| *E V E NT _ I D | < - - > | *E V E NT _ I D | | |
| E V E NT _ D A T E | | *P E R SO N_ I D | < - - > | *P E R SO N_ I D |
| T I T L E | | _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | | A G E |
| _ _ _ _ _ _ _ _ _ _ _ _ _ | | F I R ST NA M E |
| L A ST NA M E |
| _ _ _ _ _ _ _ _ _ _ _ _ _ |
1 .2 .3 . W ork i ng th e as s oc i ati on
2 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
N o w w e w i l l bri n g so m e p eo p l e an d ev en ts to geth er i n a n ew m eth o d i n E v entM anager:
priv ate v o id addP ers o nT o E v ent( L o ng pers o nI d, L o ng ev entI d) {

P ers o n aP ers o n = ( P ers o n) s es s io n. l o ad( P ers o n. cl as s , pers o nI d);

E v ent anE v ent = ( E v ent) s es s io n. l o ad( E v ent. cl as s , ev entI d);
aP ers o n. getE v ents ( ). add( anE v ent);

}
A fter l o adi n g a P ers o n an d an E v ent , si m p l y m o di fy th e c o l l ec ti o n u si n g th e n o rm al c o l l ec ti o n m eth o ds. T h ere

i s n o ex p l i c i t c al l to u pdate( ) o r s av e( ); H i bern ate au to m ati c al l y detec ts th at th e c o l l ec ti o n h as been m o di fi ed
an d n eeds to be u p dated. T h i s i s c al l ed autom atic d irty c h e c k ing . Y o u c an al so try i t by m o di fyi n g th e n am e
o r th e date p ro p erty o f an y o f yo u r o bj ec ts. A s l o n g as th ey are i n p e rs is te nt state, th at i s, bo u n d to a
p arti c u l ar H i bern ate o rg. h ib ernate. Ses s io n, H i bern ate m o n i to rs an y c h an ges an d ex ec u tes S Q L i n a w ri te-
beh i n d fash i o n . T h e p ro c ess o f syn c h ro n i z i n g th e m em o ry state w i th th e database, u su al l y o n l y at th e en d o f
a u n i t o f w o rk , i s c al l ed f lus h ing . I n o u r c o de, th e u n i t o f w o rk en ds w i th a c o m m i t, o r ro l l bac k , o f th e
database tran sac ti o n .
Y o u c an l o ad p erso n an d ev en t i n di fferen t u n i ts o f w o rk . O r yo u c an m o di fy an o bj ec t o u tsi de o f a

o rg. h ib ernate. Ses s io n, w h en i t i s n o t i n p ersi sten t state (i f i t w as p ersi sten t befo re, th i s state i s c al l ed
d e tac h e d ). Y o u c an ev en m o di fy a c o l l ec ti o n w h en i t i s detac h ed:
priv ate v o id addP ers o nT o E v ent( L o ng pers o nI d, L o ng ev entI d) {

P ers o n aP ers o n = ( P ers o n) s es s io n

. createQ u ery( " s el ect p f ro m P ers o n p l ef t j o in f etch p. ev ents w h ere p. id = : pid" )
. s etP arameter( " pid" , pers o nI d)
. u niq u eR es u l t( ); / / E ager f etch th e co l l ectio n s o w e can u s e it detach ed
E v ent anE v ent = ( E v ent) s es s io n. l o ad( E v ent. cl as s , ev entI d);
/ / E nd o f f irs t u nit o f w o rk
aP ers o n. getE v ents ( ). add( anE v ent); / / aP ers o n ( and its co l l ectio n) is detach ed
/ / B egin s eco nd u nit o f w o rk
Ses s io n s es s io n2 = H ib ernateU til . getSes s io nF acto ry( ). getC u rrentSes s io n( );

s es s io n2 . b eginT rans actio n( );
s es s io n2 . u pdate( aP ers o n); / / R eattach ment o f aP ers o n
s es s io n2 . getT rans actio n( ). co mmit( );

}
T h e c al l to u pdate m ak es a detac h ed o bj ec t p ersi sten t agai n by bi n di n g i t to a n ew u n i t o f w o rk , so an y

m o di fi c ati o n s yo u m ade to i t w h i l e detac h ed c an be sav ed to th e database. T h i s i n c l u des an y m o di fi c ati o n s
(addi ti o n s/del eti o n s) yo u m ade to a c o l l ec ti o n o f th at en ti ty o bj ec t.
T h i s i s n o t m u c h u se i n o u r ex am p l e, bu t i t i s an i m p o rtan t c o n c ep t yo u c an i n c o rp o rate i n to yo u r o w n
ap p l i c ati o n . Co m p l ete th i s ex erc i se by addi n g a n ew ac ti o n to th e m ai n m eth o d o f th e E v entM anager an d c al l i t
fro m th e c o m m an d l i n e. I f yo u n eed th e i den ti fi ers o f a p erso n an d an ev en t - th e s av e( ) m eth o d retu rn s i t
(yo u m i gh t h av e to m o di fy so m e o f th e p rev i o u s m eth o ds to retu rn th at i den ti fi er):
2 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
el s e if ( args [ 0] . eq u al s ( " addpers o nto ev ent" )) {

L o ng ev entI d = mgr. createA ndSto reE v ent( " M y E v ent" , new D ate( ));
L o ng pers o nI d = mgr. createA ndSto reP ers o n( " F o o " , " B ar" );
mgr. addP ers o nT o E v ent( pers o nI d, ev entI d);
Sys tem. o u t. printl n( " A dded pers o n " + pers o nI d + " to ev ent " + ev entI d);
}
T h i s i s an ex am p l e o f an asso c i ati o n betw een tw o eq u al l y i m p o rtan t c l asses : tw o en ti ti es. A s m en ti o n ed

earl i er, th ere are o th er c l asses an d typ es i n a typ i c al m o del , u su al l y " l ess i m p o rtan t" . S o m e yo u h av e
al ready seen , l i k e an int o r a j av a. l ang. String. W e c al l th ese c l asses v alue ty p e s , an d th ei r i n stan c es d e p e nd o n
a p arti c u l ar en ti ty. I n stan c es o f th ese typ es do n o t h av e th ei r o w n i den ti ty, n o r are th ey sh ared betw een
en ti ti es. T w o p erso n s do n o t referen c e th e sam e f irs tname o bj ec t, ev en i f th ey h av e th e sam e fi rst n am e.
V al u e typ es c an n o t o n l y be fo u n d i n th e J D K , bu t yo u c an al so w ri te dep en den t c l asses yo u rsel f su c h as an
A ddres s o r M o netaryA mo u nt c l ass. I n fac t, i n a H i bern ate ap p l i c ati o n al l J D K c l asses are c o n si dered v al u e typ es.
Y o u c an al so desi gn a c o l l ec ti o n o f v al u e typ es. T h i s i s c o n c ep tu al l y di fferen t fro m a c o l l ec ti o n o f referen c es to

o th er en ti ti es, bu t l o o k s al m o st th e sam e i n J av a.
1 . 2 . 4 . C ol l e c ti on of v al u e s
L et' s add a c o l l ec ti o n o f em ai l addresses to th e P ers o n en ti ty. T h i s w i l l be rep resen ted as a j av a. u til . Set o f
j av a. l ang. String i n stan c es:
priv ate Set email A ddres s es = new H as h Set( );
pu b l ic Set getE mail A ddres s es ( ) {

retu rn email A ddres s es ;
}
pu b l ic v o id s etE mail A ddres s es ( Set email A ddres s es ) {

th is . email A ddres s es = email A ddres s es ;
}
T h e m ap p i n g o f th i s Set i s as fo l l o w s:
< s et name=" email A ddres s es " tab l e=" P E R SO N_ E M A I L _ A D D R " >

< k ey co l u mn=" P E R SO N_ I D " / >
< el ement type=" s tring" co l u mn=" E M A I L _ A D D R " / >
< / s et>
T h e di fferen c e c o m p ared w i th th e earl i er m ap p i n g i s th e u se o f th e el ement p art w h i c h tel l s H i bern ate th at th e

c o l l ec ti o n do es n o t c o n tai n referen c es to an o th er en ti ty, bu t i s rath er a c o l l ec ti o n w h o se el em en ts are v al u es
typ es, h ere sp ec i fi c al l y o f typ e s tring . T h e l o w erc ase n am e tel l s yo u i t i s a H i bern ate m ap p i n g
typ e/c o n v erter. A gai n th e tab l e attri bu te o f th e s et el em en t determ i n es th e tabl e n am e fo r th e c o l l ec ti o n . T h e
k ey el em en t defi n es th e fo rei gn - k ey c o l u m n n am e i n th e c o l l ec ti o n tabl e. T h e co l u mn attri bu te i n th e el ement
el em en t defi n es th e c o l u m n n am e w h ere th e em ai l address v al u es w i l l ac tu al l y be sto red.
H ere i s th e u p dated sc h em a:
2 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
| | | | _ _ _ _ _ _ _ _ _ _ _ _ _
| E V E NT S | | P E R SO N_ E V E NT | | | _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
| _ _ _ _ _ _ _ _ _ _ _ _ _ | | _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | | P E R SO N | | |
| | | | | _ _ _ _ _ _ _ _ _ _ _ _ _ | | P E R SO N_ E M A I L _ A D D R |
| *E V E NT _ I D | < - - > | *E V E NT _ I D | | | | _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
| E V E NT _ D A T E | | *P E R SO N_ I D | < - - > | *P E R SO N_ I D | < - - >| *P E R SO N_ I D |
| T I T L E | | _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | | A G E | | *E M A I L _ A D D R |
| _ _ _ _ _ _ _ _ _ _ _ _ _ | | F I R ST NA M E | | _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
| L A ST NA M E |
| _ _ _ _ _ _ _ _ _ _ _ _ _ |
Y o u c an see th at th e p ri m ary k ey o f th e c o l l ec ti o n tabl e i s i n fac t a c o m p o si te k ey th at u ses bo th c o l u m n s.

T h i s al so i m p l i es th at th ere c an n o t be du p l i c ate em ai l addresses p er p erso n , w h i c h i s ex ac tl y th e sem an ti c s
w e n eed fo r a set i n J av a.
Y o u c an n o w try to add el em en ts to th i s c o l l ec ti o n , j u st l i k e w e di d befo re by l i n k i n g p erso n s an d ev en ts. I t i s

th e sam e c o de i n J av a:
priv ate v o id addE mail T o P ers o n( L o ng pers o nI d, String email A ddres s ) {

P ers o n aP ers o n = ( P ers o n) s es s io n. l o ad( P ers o n. cl as s , pers o nI d);

/ / adding to th e email A ddres s co l l ectio n migh t trigger a l az y l o ad o f th e co l l ectio n
aP ers o n. getE mail A ddres s es ( ). add( email A ddres s );

}
T h i s ti m e w e di d n o t u se a f e tc h q u ery to i n i ti al i z e th e c o l l ec ti o n . M o n i to r th e S Q L l o g an d try to o p ti m i z e th i s
w i th an eager fetc h .
1 . 2 . 5 . B i - d i re c ti onal as s oc i ati ons
N ex t yo u w i l l m ap a bi - di rec ti o n al asso c i ati o n . Y o u w i l l m ak e th e asso c i ati o n betw een p erso n an d ev en t w o rk

fro m bo th si des i n J av a. T h e database sc h em a do es n o t c h an ge, so yo u w i l l sti l l h av e m an y- to - m an y
m u l ti p l i c i ty.
N ote
A rel ati o n al database i s m o re fl ex i bl e th an a n etw o rk p ro gram m i n g l an gu age, i n th at i t do es n o t
n eed a n av i gati o n di rec ti o n ; data c an be v i ew ed an d retri ev ed i n an y p o ssi bl e w ay.
F i rst, add a c o l l ec ti o n o f p arti c i p an ts to th e E v ent c l ass:
priv ate Set participants = new H as h Set( );
pu b l ic Set getP articipants ( ) {

retu rn participants ;
}
pu b l ic v o id s etP articipants ( Set participants ) {

th is . participants = participants ;
}
N o w m ap th i s si de o f th e asso c i ati o n i n E v ent. h b m. x ml .
2 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< s et name=" participants " tab l e=" P E R SO N_ E V E NT " inv ers e=" tru e" >
< k ey co l u mn=" E V E NT _ I D " / >
< many- to - many co l u mn=" P E R SO N_ I D " cl as s =" ev ents . P ers o n" / >
< / s et>
T h ese are n o rm al s et m ap p i n gs i n bo th m ap p i n g do c u m en ts. N o ti c e th at th e c o l u m n n am es i n k ey an d

many- to - many sw ap in bo th m ap p i n g do c u m en ts. T h e m o st i m p o rtan t addi ti o n h ere i s th e inv ers e=" tru e"
attri bu te i n th e s et el em en t o f th e E v ent ' s c o l l ec ti o n m ap p i n g.
W h at th i s m ean s i s th at H i bern ate sh o u l d tak e th e o th er si de, th e P ers o n c l ass, w h en i t n eeds to fi n d o u t

i n fo rm ati o n abo u t th e l i n k betw een th e tw o . T h i s w i l l be a l o t easi er to u n derstan d o n c e yo u see h o w th e
bi - di rec ti o n al l i n k betw een o u r tw o en ti ti es i s c reated.
1 .2 .6 . W ork i ng b i - d i re c ti onal l i nk s
F i rst, k eep i n m i n d th at H i bern ate do es n o t affec t n o rm al J av a sem an ti c s. H o w di d w e c reate a l i n k betw een

a P ers o n an d an E v ent i n th e u n i di rec ti o n al ex am p l e? Y o u add an i n stan c e o f E v ent to th e c o l l ec ti o n o f ev en t
referen c es, o f an i n stan c e o f P ers o n. I f yo u w an t to m ak e th i s l i n k bi - di rec ti o n al , yo u h av e to do th e sam e o n
th e o th er si de by addi n g a P ers o n referen c e to th e c o l l ec ti o n i n an E v ent . T h i s p ro c ess o f " setti n g th e l i n k o n
bo th si des" i s abso l u tel y n ec essary w i th bi - di rec ti o n al l i n k s.
M an y dev el o p ers p ro gram defen si v el y an d c reate l i n k m an agem en t m eth o ds to c o rrec tl y set bo th si des (fo r
ex am p l e, i n P ers o n):
pro tected Set getE v ents ( ) {

retu rn ev ents ;
}
pro tected v o id s etE v ents ( Set ev ents ) {

th is . ev ents = ev ents ;
}
pu b l ic v o id addT o E v ent( E v ent ev ent) {

th is . getE v ents ( ). add( ev ent);
ev ent. getP articipants ( ). add( th is );
}
pu b l ic v o id remo v eF ro mE v ent( E v ent ev ent) {

th is . getE v ents ( ). remo v e( ev ent);
ev ent. getP articipants ( ). remo v e( th is );
}
T h e get an d set m eth o ds fo r th e c o l l ec ti o n are n o w p ro tec ted. T h i s al l o w s c l asses i n th e sam e p ac k age an d

su bc l asses to sti l l ac c ess th e m eth o ds, bu t p rev en ts ev erybo dy el se fro m al teri n g th e c o l l ec ti o n s di rec tl y.
R ep eat th e step s fo r th e c o l l ec ti o n o n th e o th er si de.
W h at abo u t th e inv ers e m ap p i n g attri bu te? F o r yo u , an d fo r J av a, a bi - di rec ti o n al l i n k i s si m p l y a m atter o f

setti n g th e referen c es o n bo th si des c o rrec tl y. H i bern ate, h o w ev er, do es n o t h av e en o u gh i n fo rm ati o n to
c o rrec tl y arran ge S Q L I NSE R T an d U P D A T E statem en ts (to av o i d c o n strai n t v i o l ati o n s). M ak i n g o n e si de o f th e
asso c i ati o n inv ers e tel l s H i bern ate to c o n si der i t a m irror o f th e o th er si de. T h at i s al l th at i s n ec essary fo r
H i bern ate to reso l v e an y i ssu es th at ari se w h en tran sfo rm i n g a di rec ti o n al n av i gati o n m o del to a S Q L
database sc h em a. T h e ru l es are strai gh tfo rw ard: al l bi - di rec ti o n al asso c i ati o n s n eed o n e si de as inv ers e . I n a
o n e- to - m an y asso c i ati o n i t h as to be th e m an y- si de, an d i n m an y- to - m an y asso c i ati o n yo u c an sel ec t ei th er
si de.
1 . 3 . P art 3 - T h e E v entM anag er w eb ap p l ication

A H i bern ate w eb ap p l i c ati o n u ses Ses s io n an d T rans actio n al m o st l i k e a stan dal o n e ap p l i c ati o n . H o w ev er,
so m e c o m m o n p attern s are u sefu l . Y o u c an n o w w ri te an E v entM anagerServ l et . T h i s serv l et c an l i st al l ev en ts
2 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
sto red i n th e database, an d i t p ro v i des an H T M L fo rm to en ter n ew ev en ts.
1 .3 .1 . W ri ti ng th e b as i c s e rv l e t
F i rst w e n eed c reate o u r basi c p ro c essi n g serv l et. S i n c e o u r serv l et o n l y h an dl es H T T P G E T req u ests, w e w i l l
o n ly im p l em en t th e do G et( ) m eth o d:
pack age o rg. h ib ernate. tu to rial . w eb ;
/ / I mpo rts
pu b l ic cl as s E v entM anagerServ l et ex tends H ttpServ l et {
pro tected v o id do G et(

H ttpServ l etR eq u es t req u es t,
H ttpServ l etR es po ns e res po ns e) th ro w s Serv l etE x ceptio n, I O E x ceptio n {
Simpl eD ateF o rmat dateF o rmatter = new Simpl eD ateF o rmat( " dd. M M . yyyy" );
try {
/ / B egin u nit o f w o rk
H ib ernateU til . getSes s io nF acto ry( ). getC u rrentSes s io n( ). b eginT rans actio n( );
/ / P ro ces s req u es t and render page. . .
/ / E nd u nit o f w o rk
H ib ernateU til . getSes s io nF acto ry( ). getC u rrentSes s io n( ). getT rans actio n( ). co mmit( );
}
catch ( E x ceptio n ex ) {
H ib ernateU til . getSes s io nF acto ry( ). getC u rrentSes s io n( ). getT rans actio n( ). ro l l b ack ( );
if ( Serv l etE x ceptio n. cl as s . is I ns tance( ex ) ) {
th ro w ( Serv l etE x ceptio n ) ex ;
}
el s e {
th ro w new Serv l etE x ceptio n( ex );
}
}
}
S av e th i s serv l et as src /m ain /j av a/org /h ibern ate/tutorial/web/E v en tM an ag erS erv let. j av a
T h e p attern ap p l i ed h ere i s c al l ed s e s s ion- p e r- re q ue s t. W h en a req u est h i ts th e serv l et, a n ew H i bern ate

Ses s io n i s o p en ed th ro u gh th e fi rst c al l to getC u rrentSes s io n( ) o n th e Ses s io nF acto ry. A database tran sac ti o n i s
th en started. A l l data ac c ess o c c u rs i n si de a tran sac ti o n i rresp ec ti v e o f w h eth er th e data i s read o r w ri tten .
D o n o t u se th e au to - c o m m i t m o de i n ap p l i c ati o n s.
D o not u se a n ew H i bern ate Ses s io n fo r ev ery database o p erati o n . U se o n e H i bern ate Ses s io n th at i s sc o p ed
to th e w h o l e req u est. U se getC u rrentSes s io n( ), so th at i t i s au to m ati c al l y bo u n d to th e c u rren t J av a th read.
N ex t, th e p o ssi bl e ac ti o n s o f th e req u est are p ro c essed an d th e resp o n se H T M L i s ren dered. W e w i l l get to

th at p art so o n .
F i n al l y, th e u n i t o f w o rk en ds w h en p ro c essi n g an d ren deri n g are c o m p l ete. I f an y p ro bl em s o c c u rred du ri n g

p ro c essi n g o r ren deri n g, an ex c ep ti o n w i l l be th ro w n an d th e database tran sac ti o n ro l l ed bac k . T h i s
c o m p l etes th e s es s io n- per- req u es t p attern . I n stead o f th e tran sac ti o n dem arc ati o n c o de i n ev ery serv l et, yo u
c o u l d al so w ri te a serv l et fi l ter. S ee th e H i bern ate w ebsi te an d W i k i fo r m o re i n fo rm ati o n abo u t th i s p attern
c al l ed O p e n S e s s ion in V ie w . Y o u w i l l n eed i t as so o n as yo u c o n si der ren deri n g yo u r v i ew i n J S P , n o t i n a
serv l et.
2 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 . 3 . 2 . P roc e s s i ng and re nd e ri ng
N o w yo u c an i m p l em en t th e p ro c essi n g o f th e req u est an d th e ren deri n g o f th e p age.
/ / W rite H T M L h eader
P rintW riter o u t = res po ns e. getW riter( );
o u t. printl n( " < h tml >< h ead>< titl e>E v ent M anager< / titl e>< / h ead>" );
/ / H andl e actio ns
if ( " s to re" . eq u al s ( req u es t. getP arameter( " actio n" )) ) {
String ev entT itl e = req u es t. getP arameter( " ev entT itl e" );
String ev entD ate = req u es t. getP arameter( " ev entD ate" );
if ( " " . eq u al s ( ev entT itl e) | | " " . eq u al s ( ev entD ate) ) {

o u t. printl n( " P l eas e enter ev ent titl e and date. " );
}
el s e {
createA ndSto reE v ent( ev entT itl e, dateF o rmatter. pars e( ev entD ate));
o u t. printl n( " A dded ev ent. " );
}
}
/ / P rint page
printE v entF o rm( o u t);
l is tE v ents ( o u t, dateF o rmatter);
/ / W rite H T M L f o o ter
o u t. printl n( " < / h tml >" );
o u t. f l u s h ( );
o u t. cl o s e( );
T h i s c o di n g styl e, w i th a m i x o f J av a an d H T M L , w o u l d n o t sc al e i n a m o re c o m p l ex ap p l i c ati o n - k eep i n m i n d

th at w e are o n l y i l l u strati n g basi c H i bern ate c o n c ep ts i n th i s tu to ri al . T h e c o de p ri n ts an H T M L h eader an d a
fo o ter. I n si de th i s p age, an H T M L fo rm fo r ev en t en try an d a l i st o f al l ev en ts i n th e database are p ri n ted.
T h e fi rst m eth o d i s tri v i al an d o n l y o u tp u ts H T M L :
priv ate v o id printE v entF o rm( P rintW riter o u t) {

o u t. printl n( " < h 2 >A dd new ev ent: < / h 2 >" );
o u t. printl n( " < f o rm>" );
o u t. printl n( " T itl e: < inpu t name=' ev entT itl e' l ength =' 50' / >" );
o u t. printl n( " D ate ( e. g. 2 4. 12 . 2 009 ): < inpu t name=' ev entD ate' l ength =' 10' / >" );
o u t. printl n( " < inpu t type=' s u b mit' name=' actio n' v al u e=' s to re' / >" );
o u t. printl n( " < / f o rm>" );
}
T h e l is tE v ents ( ) m eth o d u ses th e H i bern ate Ses s io n bo u n d to th e c u rren t th read to ex ec u te a q u ery:
2 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
priv ate v o id l is tE v ents ( P rintW riter o u t, Simpl eD ateF o rmat dateF o rmatter) {
L is t res u l t = H ib ernateU til . getSes s io nF acto ry( )

. getC u rrentSes s io n( ). createC riteria( E v ent. cl as s ). l is t( );
if ( res u l t. s iz e( ) > 0) {
o u t. printl n( " < h 2 >E v ents in datab as e: < / h 2 >" );
o u t. printl n( " < tab l e b o rder=' 1' >" );
o u t. printl n( " < tr>" );
o u t. printl n( " < th >E v ent titl e< / th >" );
o u t. printl n( " < th >E v ent date< / th >" );
o u t. printl n( " < / tr>" );
I terato r it = res u l t. iterato r( );
w h il e ( it. h as Nex t( )) {
E v ent ev ent = ( E v ent) it. nex t( );
o u t. printl n( " < tr>" );
o u t. printl n( " < td>" + ev ent. getT itl e( ) + " < / td>" );
o u t. printl n( " < td>" + dateF o rmatter. f o rmat( ev ent. getD ate( )) + " < / td>" );
o u t. printl n( " < / tr>" );
}
o u t. printl n( " < / tab l e>" );
}
}
F i n al l y, th e s to re ac ti o n i s di sp atc h ed to th e createA ndSto reE v ent( ) m eth o d, w h i c h al so u ses th e Ses s io n o f th e

c u rren t th read:
pro tected v o id createA ndSto reE v ent( String titl e, D ate th eD ate) {
E v ent th eE v ent = new E v ent( );
th eE v ent. s etT itl e( titl e);
th eE v ent. s etD ate( th eD ate);
H ib ernateU til . getSes s io nF acto ry( )

. getC u rrentSes s io n( ). s av e( th eE v ent);
}
T h e serv l et i s n o w c o m p l ete. A req u est to th e serv l et w i l l be p ro c essed i n a si n gl e Ses s io n an d T rans actio n. A s

earl i er i n th e stan dal o n e ap p l i c ati o n , H i bern ate c an au to m ati c al l y bi n d th ese o bj ec ts to th e c u rren t th read o f
ex ec u ti o n . T h i s gi v es yo u th e freedo m to l ayer yo u r c o de an d ac c ess th e Ses s io nF acto ry i n an y w ay yo u l i k e.
U su al l y yo u w o u l d u se a m o re so p h i sti c ated desi gn an d m o v e th e data ac c ess c o de i n to data ac c ess o bj ec ts
(th e D A O p attern ). S ee th e H i bern ate W i k i fo r m o re ex am p l es.
1 . 3 . 3 . D e pl oy i ng and te s ti ng
T o dep l o y th i s ap p l i c ati o n fo r testi n g w e m u st c reate a W eb A R c h i v e (W A R ). F i rst w e m u st defi n e th e W A R

desc ri p to r as src /m ain /webap p /W E B - I N F /web. x m l
2 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< ?x ml v ers io n=" 1. 0" enco ding=" U T F - 8" ?>

< w eb - app v ers io n=" 2 . 4"
x ml ns =" h ttp: / / j av a. s u n. co m/ x ml / ns / j 2 ee"
x ml ns : x s i=" h ttp: / / w w w . w 3. o rg/ 2 001/ X M L Sch ema- ins tance"
x s i: s ch emaL o catio n=" h ttp: / / j av a. s u n. co m/ x ml / ns / j 2 ee h ttp: / / j av a. s u n. co m/ x ml / ns / j 2 ee/ w eb - app_ 2 _ 4. x s d" >
< s erv l et>

< s erv l etname>E v ent M anager< / s erv l etname>
< s erv l et- cl as s >o rg. h ib ernate. tu to rial . w eb . E v entM anagerServ l et< / s erv l et- cl as s >
< / s erv l et>
< s erv l et- mapping>

< s erv l etname>E v ent M anager< / s erv l etname>
/ ev entmanager
< / s erv l et- mapping>
< / w eb - app>
T o bu i l d an d dep l o y c al l mv n pack age i n yo u r p ro j ec t di rec to ry an d c o p y th e h ibern ate- tutorial. war fi l e i n to

yo u r T o m c at webap p s di rec to ry.
N ote
I f yo u do n o t h av e T o m c at i n stal l ed, do w n l o ad i t fro m h ttp ://to m c at.ap ac h e.o rg/ an d fo l l o w th e
i n stal l ati o n i n stru c ti o n s. O u r ap p l i c ati o n req u i res n o c h an ges to th e stan dard T o m c at
c o n fi gu rati o n .
O n c e dep l o yed an d T o m c at is ru n n i n g, ac c ess th e ap p l i c ati o n at

h ttp: / / l o cal h o s t: 8080/ h ib ernate- tu to rial / ev entmanager. M ak e su re yo u w atc h th e T o m c at l o g to see H i bern ate
i n i ti al i z e w h en th e fi rst req u est h i ts yo u r serv l et (th e stati c i n i ti al i z er i n H ib ernateU til i s c al l ed) an d to get th e
detai l ed o u tp u t i f an y ex c ep ti o n s o c c u rs.
1 . 4 . S ummary
T h i s tu to ri al c o v ered th e basi c s o f w ri ti n g a si m p l e stan dal o n e H i bern ate ap p l i c ati o n an d a sm al l w eb
ap p l i c ati o n . M o re tu to ri al s are av ai l abl e fro m th e H i bern ate w ebsi te.
C h ap ter 2 . A rch itecture

2.1 . O v erv i ew
2.2. I n stan c e states
2.3 . J M X I n tegrati o n
2.4 . J CA S u p p o rt
2.5 . Co n tex tu al sessi o n s
2 . 1 . O v erv iew
T h e di agram bel o w p ro v i des a h i gh - l ev el v i ew o f th e H i bern ate arc h i tec tu re:
W e do n o t h av e th e sc o p e i n th i s do c u m en t to p ro v i de a m o re detai l ed v i ew o f al l th e ru n ti m e arc h i tec tu res

av ai l abl e; H i bern ate i s fl ex i bl e an d su p p o rts sev eral di fferen t ap p ro ac h es. W e w i l l , h o w ev er, sh o w th e tw o
ex trem es: " m i n i m al " arc h i tec tu re an d " c o m p reh en si v e" arc h i tec tu re.
T h i s n ex t di agram i l l u strates h o w H i bern ate u ti l i z es database an d c o n fi gu rati o n data to p ro v i de p ersi sten c e

serv i c es, an d p ersi sten t o bj ec ts, to th e ap p l i c ati o n .
2 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h e " m i n i m al " arc h i tec tu re h as th e ap p l i c ati o n p ro v i de i ts o w n J D B C c o n n ec ti o n s an d m an age i ts o w n

tran sac ti o n s. T h i s ap p ro ac h u ses a m i n i m al su bset o f H i bern ate' s A P I s:
T h e " c o m p reh en si v e" arc h i tec tu re abstrac ts th e ap p l i c ati o n aw ay fro m th e u n derl yi n g J D B C/J T A A P I s an d
al l o w s H i bern ate to m an age th e detai l s.
H ere are so m e defi n i ti o n s o f th e o bj ec ts dep i c ted i n th e di agram s:
S essi o n F ac to ry (o rg. h ib ernate. Ses s io nF acto ry)

A th readsafe, i m m u tabl e c ac h e o f c o m p i l ed m ap p i n gs fo r a si n gl e database. A fac to ry fo r Ses s io n an d a
c l i en t o f C o nnectio nP ro v ider, Ses s io nF acto ry c an h o l d an o p ti o n al (sec o n d- l ev el ) c ac h e o f data th at i s
reu sabl e betw een tran sac ti o n s at a p ro c ess, o r c l u ster, l ev el .
S essi o n (o rg. h ib ernate. Ses s io n)

A si n gl e- th readed, sh o rt- l i v ed o bj ec t rep resen ti n g a c o n v ersati o n betw een th e ap p l i c ati o n an d th e
p ersi sten t sto re. I t w rap s a J D B C c o n n ec ti o n an d i s a fac to ry fo r T rans actio n. Ses s io n h o l ds a m an dato ry
fi rst- l ev el c ac h e o f p ersi sten t o bj ec ts th at are u sed w h en n av i gati n g th e o bj ec t grap h o r lo o k in g u p
o bj ec ts by i den ti fi er.
P ersi sten t o bj ec ts an d c o l l ec ti o n s
S h o rt- l i v ed, si n gl e th readed o bj ec ts c o n tai n i n g p ersi sten t state an d bu si n ess fu n c ti o n . T h ese c an be
o rdi n ary J av aB ean s/P O J O s. T h ey are asso c i ated w i th ex ac tl y o n e Ses s io n. O n c e th e Ses s io n i s c l o sed, th ey
w i l l be detac h ed an d free to u se i n an y ap p l i c ati o n l ayer (fo r ex am p l e, di rec tl y as data tran sfer o bj ec ts to
an d fro m p resen tati o n ).
T ran si en t an d detac h ed o bj ec ts an d c o l l ec ti o n s
I n stan c es o f p ersi sten t c l asses th at are n o t c u rren tl y asso c i ated w i th a Ses s io n. T h ey m ay h av e been
i n stan ti ated by th e ap p l i c ati o n an d n o t yet p ersi sted, o r th ey m ay h av e been i n stan ti ated by a c l o sed
Ses s io n.
T ran sac ti o n (o rg. h ib ernate. T rans actio n)

(O p ti o n al ) A si n gl e- th readed, sh o rt- l i v ed o bj ec t u sed by th e ap p l i c ati o n to sp ec i fy ato m i c u n i ts o f w o rk . I t
abstrac ts th e ap p l i c ati o n fro m th e u n derl yi n g J D B C, J T A o r CO R B A tran sac ti o n . A Ses s io n m i gh t sp an
sev eral T rans actio ns i n so m e c ases. H o w ev er, tran sac ti o n dem arc ati o n , ei th er u si n g th e u n derl yi n g A P I o r
T rans actio n, i s n ev er o p ti o n al .
Co n n ec ti o n P ro v i der (o rg. h ib ernate. co nnectio n. C o nnectio nP ro v ider)

(O p ti o n al ) A fac to ry fo r, an d p o o l o f, J D B C c o n n ec ti o n s. I t abstrac ts th e ap p l i c ati o n fro m u n derl yi n g
D atas o u rce o r D riv erM anager. I t i s n o t ex p o sed to ap p l i c ati o n , bu t i t c an be ex ten ded an d/o r i m p l em en ted
by th e dev el o p er.
T ran sac ti o n F ac to ry (o rg. h ib ernate. T rans actio nF acto ry)

(O p ti o n al ) A fac to ry fo r T rans actio n i n stan c es. I t i s n o t ex p o sed to th e ap p l i c ati o n , bu t i t c an be ex ten ded
an d/o r i m p l em en ted by th e dev el o p er.
E x te ns ion I nte rf ac e s
H i bern ate o ffers a ran ge o f o p ti o n al ex ten si o n i n terfac es yo u c an i m p l em en t to c u sto m i z e th e beh av i o r o f
yo u r p ersi sten c e l ayer. S ee th e A P I do c u m en tati o n fo r detai l s.
G i v en a " m i n i m al " arc h i tec tu re, th e ap p l i c ati o n byp asses th e T rans actio n/T rans actio nF acto ry an d/o r
C o nnectio nP ro v ider A P I s to c o m m u n i c ate w i th J T A o r J D B C di rec tl y.
2 . 2 . I ns tance s tates
A n i n stan c e o f a p ersi sten t c l ass c an be i n o n e o f th ree di fferen t states. T h ese states are defi n ed i n rel ati o n to
a p e rs is te nc e c onte x t. T h e H i bern ate Ses s io n o bj ec t i s th e p ersi sten c e c o n tex t. T h e th ree di fferen t states are
as fo l l o w s:
tran si en t
T h e i n stan c e i s n o t asso c i ated w i th an y p ersi sten c e c o n tex t. I t h as n o p ersi sten t i den ti ty o r p ri m ary k ey
2 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
v al u e.
p ersi sten t
T h e i n stan c e i s c u rren tl y asso c i ated w i th a p ersi sten c e c o n tex t. I t h as a p ersi sten t i den ti ty (p ri m ary k ey
v al u e) an d c an h av e a c o rresp o n di n g ro w i n th e database. F o r a p arti c u l ar p ersi sten c e c o n tex t, H i bern ate
g uarante e s th at p ersi sten t i den ti ty i s eq u i v al en t to J av a i den ti ty i n rel ati o n to th e i n - m em o ry l o c ati o n o f
th e o bj ec t.
detac h ed
T h e i n stan c e w as o n c e asso c i ated w i th a p ersi sten c e c o n tex t, bu t th at c o n tex t w as c l o sed, o r th e i n stan c e
w as seri al i z ed to an o th er p ro c ess. I t h as a p ersi sten t i den ti ty an d c an h av e a c o rresp o n di n g ro w i n th e
database. F o r detac h ed i n stan c es, H i bern ate do es n o t gu aran tee th e rel ati o n sh i p betw een p ersi sten t
i den ti ty an d J av a i den ti ty.
2 .3 . J M X I nteg ration
J M X i s th e J 2E E stan dard fo r th e m an agem en t o f J av a c o m p o n en ts. H i bern ate c an be m an aged v i a a J M X
stan dard serv i c e. A N M B ean i m p l em en tati o n i s p ro v i ded i n th e di stri bu ti o n : o rg. h ib ernate. j mx . H ib ernateServ ice .
F o r an ex am p l e o f h o w to dep l o y H i bern ate as a J M X serv i c e o n th e J B o ss A p p l i c ati o n S erv er, p l ease see th e

J B o ss U ser G u i de. J B o ss A S al so p ro v i des th ese ben efi ts i f yo u dep l o y u si n g J M X :
S e s s ion M anag e m e nt: th e H i bern ate Ses s io n' s l i fe c yc l e c an be au to m ati c al l y bo u n d to th e sc o p e o f a J T A

tran sac ti o n . T h i s m ean s th at yo u n o l o n ger h av e to m an u al l y o p en an d c l o se th e Ses s io n; th i s bec o m es
th e j o b o f a J B o ss E J B i n terc ep to r. Y o u al so do n o t h av e to w o rry abo u t tran sac ti o n dem arc ati o n i n yo u r
c o de (i f yo u w o u l d l i k e to w ri te a p o rtabl e p ersi sten c e l ayer u se th e o p ti o n al H i bern ate T rans actio n A P I fo r
th i s). Y o u c al l th e H ib ernateC o ntex t to ac c ess a Ses s io n.
H A R d e p loy m e nt: th e H i bern ate J M X serv i c e i s dep l o yed u si n g a J B o ss serv i c e dep l o ym en t desc ri p to r i n
an E A R an d/o r S A R fi l e, as i t su p p o rts al l th e u su al c o n fi gu rati o n o p ti o n s o f a H i bern ate Ses s io nF acto ry.
H o w ev er, yo u sti l l n eed to n am e al l yo u r m ap p i n g fi l es i n th e dep l o ym en t desc ri p to r. I f yo u u se th e
o p ti o n al H A R dep l o ym en t, J B o ss w i l l au to m ati c al l y detec t al l m ap p i n g fi l es i n yo u r H A R fi l e.
Co n su l t th e J B o ss A S u ser gu i de fo r m o re i n fo rm ati o n abo u t th ese o p ti o n s.
A n o th er featu re av ai l abl e as a J M X serv i c e i s ru n ti m e H i bern ate stati sti c s. S ee S ec ti o n 3 .4 .6 , “ H i bern ate

stati sti c s” fo r m o re i n fo rm ati o n .
2 .4 . J C A S up p ort
H i bern ate c an al so be c o n fi gu red as a J CA c o n n ec to r. P l ease see th e w ebsi te fo r m o re i n fo rm ati o n . P l ease
n o te, h o w ev er, th at at th i s stage H i bern ate J CA su p p o rt i s u n der dev el o p m en t.
2 . 5 . C ontex tual s es s ions

M o st ap p l i c ati o n s u si n g H i bern ate n eed so m e fo rm o f " c o n tex tu al " sessi o n , w h ere a gi v en sessi o n i s i n effec t
th ro u gh o u t th e sc o p e o f a gi v en c o n tex t. H o w ev er, ac ro ss ap p l i c ati o n s th e defi n i ti o n o f w h at c o n sti tu tes a
c o n tex t i s typ i c al l y di fferen t; di fferen t c o n tex ts defi n e di fferen t sc o p es to th e n o ti o n o f c u rren t. A p p l i c ati o n s
u si n g H i bern ate p ri o r to v ersi o n 3 .0 ten ded to u ti l i z e ei th er h o m e- gro w n T h readL o cal - based c o n tex tu al
sessi o n s, h el p er c l asses su c h as H ib ernateU til , o r u ti l i z ed th i rd- p arty fram ew o rk s, su c h as S p ri n g o r P i c o ,
w h i c h p ro v i ded p ro x y/i n terc ep ti o n - based c o n tex tu al sessi o n s.
S tarti n g w i th v ersi o n 3 .0 .1 , H i bern ate added th e Ses s io nF acto ry. getC u rrentSes s io n( ) m eth o d. I n i ti al l y, th i s
assu m ed u sage o f J T A tran sac ti o n s, w h ere th e J T A tran sac ti o n defi n ed bo th th e sc o p e an d c o n tex t o f a c u rren t
sessi o n . G i v en th e m atu ri ty o f th e n u m ero u s stan d- al o n e J T A T rans actio nM anager i m p l em en tati o n s, m o st, i f
n o t al l , ap p l i c ati o n s sh o u l d be u si n g J T A tran sac ti o n m an agem en t, w h eth er o r n o t th ey are dep l o yed i n to a
J 2 E E c o n tai n er. B ased o n th at, th e J T A - based c o n tex tu al sessi o n s are al l yo u n eed to u se.
H o w ev er, as o f v ersi o n 3 .1 , th e p ro c essi n g beh i n d Ses s io nF acto ry. getC u rrentSes s io n( ) i s n o w p l u ggabl e. T o th at
en d, a n ew ex ten si o n i n terfac e, o rg. h ib ernate. co ntex t. C u rrentSes s io nC o ntex t , an d a n ew c o n fi gu rati o n
3 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
p aram eter, h ib ernate. cu rrent_ s es s io n_ co ntex t_ cl as s , h av e been added to al l o w p l u ggabi l i ty o f th e sc o p e an d

c o n tex t o f defi n i n g c u rren t sessi o n s.
S ee th e J av ado c s fo r th e o rg. h ib ernate. co ntex t. C u rrentSes s io nC o ntex t i n terfac e fo r a detai l ed di sc u ssi o n o f i ts

c o n trac t. I t defi n es a si n gl e m eth o d, cu rrentSes s io n( ), by w h i c h th e i m p l em en tati o n i s resp o n si bl e fo r trac k i n g
th e c u rren t c o n tex tu al sessi o n . O u t- o f- th e- bo x , H i bern ate c o m es w i th th ree i m p l em en tati o n s o f th i s
i n terfac e:
o rg. h ib ernate. co ntex t. J T A Ses s io nC o ntex t : c u rren t sessi o n s are trac k ed an d sc o p ed by a J T A tran sac ti o n . T h e
p ro c essi n g h ere i s ex ac tl y th e sam e as i n th e o l der J T A - o n l y ap p ro ac h . S ee th e J av ado c s fo r detai l s.
o rg. h ib ernate. co ntex t. T h readL o cal Ses s io nC o ntex t :c u rren t sessi o n s are trac k ed by th read o f ex ec u ti o n . S ee
th e J av ado c s fo r detai l s.
o rg. h ib ernate. co ntex t. M anagedSes s io nC o ntex t : c u rren t sessi o n s are trac k ed by th read o f ex ec u ti o n .
H o w ev er, yo u are resp o n si bl e to bi n d an d u n bi n d a Ses s io n i n stan c e w i th stati c m eth o ds o n th i s c l ass: i t
do es n o t o p en , fl u sh , o r c l o se a Ses s io n.
T h e fi rst tw o i m p l em en tati o n s p ro v i de a " o n e sessi o n - o n e database tran sac ti o n " p ro gram m i n g m o del . T h i s
i s al so al so k n o w n an d u sed as s e s s ion- p e r- re q ue s t. T h e begi n n i n g an d en d o f a H i bern ate sessi o n i s defi n ed
by th e du rati o n o f a database tran sac ti o n . I f yo u u se p ro gram m ati c tran sac ti o n dem arc ati o n i n p l ai n J S E
w i th o u t J T A , yo u are adv i sed to u se th e H i bern ate T rans actio n A P I to h i de th e u n derl yi n g tran sac ti o n system
fro m yo u r c o de. I f yo u u se J T A , yo u c an u ti l i z e th e J T A i n terfac es to dem arc ate tran sac ti o n s. I f yo u ex ec u te
i n an E J B c o n tai n er th at su p p o rts CM T , tran sac ti o n bo u n dari es are defi n ed dec l arati v el y an d yo u do n o t n eed
an y tran sac ti o n o r sessi o n dem arc ati o n o p erati o n s i n yo u r c o de. R efer to Ch ap ter 1 1 , Trans ac tions and
C onc urre nc y fo r m o re i n fo rm ati o n an d c o de ex am p l es.
T h e h ib ernate. cu rrent_ s es s io n_ co ntex t_ cl as s c o n fi gu rati o n p aram eter defi n es w h ic h

o rg. h ib ernate. co ntex t. C u rrentSes s io nC o ntex t i m p l em en tati o n sh o u l d be u sed. F o r bac k w ards c o m p ati bi l i ty, i f th i s
c o n fi gu rati o n p aram eter i s n o t set bu t a o rg. h ib ernate. trans actio n. T rans actio nM anagerL o o k u p i s c o n fi gu red,
H i bern ate w i l l u se th e o rg. h ib ernate. co ntex t. J T A Ses s io nC o ntex t . T yp i c al l y, th e v al u e o f th i s p aram eter w o u l d
j u st n am e th e i m p l em en tati o n c l ass to u se. F o r th e th ree o u t- o f- th e- bo x i m p l em en tati o n s, h o w ev er, th ere
are th ree c o rresp o n di n g sh o rt n am es: " j ta" , " th read" , an d " m an aged" .
C h ap ter 3 . C onfig uration

3 .1 . P ro gram m ati c c o n fi gu rati o n
3 .2. O btai n i n g a S essi o n F ac to ry
3 .3 . J D B C c o n n ec ti o n s
3 .4 . O p ti o n al c o n fi gu rati o n p ro p erti es
3 .4 .1 . S Q L D i al ec ts
3 .4 .2. O u ter J o i n F etc h i n g
3 .4 .3 . B i n ary S tream s
3 .4 .4 . S ec o n d- l ev el an d q u ery c ac h e
3 .4 .5 . Q u ery L an gu age S u bsti tu ti o n
3 .4 .6 . H i bern ate stati sti c s
3 .5 . L o ggi n g
3 .6 . I m p l em en ti n g a NamingStrategy
3 .7 . X M L c o n fi gu rati o n fi l e
3 .8 . J 2E E A p p l i c ati o n S erv er i n tegrati o n
3 .8 .1 . T ran sac ti o n strategy c o n fi gu rati o n
3 .8 .2. J N D I - bo u n d Ses s io nF acto ry
3 .8 .3 . Cu rren t S essi o n c o n tex t m an agem en t w i th J T A
3 .8 .4 . J M X dep l o ym en t
H i bern ate i s desi gn ed to o p erate i n m an y di fferen t en v i ro n m en ts an d, as su c h , th ere i s a bro ad ran ge o f

c o n fi gu rati o n p aram eters. F o rtu n atel y, m o st h av e sen si bl e defau l t v al u es an d H i bern ate i s di stri bu ted w i th an
ex am p l e h ib ernate. pro perties fi l e i n etc/ th at di sp l ays th e v ari o u s o p ti o n s. S i m p l y p u t th e ex am p l e fi l e i n yo u r
c l assp ath an d c u sto m i z e i t to su i t yo u r n eeds.
3 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
3 . 1 . P rog rammatic config uration

A n i n stan c e o f o rg. h ib ernate. cf g. C o nf igu ratio n rep resen ts an en ti re set o f m ap p i n gs o f an ap p l i c ati o n ' s J av a
typ es to an S Q L database. T h e o rg. h ib ernate. cf g. C o nf igu ratio n is u sed to bu i l d an i m m u tabl e
o rg. h ib ernate. Ses s io nF acto ry. T h e m ap p i n gs are c o m p i l ed fro m v ari o u s X M L m ap p i n g fi l es.
Y o u c an o btai n a o rg. h ib ernate. cf g. C o nf igu ratio n i n stan c e by i n stan ti ati n g i t di rec tl y an d sp ec i fyi n g X M L m ap p i n g
do c u m en ts. I f th e m ap p i n g fi l es are i n th e c l assp ath , u se addR es o u rce( ). F o r ex am p l e:
C o nf igu ratio n cf g = new C o nf igu ratio n( )

. addR es o u rce( " I tem. h b m. x ml " )
. addR es o u rce( " B id. h b m. x ml " );
A n al tern ati v e w ay i s to sp ec i fy th e m ap p ed c l ass an d al l o w H i bern ate to fi n d th e m ap p i n g do c u m en t fo r yo u :

. addC l as s ( o rg. h ib ernate. au ctio n. I tem. cl as s )
. addC l as s ( o rg. h ib ernate. au ctio n. B id. cl as s );
H i bern ate w ill th en searc h fo r m ap p i n g fi l es n am ed /org /h ibern ate/auc tion /I tem . h bm .x m l an d

/org /h ibern ate/auc tion /B id . h bm .x m lin th e c l assp ath . T h i s ap p ro ac h el i m i n ates an y h ardc o ded fi l en am es.
A o rg. h ib ernate. cf g. C o nf igu ratio n al so al l o w s yo u to sp ec i fy c o n fi gu rati o n p ro p erti es. F o r ex am p l e:

. addC l as s ( o rg. h ib ernate. au ctio n. I tem. cl as s )
. addC l as s ( o rg. h ib ernate. au ctio n. B id. cl as s )
. s etP ro perty( " h ib ernate. dial ect" , " o rg. h ib ernate. dial ect. M ySQ L I nno D B D ial ect" )
. s etP ro perty( " h ib ernate. co nnectio n. datas o u rce" , " j av a: co mp/ env / j db c/ tes t" )
. s etP ro perty( " h ib ernate. o rder_ u pdates " , " tru e" );
T h i s i s n o t th e o n l y w ay to p ass c o n fi gu rati o n p ro p erti es to H i bern ate. S o m e al tern ati v e o p ti o n s i n c l u de:
1 . P ass an i n stan c e o f j av a. u til . P ro perties to C o nf igu ratio n. s etP ro perties ( ).
2. P l ac e a fi l e n am ed h ibern ate. p rop erties i n a ro o t di rec to ry o f th e c l assp ath .

3 . S et Sys tem p ro p erti es u si n g j av a - D pro perty=v al u e.
4 . I n c l u de < pro perty> el em en ts i n h ib ernate. cf g. x ml (th i s i s di sc u ssed l ater).
I f yo u w an t to get started q u i c k l y h ibern ate. p rop erties i s th e easi est ap p ro ac h .
T h e o rg. h ib ernate. cf g. C o nf igu ratio n i s i n ten ded as a startu p - ti m e o bj ec t th at w i l l be di sc arded o n c e a

Ses s io nF acto ry i s c reated.
3 . 2 . O btaining a S es s ionF actory

W h en al l m ap p i n gs h av e been p arsed by th e o rg. h ib ernate. cf g. C o nf igu ratio n, th e ap p l i c ati o n m u st o btai n a
fac to ry fo r o rg. h ib ernate. Ses s io n i n stan c es. T h i s fac to ry i s i n ten ded to be sh ared by al l ap p l i c ati o n th reads:
Ses s io nF acto ry s es s io ns = cf g. b u il dSes s io nF acto ry( );
H i bern ate do es al l o w yo u r ap p l i c ati o n to i n stan ti ate m o re th an o n e o rg. h ib ernate. Ses s io nF acto ry. T h i s i s u sefu l
i f yo u are u si n g m o re th an o n e database.
3 . 3 . J DB C connections
I t i s adv i sabl e to h av e th e o rg. h ib ernate. Ses s io nF acto ry c reate an d p o o l J D B C c o n n ec ti o n s fo r yo u . I f yo u tak e
3 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
th i s ap p ro ac h , o p en i n g a o rg. h ib ernate. Ses s io n i s as si m p l e as:
Ses s io n s es s io n = s es s io ns . o penSes s io n( ); / / o pen a new Ses s io n
O n c e yo u start a task th at req u i res ac c ess to th e database, a J D B C c o n n ec ti o n w i l l be o btai n ed fro m th e p o o l .
B efo re yo u c an do th i s, yo u fi rst n eed to p ass so m e J D B C c o n n ec ti o n p ro p erti es to H i bern ate. A l l H i bern ate

p ro p erty n am es an d sem an ti c s are defi n ed o n th e c l ass o rg. h ib ernate. cf g. E nv iro nment . T h e m o st i m p o rtan t
setti n gs fo r J D B C c o n n ec ti o n c o n fi gu rati o n are o u tl i n ed bel o w .
H i bern ate w i l l o btai n an d p o o l c o n n ec ti o n s u si n g j av a. s q l . D riv erM anager i f yo u set th e fo l l o w i n g p ro p erti es:
Table 3.1. Hibernate JDBC Properties
Property nam e Pu rpose
h i bern ate.c o n n ec ti o n .dri v er_ c l ass J D B C d riv e r c las s

h i bern ate.c o n n ec ti o n .u rl J D B C U R L
h i bern ate.c o n n ec ti o n .u sern am e d atab as e us e r
h i bern ate.c o n n ec ti o n .p assw o rd d atab as e us e r p as s w ord
h i bern ate.c o n n ec ti o n .p o o l _ si z e m ax im um num b e r of p oole d c onne c tions
H i bern ate' s o w n c o n n ec ti o n p o o l i n g al go ri th m i s, h o w ev er, q u i te ru di m en tary. I t i s i n ten ded to h el p yo u get

started an d i s not inte nd e d f or us e in a p rod uc tion s y s te m , o r ev en fo r p erfo rm an c e testi n g. Y o u sh o u ld u se a
th i rd p arty p o o l fo r best p erfo rm an c e an d stabi l i ty. J u st rep l ac e th e h i bern ate.c o n n ec ti o n .p o o l _ si z e p ro p erty
w i th c o n n ec ti o n p o o l sp ec i fi c setti n gs. T h i s w i l l tu rn o ff H i bern ate' s i n tern al p o o l . F o r ex am p l e, yo u m i gh t lik e
to u se c 3 p 0 .
C3 P 0 i s an o p en so u rc e J D B C c o n n ec ti o n p o o l di stri bu ted al o n g w i th H i bern ate i n th e lib di rec to ry. H i bern ate

w i l l u se i ts o rg. h ib ernate. co nnectio n. C 3P 0C o nnectio nP ro v ider fo r c o n n ec ti o n p o o l i n g i f yo u set h i bern ate.c 3 p 0 .*
p ro p erti es. I f yo u w o u l d l i k e to u se P ro x o o l , refer to th e p ac k aged h ibern ate. p rop erties an d th e H i bern ate
w eb si te fo r m o re i n fo rm ati o n .
T h e fo l l o w i n g i s an ex am p l e h ibern ate. p rop erties fi l e fo r c 3 p 0 :
h ib ernate. co nnectio n. driv er_ cl as s = o rg. po s tgres q l . D riv er

h ib ernate. co nnectio n. u rl = j db c: po s tgres q l : / / l o cal h o s t/ mydatab as e
h ib ernate. co nnectio n. u s ername = myu s er
h ib ernate. co nnectio n. pas s w o rd = s ecret
h ib ernate. c3p0. min_ s iz e=5
h ib ernate. c3p0. max _ s iz e=2 0
h ib ernate. c3p0. timeo u t=1800
h ib ernate. c3p0. max _ s tatements =50
h ib ernate. dial ect = o rg. h ib ernate. dial ect. P o s tgreSQ L D ial ect
F o r u se i n si de an ap p l i c ati o n serv er, yo u sh o u l d al m o st al w ays c o n fi gu re H i bern ate to o btai n c o n n ec ti o n s

fro m an ap p l i c ati o n serv er j av ax . s q l . D atas o u rce regi stered i n J N D I . Y o u w i l l n eed to set at l east o n e o f th e
fo l l o w i n g p ro p erti es:
Table 3.2 . Hibernate Datasou rc e Properties
h i bern ate.c o n n ec ti o n .dataso u rc e d atas ourc e J N D I nam e

h i bern ate.j n di .u rl U R L of th e J N D I p rov id e r (o p ti o n al )
h i bern ate.j n di .c l ass c las s of th e J N D I InitialContextFactory (o p ti o n al )
h i bern ate.c o n n ec ti o n .u sern am e d atab as e us e r (o p ti o n al )
h i bern ate.c o n n ec ti o n .p assw o rd d atab as e us e r p as s w ord (o p ti o n al )
3 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
H ere i s an ex am p l e h ibern ate. p rop erties fi l e fo r an ap p l i c ati o n serv er p ro v i ded J N D I dataso u rc e:
h ib ernate. co nnectio n. datas o u rce = j av a: / co mp/ env / j db c/ tes t

h ib ernate. trans actio n. f acto ry_ cl as s = \
o rg. h ib ernate. trans actio n. J T A T rans actio nF acto ry
h ib ernate. trans actio n. manager_ l o o k u p_ cl as s = \
o rg. h ib ernate. trans actio n. J B o s s T rans actio nM anagerL o o k u p
h ib ernate. dial ect = o rg. h ib ernate. dial ect. P o s tgreSQ L D ial ect
J D B C c o n n ec ti o n s o btai n ed fro m a J N D I dataso u rc e w i l l au to m ati c al l y p arti c i p ate i n th e c o n tai n er- m an aged

tran sac ti o n s o f th e ap p l i c ati o n serv er.
A rbi trary c o n n ec ti o n p ro p erti es c an be gi v en by p rep en di n g " h ib ernate. co nnectio n" to th e c o n n ec ti o n p ro p erty

n am e. F o r ex am p l e, yo u c an sp ec i fy a c h arS et c o n n ec ti o n p ro p erty u si n g h i bern ate.c o n n ec ti o n .c h arS et.
Y o u c an defi n e yo u r o w n p l u gi n strategy fo r o btai n i n g J D B C c o n n ec ti o n s by i m p l em en ti n g th e i n terfac e

o rg. h ib ernate. co nnectio n. C o nnectio nP ro v ider, an d sp ec i fyi n g yo u r c u sto m i m p l em en tati o n v ia th e
h i bern ate.c o n n ec ti o n .p ro v i der_ c l ass p ro p erty.
3 . 4 . O p tional config uration p rop erties

T h ere are a n u m ber o f o th er p ro p erti es th at c o n tro l th e beh av i o r o f H i bern ate at ru n ti m e. A l l are o p ti o n al
an d h av e reaso n abl e defau l t v al u es.
W arni ng
S om e of th e s e p rop e rtie s are " s y s te m - le v e l" only . S ystem - l ev el p ro p erti es c an be set o n l y v i a
j av a - D pro perty=v al u e o r h ibern ate. p rop erties. T h ey c annot be set by th e o th er tec h n i q u es desc ri bed
abo v e.
Table 3.3. Hibernate Conf ig u ration Properties

T h e c l assn am e o f a H i bern ate o rg. h ib ernate. dial ect. D ial ect w h i c h al l o w s
H i bern ate to gen erate S Q L o p ti m i z ed fo r a p arti c u l ar rel ati o n al
database.
e.g . f u l l . cl as s name. o f . D ial ect

h i bern ate.di al ec t
I n m o st c ases H i bern ate w i l l ac tu al l y be abl e to c h o o se th e c o rrec t

o rg. h ib ernate. dial ect. D ial ect i m
p l em en tati o n based o n th e J D B C metadata
retu rn ed by th e J D B C dri v er.
W ri te al l S Q L statem en ts to c o n so l e. T h i s i s an al tern ati v e to setti n g

th e l o g c atego ry o rg. h ib ernate. SQ L to deb u g .
h i bern ate.sh o w _ sq l
e.g . tru e | f al s e
h i bern ate.fo rm at_ sq l P retty p ri n t th e S Q L i n th e l o g an d c o n so l e. e.g . tru e | f al s e

Q u al i fy u n q u al i fi ed tabl e n am es w i th th e gi v en sc h em a/tabl esp ac e i n
h i bern ate.defau l t_ sc h em a
gen erated S Q L . e.g . SC H E M A _ NA M E
Q u al i fi es u n q u al i fi ed tabl e n am es w i th th e gi v en c atal o g i n gen erated
h i bern ate.defau l t_ c atal o g
S Q L . e.g . C A T A L O G _ NA M E
T h e o rg. h ib ernate. Ses s io nF acto ry w i l l be au to m ati c al l y bo u n d to th i s
n am e i n J N D I after i t h as been c reated.
h i bern ate.sessi o n _ fac to ry_ n am e
e.g . j ndi/ co mpo s ite/ name
3 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

S ets a m ax i m u m " dep th " fo r th e o u ter j o i n fetc h tree fo r si n gl e- en ded
asso c i ati o n s (o n e- to - o n e, m an y- to - o n e). A 0 di sabl es defau l t o u ter
h i bern ate.m ax _ fetc h _ dep th j o i n fetc h i n g.
e.g . rec o m m en ded v al u es betw een 0 an d 3
S ets a defau l t si z e fo r H i bern ate batc h fetc h i n g o f asso c i ati o n s. e.g .

h i bern ate.defau l t_ batc h _ fetc h _ si z e
rec o m m en ded v al u es 4, 8, 16
S ets a defau l t m o de fo r en ti ty rep resen tati o n fo r al l sessi o n s o p en ed
fro m th i s Ses s io nF acto ry
h i bern ate.defau l t_ en ti ty_ m o de
dynamic- map, do m4j , po j o
F o rc es H i bern ate to o rder S Q L u p dates by th e p ri m ary k ey v al u e o f

h i bern ate.o rder_ u p dates th e i tem s bei n g u p dated. T h i s w i l l resu l t i n few er tran sac ti o n
deadl o c k s i n h i gh l y c o n c u rren t system s. e.g . tru e | f al s e
I f en abl ed, H i bern ate w i l l c o l l ec t stati sti c s u sefu l fo r p erfo rm an c e
h i bern ate.gen erate_ stati sti c s
tu n i n g. e.g . tru e | f al s e
I f en abl ed, gen erated i den ti fi er p ro p erti es w i l l be reset to defau l t
h i bern ate.u se_ i den ti fi er_ ro l l bac k
v al u es w h en o bj ec ts are del eted. e.g . tru e | f al s e
I f tu rn ed o n , H i bern ate w i l l gen erate c o m m en ts i n si de th e S Q L , fo r
easi er debu ggi n g, defau l ts to f al s e .
h i bern ate.u se_ sq l _ c o m m en ts
Table 3.4 . Hibernate JDBC and Connec tion Properties
A n o n - z ero v al u e determ i n es th e J D B C fetc h si z e (c al l s

h i bern ate.j dbc .fetc h _ si z e
Statement. s etF etch Siz e( )).
A n o n - z ero v al u e en abl es u se o f J D B C2 batc h u p dates by

h i bern ate.j dbc .batc h _ si z e
H i bern ate. e.g . rec o m m en ded v al u es betw een 5 an d 30
S et th i s p ro p erty to tru e i f yo u r J D B C dri v er retu rn s c o rrec t ro w
c o u n ts fro m ex ecu teB atch ( ). I i t i s u su al l y safe to tu rn th i s o p ti o n
o n . H i bern ate w i l l th en u se batc h ed D M L fo r au to m ati c al l y
h i bern ate.j dbc .batc h _ v ersi o n ed_ data
v ersi o n ed data. D efau l ts to f al s e .
S el ec t a c u sto m o rg. h ib ernate. j db c. B atch er. M o st ap p l i c ati o n s w i l l

n o t n eed th i s c o n fi gu rati o n p ro p erty.
h i bern ate.j dbc .fac to ry_ c l ass
e.g . cl as s name. o f . B atch erF acto ry
E n abl es u se o f J D B C2 sc ro l l abl e resu l tsets by H i bern ate. T h i s

p ro p erty i s o n l y n ec essary w h en u si n g u ser- su p p l i ed J D B C
h i bern ate.j dbc .u se_ sc ro l l abl e_ resu l tset
c o n n ec ti o n s. H i bern ate u ses c o n n ec ti o n m etadata o th erw i se.
U se stream s w h en w ri ti n g/readi n g b inary o r s erial iz ab l e typ es

to /fro m J D B C. * s y s te m - le v e l p rop e rty *
h i bern ate.j dbc .u se_ stream s_ fo r_ bi n ary
E n abl es u se o f J D B C3 P reparedStatement. getG eneratedK eys ( ) to
h i bern ate.j dbc .u se_ get_ gen erated_ k eys retri ev e n ati v el y gen erated k eys after i n sert. R eq u i res J D B C3 +
dri v er an d J R E 1 .4 + , set to fal se i f yo u r dri v er h as p ro bl em s w i th
3 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

th e H i bern ate i den ti fi er gen erato rs. B y defau l t, i t tri es to
determ i n e th e dri v er c ap abi l i ti es u si n g c o n n ec ti o n m etadata.
e.g . tru e| f al s e
T h e c l assn am e o f a c u sto m
o rg. h ib ernate. co nnectio n. C o nnectio nP ro v ider w h i c h p ro v i des J D B C
h i bern ate.c o n n ec ti o n .p ro v i der_ c l ass c o n n ec ti o n s to H i bern ate.
e.g . cl as s name. o f . C o nnectio nP ro v ider
S ets th e J D B C tran sac ti o n i so l ati o n l ev el . Ch ec k

j av a. s q l . C o nnectio n fo r m ean i n gfu l v al u es, bu t n o te th at m o st
databases do n o t su p p o rt al l i so l ati o n l ev el s an d so m e defi n e
h i bern ate.c o n n ec ti o n .i so l ati o n addi ti o n al , n o n - stan dard i so l ati o n s.
e.g . 1, 2 , 4, 8
E n abl es au to c o m m i t fo r J D B C p o o l ed c o n n ec ti o n s (i t i s n o t
h i bern ate.c o n n ec ti o n .au to c o m m it
rec o m m en ded). e.g . tru e | f al s e
S p ec i fi es w h en H i bern ate sh o u l d rel ease J D B C c o n n ec ti o n s. B y
defau l t, a J D B C c o n n ec ti o n i s h el d u n ti l th e sessi o n i s ex p l i c i tl y
c l o sed o r di sc o n n ec ted. F o r an ap p l i c ati o n serv er J T A
dataso u rc e, u se af ter_ s tatement to aggressi v el y rel ease
c o n n ec ti o n s after ev ery J D B C c al l . F o r a n o n - J T A c o n n ec ti o n , i t
o ften m ak es sen se to rel ease th e c o n n ec ti o n at th e en d o f eac h
tran sac ti o n , by u si n g af ter_ trans actio n. au to w ill c h o o se
af ter_ s tatement fo r th e J T A an d CM T tran sac ti o n strategi es an d
af ter_ trans actio n fo r th e J D B C tran sac ti o n strategy.
h i bern ate.c o n n ec ti o n .rel ease_ m o de
e.g . au to (defau l t) | o n_ cl o s e | af ter_ trans actio n | af ter_ s tatement
T h is setti n g o n ly affec ts Ses s io ns retu rn ed fro m

Ses s io nF acto ry. o penSes s io n. F o r Ses s io ns o btai n ed th ro u gh
Ses s io nF acto ry. getC u rrentSes s io n, th e C u rrentSes s io nC o ntex t
i m p l em en tati o n
c o n fi gu red fo r u se c o n tro l s th e c o n n ec ti o n
rel ease m o de fo r th o se Ses s io ns. S ee S ec ti o n 2.5 , “ Co n tex tu al
sessi o n s”
P ass th e J D B C p ro p erty to

h i bern ate.c o n n ec ti o n .
D riv erM anager. getC o nnectio n( ).
P ass th e p ro p erty to th e J N D I

h i bern ate.j n di .
I nitial C o ntex tF acto ry.
Table 3.5 . Hibernate Cac h e Properties
T h e c l assn am e o f a c u sto m C ach eP ro v ider.
h ib ernate. cach e. pro v ider_ cl as s

e.g . cl as s name. o f . C ach eP ro v ider
O p ti m i z es sec o n d- l ev el c ac h e o p erati o n to m i n i m i z e w ri tes, at th e

c o st o f m o re freq u en t reads. T h i s setti n g i s m o st u sefu l fo r
h ib ernate. cach e. u s e_ minimal _ pu ts
c lu stered c ac h es an d, i n H i bern ate3 , i s en abl ed by defau l t fo r
c lu stered c ac h e i m p l em en tati o n s. e.g . tru e| f al s e
E n abl es th e q u ery c ac h e. I n di v i du al q u eri es sti l l h av e to be set
h ib ernate. cach e. u s e_ q u ery_ cach e
c ac h abl e. e.g . tru e| f al s e
3 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

Can be u sed to c o m p l etel y di sabl e th e sec o n d l ev el c ac h e, w h i c h i s
en abl ed by defau l t fo r c l asses w h i c h sp ec i fy a < cach e> m ap p i n g.
h ib ernate. cach e. u s e_ s eco nd_ l ev el _ cach e
e.g . tru e| f al s e
T h e c l assn am e o f a c u sto m Q u eryC ach e i n terfac e, defau l ts to th e

bu i l t- i n StandardQ u eryC ach e.
h ib ernate. cach e. q u ery_ cach e_ f acto ry
e.g . cl as s name. o f . Q u eryC ach e
h ib ernate. cach e. regio n_ pref ix A p refi x to u se fo r sec o n d- l ev el c ac h e regi o n n am es. e.g . pref ix
F o rc es H i bern ate to sto re data i n th e sec o n d- l ev el c ac h e i n a m o re
h ib ernate. cach e. u s e_ s tru ctu red_ entries
h u m an - fri en dl y fo rm at. e.g . tru e| f al s e
Table 3.6 . Hibernate Transac tion Properties
T h e c l assn am e o f a T rans actio nF acto ry to u se w i th H i bern ate

T rans actio n A P I (defau l ts to J D B C T rans actio nF acto ry).
h ib ernate. trans actio n. f acto ry_ cl as s
e.g . cl as s name. o f . T rans actio nF acto ry
A J N D I n am e u sed by J T A T rans actio nF acto ry to o btai n th e J T A

U s erT rans actio n fro m th e ap p l i c ati o n serv er.
j ta. U s erT rans actio n
e.g . j ndi/ co mpo s ite/ name
T h e c l assn am e o f a T rans actio nM anagerL o o k u p. I t i s req u i red

w h en J V M - l ev el c ac h i n g i s en abl ed o r w h en u si n g h i l o
h ib ernate. trans actio n. manager_ l o o k u p_ cl as s gen erato r i n a J T A en v i ro n m en t.
e.g . cl as s name. o f . T rans actio nM anagerL o o k u p
I f en abl ed, th e sessi o n w i l l be au to m ati c al l y fl u sh ed du ri n g th e

befo re c o m p l eti o n p h ase o f th e tran sac ti o n . B u i l t- i n an d
au to m ati c sessi o n c o n tex t m an agem en t i s p referred, see
h ib ernate. trans actio n. f l u s h _ b ef o re_ co mpl etio n
S ec ti o n 2.5 , “ Co n tex tu al sessi o n s” .
I f en abl ed, th e sessi o n w i l l be au to m ati c al l y c l o sed du ri n g th e

after c o m p l eti o n p h ase o f th e tran sac ti o n . B u i l t- i n an d
au to m ati c sessi o n c o n tex t m an agem en t i s p referred, see
h ib ernate. trans actio n. au to _ cl o s e_ s es s io n
S ec ti o n 2.5 , “ Co n tex tu al sessi o n s” .
Table 3.7 . M isc ellaneou s Properties
S u p p l y a c u sto m strategy fo r th e sc o p i n g o f th e " c u rren t" Ses s io n.

S ee S ec ti o n 2.5 , “ Co n tex tu al sessi o n s” fo r m o re i n fo rm ati o n abo u t
h ib ernate. cu rrent_ s es s io n_ co ntex t_ cl as s th e bu i l t- i n strategi es.
e.g . j ta | th read | managed | cu s to m. C l as s
3 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

Ch o o ses th e H Q L p arser i m p l em en tati o n . e.g .
h ib ernate. q u ery. f acto ry_ cl as s o rg. h ib ernate. h q l . as t. A ST Q u eryT rans l ato rF acto ry o r
o rg. h ib ernate. h q l . cl as s ic. C l as s icQ u eryT rans l ato rF acto ry
I s u sed to m ap fro m to k en s i n H i bern ate q u eri es to S Q L to k en s

h ib ernate. q u ery. s u b s titu tio ns (to k en s m i gh t be fu n c ti o n o r l i teral n am es, fo r ex am p l e). e.g .
h q l L iteral =SQ L _ L I T E R A L , h q l F u nctio n=SQ L F U NC
A u to m ati c al l y v al i dates o r ex p o rts sc h em a D D L to th e database

w h en th e Ses s io nF acto ry i s c reated. W i th create- dro p , th e database
h ib ernate. h b m2 ddl . au to sc h em a w i l l be dro p p ed w h en th e Ses s io nF acto ry i s c l o sed ex p l i c i tl y.
e.g . v al idate | u pdate | create | create- dro p
E n abl es th e u se o f CG L I B i n stead o f ru n ti m e refl ec ti o n

(S ystem - l ev el p ro p erty). R efl ec ti o n c an so m eti m es be u sefu l w h en
tro u bl esh o o ti n g. H i bern ate al w ays req u i res CG L I B ev en i f yo u tu rn
h ib ernate. cgl ib . u s e_ ref l ectio n_ o ptimiz er
o ff th e o p ti m i z er. Y o u c an n o t set th i s p ro p erty i n h ib ernate. cf g. x ml .
3 .4 .1 . S Q L D i al e c ts
A l w ays set th e h ib ernate. dial ect p ro p erty to th e c o rrec t o rg. h ib ernate. dial ect. D ial ect su bc l ass fo r yo u r database.
I f yo u sp ec i fy a di al ec t, H i bern ate w i l l u se sen si bl e defau l ts fo r so m e o f th e o th er p ro p erti es l i sted abo v e.
T h ism ean s th at yo u w i l l n o t h av e to sp ec i fy th em m an u al l y.
Table 3.8 . Hibernate S Q L Dialec ts ( h ibern ate. d ialec t)
R DBM S Dialec t
D B 2 o rg. h ib ernate. dial ect. D B 2 D ial ect
D B 2 A S /4 0 0 o rg. h ib ernate. dial ect. D B 2 400D ial ect
D B 2O S 3 9 0 o rg. h ib ernate. dial ect. D B 2 39 0D ial ect
P o stgreS Q L o rg. h ib ernate. dial ect. P o s tgreSQ L D ial ect
M yS Q L o rg. h ib ernate. dial ect. M ySQ L D ial ect
M yS Q L w i th I n n o D B o rg. h ib ernate. dial ect. M ySQ L I nno D B D ial ect
M yS Q L w i th M yI S A M o rg. h ib ernate. dial ect. M ySQ L M yI SA M D ial ect
O rac l e (an y v ersi o n ) o rg. h ib ernate. dial ect. O racl eD ial ect
O rac l e 9 i o rg. h ib ernate. dial ect. O racl e9 iD ial ect
O rac l e 1 0 g o rg. h ib ernate. dial ect. O racl e10gD ial ect
S ybase o rg. h ib ernate. dial ect. Syb as eD ial ect
S ybase A n yw h ere o rg. h ib ernate. dial ect. Syb as eA nyw h ereD ial ect
M i c ro so ft S Q L S erv er o rg. h ib ernate. dial ect. SQ L Serv erD ial ect
S A P D B o rg. h ib ernate. dial ect. SA P D B D ial ect
I n fo rm ix o rg. h ib ernate. dial ect. I nf o rmix D ial ect
H yp erso n i c S Q L o rg. h ib ernate. dial ect. H SQ L D ial ect
I n gres o rg. h ib ernate. dial ect. I ngres D ial ect
P ro gress o rg. h ib ernate. dial ect. P ro gres s D ial ect
M c k o i S Q L o rg. h ib ernate. dial ect. M ck o iD ial ect
I n terbase o rg. h ib ernate. dial ect. I nterb as eD ial ect
P o i n tbase o rg. h ib ernate. dial ect. P o intb as eD ial ect
3 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
R DBM S Dialec t
F ro n tB ase o rg. h ib ernate. dial ect. F ro ntb as eD ial ect
F i rebi rd o rg. h ib ernate. dial ect. F ireb irdD ial ect
3 . 4 . 2 . O u te r J oi n F e tc h i ng
I f yo u r database su p p o rts A N S I , O rac l e o r S ybase styl e o u ter j o i n s, oute r j oin f e tc h ing w i l l o ften i n c rease
p erfo rm an c e by l i m i ti n g th e n u m ber o f ro u n d tri p s to an d fro m th e database. T h i s i s, h o w ev er, at th e c o st o f
p o ssi bl y m o re w o rk p erfo rm ed by th e database i tsel f. O u ter j o i n fetc h i n g al l o w s a w h o l e grap h o f o bj ec ts
c o n n ec ted by m an y- to - o n e, o n e- to - m an y, m an y- to - m an y an d o n e- to - o n e asso c i ati o n s to be retri ev ed i n a
si n gl e S Q L SE L E C T .
O u ter j o i n fetc h i n g c an be di sabl ed g lob ally by setti n g th e p ro p erty h ib ernate. max _ f etch _ depth to 0. A setti n g o f
1 o r h i gh er en abl es o u ter j o i n fetc h i n g fo r o n e- to - o n e an d m an y- to - o n e asso c i ati o n s th at h av e been m ap p ed
w i th f etch =" j o in" .
S ee S ec ti o n 1 9 .1 , “ F etc h i n g strategi es” fo r m o re i n fo rm ati o n .
3 . 4 . 3 . B i nary S tre ams
O rac l e l i m i ts th e si z e o f b yte arrays th at c an be p assed to an d/o r fro m i ts J D B C dri v er. I f yo u w i sh to u se

l arge i n stan c es o f b inary o r s erial iz ab l e typ e, yo u sh o u l d en abl e h ib ernate. j db c. u s e_ s treams _ f o r_ b inary. Th is is a
s y s te m - le v e l s e tting only .
3 . 4 . 4 . S e c ond - l e v e l and q u e ry c ac h e
T h e p ro p erti es p refi x ed by h ib ernate. cach e al l o w yo u to u se a p ro c ess o r c l u ster sc o p ed sec o n d- l ev el c ac h e

system w i th H i bern ate. S ee th e S ec ti o n 1 9 .2, “ T h e S ec o n d L ev el Cac h e” fo r m o re i n fo rm ati o n .
3 . 4 . 5 . Q u e ry L ang u ag e S u b s ti tu ti on
Y o u c an defi n e n ew H i bern ate q u ery to k en s u si n g h ib ernate. q u ery. s u b s titu tio ns . F o r ex am p l e:
h ib ernate. q u ery. s u b s titu tio ns tru e=1, f al s e=0
T h i s w o u l d c au se th e to k en s tru e an d f al s e to be tran sl ated to i n teger l i teral s i n th e gen erated S Q L .
h ib ernate. q u ery. s u b s titu tio ns to L o w ercas e=L O W E R
T h i s w o u l d al l o w yo u to ren am e th e S Q L L O W E R fu n c ti o n .
3 . 4 . 6 . H i b e rnate s tati s ti c s
I f yo u en abl e h ib ernate. generate_ s tatis tics , H i bern ate ex p o ses a n u m ber o f m etri c s th at are u sefu l w h en
tu n i n g a ru n n i n g system v i a Ses s io nF acto ry. getStatis tics ( ). H i bern ate c an ev en be c o n fi gu red to ex p o se th ese
stati sti c s v i a J M X . R ead th e J av ado c o f th e i n terfac es i n o rg. h ib ernate. s tats fo r m o re i n fo rm ati o n .
3 . 5 . L og g ing
H i bern ate u ti l i z es S i m p l e L o ggi n g F ac ade fo r J av a (S L F 4 J ) i n o rder to l o g v ari o u s system ev en ts. S L F 4 J c an
di rec t yo u r l o ggi n g o u tp u t to sev eral l o ggi n g fram ew o rk s (N O P , S i m p l e, l o g4 j v ersi o n 1 .2, J D K 1 .4 l o ggi n g,
J CL o r l o gbac k ) dep en di n g o n yo u r c h o sen bi n di n g. I n o rder to setu p l o ggi n g yo u w i l l n eed slf 4 j - ap i. j ar i n
yo u r c l assp ath to geth er w i th th e j ar fi l e fo r yo u r p referred bi n di n g - slf 4 j - log 4 j 1 2 . j ar i n th e c ase o f L o g4 J . S ee
th e S L F 4 J do c u m en tati o n fo r m o re detai l . T o u se L o g4 j yo u w i l l al so n eed to p l ac e a log 4 j . p rop erties fi l e i n
3 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
yo u r c l assp ath . A n ex am p l e p ro p erti es fi l e i s di stri bu ted w i th H i bern ate i n th e s rc/ di rec to ry.
I t i s rec o m m en ded th at yo u fam i l i ari z e yo u rsel f w i th H i bern ate' s l o g m essages. A l o t o f w o rk h as been p u t

i n to m ak i n g th e H i bern ate l o g as detai l ed as p o ssi bl e, w i th o u t m ak i n g i t u n readabl e. I t i s an essen ti al
tro u bl esh o o ti n g dev i c e. T h e m o st i n teresti n g l o g c atego ri es are th e fo l l o w i n g:
Table 3.9 . Hibernate L og Categ ories
Categ ory F u nc tion
o rg. h ib ernate. SQ L L o g al l S Q L D M L statem en ts as th ey are ex ec u ted

o rg. h ib ernate. type L o g al l J D B C p aram eters
o rg. h ib ernate. to o l . h b m2 ddl L o g al l S Q L D D L statem en ts as th ey are ex ec u ted
L o g th e state o f al l en ti ti es (m ax 20 en ti ti es) asso c i ated w i th th e sessi o n at fl u sh
o rg. h ib ernate. pretty
ti m e
o rg. h ib ernate. cach e L o g al l sec o n d- l ev el c ac h e ac ti v i ty
o rg. h ib ernate. trans actio n L o g tran sac ti o n rel ated ac ti v i ty
o rg. h ib ernate. j db c L o g al l J D B C reso u rc e ac q u i si ti o n
o rg. h ib ernate. h q l . as t. A ST L o g H Q L an d S Q L A S T s du ri n g q u ery p arsi n g
o rg. h ib ernate. s ecu re L o g al l J A A S au th o ri z ati o n req u ests
o rg. h ib ernate L o g ev eryth i n g. T h i s i s a l o t o f i n fo rm ati o n bu t i t i s u sefu l fo r tro u bl esh o o ti n g
W h en dev el o p i n g ap p l i c ati o n s w i th H i bern ate, yo u sh o u l d al m o st al w ays w o rk w i th deb u g en abl ed fo r th e

c atego ry o rg. h ib ernate. SQ L , o r, al tern ati v el y, th e p ro p erty h ib ernate. s h o w _ s q l en abl ed.
3 . 6 . I mp l ementing a NamingStrategy
T h e i n terfac e o rg. h ib ernate. cf g. NamingStrategy al l o w s yo u to sp ec i fy a " n am i n g stan dard" fo r database o bj ec ts
an d sc h em a el em en ts.
Y o u c an p ro v i de ru l es fo r au to m ati c al l y gen erati n g database i den ti fi ers fro m J av a i den ti fi ers o r fo r p ro c essi n g
" l o gi c al " c o l u m n an d tabl e n am es gi v en i n th e m ap p i n g fi l e i n to " p h ysi c al " tabl e an d c o l u m n n am es. T h i s
featu re h el p s redu c e th e v erbo si ty o f th e m ap p i n g do c u m en t, el i m i n ati n g rep eti ti v e n o i se (T B L _ p refi x es, fo r
ex am p l e). T h e defau l t strategy u sed by H i bern ate i s q u i te m i n i m al .
Y o u c an sp ec i fy a di fferen t strategy by c al l i n g C o nf igu ratio n. s etNamingStrategy( ) befo re addi n g m ap p i n gs:
Ses s io nF acto ry s f = new C o nf igu ratio n( )

. s etNamingStrategy( I mpro v edNamingStrategy. I NST A NC E )
. addF il e( " I tem. h b m. x ml " )
. addF il e( " B id. h b m. x ml " )
. b u il dSes s io nF acto ry( );
o rg. h ib ernate. cf g. I mpro v edNamingStrategy i s a bu i l t- i n strategy th at m i gh t be a u sefu l starti n g p o i n t fo r so m e

ap p l i c ati o n s.
3 . 7 . X M L config uration fil e

A n al tern ati v e ap p ro ac h to c o n fi gu rati o n i s to sp ec i fy a fu l l c o n fi gu rati o n i n a fi l e n am ed h ib ernate. cf g. x ml . T h i s
fi l e c an be u sed as a rep l ac em en t fo r th e h ib ernate. pro perties fi l e o r, i f bo th are p resen t, to o v erri de
p ro p erti es.
T h e X M L c o n fi gu rati o n fi l e i s by defau l t ex p ec ted to be i n th e ro o t o f yo u r C L A SSP A T H . H ere i s an ex am p l e:
4 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< ?x ml v ers io n=' 1. 0' enco ding=' u tf - 8' ?>

< !D O C T Y P E h ib ernate- co nf igu ratio n P U B L I C
" - / / H ib ernate/ H ib ernate C o nf igu ratio n D T D / / E N"
" h ttp: / / h ib ernate. s o u rcef o rge. net/ h ib ernate- co nf igu ratio n- 3. 0. dtd" >
< ! - - a Ses s io nF acto ry ins tance l is ted as / j ndi/ name - - >

< s es s io n- f acto ry
name=" j av a: h ib ernate/ Ses s io nF acto ry" >
< ! - - pro perties - - >

< pro perty name=" co nnectio n. datas o u rce" >j av a: / co mp/ env / j db c/ M yD B < / pro perty>
< pro perty name=" dial ect" >o rg. h ib ernate. dial ect. M ySQ L D ial ect< / pro perty>
< pro perty name=" s h o w _ s q l " >f al s e< / pro perty>
< pro perty name=" trans actio n. f acto ry_ cl as s " >
< / pro perty>
< pro perty name=" j ta. U s erT rans actio n" >j av a: co mp/ U s erT rans actio n< / pro perty>
< ! - - mapping f il es - - >

< mapping res o u rce=" o rg/ h ib ernate/ au ctio n/ I tem. h b m. x ml " / >
< mapping res o u rce=" o rg/ h ib ernate/ au ctio n/ B id. h b m. x ml " / >
< ! - - cach e s ettings - - >

< cl as s - cach e cl as s =" o rg. h ib ernate. au ctio n. I tem" u s age=" read- w rite" / >
< cl as s - cach e cl as s =" o rg. h ib ernate. au ctio n. B id" u s age=" read- o nl y" / >
< co l l ectio n- cach e co l l ectio n=" o rg. h ib ernate. au ctio n. I tem. b ids " u s age=" read- w rite" / >
T h e adv an tage o f th i s ap p ro ac h i s th e ex tern al i z ati o n o f th e m ap p i n g fi l e n am es to c o n fi gu rati o n . T h e

h ib ernate. cf g. x ml i s al so m o re c o n v en i en t o n c e yo u h av e to tu n e th e H i bern ate c ac h e. I t i s yo u r c h o i c e to u se
ei th er h ib ernate. pro perties o r h ib ernate. cf g. x ml . B o th are eq u i v al en t, ex c ep t fo r th e abo v e m en ti o n ed ben efi ts
o f u si n g th e X M L syn tax .
W i th th e X M L c o n fi gu rati o n , starti n g H i bern ate i s th en as si m p l e as:
Ses s io nF acto ry s f = new C o nf igu ratio n( ). co nf igu re( ). b u il dSes s io nF acto ry( );
Y o u c an sel ec t a di fferen t X M L c o n fi gu rati o n fi l e u si n g:
Ses s io nF acto ry s f = new C o nf igu ratio n( )

. co nf igu re( " catdb . cf g. x ml " )
3 .8 . J 2 E E A p p l ication S erv er integ ration

H i bern ate h as th e fo l l o w i n g i n tegrati o n p o i n ts fo r J 2E E i n frastru c tu re:
C ontaine r- m anag e d d atas ourc e s : H i bern ate c an u se J D B C c o n n ec ti o n s m an aged by th e c o n tai n er an d

p ro v i ded th ro u gh J N D I . U su al l y, a J T A c o m p ati bl e T rans actio nM anager an d a R es o u rceM anager tak e c are o f
tran sac ti o n m an agem en t (CM T ), esp ec i al l y di stri bu ted tran sac ti o n h an dl i n g ac ro ss sev eral dataso u rc es.
Y o u c an al so dem arc ate tran sac ti o n bo u n dari es p ro gram m ati c al l y (B M T ), o r yo u m i gh t w an t to u se th e
o p ti o n al H i bern ate T rans actio n A P I fo r th i s to k eep yo u r c o de p o rtabl e.
A utom atic J N D I b ind ing : H i bern ate c an bi n d i ts Ses s io nF acto ry to J N D I after startu p .
4 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
J TA S e s s ion b ind ing : th e H i bern ate Ses s io n c an be au to m ati c al l y bo u n d to th e sc o p e o f J T A tran sac ti o n s.

S im p ly lo o k u p th e Ses s io nF acto ry fro m J N D I an d get th e c u rren t Ses s io n. L et H i bern ate m an age fl u sh i n g
an d c l o si n g th e Ses s io n w h en yo u r J T A tran sac ti o n c o m p l etes. T ran sac ti o n dem arc ati o n i s ei th er
dec l arati v e (CM T ) o r p ro gram m ati c (B M T /U serT ran sac ti o n ).
J M X d e p loy m e nt: i f yo u h av e a J M X c ap abl e ap p l i c ati o n serv er (e.g. J B o ss A S ), yo u c an c h o o se to dep l o y

H i bern ate as a m an aged M B ean . T h i s sav es yo u th e o n e l i n e startu p c o de to bu i l d yo u r Ses s io nF acto ry
fro m a C o nf igu ratio n. T h e c o n tai n er w i l l startu p yo u r H ib ernateServ ice an d al so tak e c are o f serv i c e
dep en den c i es (dataso u rc e h as to be av ai l abl e befo re H i bern ate starts, etc ).
D ep en di n g o n yo u r en v i ro n m en t, yo u m i gh t h av e to set th e c o n fi gu rati o n o p ti o n
h ib ernate. co nnectio n. aggres s iv e_ rel eas e to tru e i f yo u r ap p l i c ati o n serv er sh o w s " c o n n ec ti o n c o n tai n m en t"
ex c ep ti o n s.
3 . 8 . 1 . T rans ac ti on s trate g y c onf i g u rati on
T h e H i bern ate Ses s io n A P I i s i n dep en den t o f an y tran sac ti o n dem arc ati o n system i n yo u r arc h i tec tu re. I f yo u
l et H i bern ate u se J D B C di rec tl y th ro u gh a c o n n ec ti o n p o o l , yo u c an begi n an d en d yo u r tran sac ti o n s by c al l i n g
th e J D B C A P I . I f yo u ru n i n a J 2E E ap p l i c ati o n serv er, yo u m i gh t w an t to u se bean - m an aged tran sac ti o n s an d
c al l th e J T A A P I an d U s erT rans actio n w h en n eeded.
T o k eep yo u r c o de p o rtabl e betw een th ese tw o (an d o th er) en v i ro n m en ts w e rec o m m en d th e o p ti o n al

H i bern ate T rans actio n A P I , w h i c h w rap s an d h i des th e u n derl yi n g system . Y o u h av e to sp ec i fy a fac to ry c l ass
fo r T rans actio n i n stan c es by setti n g th e H i bern ate c o n fi gu rati o n p ro p erty h ib ernate. trans actio n. f acto ry_ cl as s .
T h ere are th ree stan dard, o r bu i l t- i n , c h o i c es:
o rg. h ib ernate. trans actio n. J D B C T rans actio nF acto ry
del egates to database (J D B C) tran sac ti o n s (defau l t)
del egates to c o n tai n er- m an aged tran sac ti o n s i f an ex i sti n g tran sac ti o n i s u n derw ay i n th i s c o n tex t (fo r
ex am p l e, E J B sessi o n bean m eth o d). O th erw i se, a n ew tran sac ti o n i s started an d bean - m an aged
tran sac ti o n s are u sed.
o rg. h ib ernate. trans actio n. C M T T rans actio nF acto ry
del egates to c o n tai n er- m an aged J T A tran sac ti o n s
Y o u c an al so defi n e yo u r o w n tran sac ti o n strategi es (fo r a CO R B A tran sac ti o n serv i c e, fo r ex am p l e).
S o m e featu res i n H i bern ate (i .e., th e sec o n d l ev el c ac h e, Co n tex tu al S essi o n s w i th J T A , etc .) req u i re ac c ess
to th e J T A T rans actio nM anager i n a m an aged en v i ro n m en t. I n an ap p l i c ati o n serv er, si n c e J 2E E do es n o t
stan dardi z e a si n gl e m ec h an i sm , yo u h av e to sp ec i fy h o w H i bern ate sh o u l d o btai n a referen c e to th e
T rans actio nM anager:
Table 3.10 . JTA Transac tionM anag ers
Transac tion F ac tory A pplic ation S erv er
o rg. h ib ernate. trans actio n. J B o s s T rans actio nM anagerL o o k u p J B o ss

o rg. h ib ernate. trans actio n. W eb l o gicT rans actio nM anagerL o o k u p W ebl o gi c
o rg. h ib ernate. trans actio n. W eb Sph ereT rans actio nM anagerL o o k u p W ebS p h ere
o rg. h ib ernate. trans actio n. W eb Sph ereE x tendedJ T A T rans actio nL o o k u p W ebS p h ere 6
o rg. h ib ernate. trans actio n. O rio nT rans actio nM anagerL o o k u p O ri o n
o rg. h ib ernate. trans actio n. R es inT rans actio nM anagerL o o k u p R esi n
o rg. h ib ernate. trans actio n. J O T M T rans actio nM anagerL o o k u p J O T M
o rg. h ib ernate. trans actio n. J O nA ST rans actio nM anagerL o o k u p J O n A S
o rg. h ib ernate. trans actio n. J R u n4T rans actio nM anagerL o o k u p J R u n 4
4 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
Transac tion F ac tory A pplic ation S erv er

o rg. h ib ernate. trans actio n. B E ST rans actio nM anagerL o o k u p B o rl an d E S
3 . 8 . 2 . J N D I- b ou nd SessionFactory
A J N D I - bo u n d H i bern ate Ses s io nF acto ry c an si m p l i fy th e l o o k u p fu n c ti o n o f th e fac to ry an d c reate n ew

Ses s io ns. T h i s i s n o t, h o w ev er, rel ated to a J N D I bo u n d D atas o u rce; bo th si m p l y u se th e sam e regi stry.
I f yo u w i sh to h av e th e Ses s io nF acto ry bo u n d to a J N D I n am esp ac e, sp ec i fy a n am e (e.g.

j av a: h ib ernate/ Ses s io nF acto ry) u si n g th e p ro p erty h ib ernate. s es s io n_ f acto ry_ name . I f th i s p ro p erty i s o m i tted, th e
Ses s io nF acto ry w i l l n o t be bo u n d to J N D I . T h i s i s esp ec i al l y u sefu l i n en v i ro n m en ts w i th a read- o n l y J N D I
defau l t i m p l em en tati o n (i n T o m c at, fo r ex am p l e).
W h en bi n di n g th e Ses s io nF acto ry to J N D I , H i bern ate w i l l u se th e v al u es o f h ib ernate. j ndi. u rl , h ib ernate. j ndi. cl as s

to i n stan ti ate an i n i ti al c o n tex t. I f th ey are n o t sp ec i fi ed, th e defau l t I nitial C o ntex t w i l l be u sed.
H i bern ate w i l l au to m ati c al l y p l ac e th e Ses s io nF acto ry i n J N D I after yo u c al l cf g. b u il dSes s io nF acto ry( ). T h i s

m ean s yo u w i l l h av e th i s c al l i n so m e startu p c o de, o r u ti l i ty c l ass i n yo u r ap p l i c ati o n , u n l ess yo u u se J M X
dep l o ym en t w i th th e H ib ernateServ ice (th i s i s di sc u ssed l ater i n greater detai l ).
I f yo u u se a J N D I Ses s io nF acto ry, an E J B o r an y o th er c l ass, yo u c an o btai n th e Ses s io nF acto ry u si n g a J N D I

lo o k u p .
I t i s rec o m m en ded th at yo u bi n d th e Ses s io nF acto ry to J N D I in a m an aged en v i ro n m en t an d u se a s tatic

si n gl eto n o th erw i se. T o sh i el d yo u r ap p l i c ati o n c o de fro m th ese detai l s, w e al so rec o m m en d to h i de th e
ac tu al l o o k u p c o de fo r a Ses s io nF acto ry i n a h el p er c l ass, su c h as H ib ernateU til . getSes s io nF acto ry( ). N o te th at
su c h a c l ass i s al so a c o n v en i en t w ay to startu p H i bern atesee c h ap ter 1 .
3 . 8 . 3 . C u rre nt S e s s i on c onte x t manag e me nt w i th J T A
T h e easi est w ay to h an dl e Ses s io ns an d tran sac ti o n s i s H i bern ate' s au to m ati c " c u rren t" Ses s io n m an agem en t.
F o r a di sc u ssi o n o f c o n tex tu al sessi o n s see S ec ti o n 2.5 , “ Co n tex tu al sessi o n s” . U si n g th e " j ta" sessi o n c o n tex t,
i f th ere i s n o H i bern ate Ses s io n asso c i ated w i th th e c u rren t J T A tran sac ti o n , o n e w i l l be started an d asso c i ated
w i th th at J T A tran sac ti o n th e fi rst ti m e yo u c al l s es s io nF acto ry. getC u rrentSes s io n( ). T h e Ses s io ns retri ev ed v i a
getC u rrentSes s io n( ) i n th e" j ta" c o n tex t are set to au to m ati c al l y fl u sh befo re th e tran sac ti o n c o m p l etes, c l o se
after th e tran sac ti o n c o m p l etes, an d aggressi v el y rel ease J D B C c o n n ec ti o n s after eac h statem en t. T h i s al l o w s
th e Ses s io ns to be m an aged by th e l i fe c yc l e o f th e J T A tran sac ti o n to w h i c h i t i s asso c i ated, k eep i n g u ser
c o de c l ean o f su c h m an agem en t c o n c ern s. Y o u r c o de c an ei th er u se J T A p ro gram m ati c al l y th ro u gh
U s erT rans actio n, o r (rec o m m en ded fo r p o rtabl e c o de) u se th e H i bern ate T rans actio n A P I to set tran sac ti o n
bo u n dari es. I f yo u ru n i n an E J B c o n tai n er, dec l arati v e tran sac ti o n dem arc ati o n w i th CM T i s p referred.
3 .8 .4 . J M X d e pl oy me nt
T h e l i n e cf g. b u il dSes s io nF acto ry( ) sti l l h as to be ex ec u ted so m ew h ere to get a Ses s io nF acto ry i n to J N D I . Y o u c an

do th i s ei th er i n a s tatic i n i ti al i z er bl o c k , l i k e th e o n e i n H ib ernateU til , o r yo u c an dep l o y H i bern ate as a
m anag e d s e rv ic e .
H i bern ate i s di stri bu ted w i th o rg. h ib ernate. j mx . H ib ernateServ ice fo r dep l o ym en t o n an ap p l i c ati o n serv er w i th
J M X c ap abi l i ti es, su c h as J B o ss A S . T h e ac tu al dep l o ym en t an d c o n fi gu rati o n i s v en do r- sp ec i fi c . H ere i s an
ex am p l e j b o s s - s erv ice. x ml fo r J B o ss 4 .0 .x :
4 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< ?x ml v ers io n=" 1. 0" ?>

< s erv er>
< mb ean co de=" o rg. h ib ernate. j mx . H ib ernateServ ice"

name=" j b o s s . j ca: s erv ice=H ib ernateF acto ry, name=H ib ernateF acto ry" >
< ! - - R eq u ired s erv ices - - >

< depends >j b o s s . j ca: s erv ice=R A R D epl o yer< / depends >
< depends >j b o s s . j ca: s erv ice=L o cal T x C M , name=H s q l D S< / depends >
< ! - - B ind th e H ib ernate s erv ice to J ND I - - >

< attrib u te name=" J ndiName" >j av a: / h ib ernate/ Ses s io nF acto ry< / attrib u te>
< ! - - D atas o u rce s ettings - - >

< attrib u te name=" D atas o u rce" >j av a: H s q l D S< / attrib u te>
< attrib u te name=" D ial ect" >o rg. h ib ernate. dial ect. H SQ L D ial ect< / attrib u te>
< ! - - T rans actio n integratio n - - >

< attrib u te name=" T rans actio nStrategy" >
o rg. h ib ernate. trans actio n. J T A T rans actio nF acto ry< / attrib u te>
< attrib u te name=" T rans actio nM anagerL o o k u pStrategy" >
o rg. h ib ernate. trans actio n. J B o s s T rans actio nM anagerL o o k u p< / attrib u te>
< attrib u te name=" F l u s h B ef o reC o mpl etio nE nab l ed" >tru e< / attrib u te>
< attrib u te name=" A u to C l o s eSes s io nE nab l ed" >tru e< / attrib u te>
< ! - - F etch ing o ptio ns - - >

< attrib u te name=" M ax imu mF etch D epth " >5< / attrib u te>
< ! - - Seco nd- l ev el cach ing - - >

< attrib u te name=" Seco ndL ev el C ach eE nab l ed" >tru e< / attrib u te>
< attrib u te name=" C ach eP ro v iderC l as s " >o rg. h ib ernate. cach e. E h C ach eP ro v ider< / attrib u te>
< attrib u te name=" Q u eryC ach eE nab l ed" >tru e< / attrib u te>
< ! - - L o gging - - >

< attrib u te name=" Sh o w Sq l E nab l ed" >tru e< / attrib u te>
< ! - - M apping f il es - - >

< attrib u te name=" M apR es o u rces " >au ctio n/ I tem. h b m. x ml , au ctio n/ C atego ry. h b m. x ml < / attrib u te>
< / mb ean>
< / s erv er>
T h i s fi l e i s dep l o yed i n a di rec to ry c al l ed M E T A - I NF an d p ac k aged i n a J A R fi l e w i th th e ex ten si o n . s ar (serv i c e

arc h i v e). Y o u al so n eed to p ac k age H i bern ate, i ts req u i red th i rd- p arty l i brari es, yo u r c o m p i l ed p ersi sten t
c l asses, as w el l as yo u r m ap p i n g fi l es i n th e sam e arc h i v e. Y o u r en terp ri se bean s (u su al l y sessi o n bean s) c an
be k ep t i n th ei r o w n J A R fi l e, bu t yo u c an i n c l u de th i s E J B J A R fi l e i n th e m ai n serv i c e arc h i v e to get a si n gl e
(h o t- )dep l o yabl e u n i t. Co n su l t th e J B o ss A S do c u m en tati o n fo r m o re i n fo rm ati o n abo u t J M X serv i c e an d E J B
dep l o ym en t.
C h ap ter 4 . P ers is tent C l as s es

4 .1 . A si m p l e P O J O ex am p l e
4 .1 .1 . I m p l em en t a n o - argu m en t c o n stru c to r
4 .1 .2. P ro v i de an i den ti fi er p ro p erty (o p ti o n al )
4 .1 .3 . P refer n o n - fi n al c l asses (o p ti o n al )
4 .1 .4 . D ec l are ac c esso rs an d m u tato rs fo r p ersi sten t fi el ds (o p ti o n al )
4 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
4 .2. I m p l em en ti n g i n h eri tan c e

4 .3 . I m p l em en ti n g eq u al s ( ) an d h as h C o de( )
4 .4 . D yn am i c m o del s
4 .5 . T u p l i z ers
4 .6 . E n ti tyN am eR eso l v ers
P ersi sten t c l asses are c l asses i n an ap p l i c ati o n th at i m p l em en t th e en ti ti es o f th e bu si n ess p ro bl em (e.g.

Cu sto m er an d O rder i n an E - c o m m erc e ap p l i c ati o n ). N o t al l i n stan c es o f a p ersi sten t c l ass are c o n si dered to
be i n th e p ersi sten t state. F o r ex am p l e, an i n stan c e c an i n stead be tran si en t o r detac h ed.
H i bern ate w o rk s best i f th ese c l asses fo l l o w so m e si m p l e ru l es, al so k n o w n as th e P l ai n O l d J av a O bj ec t

(P O J O ) p ro gram m i n g m o del . H o w ev er, n o n e o f th ese ru l es are h ard req u i rem en ts. I n deed, H i bern ate3
assu m es v ery l i ttl e abo u t th e n atu re o f yo u r p ersi sten t o bj ec ts. Y o u c an ex p ress a do m ai n m o del i n o th er
w ays (u si n g trees o f M ap i n stan c es, fo r ex am p l e).
4 .1 . A s imp l e P O J O ex amp l e
M o st J av a ap p l i c ati o n s req u i re a p ersi sten t c l ass rep resen ti n g fel i n es. F o r ex am p l e:
4 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
pack age eg;

impo rt j av a. u til . Set;
pu b l ic cl as s C at {
priv ate L o ng id; / / identif ier
priv ate D ate b irth date;

priv ate C o l o r co l o r;
priv ate ch ar s ex ;
priv ate f l o at w eigh t;
priv ate int l itterI d;
priv ate C at mo th er;

priv ate Set k ittens = new H as h Set( );

th is . id=id;
}
retu rn id;
}
v o id s etB irth date( D ate date) {

b irth date = date;
}
pu b l ic D ate getB irth date( ) {
retu rn b irth date;
}
v o id s etW eigh t( f l o at w eigh t) {

th is . w eigh t = w eigh t;
}
pu b l ic f l o at getW eigh t( ) {
retu rn w eigh t;
}
pu b l ic C o l o r getC o l o r( ) {
retu rn co l o r;
}
v o id s etC o l o r( C o l o r co l o r) {
th is . co l o r = co l o r;
}
v o id s etSex ( ch ar s ex ) {
th is . s ex =s ex ;
}
pu b l ic ch ar getSex ( ) {
retu rn s ex ;
}
v o id s etL itterI d( int id) {

th is . l itterI d = id;
}
pu b l ic int getL itterI d( ) {
retu rn l itterI d;
}
v o id s etM o th er( C at mo th er) {

th is . mo th er = mo th er;
}
4 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h e fo u r m ai n ru l es o f p ersi sten t c l asses are ex p l o red i n m o re detai l i n th e fo l l o w i n g sec ti o n s.
4 . 1 . 1 . Impl e me nt a no- arg u me nt c ons tru c tor
C at h as a n o - argu m en t c o n stru c to r. A l l p ersi sten t c l asses m u st h av e a defau l t c o n stru c to r (w h i c h c an be

n o n - p u bl i c ) so th at H i bern ate c an i n stan ti ate th em u si n g C o ns tru cto r. new I ns tance( ). I t i s rec o m m en ded th at
yo u h av e a defau l t c o n stru c to r w i th at l east p ac k ag e v i si bi l i ty fo r ru n ti m e p ro x y gen erati o n i n H i bern ate.
4 . 1 . 2 . P rov i d e an i d e nti f i e r prope rty ( opti onal )
C at h as a p ro p erty c al l ed id. T h i s p ro p erty m ap s to th e p ri m ary k ey c o l u m n o f a database tabl e. T h e p ro p erty

m i gh t h av e been c al l ed an yth i n g, an d i ts typ e m i gh t h av e been an y p ri m i ti v e typ e, an y p ri m i ti v e " w rap p er"
typ e, j av a. l ang. String o r j av a. u til . D ate. I f yo u r l egac y database tabl e h as c o m p o si te k eys, yo u c an u se a
u ser- defi n ed c l ass w i th p ro p erti es o f th ese typ es (see th e sec ti o n o n c o m p o si te i den ti fi ers l ater i n th e
c h ap ter.)
T h e i den ti fi er p ro p erty i s stri c tl y o p ti o n al . Y o u c an l eav e th em o ff an d l et H i bern ate k eep trac k o f o bj ec t

i den ti fi ers i n tern al l y. W e do n o t rec o m m en d th i s, h o w ev er.
I n fac t, so m e fu n c ti o n al i ty i s av ai l abl e o n l y to c l asses th at dec l are an i den ti fi er p ro p erty:
T ran si ti v e reattac h m en t fo r detac h ed o bj ec ts (c asc ade u p date o r c asc ade m erge) - see S ec ti o n 1 0 .1 1 ,
“ T ran si ti v e p ersi sten c e”
Ses s io n. s av eO rU pdate( )
Ses s io n. merge( )
W e rec o m m en d th at yo u dec l are c o n si sten tl y- n am ed i den ti fi er p ro p erti es o n p ersi sten t c l asses an d th at yo u

u se a n u l l abl e (i .e., n o n - p ri m i ti v e) typ e.
4 . 1 . 3 . P re f e r non- f i nal c l as s e s ( opti onal )
A c en tral featu re o f H i bern ate, p rox ie s , dep en ds u p o n th e p ersi sten t c l ass bei n g ei th er n o n - fi n al , o r th e
im p l em en tati o n o f an i n terfac e th at dec l ares al l p u bl i c m eth o ds.
Y o u c an p ersi st f inal c l asses th at do n o t im p l em en t an i n terfac e w i th H i bern ate. Y o u w i l l n o t, h o w ev er, be

abl e to u se p ro x i es fo r l az y asso c i ati o n fetc h i n g w h i c h w i l l u l ti m atel y l i m i t yo u r o p ti o n s fo r p erfo rm an c e
tu n i n g.
Y o u sh o u l d al so av o i d dec l ari n g pu b l ic f inal m eth o ds o n th e n o n - fi n al c l asses. I f yo u w an t to u se a c l ass w i th a

pu b l ic f inal m eth o d, yo u m u st ex p l i c i tl y di sabl e p ro x yi n g by setti n g l az y=" f al s e" .
4 . 1 . 4 . D e c l are ac c e s s ors and mu tators f or pe rs i s te nt f i e l d s ( opti onal )
C at dec l ares ac c esso r m eth o ds fo r al l i ts p ersi sten t fi el ds. M an y o th er O R M to o l s di rec tl y p ersi st i n stan c e
v ari abl es. I t i s better to p ro v i de an i n di rec ti o n betw een th e rel ati o n al sc h em a an d i n tern al data stru c tu res o f
th e c l ass. B y defau l t, H i bern ate p ersi sts J av aB ean s styl e p ro p erti es an d rec o gn i z es m eth o d n am es o f th e
fo rm getF o o , is F o o an d s etF o o . I f req u i red, yo u c an sw i tc h to di rec t fi el d ac c ess fo r p arti c u l ar p ro p erti es.
P ro p erti es n eed not be dec l ared p u bl i c - H i bern ate c an p ersi st a p ro p erty w i th a defau l t, pro tected o r priv ate
get / set p ai r.
4 . 2 . I mp l ementing inh eritance

A su bc l ass m u st al so o bserv e th e fi rst an d sec o n d ru l es. I t i n h eri ts i ts i den ti fi er p ro p erty fro m th e su p erc l ass,
C at . F o r ex am p l e:
4 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
pack age eg;
pu b l ic cl as s D o mes ticC at ex tends C at {

priv ate String name;
pu b l ic String getName( ) {
retu rn name;
}
pro tected v o id s etName( String name) {
th is . name=name;
}
}
4 . 3 . I mp l ementing eq u al s ( ) and h as h C o d e( )
Y o u h av e to o v erri de th e eq u al s ( ) an d h as h C o de( ) m eth o ds i f yo u :
i n ten d to p u t i n stan c es o f p ersi sten t c l asses i n a Set (th e rec o m m en ded w ay to rep resen t m an y- v al u ed
asso c i ati o n s); and
i n ten d to u se reattac h m en t o f detac h ed i n stan c es
H i bern ate gu aran tees eq u i v al en c e o f p ersi sten t i den ti ty (database ro w ) an d J av a i den ti ty o n l y i n si de a

p arti c u l ar sessi o n sc o p e. W h en yo u m i x i n stan c es retri ev ed i n di fferen t sessi o n s, yo u m u st i m p l em en t
eq u al s ( ) an d h as h C o de( ) i f yo u w i sh to h av e m ean i n gfu l sem an ti c s fo r Set s.
T h em o st o bv i o u s w ay i s to i m p l em en t eq u al s ( )/h as h C o de( ) by c o m p ari n g th e i den ti fi er v al u e o f bo th o bj ec ts.

I f th e v al u e i s th e sam e, bo th m u st be th e sam e database ro w , bec au se th ey are eq u al . I f bo th are added to
a Set , yo u w i l l o n l y h av e o n e el em en t i n th e Set ). U n fo rtu n atel y, yo u c an n o t u se th at ap p ro ac h w i th
gen erated i den ti fi ers. H i bern ate w i l l o n l y assi gn i den ti fi er v al u es to o bj ec ts th at are p ersi sten t; a n ew l y
c reated i n stan c e w i l l n o t h av e an y i den ti fi er v al u e. F u rth erm o re, i f an i n stan c e i s u n sav ed an d c u rren tl y i n a
Set , sav i n g i t w i l l assi gn an i den ti fi er v al u e to th e o bj ec t. I f eq u al s ( ) an d h as h C o de( ) are based o n th e i den ti fi er
v al u e, th e h ash c o de w o u l d c h an ge, break i n g th e c o n trac t o f th e Set . S ee th e H i bern ate w ebsi te fo r a fu l l
di sc u ssi o n o f th i s p ro bl em . T h i s i s n o t a H i bern ate i ssu e, bu t n o rm al J av a sem an ti c s o f o bj ec t i den ti ty an d
eq u al i ty.
I t i s rec o m m en ded th at yo u i m p l em en t eq u al s ( ) an d h as h C o de( ) u si n g B us ine s s k e y e q uality . B u si n ess k ey

eq u al i ty m ean s th at th e eq u al s ( ) m eth o d c o m p ares o n l y th e p ro p erti es th at fo rm th e bu si n ess k ey. I t i s a k ey
th at w o u l d i den ti fy o u r i n stan c e i n th e real w o rl d (a natural c an di date k ey):
4 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
...
pu b l ic b o o l ean eq u al s ( O b j ect o th er) {
if ( th is == o th er) retu rn tru e;
if ( ! ( o th er ins tanceo f C at) ) retu rn f al s e;
f inal C at cat = ( C at) o th er;
if ( ! cat. getL itterI d( ). eq u al s ( getL itterI d( ) ) ) retu rn f al s e;

if ( ! cat. getM o th er( ). eq u al s ( getM o th er( ) ) ) retu rn f al s e;
retu rn tru e;
}
pu b l ic int h as h C o de( ) {
int res u l t;
res u l t = getM o th er( ). h as h C o de( );
res u l t = 2 9 * res u l t + getL itterI d( );
retu rn res u l t;
}
A bu si n ess k ey do es n o t h av e to be as so l i d as a database p ri m ary k ey c an di date (see S ec ti o n 1 1 .1 .3 ,

“ Co n si deri n g o bj ec t i den ti ty” ). I m m u tabl e o r u n i q u e p ro p erti es are u su al l y go o d c an di dates fo r a bu si n ess
k ey.
4 . 4 . Dy namic mod el s
N ote
Th e f ollow ing f e ature s are c urre ntly c ons id e re d e x p e rim e ntal and m ay c h ang e in th e ne ar
f uture .
P ersi sten t en ti ti es do n o t n ec essari l y h av e to be rep resen ted as P O J O c l asses o r as J av aB ean o bj ec ts at

ru n ti m e. H i bern ate al so su p p o rts dyn am i c m o del s (u si n g M ap s o f M ap s at ru n ti m e) an d th e rep resen tati o n o f
en ti ti es as D O M 4 J trees. W i th th i s ap p ro ac h , yo u do n o t w ri te p ersi sten t c l asses, o n l y m ap p i n g fi l es.
B y defau l t, H i bern ate w o rk s i n n o rm al P O J O m o de. Y o u c an set a defau l t en ti ty rep resen tati o n m o de fo r a

p arti c u l ar Ses s io nF acto ry u si n g th e def au l t_ entity_ mo de c o n fi gu rati o n o p ti o n (see T abl e 3 .3 , “ H i bern ate
Co n fi gu rati o n P ro p erti es” ).
T h e fo l l o w i n g ex am p l es dem o n strate th e rep resen tati o n u si n g M ap s. F i rst, i n th e m ap p i n g fi l e an entityname

h as to be dec l ared i n stead o f, o r i n addi ti o n to , a c l ass n am e:
4 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< h ib ernate- mapping>
< cl as s entityname=" C u s to mer" >
< id name=" id"

type=" l o ng"
co l u mn=" I D " >
< generato r cl as s =" s eq u ence" / >
< / id>
< pro perty name=" name"

co l u mn=" NA M E "
type=" s tring" / >
< pro perty name=" addres s "

co l u mn=" A D D R E SS"
type=" s tring" / >
< many- to - o ne name=" o rganiz atio n"

co l u mn=" O R G A NI Z A T I O N_ I D "
cl as s =" O rganiz atio n" / >

< k ey co l u mn=" C U ST O M E R _ I D " / >
< o ne- to - many cl as s =" O rder" / >

< / cl as s >
E v en th o u gh asso c i ati o n s are dec l ared u si n g target c l ass n am es, th e target typ e o f asso c i ati o n s c an al so be a
dyn am i c en ti ty i n stead o f a P O J O .
A fter setti n g th e defau l t en ti ty m o de to dynamic- map fo r th e Ses s io nF acto ry, yo u c an , at ru n ti m e, w o rk w i th

M aps o f M ap s:
5 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
Ses s io n s = o penSes s io n( );
T rans actio n tx = s . b eginT rans actio n( );
Ses s io n s = o penSes s io n( );
/ / C reate a cu s to mer
M ap dav id = new H as h M ap( );
dav id. pu t( " name" , " D av id" );
/ / C reate an o rganiz atio n

M ap f o o b ar = new H as h M ap( );
f o o b ar. pu t( " name" , " F o o b ar I nc. " );
/ / L ink b o th
dav id. pu t( " o rganiz atio n" , f o o b ar);
/ / Sav e b o th
s . s av e( " C u s to mer" , dav id);
s . s av e( " O rganiz atio n" , f o o b ar);
tx . co mmit( );
s . cl o s e( );
O n e o f th e m ai n adv an tages o f dyn am i c m ap p i n g i s q u i c k tu rn aro u n d ti m e fo r p ro to typ i n g, w i th o u t th e n eed

fo r en ti ty c l ass i m p l em en tati o n . H o w ev er, yo u l o se c o m p i l e- ti m e typ e c h ec k i n g an d w i l l l i k el y deal w i th
m an y ex c ep ti o n s at ru n ti m e. A s a resu lt o f th e H i bern ate m ap p i n g, th e database sc h em a c an easi l y be
n o rm al i z ed an d so u n d, al l o w i n g to add a p ro p er do m ai n m o del i m p l em en tati o n o n to p l ater o n .
E n ti ty rep resen tati o n m o des c an al so be set o n a p er Ses s io n basi s:
Ses s io n dynamicSes s io n = po j o Ses s io n. getSes s io n( E ntityM o de. M A P );
/ / C reate a cu s to mer
M ap dav id = new H as h M ap( );
dav id. pu t( " name" , " D av id" );
dynamicSes s io n. s av e( " C u s to mer" , dav id);
...
dynamicSes s io n. f l u s h ( );
dynamicSes s io n. cl o s e( )
...
/ / C o ntinu e o n po j o Ses s io n
P l ease n o te th at th e c al l to getSes s io n( ) u si n g an E ntityM o de i s o n th e Ses s io n A P I , n o t th e Ses s io nF acto ry. T h at

w ay, th e n ew Ses s io n sh ares th e u n derl yi n g J D B C c o n n ec ti o n , tran sac ti o n , an d o th er c o n tex t i n fo rm ati o n .
T h i s m ean s yo u do n o t h av e to c al l f l u s h ( ) an d cl o s e( ) o n th e sec o n dary Ses s io n, an d al so l eav e th e tran sac ti o n
an d c o n n ec ti o n h an dl i n g to th e p ri m ary u n i t o f w o rk .
M o re i n fo rm ati o n abo u t th e X M L rep resen tati o n c ap abi l i ti es c an be fo u n d i n Ch ap ter 1 8 , X M L M ap p ing .
4 . 5 . T up l iz ers
o rg. h ib ernate. tu pl e. T u pl iz er, an d i ts su b- i n terfac es, are resp o n si bl e fo r m an agi n g a p arti c u l ar rep resen tati o n o f
a p i ec e o f data gi v en th at rep resen tati o n ' s o rg. h ib ernate. E ntityM o de . I f a gi v en p i ec e o f data i s th o u gh t o f as a
data stru c tu re, th en a tu p l i z er i s th e th i n g th at k n o w s h o w to c reate su c h a data stru c tu re an d h o w to ex trac t
v al u es fro m an d i n j ec t v al u es i n to su c h a data stru c tu re. F o r ex am p l e, fo r th e P O J O en ti ty m o de, th e
c o rresp o n di n g tu p l i z er k n o w s h o w c reate th e P O J O th ro u gh i ts c o n stru c to r. I t al so k n o w s h o w to ac c ess th e
P O J O p ro p erti es u si n g th e defi n ed p ro p erty ac c esso rs.
T h ere are tw o h i gh - l ev el typ es o f T u p l i z ers, rep resen ted by th e o rg. h ib ernate. tu pl e. entity. E ntityT u pl iz er an d
o rg. h ib ernate. tu pl e. co mpo nent. C o mpo nentT u pl iz er i n terfac es. E ntityT u pl iz ers are resp o n si bl e fo r m an agi n g th e
abo v e m en ti o n ed c o n trac ts i n regards to en ti ti es, w h i l e C o mpo nentT u pl iz ers do th e sam e fo r c o m p o n en ts.
5 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
U sers c an al so p l u g i n th ei r o w n tu p l i z ers. P erh ap s yo u req u i re th at a j av a. u til . M ap i m p l em en tati o n o th er th an

j av a. u til . H as h M ap be u sed w h i l e i n th e dyn am i c - m ap en ti ty- m o de. O r p erh ap s yo u n eed to defi n e a di fferen t
p ro x y gen erati o n strategy th an th e o n e u sed by defau l t. B o th w o u l d be ac h i ev ed by defi n i n g a c u sto m
tu p l i z er i m p l em en tati o n . T u p l i z er defi n i ti o n s are attac h ed to th e en ti ty o r c o m p o n en t m ap p i n g th ey are
m ean t to m an age. G o i n g bac k to th e ex am p l e o f o u r c u sto m er en ti ty:

< cl as s entityname=" C u s to mer" >
< !- -
O v erride th e dynamic- map entity- mo de
tu pl iz er f o r th e cu s to mer entity
- - >
< tu pl iz er entity- mo de=" dynamic- map"
cl as s =" C u s to mM apT u pl iz erI mpl " / >
< id name=" id" type=" l o ng" co l u mn=" I D " >

< / id>
< ! - - o th er pro perties - - >

...
< / cl as s >
pu b l ic cl as s C u s to mM apT u pl iz erI mpl

ex tends o rg. h ib ernate. tu pl e. entity. D ynamicM apE ntityT u pl iz er {
/ / o v erride th e b u il dI ns tantiato r( ) meth o d to pl u g in o u r cu s to m map. . .
pro tected f inal I ns tantiato r b u il dI ns tantiato r(
o rg. h ib ernate. mapping. P ers is tentC l as s mappingI nf o ) {
retu rn new C u s to mM apI ns tantiato r( mappingI nf o );
}
priv ate s tatic f inal cl as s C u s to mM apI ns tantiato r

ex tends o rg. h ib ernate. tu pl e. D ynamicM apI ns tantito r {
/ / o v erride th e generateM ap( ) meth o d to retu rn o u r cu s to m map. . .
pro tected f inal M ap generateM ap( ) {
retu rn new C u s to mM ap( );
}
}
}
4 . 6 . E ntity N ameRes ol v ers

T h e o rg. h ib ernate. E ntityNameR es o l v er i n terfac e i s a c o n trac t fo r reso l v i n g th e en ti ty n am e o f a gi v en en ti ty
i n stan c e. T h e i n terfac e defi n es a si n gl e m eth o d res o l v eE ntityName w h i c h i s p assed th e en ti ty i n stan c e an d i s
ex p ec ted to retu rn th e ap p ro p ri ate en ti ty n am e (n u l l i s al l o w ed an d w o u l d i n di c ate th at th e reso l v er do es n o t
k n o w h o w to reso l v e th e en ti ty n am e o f th e gi v en en ti ty i n stan c e). G en eral l y sp eak i n g, an
o rg. h ib ernate. E ntityNameR es o l v er i s go i n g to be m o st u sefu l i n th e c ase o f dyn am i c m o del s. O n e ex am p l e m i gh t
be u si n g p ro x i ed i n terfac es as yo u r do m ai n m o del . T h e h i bern ate test su i te h as an ex am p l e o f th i s ex ac t
styl e o f u sage u n der th e o rg.h i bern ate.test.dyn am i c en ti ty.tu p l i z er2. H ere i s so m e o f th e c o de fro m th at
p ac k age fo r i l l u strati o n .
5 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
/ **
*A v ery triv ial J D K P ro x y I nv o catio nH andl er impl ementatio n w h ere w e pro x y an interf ace as
* th e do main mo del and s impl y s to re pers is tent s tate in an internal M ap. T h is is an ex tremel y
* triv ial ex ampl e meant o nl y f o r il l u s tratio n.
*/
pu b l ic f inal cl as s D ataP ro x yH andl er impl ements I nv o catio nH andl er {
priv ate String entityName;
priv ate H as h M ap data = new H as h M ap( );
pu b l ic D ataP ro x yH andl er( String entityName, Serial iz ab l e id) {

th is . entityName = entityName;
data. pu t( " I d" , id );
}
pu b l ic O b j ect inv o k e( O b j ect pro x y, M eth o d meth o d, O b j ect[ ] args ) th ro w s T h ro w ab l e {

String meth o dName = meth o d. getName( );
if ( meth o dName. s tarts W ith ( " s et" ) ) {
String pro pertyName = meth o dName. s u b s tring( 3 );
data. pu t( pro pertyName, args [ 0] );
}
el s e if ( meth o dName. s tarts W ith ( " get" ) ) {
String pro pertyName = meth o dName. s u b s tring( 3 );
retu rn data. get( pro pertyName );
}
el s e if ( " to String" . eq u al s ( meth o dName ) ) {
retu rn entityName + " # " + data. get( " I d" );
}
el s e if ( " h as h C o de" . eq u al s ( meth o dName ) ) {
retu rn new I nteger( th is . h as h C o de( ) );
}
retu rn nu l l ;
}
pu b l ic String getE ntityName( ) {

retu rn entityName;
}
pu b l ic H as h M ap getD ata( ) {
retu rn data;
}
}
/ **
*
*/
pu b l ic cl as s P ro x yH el per {
pu b l ic s tatic String ex tractE ntityName( O b j ect o b j ect) {
/ / O u r cu s to m j av a. l ang. ref l ect. P ro x y ins tances actu al l y b u ndl e
/ / th eir appro priate entity name, s o w e s impl y ex tract it f ro m th ere
/ / if th is repres ents o ne o f o u r pro x ies ; o th erw is e, w e retu rn nu l l
if ( P ro x y. is P ro x yC l as s ( o b j ect. getC l as s ( ) ) ) {
I nv o catio nH andl er h andl er = P ro x y. getI nv o catio nH andl er( o b j ect );
if ( D ataP ro x yH andl er. cl as s . is A s s ignab l eF ro m( h andl er. getC l as s ( ) ) ) {
D ataP ro x yH andl er myH andl er = ( D ataP ro x yH andl er ) h andl er;
retu rn myH andl er. getE ntityName( );
}
}
retu rn nu l l ;
}
/ / v ario u s o th er u til ity meth o ds . . . .
5 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I n o rder to regi ster an o rg. h ib ernate. E ntityNameR es o l v er u sers m u st ei th er:
1 . I m p l em en t a c u sto m T u p l i z er, i m p l em en ti n g th e getE ntityNameR es o l v ers m eth o d.
2. R egi ster i t w i th th e o rg. h ib ernate. impl . Ses s io nF acto ryI mpl (w h i c h i s th e i m p l em en tati o n c l ass fo r
o rg. h ib ernate. Ses s io nF acto ry) u si n g th e regis terE ntityNameR es o l v er m eth o d.
C h ap ter 5 . B as ic O / R M ap p ing
5 .1 . M ap p i n g dec l arati o n
5 .1 .1 . D o c typ e
5 .1 .2. H i bern ate- m ap p i n g
5 .1 .3 . Cl ass
5 .1 .4 . i d
5 .1 .5 . E n h an c ed i den ti fi er gen erato rs
5 .1 .6 . I den ti fi er gen erato r o p ti m i z ati o n
5 .1 .7 . c o m p o si te- i d
5 .1 .8 . D i sc ri m i n ato r
5 .1 .9 . V ersi o n (o p ti o n al )
5 .1 .1 0 . T i m estam p (o p ti o n al )
5 .1 .1 1 . P ro p erty
5 .1 .1 2. M an y- to - o n e
5 .1 .1 3 . O n e- to - o n e
5 .1 .1 4 . N atu ral - i d
5 .1 .1 5 . Co m p o n en t an d dyn am i c - c o m p o n en t
5 .1 .1 6 . P ro p erti es
5 .1 .1 7 . S u bc l ass
5 .1 .1 8 . J o i n ed- su bc l ass
5 .1 .1 9 . U n i o n - su bc l ass
5 .1 .20 . J o i n
5 .1 .21 . K ey
5 .1 .22. Co l u m n an d fo rm u l a el em en ts
5 .1 .23 . I m p o rt
5 .1 .24 . A n y
5 .2. H i bern ate typ es
5 .2.1 . E n ti ti es an d v al u es
5 .2.2. B asi c v al u e typ es
5 .2.3 . Cu sto m v al u e typ es
5 .3 . M ap p i n g a c l ass m o re th an o n c e
5 .4 . S Q L q u o ted i den ti fi ers
5 .5 . M etadata al tern ati v es
5 .5 .1 . U si n g X D o c l et m ark u p
5 .5 .2. U si n g J D K 5 .0 A n n o tati o n s
5 .6 . G en erated p ro p erti es
5 .7 . A u x i l i ary database o bj ec ts
5 . 1 . M ap p ing d ecl aration

O bj ec t/rel ati o n al m ap p i n gs are u su al l y defi n ed i n an X M L do c u m en t. T h e m ap p i n g do c u m en t i s desi gn ed to
be readabl e an d h an d- edi tabl e. T h e m ap p i n g l an gu age i s J av a- c en tri c , m ean i n g th at m ap p i n gs are
c o n stru c ted aro u n d p ersi sten t c l ass dec l arati o n s an d n o t tabl e dec l arati o n s.
P l ease n o te th at ev en th o u gh m an y H i bern ate u sers c h o o se to w ri te th e X M L by h an d, a n u m ber o f to o l s

ex i st to gen erate th e m ap p i n g do c u m en t. T h ese i n c l u de X D o c l et, M i ddl egen an d A n dro M D A .
H ere i s an ex am p l e m ap p i n g:
5 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< ?x ml v ers io n=" 1. 0" ?>

< h ib ernate- mapping pack age=" eg" >
< cl as s name=" C at"

tab l e=" cats "
dis criminato r- v al u e=" C " >
< id name=" id" >

< / id>
< dis criminato r co l u mn=" s u b cl as s "

type=" ch aracter" / >
< pro perty name=" w eigh t" / >
< pro perty name=" b irth date"

type=" date"
no t- nu l l =" tru e"
u pdate=" f al s e" / >
< pro perty name=" co l o r"

type=" eg. types . C o l o rU s erT ype"
< pro perty name=" s ex "

< pro perty name=" l itterI d"

co l u mn=" l itterI d"
< many- to - o ne name=" mo th er"

co l u mn=" mo th er_ id"
< s et name=" k ittens "

inv ers e=" tru e"
o rder- b y=" l itter_ id" >
< k ey co l u mn=" mo th er_ id" / >
< o ne- to - many cl as s =" C at" / >
< / s et>
< s u b cl as s name=" D o mes ticC at"

dis criminato r- v al u e=" D " >

type=" s tring" / >
< / s u b cl as s >
< / cl as s >
< cl as s name=" D o g" >

< ! - - mapping f o r D o g co u l d go h ere - - >
5 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
W e w i l l n o w di sc u ss th e c o n ten t o f th e m ap p i n g do c u m en t. W e w i l l o n l y desc ri be, h o w ev er, th e do c u m en t

el em en ts an d attri bu tes th at are u sed by H i bern ate at ru n ti m e. T h e m ap p i n g do c u m en t al so c o n tai n s so m e
ex tra o p ti o n al attri bu tes an d el em en ts th at affec t th e database sc h em as ex p o rted by th e sc h em a ex p o rt to o l
(fo r ex am p l e, th e no t- nu l l attri bu te).
5 . 1 . 1 . D oc ty pe
A l l X M L m ap p i n gs sh o u l d dec l are th e do c typ e sh o w n . T h e ac tu al D T D c an be fo u n d at th e U R L abo v e, i n th e

di rec to ry h ib ernate- x . x . x / s rc/ o rg/ h ib ernate , o r i n h ib ernate3. j ar. H i bern ate w i l l al w ays l o o k fo r th e D T D i n i ts
c l assp ath fi rst. I f yo u ex p eri en c e l o o k u p s o f th e D T D u si n g an I n tern et c o n n ec ti o n , c h ec k th e D T D dec l arati o n
agai n st th e c o n ten ts o f yo u r c l assp ath .
5.1.1.1. EntityResolver
H i bern ate w i l l fi rst attem p t to reso l v e D T D s i n i ts c l assp ath . I t do es th i s i s by regi steri n g a c u sto m
o rg. x ml . s ax . E ntityR es o l v er i m p l em en tati o n w i th th e S A X R eader i t u ses to read i n th e x m l fi l es. T h i s c u sto m
E ntityR es o l v er rec o gn i z es tw o di fferen t system I d n am esp ac es:
a h ib ernate names pace i s rec o gn i z ed w h en ev er th e reso l v er en c o u n ters a system I d starti n g w i th

h ttp: / / h ib ernate. s o u rcef o rge. net/ . T h e reso l v er attem p ts to reso l v e th ese en ti ti es v i a th e c l assl o ader w h i c h
l o aded th e H i bern ate c l asses.
a u s er names pace i s rec o gn i z ed w h en ev er th e reso l v er en c o u n ters a system I d u si n g a cl as s path : / / U R L
p ro to c o l . T h e reso l v er w i l l attem p t to reso l v e th ese en ti ti es v i a (1 ) th e c u rren t th read c o n tex t c l assl o ader
an d (2) th e c l assl o ader w h i c h l o aded th e H i bern ate c l asses.
T h e fo l l o w i n g i s an ex am p l e o f u ti l i z i n g u ser n am esp ac i n g:
< ?x ml v ers io n=" 1. 0" ?>

" h ttp: / / h ib ernate. s o u rcef o rge. net/ h ib ernate- mapping- 3. 0. dtd" [
< ! E NT I T Y types SY ST E M " cl as s path : / / yo u r/ do main/ types . x ml " >
] >
< h ib ernate- mapping pack age=" yo u r. do main" >

< cl as s name=" M yE ntity" >
< id name=" id" type=" my- cu s to m- id- type" >
...
< / id>
< cl as s >
& types ;
W h ere types . x ml i s a reso u rc e i n th e yo u r. do main p ac k age an d c o n tai n s a c u sto m typ edef.
5 . 1 . 2 . H i b e rnate - mappi ng
T h i s el em en t h as sev eral o p ti o n al attri bu tes. T h e s ch ema an d catal o g attri bu tes sp ec i fy th at tabl es referred to
i n th i s m ap p i n g bel o n g to th e n am ed sc h em a an d/o r c atal o g. I f th ey are sp ec i fi ed, tabl en am es w i l l be
q u al i fi ed by th e gi v en sc h em a an d c atal o g n am es. I f th ey are m i ssi n g, tabl en am es w i l l be u n q u al i fi ed. T h e
def au l t- cas cade attri bu te sp ec i fi es w h at c asc ade styl e sh o u l d be assu m ed fo r p ro p erti es an d c o l l ec ti o n s th at do
n o t sp ec i fy a cas cade attri bu te. B y defau l t, th e au to - impo rt attri bu te al l o w s yo u to u se u n q u al i fi ed c l ass n am es
i n th e q u ery l an gu age.
5 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< h ib ernate- mapping

s ch ema=" s ch emaName"
catal o g=" catal o gName"
def au l t- cas cade=" cas cade_ s tyl e"
def au l t- acces s =" f iel d| pro perty| C l as s Name"
def au l t- l az y=" tru e| f al s e"
au to - impo rt=" tru e| f al s e"
pack age=" pack age. name"
/ >
s ch ema (o p ti o n al ): th e n am e o f a database sc h em a.
catal o g (o p ti o n al ): th e n am e o f a database c atal o g.
def au l t- cas cade (o p ti o n al - defau l ts to no ne): a defau l t c asc ade styl e.
def au l t- acces s (o p ti o n al - defau l ts to pro perty): th e strategy H i bern ate sh o u l d u se fo r ac c essi n g al l

p ro p erti es. I t c an be a c u sto m im p l em en tati o n o f P ro pertyA cces s o r.
def au l t- l az y (o p ti o n al - defau l ts to tru e ): th e defau l t v al u e fo r u n sp ec i fi ed l az y attri bu tes o f c l ass an d
c o l l ec ti o n m ap p i n gs.
au to - impo rt (o p ti o n al - defau l ts to tru e): sp ec i fi es w h eth er w e c an u se u n q u al i fi ed c l ass n am es o f
c l asses i n th i s m ap p i n g i n th e q u ery l an gu age.
pack age (o p ti o n al ): sp ec i fi es a p ac k age p refi x to u se fo r u n q u al i fi ed c l ass n am es i n th e m ap p i n g
do c u m en t.
I f yo u h av e tw o p ersi sten t c l asses w i th th e sam e u n q u al i fi ed n am e, yo u sh o u l d set au to - impo rt=" f al s e" . A n

ex c ep ti o n w i l l resu l t i f yo u attem p t to assi gn tw o c l asses to th e sam e " i m p o rted" n am e.
T h e h ib ernate- mapping el em en t al l o w s yo u to n est sev eral p ersi sten t < cl as s > m ap p i n gs, as sh o w n abo v e. I t i s,
h o w ev er, go o d p rac ti c e (an d ex p ec ted by so m e to o l s) to m ap o n l y a si n gl e p ersi sten t c l ass, o r a si n gl e c l ass
h i erarc h y, i n o n e m ap p i n g fi l e an d n am e i t after th e p ersi sten t su p erc l ass. F o r ex am p l e, C at. h b m. x ml ,
D o g. h b m. x ml , o r i f u si n g i n h eri tan c e, A nimal . h b m. x ml .
5 . 1 . 3 . C l as s
Y o u c an dec l are a p ersi sten t c l ass u si n g th e cl as s el em en t. F o r ex am p l e:
< cl as s
name=" C l as s Name"
tab l e=" tab l eName"
dis criminato r- v al u e=" dis criminato r_ v al u e"
mu tab l e=" tru e| f al s e"
s ch ema=" o w ner"
catal o g=" catal o g"
pro x y=" P ro x yI nterf ace"
dynamic- u pdate=" tru e| f al s e"
dynamic- ins ert=" tru e| f al s e"
s el ect- b ef o re- u pdate=" tru e| f al s e"
po l ymo rph is m=" impl icit| ex pl icit"
w h ere=" arb itrary s q l w h ere co nditio n"
pers is ter=" P ers is terC l as s "
b atch - s iz e=" N"
o ptimis tic- l o ck =" no ne| v ers io n| dirty| al l "
l az y=" tru e| f al s e"
entityname=" E ntityName"
ch eck =" arb itrary s q l ch eck co nditio n"
ro w id=" ro w id"
s u b s el ect=" SQ L ex pres s io n"
ab s tract=" tru e| f al s e"
no de=" el ement- name"
/ >
5 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
name (o p ti o n al ): th e fu l l y q u al i fi ed J av a c l ass n am e o f th e p ersi sten t c l ass o r i n terfac e. I f th i s

attri bu te i s m i ssi n g, i t i s assu m ed th at th e m ap p i n g i s fo r a n o n - P O J O en ti ty.
tab l e (o p ti o n al - defau l ts to th e u n q u al i fi ed c l ass n am e): th e n am e o f i ts database tabl e.
dis criminato r- v al u e (o p ti o n al - defau l ts to th e c l ass n am e): a v al u e th at di sti n gu i sh es i n di v i du al

su bc l asses th at i s u sed fo r p o l ym o rp h i c beh av i o r. A c c ep tabl e v al u es i n c l u de nu l l an d no t nu l l .
mu tab l e (o p ti o n al - defau l ts to tru e): sp ec i fi es th at i n stan c es o f th e c l ass are (n o t) m u tabl e.
s ch ema (o p ti o n al ): o v erri des th e sc h em a n am e sp ec i fi ed by th e ro o t < h ib ernate- mapping> el em en t.
catal o g (o p ti o n al ): o v erri des th e c atal o g n am e sp ec i fi ed by th e ro o t < h ib ernate- mapping> el em en t.
pro x y (o p ti o n al ): sp ec i fi es an i n terfac e to u se fo r l az y i n i ti al i z i n g p ro x i es. Y o u c an sp ec i fy th e n am e o f

th e c l ass i tsel f.
dynamic- u pdate (o p ti o n al - defau l ts to f al s e): sp ec i fi es th at U P D A T E S Q L sh o u l d be gen erated at
ru n ti m e an d c an c o n tai n o n l y th o se c o l u m n s w h o se v al u es h av e c h an ged.
dynamic- ins ert (o p ti o n al - defau l ts to f al s e ): sp ec i fi es th at I NSE R T S Q L sh o u l d be gen erated at ru n ti m e
an d c o n tai n o n l y th e c o l u m n s w h o se v al u es are n o t n u l l .
s el ect- b ef o re- u pdate (o p ti o n al - defau l ts to f al s e): sp ec i fi es th at H i bern ate sh o u l d ne v e r p erfo rm an
S Q L U P D A T E u n l ess i t i s c ertai n th at an o bj ec t i s ac tu al l y m o di fi ed. O n l y w h en a tran si en t o bj ec t h as
been asso c i ated w i th a n ew sessi o n u si n g u pdate( ), w i l l H i bern ate p erfo rm an ex tra S Q L SE L E C T to
determ i n e i f an U P D A T E i s ac tu al l y req u i red.
po l ymo rph is m (o p ti o n al - defau l ts to impl icit ): determ i n es w h eth er i m p l i c i t o r ex p l i c i t q u ery
p o l ym o rp h i sm i s u sed.
1 2 w h ere (o p ti o n al ): sp ec i fi es an arbi trary S Q L W H E R E c o n di ti o n to be u sed w h en retri ev i n g o bj ec ts o f
th i s c l ass.
pers is ter (o p ti o n al ): sp ec i fi es a c u sto m C l as s P ers is ter.
b atch - s iz e (o p ti o n al - defau l ts to 1): sp ec i fi es a " batc h si z e" fo r fetc h i n g i n stan c es o f th i s c l ass by

i den ti fi er.
o ptimis tic- l o ck (o p ti o n al - defau l ts to v ers io n): determ i n es th e o p ti m i sti c l o c k i n g strategy.
(1 6 ) l az y (o p ti o n al ): l az y fetc h i n g c an be di sabl ed by setti n g l az y=" f al s e" .

(1 7 ) entityname (o p ti o n al - defau l ts to th e c l ass n am e): H i bern ate3 al l o w s a c l ass to be m ap p ed m u l ti p l e
ti m es, p o ten ti al l y to di fferen t tabl es. I t al so al l o w s en ti ty m ap p i n gs th at are rep resen ted by M ap s o r
X M L at th e J av a l ev el . I n th ese c ases, yo u sh o u l d p ro v i de an ex p l i c i t arbi trary n am e fo r th e en ti ty.
S ee S ec ti o n 4 .4 , “ D yn am i c m o del s” an d Ch ap ter 1 8 , X M L M ap p ing fo r m o re i n fo rm ati o n .
(1 8 ) ch eck (o p ti o n al ): an S Q L ex p ressi o n u sed to gen erate a m u l ti - ro w c h e c k c o n strai n t fo r au to m ati c
sc h em a gen erati o n .
(1 9 ) ro w id (o p ti o n al ): H i bern ate c an u se R O W I D s o n databases. O n O rac l e, fo r ex am p l e, H i bern ate c an
u se th e ro w id ex tra c o l u m n fo r fast u p dates o n c e th i s o p ti o n h as been set to ro w id . A R O W I D i s an
im p l em en tati o n detai l an d rep resen ts th e p h ysi c al l o c ati o n o f a sto red tu p l e.
(20 ) s u b s el ect (o p ti o n al ): m ap s an i m m u tabl e an d read- o n l y en ti ty to a database su bsel ec t. T h i s i s u sefu l
i f yo u w an t to h av e a v i ew i n stead o f a base tabl e. S ee bel o w fo r m o re i n fo rm ati o n .
(21 ) ab s tract (o p ti o n al ): i s u sed to m ark abstrac t su p erc l asses i n h i erarc h i es.
I t i s ac c ep tabl e fo r th e n am ed p ersi sten t c l ass to be an i n terfac e. Y o u c an dec l are i m p l em en ti n g c l asses o f

th at i n terfac e u si n g th e < s u b cl as s > el em en t. Y o u c an p ersi st an y s tatic i n n er c l ass. S p ec i fy th e c l ass n am e
u si n g th e stan dard fo rm i .e. e. g. F o o $ B ar.
I m m u tabl e c l asses, mu tab l e=" f al s e" , c an n o t be u p dated o r del eted by th e ap p l i c ati o n . T h i s al l o w s H i bern ate to
m ak e so m e m i n o r p erfo rm an c e o p ti m i z ati o n s.
T h e o p ti o n al pro x y attri bu te en abl es l az y i n i ti al i z ati o n o f p ersi sten t i n stan c es o f th e c l ass. H i bern ate w i l l
i n i ti al l y retu rn CG L I B p ro x i es th at i m p l em en t th e n am ed i n terfac e. T h e p ersi sten t o bj ec t w i l l l o ad w h en a
m eth o d o f th e p ro x y i s i n v o k ed. S ee " I n i ti al i z i n g c o l l ec ti o n s an d p ro x i es" bel o w .
I m p lic it p o l ym o rp h i sm m ean s th at i n stan c es o f th e c l ass w i l l be retu rn ed by a q u ery th at n am es an y

su p erc l ass o r i m p l em en ted i n terfac e o r c l ass, an d th at i n stan c es o f an y su bc l ass o f th e c l ass w i l l be retu rn ed
by a q u ery th at n am es th e c l ass i tsel f. E x p lic it p o l ym o rp h i sm m ean s th at c l ass i n stan c es w i l l be retu rn ed o n l y
by q u eri es th at ex p l i c i tl y n am e th at c l ass. Q u eri es th at n am e th e c l ass w i l l retu rn o n l y i n stan c es o f su bc l asses
5 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
m ap p ed i n si de th i s < cl as s > dec l arati o n as a < s u b cl as s > o r < j o ined- s u b cl as s >. F o r m o st p u rp o ses, th e defau l t
po l ymo rph is m=" impl icit" i s ap p ro p ri ate. E x p l i c i t p o l ym o rp h i sm i s u sefu l w h en tw o di fferen t c l asses are m ap p ed
to th e sam e tabl e T h i s al l o w s a " l i gh tw ei gh t" c l ass th at c o n tai n s a su bset o f th e tabl e c o l u m n s.
T h e pers is ter attri bu te l ets yo u c u sto m i z e th e p ersi sten c e strategy u sed fo r th e c l ass. Y o u c an , fo r ex am p l e,
sp ec i fy yo u r o w n su bc l ass o f o rg. h ib ernate. pers is ter. E ntityP ers is ter, o r yo u c an ev en p ro v i de a c o m p l etel y n ew
im p l em en tati o n o f th e i n terfac e o rg. h ib ernate. pers is ter. C l as s P ers is ter th at i m p l em en ts, fo r ex am p l e,
p ersi sten c e v i a sto red p ro c edu re c al l s, seri al i z ati o n to fl at fi l es o r L D A P . S ee o rg. h ib ernate. tes t. C u s to mP ers is ter
fo r a si m p l e ex am p l e o f " p ersi sten c e" to a H as h tab l e.
T h e dynamic- u pdate an d dynamic- ins ert setti n gs are n o t i n h eri ted by su bc l asses, so th ey c an al so be sp ec i fi ed
o n th e < s u b cl as s > o r < j o ined- s u b cl as s > el em en ts. A l th o u gh th ese setti n gs c an i n c rease p erfo rm an c e i n so m e
c ases, th ey c an ac tu al l y dec rease p erfo rm an c e i n o th ers.
U se o f s el ect- b ef o re- u pdate w i l l u su al l y dec rease p erfo rm an c e. I t i s u sefu l to p rev en t a database u p date
tri gger bei n g c al l ed u n n ec essari l y i f yo u reattac h a grap h o f detac h ed i n stan c es to a Ses s io n.
I f yo u en abl e dynamic- u pdate , yo u w i l l h av e a c h o i c e o f o p ti m i sti c l o c k i n g strategi es:
v ers io n: c h ec k th e v ersi o n /ti m estam p c o l u m n s
al l : c h ec k al l c o l u m n s
dirty: c h ec k th e c h an ged c o l u m n s, al l o w i n g so m e c o n c u rren t u p dates
no ne: do n o t u se o p ti m i sti c l o c k i n g
I t i s s trong ly rec o m m en ded th at yo u u se v ersi o n /ti m estam p c o l u m n s fo r o p ti m i sti c l o c k i n g w i th H i bern ate.

T h i s strategy o p ti m i z es p erfo rm an c e an d c o rrec tl y h an dl es m o di fi c ati o n s m ade to detac h ed i n stan c es (i .e.
w h en Ses s io n. merge( ) i s u sed).
T h ere i s n o di fferen c e betw een a v i ew an d a base tabl e fo r a H i bern ate m ap p i n g. T h i s i s tran sp aren t at th e
database l ev el , al th o u gh so m e D B M S do n o t su p p o rt v i ew s p ro p erl y, esp ec i al l y w i th u p dates. S o m eti m es yo u
w an t to u se a v i ew , bu t yo u c an n o t c reate o n e i n th e database (i .e. w i th a l egac y sc h em a). I n th i s c ase, yo u
c an m ap an i m m u tabl e an d read- o n l y en ti ty to a gi v en S Q L su bsel ec t ex p ressi o n :
< cl as s name=" Su mmary" >

< s u b s el ect>
s el ect item. name, max ( b id. amo u nt), co u nt( *)
f ro m item
j o in b id o n b id. item_ id = item. id
gro u p b y item. name
< / s u b s el ect>
< s ynch ro niz e tab l e=" item" / >
< s ynch ro niz e tab l e=" b id" / >
< id name=" name" / >
...
< / cl as s >
D ec l are th e tabl es to syn c h ro n i z e th i s en ti ty w i th , en su ri n g th at au to - fl u sh h ap p en s c o rrec tl y an d th at q u eri es

agai n st th e deri v ed en ti ty do n o t retu rn stal e data. T h e < s u b s el ect> i s av ai l abl e bo th as an attri bu te an d a
n ested m ap p i n g el em en t.
5 .1 .4 . id
M ap p ed c l asses m us t dec l are th e p ri m ary k ey c o l u m n o f th e database tabl e. M o st c l asses w i l l al so h av e a

J av aB ean s- styl e p ro p erty h o l di n g th e u n i q u e i den ti fi er o f an i n stan c e. T h e < id> el em en t defi n es th e m ap p i n g
fro m th at p ro p erty to th e p ri m ary k ey c o l u m n .
5 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< id
name=" pro pertyName"
type=" typename"
co l u mn=" co l u mn_ name"
u ns av ed- v al u e=" nu l l | any| no ne| u ndef ined| id_ v al u e"
acces s =" f iel d| pro perty| C l as s Name" >
no de=" el ement- name| @ attrib u te- name| el ement/ @ attrib u te| . "
< generato r cl as s =" generato rC l as s " / >

< / id>
name (o p ti o n al ): th e n am e o f th e i den ti fi er p ro p erty.
type (o p ti o n al ): a n am e th at i n di c ates th e H i bern ate typ e.
co l u mn (o p ti o n al - defau l ts to th e p ro p erty n am e): th e n am e o f th e p ri m ary k ey c o l u m n .
u ns av ed- v al u e (o p ti o n al - defau l ts to a " sen si bl e" v al u e): an i den ti fi er p ro p erty v al u e th at i n di c ates an

i n stan c e i s n ew l y i n stan ti ated (u n sav ed), di sti n gu i sh i n g i t fro m detac h ed i n stan c es th at w ere sav ed o r
l o aded i n a p rev i o u s sessi o n .
acces s (o p ti o n al - defau l ts to pro perty): th e strategy H i bern ate sh o u l d u se fo r ac c essi n g th e p ro p erty
v al u e.
I f th e name attri bu te i s m i ssi n g, i t i s assu m ed th at th e c l ass h as n o i den ti fi er p ro p erty.
T h e u ns av ed- v al u e attri bu te i s al m o st n ev er n eeded i n H i bern ate3 .
T h ere i s an al tern ati v e < co mpo s ite- id> dec l arati o n th at al l o w s ac c ess to l egac y data w i th c o m p o si te k eys. I ts
u se i s stro n gl y di sc o u raged fo r an yth i n g el se.
5.1.4 .1. G enera tor
T h e o p ti o n al < generato r> c h i l d el em en t n am es a J av a c l ass u sed to gen erate u n i q u e i den ti fi ers fo r i n stan c es
o f th e p ersi sten t c l ass. I f an y p aram eters are req u i red to c o n fi gu re o r i n i ti al i z e th e gen erato r i n stan c e, th ey
are p assed u si n g th e < param> el em en t.
< id name=" id" type=" l o ng" co l u mn=" cat_ id" >

< generato r cl as s =" o rg. h ib ernate. id. T ab l eH iL o G enerato r" >
< param name=" tab l e" >u id_ tab l e< / param>
< param name=" co l u mn" >nex t_ h i_ v al u e_ co l u mn< / param>
< / generato r>
< / id>
A l l gen erato rs i m p l em en t th e i n terfac e o rg. h ib ernate. id. I dentif ierG enerato r. T h i s i s a v ery si m p l e i n terfac e.
S o m e ap p l i c ati o n s c an c h o o se to p ro v i de th ei r o w n sp ec i al i z ed i m p l em en tati o n s, h o w ev er, H i bern ate
p ro v i des a ran ge o f bu i l t- i n i m p l em en tati o n s. T h e sh o rtc u t n am es fo r th e bu i l t- i n gen erato rs are as fo l l o w s:
increment
gen erates i den ti fi ers o f typ e l o ng, s h o rt o r int th at are u n i q u e o n l y w h en n o o th er p ro c ess i s i n serti n g data
i n to th e sam e tabl e. D o not us e in a c lus te r.
identity
su p p o rts i den ti ty c o l u m n s i n D B 2, M yS Q L , M S S Q L S erv er, S ybase an d H yp erso n i c S Q L . T h e retu rn ed

i den ti fi er i s o f typ e l o ng, s h o rt o r int .
s eq u ence
u ses a seq u en c e i n D B 2, P o stgreS Q L , O rac l e, S A P D B , M c K o i o r a gen erato r i n I n terbase. T h e retu rn ed

i den ti fi er i s o f typ e l o ng, s h o rt o r int
h il o
u ses a h i /l o al go ri th m to effi c i en tl y gen erate i den ti fi ers o f typ e l o ng, s h o rt o r int , gi v en a tabl e an d c o l u m n
(by defau l t h ib ernate_ u niq u e_ k ey an d nex t_ h i resp ec ti v el y) as a so u rc e o f h i v al u es. T h e h i /l o al go ri th m
6 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
gen erates i den ti fi ers th at are u n i q u e o n l y fo r a p arti c u l ar database.
s eq h il o
u ses a h i /l o al go ri th m to effi c i en tl y gen erate i den ti fi ers o f typ e l o ng, s h o rt o r int , gi v en a n am ed database
seq u en c e.
u u id
u ses a 1 28 - bi t U U I D al go ri th m to gen erate i den ti fi ers o f typ e stri n g th at are u n i q u e w i th i n a n etw o rk (th e
I P address i s u sed). T h e U U I D i s en c o ded as a stri n g o f 3 2 h ex adec i m al di gi ts i n l en gth .
gu id
u ses a database- gen erated G U I D stri n g o n M S S Q L S erv er an d M yS Q L .
nativ e
sel ec ts identity, s eq u ence o r h il o dep en di n g u p o n th e c ap abi l i ti es o f th e u n derl yi n g database.
as s igned
l ets th e ap p l i c ati o n assi gn an i den ti fi er to th e o bj ec t befo re s av e( ) i s c al l ed. T h i s i s th e defau l t strategy i f

n o < generato r> el em en t i s sp ec i fi ed.
s el ect
retri ev es a p ri m ary k ey, assi gn ed by a database tri gger, by sel ec ti n g th e ro w by so m e u n i q u e k ey an d

retri ev i n g th e p ri m ary k ey v al u e.
f o reign
u ses th e i den ti fi er o f an o th er asso c i ated o bj ec t. I t i s u su al l y u sed i n c o n j u n c ti o n w i th a < o ne- to - o ne>

p ri m ary k ey asso c i ati o n .
s eq u ence- identity
a sp ec i al i z ed seq u en c e gen erati o n strategy th at u ti l i z es a database seq u en c e fo r th e ac tu al v al u e

gen erati o n , bu t c o m bi n es th i s w i th J D B C3 getG en eratedK eys to retu rn th e gen erated i den ti fi er v al u e as
p art o f th e i n sert statem en t ex ec u ti o n . T h i s strategy i s o n l y su p p o rted o n O rac l e 1 0 g dri v ers targeted fo r
J D K 1 .4 . Co m m en ts o n th ese i n sert statem en ts are di sabl ed du e to a bu g i n th e O rac l e dri v ers.
5.1.4 .2 . H i/ lo a lg orith m
T h e h il o an d s eq h il o gen erato rs p ro v i de tw o al tern ate i m p l em en tati o n s o f th e h i /l o al go ri th m . T h e fi rst

i m p l em en tati o n req u i res a " sp ec i al " database tabl e to h o l d th e n ex t av ai l abl e " h i " v al u e. W h ere su p p o rted,
th e sec o n d u ses an O rac l e- styl e seq u en c e.

< generato r cl as s =" h il o " >
< param name=" tab l e" >h i_ v al u e< / param>
< param name=" co l u mn" >nex t_ v al u e< / param>
< param name=" max _ l o " >100< / param>
< / generato r>
< / id>

< generato r cl as s =" s eq h il o " >
< param name=" s eq u ence" >h i_ v al u e< / param>
< param name=" max _ l o " >100< / param>
< / generato r>
< / id>
U n fo rtu n atel y, yo u c an n o t u se h il o w h en su p p l yi n g yo u r o w n C o nnectio n to H i bern ate. W h en H i bern ate u ses

an ap p l i c ati o n serv er dataso u rc e to o btai n c o n n ec ti o n s en l i sted w i th J T A , yo u m u st c o n fi gu re th e
h ib ernate. trans actio n. manager_ l o o k u p_ cl as s .
5.1.4 .3 . U U I D a lg orith m
6 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h e U U I D c o n tai n s: I P address, startu p ti m e o f th e J V M th at i s ac c u rate to a q u arter sec o n d, system ti m e an d

a c o u n ter v al u e th at i s u n i q u e w i th i n th e J V M . I t i s n o t p o ssi bl e to o btai n a M A C address o r m em o ry address
fro m J av a c o de, so th i s i s th e best o p ti o n w i th o u t u si n g J N I .
5.1.4 .4 . I d entity c olu m ns a nd seq u enc es
F o r databases th at su p p o rt i den ti ty c o l u m n s (D B 2, M yS Q L , S ybase, M S S Q L ), yo u c an u se identity k ey

gen erati o n . F o r databases th at su p p o rt seq u en c es (D B 2, O rac l e, P o stgreS Q L , I n terbase, M c K o i , S A P D B ) yo u
c an u se s eq u ence styl e k ey gen erati o n . B o th o f th ese strategi es req u i re tw o S Q L q u eri es to i n sert a n ew
o bj ec t. F o r ex am p l e:
< id name=" id" type=" l o ng" co l u mn=" pers o n_ id" >

< generato r cl as s =" s eq u ence" >
< param name=" s eq u ence" >pers o n_ id_ s eq u ence< / param>
< / generato r>
< / id>
< id name=" id" type=" l o ng" co l u mn=" pers o n_ id" u ns av ed- v al u e=" 0" >
< generato r cl as s =" identity" / >
< / id>
F o r c ro ss- p l atfo rm dev el o p m en t, th e nativ e strategy w i l l , dep en di n g o n th e c ap abi l i ti es o f th e u n derl yi n g

database, c h o o se fro m th e identity, s eq u ence an d h il o strategi es.
5.1.4 .5. A ssig ned id entif iers
I f yo u w an t th e ap p l i c ati o n to assi gn i den ti fi ers, as o p p o sed to h av i n g H i bern ate gen erate th em , yo u c an u se

th e as s igned gen erato r. T h i s sp ec i al gen erato r u ses th e i den ti fi er v al u e al ready assi gn ed to th e o bj ec t' s
i den ti fi er p ro p erty. T h e gen erato r i s u sed w h en th e p ri m ary k ey i s a n atu ral k ey i n stead o f a su rro gate k ey.
T h i s i s th e defau l t beh av i o r i f yo u do n o t sp ec i fy a < generato r> el em en t.
T h e as s igned gen erato r m ak es H i bern ate u se u ns av ed- v al u e=" u ndef ined" . T h i s fo rc es H i bern ate to go to th e
database to determ i n e i f an i n stan c e i s tran si en t o r detac h ed, u n l ess th ere i s a v ersi o n o r ti m estam p
p ro p erty, o r yo u defi n e I ntercepto r. is U ns av ed( ).
5.1.4 .6 . P rim a ry k eys a ssig ned b y trig g ers
H i bern ate do es n o t gen erate D D L w i th tri ggers. I t i s fo r l egac y sc h em as o n l y.
< id name=" id" type=" l o ng" co l u mn=" pers o n_ id" >

< generato r cl as s =" s el ect" >
< param name=" k ey" >s o cial Secu rityNu mb er< / param>
< / generato r>
< / id>
I n th e abo v e ex am p l e, th ere i s a u n i q u e v al u ed p ro p erty n am ed s o cial Secu rityNu mb er. I t i s defi n ed by th e

c l ass, as a n atu ral k ey an d a su rro gate k ey n am ed pers o n_ id, w h o se v al u e i s gen erated by a tri gger.
5 . 1 . 5 . E nh anc e d i d e nti f i e r g e ne rators
S tarti n g w i th rel ease 3 .2.3 , th ere are 2 n ew gen erato rs w h i c h rep resen t a re- th i n k i n g o f 2 di fferen t asp ec ts
o f i den ti fi er gen erati o n . T h e fi rst asp ec t i s database p o rtabi l i ty; th e sec o n d i s o p ti m i z ati o n O p ti m i z ati o n
m ean s th at yo u do n o t h av e to q u ery th e database fo r ev ery req u est fo r a n ew i den ti fi er v al u e. T h ese tw o
n ew gen erato rs are i n ten ded to tak e th e p l ac e o f so m e o f th e n am ed gen erato rs desc ri bed abo v e, starti n g in
3 .3 .x . H o w ev er, th ey are i n c l u ded i n th e c u rren t rel eases an d c an be referen c ed by F Q N .
T h e fi rst o f th ese n ew gen erato rs i s o rg. h ib ernate. id. enh anced. Seq u enceStyl eG enerato r w h i c h i s i n ten ded, fi rstl y,
as a rep l ac em en t fo r th e s eq u ence gen erato r an d, sec o n dl y, as a better p o rtabi l i ty gen erato r th an nativ e. T h i s
6 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
i s bec au se nativ e gen eral l y c h o o ses betw een identity an d s eq u ence w h i c h h av e l argel y di fferen t sem an ti c s th at
c an c au se su btl e i ssu es i n ap p l i c ati o n s eyei n g p o rtabi l i ty. o rg. h ib ernate. id. enh anced. Seq u enceStyl eG enerato r,
h o w ev er, ac h i ev es p o rtabi l i ty i n a di fferen t m an n er. I t c h o o ses betw een a tabl e o r a seq u en c e i n th e
database to sto re i ts i n c rem en ti n g v al u es, dep en di n g o n th e c ap abi l i ti es o f th e di al ec t bei n g u sed. T h e
di fferen c e betw een th i s an d nativ e i s th at tabl e- based an d seq u en c e- based sto rage h av e th e sam e ex ac t
sem an ti c . I n fac t, seq u en c es are ex ac tl y w h at H i bern ate tri es to em u l ate w i th i ts tabl e- based gen erato rs.
T h i s gen erato r h as a n u m ber o f c o n fi gu rati o n p aram eters:
s eq u ence_ name (o p ti o n al , defau l ts to h ib ernate_ s eq u ence ): th e n am e o f th e seq u en c e o r tabl e to be u sed.
initial _ v al u e (o p ti o n al , defau l ts to 1): th e i n i ti al v al u e to be retri ev ed fro m th e seq u en c e/tabl e. I n

seq u en c e c reati o n term s, th i s i s an al o go u s to th e c l au se typ i c al l y n am ed " S T A R T S W I T H " .
increment_ s iz e (o p ti o n al - defau l ts to 1): th e v al u e by w h i c h su bseq u en t c al l s to th e seq u en c e/tabl e sh o u l d
di ffer. I n seq u en c e c reati o n term s, th i s i s an al o go u s to th e c l au se typ i c al l y n am ed " I N CR E M E N T B Y " .
f o rce_ tab l e_ u s e (o p ti o n al - defau l ts to f al s e): sh o u l d w e fo rc e th e u se o f a tabl e as th e bac k i n g stru c tu re
ev en th o u gh th e di al ec t m i gh t su p p o rt seq u en c e?
v al u e_ co l u mn (o p ti o n al - defau l ts to nex t_ v al ): o n l y rel ev an t fo r tabl e stru c tu res, i t i s th e n am e o f th e
c o l u m n o n th e tabl e w h i c h i s u sed to h o l d th e v al u e.
o ptimiz er (o p ti o n al - defau l ts to no ne ): S ee S ec ti o n 5 .1 .6 , “ I den ti fi er gen erato r o p ti m i z ati o n ”
T h e sec o n d o f th ese n ew gen erato rs i s o rg. h ib ernate. id. enh anced. T ab l eG enerato r, w h i c h i s i n ten ded, fi rstl y, as a
rep l ac em en t fo r th e tab l e gen erato r, ev en th o u gh it ac tu al l y fu n c ti o n s m u c h m o re lik e
o rg. h ib ernate. id. M u l tipl eH iL o P erT ab l eG enerato r, an d sec o n dl y, as a re- i m p l em en tati o n o f
o rg. h ib ernate. id. M u l tipl eH iL o P erT ab l eG enerato r th at u ti l i z es th e n o ti o n o f p l u ggabl e o p ti m i z ers. E ssen ti al l y th i s
gen erato r defi n es a tabl e c ap abl e o f h o l di n g a n u m ber o f di fferen t i n c rem en t v al u es si m u l tan eo u sl y by u si n g
m u l ti p l e di sti n c tl y k eyed ro w s. T h i s gen erato r h as a n u m ber o f c o n fi gu rati o n p aram eters:
tab l e_ name (o p ti o n al - defau l ts to h ib ernate_ s eq u ences ): th e n am e o f th e tabl e to be u sed.

v al u e_ co l u mn_ name (o p ti o n al - defau l ts to nex t_ v al ): th e n am e o f th e c o l u m n o n th e tabl e th at i s u sed to
h o l d th e v al u e.
s egment_ co l u mn_ name (o p ti o n al - defau l ts to s eq u ence_ name ): th e n am e o f th e c o l u m n o n th e tabl e th at i s
u sed to h o l d th e " segm en t k ey" . T h i s i s th e v al u e w h i c h i den ti fi es w h i c h i n c rem en t v al u e to u se.
s egment_ v al u e (o p ti o n al - defau l ts to def au l t ): T h e " segm en t k ey" v al u e fo r th e segm en t fro m w h ic h w e
w an t to p u l l i n c rem en t v al u es fo r th i s gen erato r.
s egment_ v al u e_ l ength (o p ti o n al - defau l ts to 2 55): U sed fo r sc h em a gen erati o n ; th e c o l u m n si z e to c reate
th i s segm en t k ey c o l u m n .
initial _ v al u e (o p ti o n al - defau l ts to 1): T h e i n i ti al v al u e to be retri ev ed fro m th e tabl e.
increment_ s iz e (o p ti o n al - defau l ts to 1): T h e v al u e by w h i c h su bseq u en t c al l s to th e tabl e sh o u l d di ffer.
o ptimiz er (o p ti o n al - defau l ts to ): See Sectio n 5. 1. 6 , “ I dentif ier generato r o ptimiz atio n”
5 . 1 . 6 . Id e nti f i e r g e ne rator opti mi z ati on
F o r i den ti fi er gen erato rs th at sto re v al u es i n th e database, i t i s i n effi c i en t fo r th em to h i t th e database o n

eac h an d ev ery c al l to gen erate a n ew i den ti fi er v al u e. I n stead, yo u c an gro u p a bu n c h o f th em i n m em o ry
an d o n l y h i t th e database w h en yo u h av e ex h au sted yo u r i n - m em o ry v al u e gro u p . T h i s i s th e ro l e o f th e
p l u ggabl e o p ti m i z ers. Cu rren tl y o n l y th e tw o en h an c ed gen erato rs (S ec ti o n 5 .1 .5 , “ E n h an c ed i den ti fi er
gen erato rs” su p p o rt th i s o p erati o n .
no ne (gen eral l y th i s i s th e defau l t i f n o o p ti m i z er w as sp ec i fi ed): th i s w i l l n o t p erfo rm an y o p ti m i z ati o n s

an d h i t th e database fo r eac h an d ev ery req u est.
h il o : ap p l i es a h i /l o al go ri th m aro u n d th e database retri ev ed v al u es. T h e v al u es fro m th e database fo r

th i s o p ti m i z er are ex p ec ted to be seq u en ti al . T h e v al u es retri ev ed fro m th e database stru c tu re fo r th i s
o p ti m i z er i n di c ates th e " gro u p n u m ber" . T h e increment_ s iz e i s m u l ti p l i ed by th at v al u e i n m em o ry to
defi n e a gro u p " h i v al u e" .
po o l ed : as w i th th e c ase o f h il o , th i s o p ti m i z er attem p ts to m in im i z e th e n u m ber o f h i ts to th e database.
H ere, h o w ev er, w e si m p l y sto re th e starti n g v al u e fo r th e " n ex t gro u p " i n to th e database stru c tu re rath er
6 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
th an a seq u en ti al v al u e i n c o m bi n ati o n w i th an i n - m em o ry gro u p i n g al go ri th m . H ere, increment_ s iz e

refers to th e v al u es c o m i n g fro m th e database.
5 . 1 . 7 . c ompos i te - i d
< co mpo s ite- id

cl as s =" C l as s Name"
mapped=" tru e| f al s e"
acces s =" f iel d| pro perty| C l as s Name" >
no de=" el ement- name| . "
< k ey- pro perty name=" pro pertyName" type=" typename" co l u mn=" co l u mn_ name" / >
< k ey- many- to - o ne name=" pro pertyName cl as s =" C l as s Name" co l u mn=" co l u mn_ name" / >
......
< / co mpo s ite- id>
A tabl e w i th a c o m p o si te k ey c an be m ap p ed w i th m u l ti p l e p ro p erti es o f th e c l ass as i den ti fi er p ro p erti es. T h e

< co mpo s ite- id> el em en t ac c ep ts < k ey- pro perty> p ro p erty m ap p i n gs an d < k ey- many- to - o ne> m ap p i n gs as c h i l d
el em en ts.
< co mpo s ite- id>

< k ey- pro perty name=" medicareNu mb er" / >
< k ey- pro perty name=" dependent" / >
T h e p ersi sten t c l ass m us t o v erri de eq u al s ( ) an d h as h C o de( ) to im p l em en t c o m p o si te i den ti fi er eq u al i ty. I t

m u st al so i m p l em en t Serial iz ab l e.
U n fo rtu n atel y, th i s ap p ro ac h m ean s th at a p ersi sten t o bj ec t i s i ts o w n i den ti fi er. T h ere i s n o c o n v en i en t

" h an dl e" o th er th an th e o bj ec t i tsel f. Y o u m u st i n stan ti ate an i n stan c e o f th e p ersi sten t c l ass i tsel f an d
p o p u l ate i ts i den ti fi er p ro p erti es befo re yo u c an l o ad( ) th e p ersi sten t state asso c i ated w i th a c o m p o si te k ey.
W e c al l th i s ap p ro ac h an e m b e d d e d c o m p o si te i den ti fi er, an d di sc o u rage i t fo r seri o u s ap p l i c ati o n s.
A sec o n d ap p ro ac h i s w h at w e c al l a m ap p e d c o m p o si te i den ti fi er, w h ere th e i den ti fi er p ro p erti es n am ed

i n si de th e < co mpo s ite- id> el em en t are du p l i c ated o n bo th th e p ersi sten t c l ass an d a sep arate i den ti fi er c l ass.
< co mpo s ite- id cl as s =" M edicareI d" mapped=" tru e" >
< k ey- pro perty name=" medicareNu mb er" / >
< k ey- pro perty name=" dependent" / >
I n th i s ex am p l e, bo th th e c o m p o si te i den ti fi er c l ass, M edicareI d , an d th e en ti ty c l ass i tsel f h av e p ro p erti es

n am ed medicareNu mb er an d dependent . T h e i den ti fi er c l ass m u st o v erri de eq u al s ( ) an d h as h C o de( ) an d
im p l em en t Serial iz ab l e. T h e m ai n di sadv an tage o f th i s ap p ro ac h i s c o de du p l i c ati o n .
T h e fo l l o w i n g attri bu tes are u sed to sp ec i fy a m ap p ed c o m p o si te i den ti fi er:
mapped (o p ti o n al - defau l ts to f al s e ): i n di c ates th at a m ap p ed c o m p o si te i den ti fi er i s u sed, an d th at th e

c o n tai n ed p ro p erty m ap p i n gs refer to bo th th e en ti ty c l ass an d th e c o m p o si te i den ti fi er c l ass.
cl as s (o p ti o n al - bu t req u i red fo r a m ap p ed c o m p o si te i den ti fi er): th e c l ass u sed as a c o m p o si te i den ti fi er.
W e w i l l desc ri be a th i rd, ev en m o re c o n v en i en t ap p ro ac h , w h ere th e c o m p o si te i den ti fi er i s i m p l em en ted as

a c o m p o n en t c l ass i n S ec ti o n 8 .4 , “ Co m p o n en ts as c o m p o si te i den ti fi ers” . T h e attri bu tes desc ri bed bel o w
ap p l y o n l y to th i s al tern ati v e ap p ro ac h :
name (o p ti o n al - req u i red fo r th i s ap p ro ac h ): a p ro p erty o f c o m p o n en t typ e th at h o l ds th e c o m p o si te

i den ti fi er. P l ease see c h ap ter 9 fo r m o re i n fo rm ati o n .
acces s (o p ti o n al - defau l ts to pro perty): th e strategy H i bern ate u ses fo r ac c essi n g th e p ro p erty v al u e.
6 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
cl as s (o p ti o n al - defau l ts to th e p ro p erty typ e determ i n ed by refl ec ti o n ): th e c o m p o n en t c l ass u sed as a

c o m p o si te i den ti fi er. P l ease see th e n ex t sec ti o n fo r m o re i n fo rm ati o n .
T h e th i rd ap p ro ac h , an id e ntif ie r c om p one nt, i s rec o m m en ded fo r al m o st al l ap p l i c ati o n s.
5 . 1 . 8 . D i s c ri mi nator
T h e < dis criminato r> el em en t i s req u i red fo r p o l ym o rp h i c p ersi sten c e u si n g th e tabl e- p er- c l ass- h i erarc h y
m
ap p i n g strategy. I t dec l ares a di sc ri m i n ato r c o l u m n o f th e tabl e. T h e di sc ri m i n ato r c o l u m n c o n tai n s m ark er
v al u es th at tel l th e p ersi sten c e l ayer w h at su bc l ass to i n stan ti ate fo r a p arti c u l ar ro w . A restri c ted set o f
typ es c an be u sed: s tring, ch aracter, integer, b yte, s h o rt , b o o l ean, yes _ no , tru e_ f al s e .
< dis criminato r

co l u mn=" dis criminato r_ co l u mn"
type=" dis criminato r_ type"
f o rce=" tru e| f al s e"
ins ert=" tru e| f al s e"
f o rmu l a=" arb itrary s q l ex pres s io n"
/ >
co l u mn (o p ti o n al - defau l ts to cl as s ): th e n am e o f th e di sc ri m i n ato r c o l u m n .
type (o p ti o n al - defau l ts to s tring ): a n am e th at i n di c ates th e H i bern ate typ e
f o rce (o p ti o n al - defau l ts to f al s e ): " fo rc es" H i bern ate to sp ec i fy th e al l o w ed di sc ri m i n ato r v al u es, ev en

w h en retri ev i n g al l i n stan c es o f th e ro o t c l ass.
ins ert (o p ti o n al - defau l ts to tru e ): set th i s to f al s e i f yo u r di sc ri m i n ato r c o l u m n i s al so p art o f a
m ap p ed c o m p o si te i den ti fi er. I t tel l s H i bern ate n o t to i n c l u de th e c o l u m n i n S Q L I NSE R T s .
f o rmu l a (o p ti o n al ): an arbi trary S Q L ex p ressi o n th at i s ex ec u ted w h en a typ e h as to be ev al u ated. I t
al l o w s c o n ten t- based di sc ri m i n ati o n .
A c tu al v al u es o f th e di sc ri m i n ato r c o l u m n are sp ec i fi ed by th e dis criminato r- v al u e attri bu te o f th e < cl as s > an d

< s u b cl as s > el em en ts.
T h e f o rce attri bu te i s o n l y u sefu l i f th e tabl e c o n tai n s ro w s w i th " ex tra" di sc ri m i n ato r v al u es th at are n o t

m ap p ed to a p ersi sten t c l ass. T h i s w i l l n o t u su al l y be th e c ase.
T h e f o rmu l a attri bu te al l o w s yo u to dec l are an arbi trary S Q L ex p ressi o n th at w i l l be u sed to ev al u ate th e typ e
o f a ro w . F o r ex am p l e:
< dis criminato r

f o rmu l a=" cas e w h en C L A SS_ T Y P E in ( ' a' , ' b ' , ' c' ) th en 0 el s e 1 end"
type=" integer" / >
5 . 1 . 9 . V e rs i on ( opti onal )
T h e < v ers io n> el em en t i s o p ti o n al an d i n di c ates th at th e tabl e c o n tai n s v ersi o n ed data. T h i s i s p arti c u l arl y
u sefu l i f yo u p l an to u se long trans ac tions . S ee bel o w fo r m o re i n fo rm ati o n :
< v ers io n
co l u mn=" v ers io n_ co l u mn"
type=" typename"
acces s =" f iel d| pro perty| C l as s Name"
u ns av ed- v al u e=" nu l l | negativ e| u ndef ined"
generated=" nev er| al w ays "
/ >
6 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
co l u mn (o p ti o n al - defau l ts to th e p ro p erty n am e): th e n am e o f th e c o l u m n h o l di n g th e v ersi o n

n u m ber.
name : th e n am e o f a p ro p erty o f th e p ersi sten t c l ass.
type (o p ti o n al - defau l ts to integer): th e typ e o f th e v ersi o n n u m ber.
acces s (o p ti o n al - defau l ts to pro perty): th e strategy H i bern ate u ses to ac c ess th e p ro p erty v al u e.
u ns av ed- v al u e (o p ti o n al - defau l ts to u ndef ined ): a v ersi o n p ro p erty v al u e th at i n di c ates th at an

i n stan c e i s n ew l y i n stan ti ated (u n sav ed), di sti n gu i sh i n g i t fro m detac h ed i n stan c es th at w ere sav ed o r
l o aded i n a p rev i o u s sessi o n . U ndef ined sp ec i fi es th at th e i den ti fi er p ro p erty v al u e sh o u l d be u sed.
generated (o p ti o n al - defau l ts to nev er): sp ec i fi es th at th i s v ersi o n p ro p erty v al u e i s gen erated by th e
database. S ee th e di sc u ssi o n o f gen erated p ro p erti es fo r m o re i n fo rm ati o n .
ins ert (o p ti o n al - defau l ts to tru e ): sp ec i fi es w h eth er th e v ersi o n c o lu m n sh o u l d be i n c l u ded i n S Q L
i n sert statem en ts. I t c an be set to f al s e i f th e database c o l u m n i s defi n ed w i th a defau l t v al u e o f 0.
V ersi o n n u m bers c an be o f H i bern ate typ e l o ng , integer, s h o rt , times tamp o r cal endar.
A v ersi o n o r ti m estam p p ro p erty sh o u l d n ev er be n u l l fo r a detac h ed i n stan c e. H i bern ate w i l l detec t an y

i n stan c e w i th a n u l l v ersi o n o r ti m estam p as tran si en t, i rresp ec ti v e o f w h at o th er u ns av ed- v al u e strategi es are
sp ec i fi ed. D e c laring a nullab le v e rs ion or tim e s tam p p rop e rty is an e as y w ay to av oid p rob le m s w ith
trans itiv e re attac h m e nt in H ib e rnate . I t is e s p e c ially us e f ul f or p e op le us ing as s ig ne d id e ntif ie rs or c om p os ite
k e y s .
5 . 1 . 1 0 . T i me s tamp ( opti onal )
T h e o p ti o n al < times tamp> el em en t i n di c ates th at th e tabl e c o n tai n s ti m estam p ed data. T h i s p ro v i des an

al tern ati v e to v ersi o n i n g. T i m estam p s are a l ess safe i m p l em en tati o n o f o p ti m i sti c l o c k i n g. H o w ev er,
so m eti m es th e ap p l i c ati o n m i gh t u se th e ti m estam p s i n o th er w ays.
< times tamp

co l u mn=" times tamp_ co l u mn"
u ns av ed- v al u e=" nu l l | u ndef ined"
s o u rce=" v m| db "
generated=" nev er| al w ays "
/ >
co l u mn (o p ti o n al - defau l ts to th e p ro p erty n am e): th e n am e o f a c o l u m n h o l di n g th e ti m estam p .
name : th e n am e o f a J av aB ean s styl e p ro p erty o f J av a typ e D ate o r T imes tamp o f th e p ersi sten t c l ass.
u ns av ed- v al u e (o p ti o n al - defau l ts to nu l l ): a v ersi o n p ro p erty v al u e th at i n di c ates th at an i n stan c e i s

n ew l y i n stan ti ated (u n sav ed), di sti n gu i sh i n g i t fro m detac h ed i n stan c es th at w ere sav ed o r l o aded i n
a p rev i o u s sessi o n . U ndef ined sp ec i fi es th at th e i den ti fi er p ro p erty v al u e sh o u l d be u sed.
s o u rce (o p ti o n al - defau l ts to v m): W h ere sh o u l d H i bern ate retri ev e th e ti m estam p v al u e fro m ? F ro m
th e database, o r fro m th e c u rren t J V M ? D atabase- based ti m estam p s i n c u r an o v erh ead bec au se
H i bern ate m u st h i t th e database i n o rder to determ i n e th e " n ex t v al u e" . I t i s safer to u se i n c l u stered
en v i ro n m en ts. N o t al l D ial ects are k n o w n to su p p o rt th e retri ev al o f th e database' s c u rren t
ti m estam p . O th ers m ay al so be u n safe fo r u sage i n l o c k i n g du e to l ac k o f p rec i si o n (O rac l e 8 , fo r
ex am p l e).
generated (o p ti o n al - defau l ts to nev er): sp ec i fi es th at th i s ti m estam p p ro p erty v al u e i s ac tu al l y
gen erated by th e database. S ee th e di sc u ssi o n o f gen erated p ro p erti es fo r m o re i n fo rm ati o n .
6 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
N ote
< T imes tamp> i s eq u i v al en t to < v ers io n type=" times tamp" >. A n d < times tamp s o u rce=" db " > i s
eq u i v al en t to < v ers io n type=" db times tamp" >
5 . 1 . 1 1 . P rope rty
T h e < pro perty> el em en t dec l ares a p ersi sten t J av aB ean styl e p ro p erty o f th e c l ass.
< pro perty

type=" typename"
u pdate=" tru e| f al s e"
f o rmu l a=" arb itrary SQ L ex pres s io n"
u niq u e=" tru e| f al s e"
no t- nu l l =" tru e| f al s e"
o ptimis tic- l o ck =" tru e| f al s e"
generated=" nev er| ins ert| al w ays "
index =" index _ name"
u niq u e_ k ey=" u niq u e_ k ey_ id"
l ength =" L "
precis io n=" P "
s cal e=" S"
/ >
name : th e n am e o f th e p ro p erty, w i th an i n i ti al l o w erc ase l etter.
co l u mn (o p ti o n al - defau l ts to th e p ro p erty n am e): th e n am e o f th e m ap p ed database tabl e c o l u m n .

T h i s c an al so be sp ec i fi ed by n ested < co l u mn> el em en t(s).
type (o p ti o n al ): a n am e th at i n di c ates th e H i bern ate typ e.
u pdate, ins ert (o p ti o n al - defau l ts to tru e ): sp ec i fi es th at th e m ap p ed c o l u m n s sh o u l d be i n c l u ded i n

S Q L U P D A T E an d/o r I NSE R T statem en ts. S etti n g bo th to f al s e al l o w s a p u re " deri v ed" p ro p erty w h o se
v al u e i s i n i ti al i z ed fro m so m e o th er p ro p erty th at m ap s to th e sam e c o l u m n (s), o r by a tri gger o r
o th er ap p l i c ati o n .
f o rmu l a (o p ti o n al ): an S Q L ex p ressi o n th at defi n es th e v al u e fo r a c om p ute d p ro p erty. Co m p u ted
p ro p erti es do n o t h av e a c o l u m n m ap p i n g o f th ei r o w n .
l az y (o p ti o n al - defau l ts to f al s e): sp ec i fi es th at th i s p ro p erty sh o u l d be fetc h ed l az i l y w h en th e

i n stan c e v ari abl e i s fi rst ac c essed. I t req u i res bu i l d- ti m e bytec o de i n stru m en tati o n .
u niq u e (o p ti o n al ): en abl es th e D D L gen erati o n o f a u n i q u e c o n strai n t fo r th e c o l u m n s. A l so , al l o w th i s
to be th e target o f a pro perty- ref .
no t- nu l l (o p ti o n al ): en abl es th e D D L gen erati o n o f a n u l l abi l i ty c o n strai n t fo r th e c o l u m n s.
o ptimis tic- l o ck (o p ti o n al - defau l ts to tru e ): sp ec i fi es th at u p dates to th i s p ro p erty do o r do n o t req u i re

ac q u i si ti o n o f th e o p ti m i sti c l o c k . I n o th er w o rds, i t determ i n es i f a v ersi o n i n c rem en t sh o u l d o c c u r
w h en th i s p ro p erty i s di rty.
generated (o p ti o n al - defau l ts to nev er): sp ec i fi es th at th i s p ro p erty v al u e i s ac tu al l y gen erated by th e
database. S ee th e di sc u ssi o n o f gen erated p ro p erti es fo r m o re i n fo rm ati o n .
ty p e nam e c o u l d be:
1 . T h e n am e o f a H i bern ate basi c typ e:
6 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
integer, s tring, ch aracter, date, times tamp, f l o at, b inary, s erial iz ab l e, o b j ect, b l o b etc .
2. T h e n am e o f a J av a c l ass w i th a defau l t basi c typ e:

int, f l o at, ch ar, j av a. l ang. String, j av a. u til . D ate, j av a. l ang. I nteger, j av a. s q l . C l o b etc .
3 . T h e n am e o f a seri al i z abl e J av a c l ass.

4 . T h e c l ass n am e o f a c u sto m typ e: co m. il l f l o w . type. M yC u s to mT ype etc .
I f yo u do n o t sp ec i fy a typ e, H i bern ate w i l l u se refl ec ti o n u p o n th e n am ed p ro p erty an d gu ess th e c o rrec t

H i bern ate typ e. H i bern ate w i l l attem p t to i n terp ret th e n am e o f th e retu rn c l ass o f th e p ro p erty getter u si n g,
i n o rder, ru l es 2, 3 , an d 4 . I n c ertai n c ases yo u w i l l n eed th e type attri bu te. F o r ex am p l e, to di sti n gu i sh
betw een H ib ernate. D A T E an d H ib ernate. T I M E ST A M P , o r to sp ec i fy a c u sto m typ e.
T h e acces s attri bu te al l o w s yo u to c o n tro l h o w H i bern ate ac c esses th e p ro p erty at ru n ti m e. B y defau l t,

H i bern ate w i l l c al l th e p ro p erty get/set p ai r. I f yo u sp ec i fy acces s =" f iel d" , H i bern ate w i l l byp ass th e get/set
p ai r an d ac c ess th e fi el d di rec tl y u si n g refl ec ti o n . Y o u c an sp ec i fy yo u r o w n strategy fo r p ro p erty ac c ess by
n am i n g a c l ass th at i m p l em en ts th e i n terfac e o rg. h ib ernate. pro perty. P ro pertyA cces s o r.
A p o w erfu l featu re i s deri v ed p ro p erti es. T h ese p ro p erti es are by defi n i ti o n read- o n l y. T h e p ro p erty v al u e i s
c o m p u ted at l o ad ti m e. Y o u dec l are th e c o m p u tati o n as an S Q L ex p ressi o n . T h i s th en tran sl ates to a SE L E C T
c l au se su bq u ery i n th e S Q L q u ery th at l o ads an i n stan c e:
< pro perty name=" to tal P rice"

f o rmu l a=" ( SE L E C T SU M ( l i. q u antity*p. price) F R O M L ineI tem l i, P ro du ct p
W H E R E l i. pro du ctI d = p. pro du ctI d
A ND l i. cu s to merI d = cu s to merI d
A ND l i. o rderNu mb er = o rderNu mb er )" / >
Y o u c an referen c e th e en ti ty tabl e by n o t dec l ari n g an al i as o n a p arti c u l ar c o l u m n . T h i s w o u l d be cu s to merI d

i n th e gi v en ex am p l e. Y o u c an al so u se th e n ested < f o rmu l a> m ap p i n g el em en t i f yo u do n o t w an t to u se th e
attri bu te.
5 . 1 . 1 2 . M any - to- one
A n o rdi n ary asso c i ati o n to an o th er p ersi sten t c l ass i s dec l ared u si n g a many- to - o ne el em en t. T h e rel ati o n al
m o del i s a m an y- to - o n e asso c i ati o n ; a fo rei gn k ey i n o n e tabl e i s referen c i n g th e p ri m ary k ey c o l u m n (s) o f
th e target tabl e.
< many- to - o ne
cas cade=" cas cade_ s tyl e"
f etch =" j o in| s el ect"
pro perty- ref =" pro pertyNameF ro mA s s o ciatedC l as s "
l az y=" pro x y| no - pro x y| f al s e"
no t- f o u nd=" igno re| ex ceptio n"
f o rmu l a=" arb itrary SQ L ex pres s io n"
emb ed- x ml =" tru e| f al s e"
u niq u e_ k ey=" u niq u e_ k ey_ id"
f o reign- k ey=" f o reign_ k ey_ name"
/ >
6 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
name : th e n am e o f th e p ro p erty.
co l u mn (o p ti o n al ): th e n am e o f th e fo rei gn k ey c o l u m n . T h i s c an al so be sp ec i fi ed by n ested < co l u mn>

el em en t(s).
cl as s (o p ti o n al - defau l ts to th e p ro p erty typ e determ i n ed by refl ec ti o n ): th e n am e o f th e asso c i ated
c l ass.
cas cade (o p ti o n al ): sp ec i fi es w h i c h o p erati o n s sh o u l d be c asc aded fro m th e p aren t o bj ec t to th e
asso c i ated o bj ec t.
f etch (o p ti o n al - defau l ts to s el ect ): c h o o ses betw een o u ter- j o i n fetc h i n g o r seq u en ti al sel ec t fetc h i n g.
u pdate, ins ert (o p ti o n al - defau l ts to tru e ): sp ec i fi es th at th e m ap p ed c o l u m n s sh o u l d be i n c l u ded i n

S Q L U P D A T E an d/o r I NSE R T statem en ts. S etti n g bo th to f al s e al l o w s a p u re " deri v ed" asso c i ati o n
w h o se v al u e i s i n i ti al i z ed fro m an o th er p ro p erty th at m ap s to th e sam e c o l u m n (s), o r by a tri gger o r
o th er ap p l i c ati o n .
pro perty- ref (o p ti o n al ): th e n am e o f a p ro p erty o f th e asso c i ated c l ass th at i s j o i n ed to th i s fo rei gn
k ey. I f n o t sp ec i fi ed, th e p ri m ary k ey o f th e asso c i ated c l ass i s u sed.
u niq u e (o p ti o n al ): en abl es th e D D L gen erati o n o f a u n i q u e c o n strai n t fo r th e fo rei gn - k ey c o l u m n . B y

al l o w i n g th i s to be th e target o f a pro perty- ref , yo u c an m ak e th e asso c i ati o n m u l ti p l i c i ty o n e- to - o n e.
no t- nu l l (o p ti o n al ): en abl es th e D D L gen erati o n o f a n u l l abi l i ty c o n strai n t fo r th e fo rei gn k ey c o l u m n s.
o ptimis tic- l o ck (o p ti o n al - defau l ts to tru e ): sp ec i fi es th at u p dates to th i s p ro p erty do o r do n o t req u i re

ac q u i si ti o n o f th e o p ti m i sti c l o c k . I n o th er w o rds, i t determ i n es i f a v ersi o n i n c rem en t sh o u l d o c c u r
w h en th i s p ro p erty i s di rty.
1 2 l az y (o p ti o n al - defau l ts to pro x y): by defau l t, si n gl e p o i n t asso c i ati o n s are p ro x i ed. l az y=" no - pro x y"
sp ec i fi es th at th e p ro p erty sh o u l d be fetc h ed l az i l y w h en th e i n stan c e v ari abl e i s fi rst ac c essed. T h i s
req u i res bu i l d- ti m e bytec o de i n stru m en tati o n . l az y=" f al s e" sp ec i fi es th at th e asso c i ati o n w i l l al w ays be
eagerl y fetc h ed.
no t- f o u nd (o p ti o n al - defau l ts to ex ceptio n): sp ec i fi es h o w fo rei gn k eys th at referen c e m i ssi n g ro w s w i l l
be h an dl ed. igno re w i l l treat a m i ssi n g ro w as a n u l l asso c i ati o n .
entityname (o p ti o n al ): th e en ti ty n am e o f th e asso c i ated c l ass.
f o rmu l a (o p ti o n al ): an S Q L ex p ressi o n th at defi n es th e v al u e fo r a c om p ute d fo rei gn k ey.
S etti n g a v al u e o f th e cas cade attri bu te to an y m ean i n gfu l v al u e o th er th an no ne w i l l p ro p agate c ertai n

o p erati o n s to th e asso c i ated o bj ec t. T h e m ean i n gfu l v al u es are di v i ded i n to th ree c atego ri es. F i rst, basi c
o p erati o n s, w h i c h i n c l u de: pers is t, merge, del ete, s av e- u pdate, ev ict, repl icate, l o ck and ref res h ; sec o n d, sp ec i al
v al u es: del ete- o rph an; an d th i rd,al l c o m m a- sep arated c o m bi n ati o n s o f o p erati o n n am es:
cas cade=" pers is t, merge, ev ict" o r cas cade=" al l , del ete- o rph an" . S ee S ec ti o n 1 0 .1 1 , “ T ran si ti v e p ersi sten c e” fo r a
fu l l ex p l an ati o n . N o te th at si n gl e v al u ed, m an y- to - o n e an d o n e- to - o n e, asso c i ati o n s do n o t su p p o rt o rp h an
del ete.
H ere i s an ex am p l e o f a typ i c al many- to - o ne dec l arati o n :
< many- to - o ne name=" pro du ct" cl as s =" P ro du ct" co l u mn=" P R O D U C T _ I D " / >
T h e pro perty- ref attri bu te sh o u l d o n l y be u sed fo r m ap p i n g l egac y data w h ere a fo rei gn k ey refers to a u n i q u e
k ey o f th e asso c i ated tabl e o th er th an th e p ri m ary k ey. T h i s i s a c o m p l i c ated an d c o n fu si n g rel ati o n al m o del .
F o r ex am p l e, i f th e P ro du ct c l ass h ad a u n i q u e seri al n u m ber th at i s n o t th e p ri m ary k ey. T h e u niq u e attri bu te
c o n tro l s H i bern ate' s D D L gen erati o n w i th th e S c h em aE x p o rt to o l .
< pro perty name=" s erial Nu mb er" u niq u e=" tru e" type=" s tring" co l u mn=" SE R I A L _ NU M B E R " / >
T h en th e m ap p i n g fo r O rderI tem m i gh t u se:
< many- to - o ne name=" pro du ct" pro perty- ref =" s erial Nu mb er" co l u mn=" P R O D U C T _ SE R I A L _ NU M B E R " / >
T h i s i s n o t en c o u raged, h o w ev er.
I f th e referen c ed u n i q u e k ey c o m p ri ses m u l ti p l e p ro p erti es o f th e asso c i ated en ti ty, yo u sh o u l d m ap th e

referen c ed p ro p erti es i n si de a n am ed < pro perties > el em en t.
6 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I f th e referen c ed u n i q u e k ey i s th e p ro p erty o f a c o m p o n en t, yo u c an sp ec i fy a p ro p erty p ath :
< many- to - o ne name=" o w ner" pro perty- ref =" identity. s s n" co l u mn=" O W NE R _ SSN" / >
5 . 1 . 1 3 . O ne - to- one
A o n e- to - o n e asso c i ati o n to an o th er p ersi sten t c l ass i s dec l ared u si n g a o ne- to - o ne el em en t.
< o ne- to - o ne
co ns trained=" tru e| f al s e"
f o rmu l a=" any SQ L ex pres s io n"
l az y=" pro x y| no - pro x y| f al s e"
f o reign- k ey=" f o reign_ k ey_ name"
/ >
cl as s (o p ti o n al - defau l ts to th e p ro p erty typ e determ i n ed by refl ec ti o n ): th e n am e o f th e asso c i ated

c l ass.
cas cade (o p ti o n al ): sp ec i fi es w h i c h o p erati o n s sh o u l d be c asc aded fro m th e p aren t o bj ec t to th e
asso c i ated o bj ec t.
co ns trained (o p ti o n al ): sp ec i fi es th at a fo rei gn k ey c o n strai n t o n th e p ri m ary k ey o f th e m ap p ed tabl e
an d referen c es th e tabl e o f th e asso c i ated c l ass. T h i s o p ti o n affec ts th e o rder i n w h i c h s av e( ) an d
del ete( ) are c asc aded, an d determ i n es w h eth er th e asso c i ati o n c an be p ro x i ed. I t i s al so u sed by th e
sc h em a ex p o rt to o l .
f etch (o p ti o n al - defau l ts to s el ect ): c h o o ses betw een o u ter- j o i n fetc h i n g o r seq u en ti al sel ec t fetc h i n g.
pro perty- ref (o p ti o n al ): th e n am e o f a p ro p erty o f th e asso c i ated c l ass th at i s j o i n ed to th e p ri m ary k ey

o f th i s c l ass. I f n o t sp ec i fi ed, th e p ri m ary k ey o f th e asso c i ated c l ass i s u sed.
f o rmu l a (o p ti o n al ): al m o st al l o n e- to - o n e asso c i ati o n s m ap to th e p ri m ary k ey o f th e o w n i n g en ti ty. I f

th i s i s n o t th e c ase, yo u c an sp ec i fy an o th er c o l u m n , c o l u m n s o r ex p ressi o n to j o i n o n u si n g an S Q L
fo rm u l a. S ee o rg. h ib ernate. tes t. o neto o nef o rmu l a fo r an ex am p l e.
l az y (o p ti o n al - defau l ts to pro x y): by defau l t, si n gl e p o i n t asso c i ati o n s are p ro x i ed. l az y=" no - pro x y"
sp ec i fi es th at th e p ro p erty sh o u l d be fetc h ed l az i l y w h en th e i n stan c e v ari abl e i s fi rst ac c essed. I t
req u i res bu i l d- ti m e bytec o de i n stru m en tati o n . l az y=" f al s e" sp ec i fi es th at th e asso c i ati o n w i l l al w ays be
eagerl y fetc h ed. N ote th at if cons trained = " f als e" , p rox y ing is im p os s ib le and H ib e rnate w ill e ag e rly
f e tc h th e as s oc iation.
entityname (o p ti o n al ): th e en ti ty n am e o f th e asso c i ated c l ass.
T h ere are tw o v ari eti es o f o n e- to - o n e asso c i ati o n s:
p ri m ary k ey asso c i ati o n s

u n i q u e fo rei gn k ey asso c i ati o n s
P ri m ary k ey asso c i ati o n s do n o t n eed an ex tra tabl e c o l u m n . I f tw o ro w s are rel ated by th e asso c i ati o n , th en
th e tw o tabl e ro w s sh are th e sam e p ri m ary k ey v al u e. T o rel ate tw o o bj ec ts by a p ri m ary k ey asso c i ati o n ,
en su re th at th ey are assi gn ed th e sam e i den ti fi er v al u e.
F o r a p ri m ary k ey asso c i ati o n , add th e fo l l o w i n g m ap p i n gs to E mpl o yee an d P ers o n resp ec ti v el y:
7 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< o ne- to - o ne name=" pers o n" cl as s =" P ers o n" / >
< o ne- to - o ne name=" empl o yee" cl as s =" E mpl o yee" co ns trained=" tru e" / >
E n su re th at th e p ri m ary k eys o f th e rel ated ro w s i n th e P E R S O N an d E M P L O Y E E tabl es are eq u al . Y o u u se a

sp ec i al H i bern ate i den ti fi er gen erati o n strategy c al l ed f o reign:
< cl as s name=" pers o n" tab l e=" P E R SO N" >

< generato r cl as s =" f o reign" >
< param name=" pro perty" >empl o yee< / param>
< / generato r>
< / id>
...
< o ne- to - o ne name=" empl o yee"
cl as s =" E mpl o yee"
co ns trained=" tru e" / >
< / cl as s >
A n ew l y sav ed i n stan c e o f P ers o n i s assi gn ed th e sam e p ri m ary k ey v al u e as th e E mpl o yee i n stan c e referred
w i th th e empl o yee p ro p erty o f th at P ers o n.
A l tern ati v el y, a fo rei gn k ey w i th a u n i q u e c o n strai n t, fro m E mpl o yee to P ers o n, c an be ex p ressed as:
< many- to - o ne name=" pers o n" cl as s =" P ers o n" co l u mn=" P E R SO N_ I D " u niq u e=" tru e" / >
T h i s asso c i ati o n c an be m ade bi di rec ti o n al by addi n g th e fo l l o w i n g to th e P ers o n m ap p i n g:
< o ne- to - o ne name=" empl o yee" cl as s =" E mpl o yee" pro perty- ref =" pers o n" / >
5 . 1 . 1 4 . N atu ral - i d
< natu ral - id mu tab l e=" tru e| f al s e" / >

< pro perty . . . / >
< many- to - o ne . . . / >
......
< / natu ral - id>
A l th o u gh w e rec o m m en d th e u se o f su rro gate k eys as p ri m ary k eys, yo u sh o u l d try to i den ti fy n atu ral k eys
fo r al l en ti ti es. A n atu ral k ey i s a p ro p erty o r c o m bi n ati o n o f p ro p erti es th at i s u n i q u e an d n o n - n u l l . I t i s al so
i m m u tabl e. M ap th e p ro p erti es o f th e n atu ral k ey i n si de th e < natu ral - id> el em en t. H i bern ate w i l l gen erate
th e n ec essary u n i q u e k ey an d n u l l abi l i ty c o n strai n ts an d, as a resu l t, yo u r m ap p i n g w i l l be m o re
sel f- do c u m en ti n g.
I t i s rec o m m en ded th at yo u i m p l em en t eq u al s ( ) an d h as h C o de( ) to c o m p are th e n atu ral k ey p ro p erti es o f th e

en ti ty.
T h i s m ap p i n g i s n o t i n ten ded fo r u se w i th en ti ti es th at h av e n atu ral p ri m ary k eys.
mu tab l e (o p ti o n al - defau l ts to f al s e ): by defau l t, n atu ral i den ti fi er p ro p erti es are assu m ed to be

im m u tabl e (c o n stan t).
5 . 1 . 1 5 . C ompone nt and d y nami c - c ompone nt
T h e < co mpo nent> el em en t m ap s p ro p erti es o f a c h i l d o bj ec t to c o lu m n s o f th e tabl e o f a p aren t c l ass.

Co m p o n en ts c an , i n tu rn , dec l are th ei r o w n p ro p erti es, c o m p o n en ts o r c o l l ec ti o n s. S ee th e " Co m p o n en t"
ex am p l es bel o w :
7 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< co mpo nent

cl as s =" cl as s Name"
>
< pro perty . . . . . / >

< many- to - o ne . . . . / >
........
< / co mpo nent>
cl as s (o p ti o n al - defau l ts to th e p ro p erty typ e determ i n ed by refl ec ti o n ): th e n am e o f th e c o m p o n en t

(c h i l d) c l ass.
ins ert : do th e m ap p ed c o l u m n s ap p ear i n S Q L I NSE R T s ?
u pdate : do th e m ap p ed c o l u m n s ap p ear i n S Q L U P D A T E s ?
l az y (o p ti o n al - defau l ts to f al s e): sp ec i fi es th at th i s c o m p o n en t sh o u l d be fetc h ed l az i l y w h en th e

i n stan c e v ari abl e i s fi rst ac c essed. I t req u i res bu i l d- ti m e bytec o de i n stru m en tati o n .
o ptimis tic- l o ck (o p ti o n al - defau l ts to tru e ): sp ec i fi es th at u p dates to th i s c o m p o n en t ei th er do o r do n o t
req u i re ac q u i si ti o n o f th e o p ti m i sti c l o c k . I t determ i n es i f a v ersi o n i n c rem en t sh o u l d o c c u r w h en th i s
p ro p erty i s di rty.
u niq u e (o p ti o n al - defau l ts to f al s e ): sp ec i fi es th at a u n i q u e c o n strai n t ex i sts u p o n al l m ap p ed c o l u m n s
o f th e c o m p o n en t.
T h e c h i l d < pro perty> tags m ap p ro p erti es o f th e c h i l d c l ass to tabl e c o l u m n s.
T h e < co mpo nent> el em en t al l o w s a < parent> su bel em en t th at m ap s a p ro p erty o f th e c o m p o n en t c l ass as a

referen c e bac k to th e c o n tai n i n g en ti ty.
T h e < dynamic- co mpo nent> el em en t al l o w s a M ap to be m ap p ed as a c o m p o n en t, w h ere th e p ro p erty n am es

refer to k eys o f th e m ap . S ee S ec ti o n 8 .5 , “ D yn am i c c o m p o n en ts” fo r m o re i n fo rm ati o n .
5 . 1 . 1 6 . P rope rti e s
T h e < pro perties > el em en t al l o w s th e defi n i ti o n o f a n am ed, l o gi c al gro u p i n g o f th e p ro p erti es o f a c l ass. T h e

m o st i m p o rtan t u se o f th e c o n stru c t i s th at i t al l o w s a c o m bi n ati o n o f p ro p erti es to be th e target o f a
pro perty- ref . I t i s al so a c o n v en i en t w ay to defi n e a m u l ti - c o l u m n u n i q u e c o n strai n t. F o r ex am p l e:
< pro perties

name=" l o gical Name"
>
< pro perty . . . . . / >

< many- to - o ne . . . . / >
........
< / pro perties >
7 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
name : th e l o gi c al n am e o f th e gro u p i n g. I t i s not an ac tu al p ro p erty n am e.
ins ert : do th e m ap p ed c o l u m n s ap p ear i n S Q L I NSE R T s ?
u pdate : do th e m ap p ed c o l u m n s ap p ear i n S Q L U P D A T E s ?
o ptimis tic- l o ck (o p ti o n al - defau l ts to tru e ): sp ec i fi es th at u p dates to th ese p ro p erti es ei th er do o r do

n o t req u i re ac q u i si ti o n o f th e o p ti m i sti c l o c k . I t determ i n es i f a v ersi o n i n c rem en t sh o u l d o c c u r w h en
th ese p ro p erti es are di rty.
u niq u e (o p ti o n al - defau l ts to f al s e ): sp ec i fi es th at a u n i q u e c o n strai n t ex i sts u p o n al l m ap p ed c o l u m n s
o f th e c o m p o n en t.
F o r ex am p l e, i f w e h av e th e fo l l o w i n g < pro perties > m ap p i n g:
< cl as s name=" P ers o n" >

< id name=" pers o nNu mb er" / >
...
< pro perties name=" name"
u niq u e=" tru e" u pdate=" f al s e" >
< pro perty name=" f irs tName" / >
< pro perty name=" initial " / >
< pro perty name=" l as tName" / >
< / pro perties >
< / cl as s >
Y o u m i gh t h av e so m e l egac y data asso c i ati o n th at refers to th i s u n i q u e k ey o f th e P ers o n tabl e, i n stead o f to

th e p ri m ary k ey:
< many- to - o ne name=" pers o n"

cl as s =" P ers o n" pro perty- ref =" name" >
< co l u mn name=" f irs tName" / >
< co l u mn name=" initial " / >
< co l u mn name=" l as tName" / >
< / many- to - o ne>
T h e u se o f th i s o u tsi de th e c o n tex t o f m ap p i n g l egac y data i s n o t rec o m m en ded.
5 . 1 . 1 7 . S u b c l as s
P o l ym o rp h i c p ersi sten c e req u i res th e dec l arati o n o f eac h su bc l ass o f th e ro o t p ersi sten t c l ass. F o r th e tabl e-
p er- c l ass- h i erarc h y m ap p i n g strategy, th e < s u b cl as s > dec l arati o n i s u sed. F o r ex am p l e:
< s u b cl as s
dis criminato r- v al u e=" dis criminato r_ v al u e"
ex tends =" Su percl as s Name" >
< pro perty . . . . / >

.....
< / s u b cl as s >
name : th e fu l l y q u al i fi ed c l ass n am e o f th e su bc l ass.
dis criminato r- v al u e (o p ti o n al - defau l ts to th e c l ass n am e): a v al u e th at di sti n gu i sh es i n di v i du al

su bc l asses.
7 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
pro x y (o p ti o n al ): sp ec i fi es a c l ass o r i n terfac e u sed fo r l az y i n i ti al i z i n g p ro x i es.
l az y (o p ti o n al - defau l ts to tru e): setti n g l az y=" f al s e" di sabl es th e u se o f l az y fetc h i n g.
E ac h su bc l ass dec l ares i ts o w n p ersi sten t p ro p erti es an d su bc l asses. < v ers io n> an d < id> p ro p erti es are
assu m ed to be i n h eri ted fro m th e ro o t c l ass. E ac h su bc l ass i n a h i erarc h y m u st defi n e a u n i q u e
dis criminato r- v al u e. I f th i s i s n o t sp ec i fi ed, th e fu l l y q u al i fi ed J av a c l ass n am e i s u sed.
F o r i n fo rm ati o n abo u t i n h eri tan c e m ap p i n gs see Ch ap ter 9 , I nh e ritanc e m ap p ing .
5 . 1 . 1 8 . J oi ne d - s u b c l as s
E ac h su bc l ass c an al so be m ap p ed to i ts o w n tabl e. T h i s i s c al l ed th e tabl e- p er- su bc l ass m ap p i n g strategy. A n

i n h eri ted state i s retri ev ed by j o i n i n g w i th th e tabl e o f th e su p erc l ass. T o do th i s yo u u se th e
< j o ined- s u b cl as s > el em en t. F o r ex am p l e:
< j o ined- s u b cl as s
tab l e=" tab l ename"
s ch ema=" s ch ema"
ex tends =" Su percl as s Name"
pers is ter=" C l as s Name"
no de=" el ement- name" >
< k ey . . . . >
< pro perty . . . . / >

.....
< / j o ined- s u b cl as s >
tab l e: th e n am e o f th e su bc l ass tabl e.
pro x y (o p ti o n al ): sp ec i fi es a c l ass o r i n terfac e to u se fo r l az y i n i ti al i z i n g p ro x i es.
l az y (o p ti o n al , defau l ts to tru e ): setti n g l az y=" f al s e" di sabl es th e u se o f l az y fetc h i n g.
A di sc ri m i n ato r c o l u m n i s n o t req u i red fo r th i s m ap p i n g strategy. E ac h su bc l ass m u st, h o w ev er, dec l are a

tabl e c o l u m n h o l di n g th e o bj ec t i den ti fi er u si n g th e < k ey> el em en t. T h e m ap p i n g at th e start o f th e c h ap ter
w o u l d th en be re- w ri tten as:
7 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< ?x ml v ers io n=" 1. 0" ?>

" - / / H ib ernate/ H ib ernate M apping D T D / / E N"
< cl as s name=" C at" tab l e=" C A T S" >

< id name=" id" co l u mn=" u id" type=" l o ng" >
< generato r cl as s =" h il o " / >
< / id>
< pro perty name=" b irth date" type=" date" / >
< pro perty name=" co l o r" no t- nu l l =" tru e" / >
< pro perty name=" s ex " no t- nu l l =" tru e" / >
< pro perty name=" w eigh t" / >
< many- to - o ne name=" mate" / >
< s et name=" k ittens " >
< k ey co l u mn=" M O T H E R " / >
< o ne- to - many cl as s =" C at" / >
< / s et>
< j o ined- s u b cl as s name=" D o mes ticC at" tab l e=" D O M E ST I C _ C A T S" >
< k ey co l u mn=" C A T " / >
< pro perty name=" name" type=" s tring" / >
< / cl as s >
< cl as s name=" eg. D o g" >

< ! - - mapping f o r D o g co u l d go h ere - - >
< / cl as s >
5 . 1 . 1 9 . U ni on- s u b c l as s
A th i rd o p ti o n i s to m ap o n l y th e c o n c rete c l asses o f an i n h eri tan c e h i erarc h y to tabl es. T h i s i s c al l ed th e

tabl e- p er- c o n c rete- c l ass strategy. E ac h tabl e defi n es al l p ersi sten t states o f th e c l ass, i n c l u di n g th e i n h eri ted
state. I n H i bern ate, i t i s n o t n ec essary to ex p l i c i tl y m ap su c h i n h eri tan c e h i erarc h i es. Y o u c an m ap eac h c l ass
w i th a sep arate < cl as s > dec l arati o n . H o w ev er, i f yo u w i sh u se p o l ym o rp h i c asso c i ati o n s (e.g. an asso c i ati o n
to th e su p erc l ass o f yo u r h i erarc h y), yo u n eed to u se th e m ap p i n g. F o r ex am p l e:
7 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< pro perty . . . . / >

.....

tab l e: th e n am e o f th e su bc l ass tabl e.
pro x y (o p ti o n al ): sp ec i fi es a c l ass o r i n terfac e to u se fo r l az y i n i ti al i z i n g p ro x i es.
l az y (o p ti o n al , defau l ts to tru e ): setti n g l az y=" f al s e" di sabl es th e u se o f l az y fetc h i n g.
N o di sc ri m i n ato r c o l u m n o r k ey c o l u m n i s req u i red fo r th i s m ap p i n g strategy.
5 . 1 . 2 0 . J oi n
U si n g th e < j o in> el em en t, i t i s p o ssi bl e to m ap p ro p erti es o f o n e c l ass to sev eral tabl es th at h av e a

o n e- to - o n e rel ati o n sh i p . F o r ex am p l e:
< j o in
s ch ema=" o w ner"
inv ers e=" tru e| f al s e"
o ptio nal =" tru e| f al s e" >
< k ey . . . / >
< pro perty . . . / >

...
< / j o in>
tab l e: th e n am e o f th e j o i n ed tabl e.
s ch ema (o p ti o n al ): o v erri des th e sc h em a n am e sp ec i fi ed by th e ro o t < h ib ernate- mapping> el em en t.
catal o g (o p ti o n al ): o v erri des th e c atal o g n am e sp ec i fi ed by th e ro o t < h ib ernate- mapping> el em en t.
f etch (o p ti o n al - defau l ts to j o in): i f set to j o in, th e defau l t, H i bern ate w i l l u se an i n n er j o i n to retri ev e

a < j o in> defi n ed by a c l ass o r i ts su p erc l asses. I t w i l l u se an o u ter j o i n fo r a < j o in> defi n ed by a
su bc l ass. I f set to s el ect th en H i bern ate w i l l u se a seq u en ti al sel ec t fo r a < j o in> defi n ed o n a su bc l ass.
T h i s w i l l be i ssu ed o n l y i f a ro w rep resen ts an i n stan c e o f th e su bc l ass. I n n er j o i n s w i l l sti l l be u sed to
retri ev e a < j o in> defi n ed by th e c l ass an d i ts su p erc l asses.
7 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
inv ers e (o p ti o n al - defau l ts to f al s e ): i f en abl ed, H i bern ate w i l l n o t i n sert o r u p date th e p ro p erti es
defi n ed by th i s j o i n .
o ptio nal (o p ti o n al - defau l ts to f al s e ): i f en abl ed, H i bern ate w i l l i n sert a ro w o n l y i f th e p ro p erti es
defi n ed by th i s j o i n are n o n - n u l l . I t w i l l al w ays u se an o u ter j o i n to retri ev e th e p ro p erti es.
F o r ex am p l e, address i n fo rm ati o n fo r a p erso n c an be m ap p ed to a sep arate tabl e w h i l e p reserv i n g v al u e

typ e sem an ti c s fo r al l p ro p erti es:
< cl as s name=" P ers o n"

tab l e=" P E R SO N" >
< id name=" id" co l u mn=" P E R SO N_ I D " >. . . < / id>
< j o in tab l e=" A D D R E SS" >

< k ey co l u mn=" A D D R E SS_ I D " / >
< pro perty name=" addres s " / >
< pro perty name=" z ip" / >
< pro perty name=" co u ntry" / >
< / j o in>
...
T h i s featu re i s o ften o n l y u sefu l fo r l egac y data m o del s. W e rec o m m en d few er tabl es th an c l asses an d a
fi n e- grai n ed do m ai n m o del . H o w ev er, i t i s u sefu l fo r sw i tc h i n g betw een i n h eri tan c e m ap p i n g strategi es i n a
si n gl e h i erarc h y, as ex p l ai n ed l ater.
5 .1 .2 1 . K e y
T h e < k ey> el em en t h as featu red a few ti m es w i th i n th i s gu i de. I t ap p ears an yw h ere th e p aren t m ap p i n g

el em en t defi n es a j o i n to a n ew tabl e th at referen c es th e p ri m ary k ey o f th e o ri gi n al tabl e. I t al so defi n es th e
fo rei gn k ey i n th e j o i n ed tabl e:
< k ey
co l u mn=" co l u mnname"
o n- del ete=" no actio n| cas cade"
pro perty- ref =" pro pertyName"
/ >
co l u mn (o p ti o n al ): th e n am e o f th e fo rei gn k ey c o l u m n . T h i s c an al so be sp ec i fi ed by n ested < co l u mn>

el em en t(s).
o n- del ete (o p ti o n al - defau l ts to no actio n): sp ec i fi es w h eth er th e fo rei gn k ey c o n strai n t h as
database- l ev el c asc ade del ete en abl ed.
pro perty- ref (o p ti o n al ): sp ec i fi es th at th e fo rei gn k ey refers to c o l u m n s th at are n o t th e p ri m ary k ey o f
th e o ri gi n al tabl e. I t i s p ro v i ded fo r l egac y data.
no t- nu l l (o p ti o n al ): sp ec i fi es th at th e fo rei gn k ey c o l u m n s are n o t n u l l abl e. T h i s i s i m p l i ed w h en ev er
th e fo rei gn k ey i s al so p art o f th e p ri m ary k ey.
u pdate (o p ti o n al ): sp ec i fi es th at th e fo rei gn k ey sh o u l d n ev er be u p dated. T h i s i s i m p l i ed w h en ev er
th e fo rei gn k ey i s al so p art o f th e p ri m ary k ey.
u niq u e (o p ti o n al ): sp ec i fi es th at th e fo rei gn k ey sh o u l d h av e a u n i q u e c o n strai n t. T h i s i s i m p l i ed
w h en ev er th e fo rei gn k ey i s al so th e p ri m ary k ey.
F o r system s w h ere del ete p erfo rm an c e i s i m p o rtan t, w e rec o m m en d th at al l k eys sh o u l d be defi n ed

o n- del ete=" cas cade" . H i bern ate u ses a database- l ev el O N C A SC A D E D E L E T E c o n strai n t, i n stead o f m an y
i n di v i du al D E L E T E statem en ts. B e aw are th at th i s featu re byp asses H i bern ate' s u su al o p ti m i sti c lo c k in g
strategy fo r v ersi o n ed data.
T h e no t- nu l l an d u pdate attri bu tes are u sefu l w h en m ap p i n g a u n i di rec ti o n al o n e- to - m an y asso c i ati o n . I f yo u
7 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
m ap a u n i di rec ti o n al o n e- to - m an y asso c i ati o n to a n o n - n u l l abl e fo rei gn k ey, yo u m us t dec l are th e k ey

c o l u m n u si n g < k ey no t- nu l l =" tru e" >.
5 . 1 . 2 2 . C ol u mn and f ormu l a e l e me nts
M ap p i n g el em en ts w h i c h ac c ep t a co l u mn attri bu te w i l l al tern ati v el y ac c ep t a < co l u mn> su bel em en t. L i k ew i se,

< f o rmu l a> i s an al tern ati v e to th e f o rmu l a attri bu te. F o r ex am p l e:
< co l u mn
name=" co l u mn_ name"
l ength =" N"
precis io n=" N"
s cal e=" N"
u niq u e- k ey=" mu l tico l u mn_ u niq u e_ k ey_ name"
s q l - type=" s q l _ type_ name"
ch eck =" SQ L ex pres s io n"
def au l t=" SQ L ex pres s io n" / >
< f o rmu l a>SQ L ex pres s io n< / f o rmu l a>
co l u mn an d f o rmu l a attri bu tes c an ev en be c o m bi n ed w i th i n th e sam e p ro p erty o r asso c i ati o n m ap p i n g to

ex p ress, fo r ex am p l e, ex o ti c j o i n c o n di ti o n s.
< many- to - o ne name=" h o meA ddres s " cl as s =" A ddres s "

ins ert=" f al s e" u pdate=" f al s e" >
< co l u mn name=" pers o n_ id" no t- nu l l =" tru e" l ength =" 10" / >
< f o rmu l a>' M A I L I NG ' < / f o rmu l a>
5 . 1 . 2 3 . Import
I f yo u r ap p l i c ati o n h as tw o p ersi sten t c l asses w i th th e sam e n am e, an d yo u do n o t w an t to sp ec i fy th e fu l l y

q u al i fi ed p ac k age n am e i n H i bern ate q u eri es, c l asses c an be " i m p o rted" ex p l i c i tl y, rath er th an rel yi n g u p o n
au to - impo rt=" tru e" . Y o u c an al so i m p o rt c l asses an d i n terfac es th at are n o t ex p l i c i tl y m ap p ed:
< impo rt cl as s =" j av a. l ang. O b j ect" rename=" U niv ers e" / >
< impo rt
rename=" Sh o rtName"
/ >
cl as s : th e fu l l y q u al i fi ed c l ass n am e o f an y J av a c l ass.
rename (o p ti o n al - defau l ts to th e u n q u al i fi ed c l ass n am e): a n am e th at c an be u sed i n th e q u ery

l an gu age.
5 . 1 . 2 4 . A ny
T h ere i s o n e m o re typ e o f p ro p erty m ap p i n g. T h e < any> m ap p i n g el em en t defi n es a p o l ym o rp h i c asso c i ati o n

to c l asses fro m m u l ti p l e tabl es. T h i s typ e o f m ap p i n g req u i res m o re th an o n e c o l u m n . T h e fi rst c o l u m n
c o n tai n s th e typ e o f th e asso c i ated en ti ty. T h e rem ai n i n g c o l u m n s c o n tai n th e i den ti fi er. I t i s i m p o ssi bl e to
sp ec i fy a fo rei gn k ey c o n strai n t fo r th i s k i n d o f asso c i ati o n . T h i s i s n o t th e u su al w ay o f m ap p i n g p o l ym o rp h i c
asso c i ati o n s an d yo u sh o u l d u se th i s o n l y i n sp ec i al c ases. F o r ex am p l e, fo r au di t l o gs, u ser sessi o n data, etc .
7 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h e meta- type attri bu te al l o w s th e ap p l i c ati o n to sp ec i fy a c u sto m typ e th at m ap s database c o l u m n v al u es to

p ersi sten t c l asses th at h av e i den ti fi er p ro p erti es o f th e typ e sp ec i fi ed by id- type . Y o u m u st sp ec i fy th e
m ap p i n g fro m v al u es o f th e m eta- typ e to c l ass n am es.
< any name=" b eing" id- type=" l o ng" meta- type=" s tring" >
< meta- v al u e v al u e=" T B L _ A NI M A L " cl as s =" A nimal " / >
< meta- v al u e v al u e=" T B L _ H U M A N" cl as s =" H u man" / >
< meta- v al u e v al u e=" T B L _ A L I E N" cl as s =" A l ien" / >
< co l u mn name=" tab l e_ name" / >
< co l u mn name=" id" / >
< / any>
< any
id- type=" idtypename"
meta- type=" metatypename"
>
< meta- v al u e . . . / >
< meta- v al u e . . . / >
.....
< co l u mn . . . . / >
< co l u mn . . . . / >
.....
< / any>
name : th e p ro p erty n am e.
id- type: th e i den ti fi er typ e.
meta- type (o p ti o n al - defau l ts to s tring ): an y typ e th at i s al l o w ed fo r a di sc ri m i n ato r m ap p i n g.
cas cade (o p ti o n al - defau l ts to no ne ): th e c asc ade styl e.
o ptimis tic- l o ck (o p ti o n al - defau l ts to tru e ): sp ec i fi es th at u p dates to th i s p ro p erty ei th er do o r do n o t

req u i re ac q u i si ti o n o f th e o p ti m i sti c l o c k . I t defi n es w h eth er a v ersi o n i n c rem en t sh o u l d o c c u r i f th i s
p ro p erty i s di rty.
5 . 2 . Hibernate ty p es
5 . 2 . 1 . E nti ti e s and v al u e s
I n rel ati o n to th e p ersi sten c e serv i c e, J av a l an gu age- l ev el o bj ec ts are c l assi fi ed i n to tw o gro u p s:
A n e ntity ex i sts i n dep en den tl y o f an y o th er o bj ec ts h o l di n g referen c es to th e en ti ty. Co n trast th i s w i th th e

u su al J av a m o del , w h ere an u n referen c ed o bj ec t i s garbage c o l l ec ted. E n ti ti es m u st be ex p l i c i tl y sav ed an d
del eted. S av es an d del eti o n s, h o w ev er, c an be c as c ad e d fro m a p aren t en ti ty to i ts c h i l dren . T h i s i s di fferen t
fro m th e O D M G m o del o f o bj ec t p ersi sten c e by reac h abi l i ty an d c o rresp o n ds m o re c l o sel y to h o w ap p l i c ati o n
o bj ec ts are u su al l y u sed i n l arge system s. E n ti ti es su p p o rt c i rc u l ar an d sh ared referen c es. T h ey c an al so be
v ersi o n ed.
A n en ti ty' s p ersi sten t state c o n si sts o f referen c es to o th er en ti ti es an d i n stan c es o f v alue typ es. V al u es are
p ri m i ti v es: c o l l ec ti o n s (n o t w h at i s i n si de a c o l l ec ti o n ), c o m p o n en ts an d c ertai n i m m u tabl e o bj ec ts. U n l i k e
en ti ti es, v al u es i n p arti c u l ar c o l l ec ti o n s an d c o m p o n en ts, are p ersi sted an d del eted by reac h abi l i ty. S i n c e
v al u e o bj ec ts an d p ri m i ti v es are p ersi sted an d del eted al o n g w i th th ei r c o n tai n i n g en ti ty, th ey c an n o t be
i n dep en den tl y v ersi o n ed. V al u es h av e n o i n dep en den t i den ti ty, so th ey c an n o t be sh ared by tw o en ti ti es o r
c o l l ec ti o n s.
7 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
U n ti l n o w , w e h av e been u si n g th e term " p ersi sten t c l ass" to refer to en ti ti es. W e w i l l c o n ti n u e to do th at. N o t

al l u ser- defi n ed c l asses w i th a p ersi sten t state, h o w ev er, are en ti ti es. A c om p one nt i s a u ser- defi n ed c l ass
w i th v al u e sem an ti c s. A J av a p ro p erty o f typ e j av a. l ang. String al so h as v al u e sem an ti c s. G i v en th i s defi n i ti o n ,
al l typ es (c l asses) p ro v i ded by th e J D K h av e v al u e typ e sem an ti c s i n J av a, w h i l e u ser- defi n ed typ es c an be
m ap p ed w i th en ti ty o r v al u e typ e sem an ti c s. T h i s dec i si o n i s u p to th e ap p l i c ati o n dev el o p er. A n en ti ty c l ass
i n a do m ai n m o del w i l l n o rm al l y h av e sh ared referen c es to a si n gl e i n stan c e o f th at c l ass, w h i l e c o m p o si ti o n
o r aggregati o n u su al l y tran sl ates to a v al u e typ e.
W e w i l l rev i si t bo th c o n c ep ts th ro u gh o u t th i s referen c e gu i de.
T h e c h al l en ge i s to m ap th e J av a typ e system , an d th e dev el o p ers' defi n i ti o n o f en ti ti es an d v al u e typ es, to

th e S Q L /database typ e system . T h e bri dge betw een bo th system s i s p ro v i ded by H i bern ate. F o r en ti ti es,
< cl as s >, < s u b cl as s > an d so o n are u sed. F o r v al u e typ es w e u se < pro perty>, < co mpo nent>etc ., th at u su al l y
h av e a type attri bu te. T h e v al u e o f th i s attri bu te i s th e n am e o f a H i bern ate m ap p ing ty p e . H i bern ate
p ro v i des a ran ge o f m ap p i n gs fo r stan dard J D K v al u e typ es o u t o f th e bo x . Y o u c an w ri te yo u r o w n m ap p i n g
typ es an d i m p l em en t yo u r o w n c u sto m c o n v ersi o n strategi es.
W i th th e ex c ep ti o n o f c o l l ec ti o n s, al l bu i l t- i n H i bern ate typ es su p p o rt n u l l sem an ti c s.
5 . 2 . 2 . B as i c v al u e ty pe s
T h e bu i l t- i n b as ic m ap p ing ty p e s c an be ro u gh l y c atego ri z ed i n to th e fo l l o w i n g:
integer, l o ng, s h o rt, f l o at, do u b l e, ch aracter, b yte, b o o l ean, yes _ no , tru e_ f al s e
T yp e m ap p i n gs fro m J av a p ri m i ti v es o r w rap p er c l asses to ap p ro p ri ate (v en do r- sp ec i fi c ) S Q L c o l u m n

typ es. b o o l ean, yes _ no an d tru e_ f al s e are al l al tern ati v e en c o di n gs fo r a J av a b o o l ean o r j av a. l ang. B o o l ean.
s tring
A typ e m ap p i n g fro m j av a. l ang. String to V A R C H A R (o r O rac l e V A R C H A R 2 ).
date, time, times tamp
T yp e m ap p i n gs fro m j av a. u til . D ate an d i ts su bc l asses to S Q L typ es D A T E , T I M E an d T I M E ST A M P (o r

eq u i v al en t).
cal endar, cal endar_ date
T yp e m ap p i n gs fro m j av a. u til . C al endar to S Q L typ es T I M E ST A M P an d D A T E (o r eq u i v al en t).
b ig_ decimal , b ig_ integer
T yp e m ap p i n gs fro m j av a. math . B igD ecimal an d j av a. math . B igI nteger to NU M E R I C (o r O rac l e NU M B E R ).
l o cal e, timez o ne, cu rrency
T yp e m ap p i n gs fro m j av a. u til . L o cal e, j av a. u til . T imeZ o ne an d j av a. u til . C u rrency to V A R C H A R (o r O rac l e

V A R C H A R 2 ). I n stan c es o f L o cal e an d C u rrency are m ap p ed to th ei r I S O c o des. I n stan c es o f T imeZ o ne are
m ap p ed to th ei r I D .
cl as s
A typ e m ap p i n g fro m j av a. l ang. C l as s to V A R C H A R (o r O rac l e V A R C H A R 2 ). A C l as s i s m ap p ed to i ts fu l l y

q u al i fi ed n am e.
b inary
M ap s byte arrays to an ap p ro p ri ate S Q L bi n ary typ e.
tex t
M ap s l o n g J av a stri n gs to a S Q L C L O B o r T E X T typ e.
s erial iz ab l e
M ap s seri al i z abl e J av a typ es to an ap p ro p ri ate S Q L bi n ary typ e. Y o u c an al so i n di c ate th e H i bern ate typ e
s erial iz ab l e w i th
th e n am e o f a seri al i z abl e J av a c l ass o r i n terfac e th at do es n o t defau l t to a basi c typ e.
cl o b , b l o b
T yp e m ap p i n gs fo r th e J D B C c l asses j av a. s q l . C l o b an d j av a. s q l . B l o b . T h ese typ es c an be i n c o n v en i en t fo r
8 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
so m e ap p l i c ati o n s, si n c e th e bl o b o r c l o b o bj ec t c an n o t be reu sed o u tsi de o f a tran sac ti o n . D ri v er su p p o rt

i s p atc h y an d i n c o n si sten t.
imm_ date, imm_ time, imm_ times tamp, imm_ cal endar, imm_ cal endar_ date, imm_ s erial iz ab l e, imm_ b inary
T yp e m ap p i n gs fo r w h at are c o n si dered m u tabl e J av a typ es. T h i s i s w h ere H i bern ate m ak es c ertai n

o p ti m i z ati o n s ap p ro p ri ate o n l y fo r i m m u tabl e J av a typ es, an d th e ap p l i c ati o n treats th e o bj ec t as
i m m u tabl e. F o r ex am p l e, yo u sh o u l d n o t c al l D ate. s etT ime( ) fo r an i n stan c e m ap p ed as imm_ times tamp. T o
c h an ge th e v al u e o f th e p ro p erty, an d h av e th at c h an ge m ade p ersi sten t, th e ap p l i c ati o n m u st assi gn a
n ew , n o n i den ti c al , o bj ec t to th e p ro p erty.
U n i q u e i den ti fi ers o f en ti ti es an d c o l l ec ti o n s c an be o f an y basi c typ e ex c ep t b inary, b l o b an d cl o b . Co m p o si te

i den ti fi ers are al so al l o w ed. S ee bel o w fo r m o re i n fo rm ati o n .
T h e basi c v al u e typ es h av e c o rresp o n di n g T ype c o n stan ts defi n ed o n o rg. h ib ernate. H ib ernate. F o r ex am p l e,

H ib ernate. ST R I NG rep resen ts th e s tring typ e.
5 . 2 . 3 . C u s tom v al u e ty pe s
I t i s rel ati v el y easy fo r dev el o p ers to c reate th ei r o w n v al u e typ es. F o r ex am p l e, yo u m i gh t w an t to p ersi st

p ro p erti es o f typ e j av a. l ang. B igI nteger to V A R C H A R c o l u m n s. H i bern ate do es n o t p ro v i de a bu i l t- i n typ e fo r th i s.
Cu sto m typ es are n o t l i m i ted to m ap p i n g a p ro p erty, o r c o l l ec ti o n el em en t, to a si n gl e tabl e c o l u m n . S o , fo r
ex am p l e, yo u m i gh t h av e a J av a p ro p erty getName( )/s etName( ) o f typ e j av a. l ang. String th at i s p ersi sted to th e
c o l u m n s F I R ST _ NA M E , I NI T I A L , SU R NA M E .
T o i m p l em en t a c u sto m typ e, i m p l em en t ei th er o rg. h ib ernate. U s erT ype o r o rg. h ib ernate. C o mpo s iteU s erT ype an d
dec l are p ro p erti es u si n g th e fu l l y q u al i fi ed c l assn am e o f th e typ e. V i ew o rg. h ib ernate. tes t. D o u b l eStringT ype to
see th e k i n d o f th i n gs th at are p o ssi bl e.
< pro perty name=" tw o Strings " type=" o rg. h ib ernate. tes t. D o u b l eStringT ype" >
< co l u mn name=" f irs t_ s tring" / >
< co l u mn name=" s eco nd_ s tring" / >
< / pro perty>
N o ti c e th e u se o f < co l u mn> tags to m ap a p ro p erty to m u l ti p l e c o l u m n s.
T h e C o mpo s iteU s erT ype , E nh ancedU s erT ype , U s erC o l l ectio nT ype , an d U s erV ers io nT ype i n terfac es p ro v i de su p p o rt
fo r m o re sp ec i al i z ed u ses.
Y o u c an ev en su p p l y p aram eters to a U s erT ype i n th e m ap p i n g fi l e. T o do th i s, yo u r U s erT ype m u st i m p l em en t

th e o rg. h ib ernate. u s ertype. P arameteriz edT ype i n terfac e. T o su p p l y p aram eters to yo u r c u sto m typ e, yo u c an u se
th e < type> el em en t i n yo u r m ap p i n g fi l es.
< pro perty name=" prio rity" >

< type name=" co m. myco mpany. u s ertypes . D ef au l tV al u eI ntegerT ype" >
< param name=" def au l t" >0< / param>
< / type>
< / pro perty>
T h e U s erT ype c an n o w retri ev e th e v al u e fo r th e p aram eter n am ed def au l t fro m th e P ro perties o bj ec t p assed to

i t.
I f yo u regu l arl y u se a c ertai n U s erT ype, i t i s u sefu l to defi n e a sh o rter n am e fo r i t. Y o u c an do th i s u si n g th e

< typedef > el em en t. T yp edefs assi gn a n am e to a c u sto m typ e, an d c an al so c o n tai n a l i st o f defau l t
p aram eter v al u es i f th e typ e i s p aram eteri z ed.
< typedef cl as s =" co m. myco mpany. u s ertypes . D ef au l tV al u eI ntegerT ype" name=" def au l t_ z ero " >
< param name=" def au l t" >0< / param>
< / typedef >
< pro perty name=" prio rity" type=" def au l t_ z ero " / >
8 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I t i s al so p o ssi bl e to o v erri de th e p aram eters su p p l i ed i n a typ edef o n a c ase- by- c ase basi s by u si n g typ e
p aram eters o n th e p ro p erty m ap p i n g.
E v en th o u gh H i bern ate' s ri c h ran ge o f bu i l t- i n typ es an d su p p o rt fo r c o m p o n en ts m ean s yo u w i l l rarel y n eed

to u se a c u sto m typ e, i t i s c o n si dered go o d p rac ti c e to u se c u sto m typ es fo r n o n - en ti ty c l asses th at o c c u r
freq u en tl y i n yo u r ap p l i c ati o n . F o r ex am p l e, a M o netaryA mo u nt c l ass i s a go o d c an di date fo r a
C o mpo s iteU s erT ype , ev en th o u gh i t c o u l d be m ap p ed as a c o m p o n en t. O n e reaso n fo r th i s i s abstrac ti o n . W i th
a c u sto m typ e, yo u r m ap p i n g do c u m en ts w o u l d be p ro tec ted agai n st c h an ges to th e w ay m o n etary v al u es
are rep resen ted.
5 . 3 . M ap p ing a cl as s more th an once

I t i s p o ssi bl e to p ro v i de m o re th an o n e m ap p i n g fo r a p arti c u l ar p ersi sten t c l ass. I n th i s c ase, yo u m u st
sp ec i fy an e ntity nam e to di sam bi gu ate betw een i n stan c es o f th e tw o m ap p ed en ti ti es. B y defau l t, th e en ti ty
n am e i s th e sam e as th e c l ass n am e. H i bern ate l ets yo u sp ec i fy th e en ti ty n am e w h en w o rk i n g w i th
p ersi sten t o bj ec ts, w h en w ri ti n g q u eri es, o r w h en m ap p i n g asso c i ati o n s to th e n am ed en ti ty.
< cl as s name=" C o ntract" tab l e=" C o ntracts "

entityname=" C u rrentC o ntract" >
...
< s et name=" h is to ry" inv ers e=" tru e"
o rder- b y=" ef f ectiv eE ndD ate des c" >
< k ey co l u mn=" cu rrentC o ntractI d" / >
< o ne- to - many entityname=" H is to rical C o ntract" / >
< / s et>
< / cl as s >
< cl as s name=" C o ntract" tab l e=" C o ntractH is to ry"

entityname=" H is to rical C o ntract" >
...
< many- to - o ne name=" cu rrentC o ntract"
co l u mn=" cu rrentC o ntractI d"
entityname=" C u rrentC o ntract" / >
< / cl as s >
A sso c i ati o n s are n o w sp ec i fi ed u si n g entityname i n stead o f cl as s .
5 . 4 . S Q L q uoted id entifiers
Y o u c an fo rc e H i bern ate to q u o te an i den ti fi er i n th e gen erated S Q L by en c l o si n g th e tabl e o r c o l u m n n am e i n
bac k ti c k s i n th e m ap p i n g do c u m en t. H i bern ate w i l l u se th e c o rrec t q u o tati o n styl e fo r th e S Q L D ial ect . T h i s i s
u su al l y do u bl e q u o tes, bu t th e S Q L S erv er u ses brac k ets an d M yS Q L u ses bac k ti c k s.
< cl as s name=" L ineI tem" tab l e=" ` L ine I tem` " >
< id name=" id" co l u mn=" ` I tem I d` " / >< generato r cl as s =" as s igned" / >< / id>
< pro perty name=" itemNu mb er" co l u mn=" ` I tem # ` " / >
...
< / cl as s >
5 . 5 . M etad ata al ternativ es

X M L do es n o t su i t al l u sers so th ere are so m e al tern ati v e w ays to defi n e O /R m ap p i n g m etadata i n
H i bern ate.
5 . 5 . 1 . U s i ng X D oc l e t mark u p
M an y H i bern ate u sers p refer to em bed m ap p i n g i n fo rm ati o n di rec tl y i n so u rc ec o de u si n g X D o c l et
8 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
@ h ib ernate. tags . W e do n o t c o v er th i s ap p ro ac h i n th i s referen c e gu i de si n c e i t i s c o n si dered p art o f X D o c l et.

H o w ev er, w e i n c l u de th e fo l l o w i n g ex am p l e o f th e C at c l ass w i th X D o c l et m ap p i n gs:
8 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
pack age eg;

/ **
* @ h ib ernate. cl as s
* tab l e=" C A T S"
*/
priv ate L o ng id; / / identif ier
priv ate D ate b irth date;
priv ate C at mo th er;
priv ate Set k ittens
priv ate C o l o r co l o r;
priv ate ch ar s ex ;
priv ate f l o at w eigh t;
/ *
*@ h ib ernate. id
* generato r- cl as s =" nativ e"
* co l u mn=" C A T _ I D "
*/
retu rn id;
}
th is . id=id;
}
/ **
*@ h ib ernate. many- to - o ne
* co l u mn=" P A R E NT _ I D "
*/
pu b l ic C at getM o th er( ) {
retu rn mo th er;
}
v o id s etM o th er( C at mo th er) {
th is . mo th er = mo th er;
}
/ **
*@ h ib ernate. pro perty
* co l u mn=" B I R T H _ D A T E "
*/
pu b l ic D ate getB irth date( ) {
retu rn b irth date;
}
v o id s etB irth date( D ate date) {
b irth date = date;
}
/ **
*@ h ib ernate. pro perty
* co l u mn=" W E I G H T "
*/
pu b l ic f l o at getW eigh t( ) {
retu rn w eigh t;
}
v o id s etW eigh t( f l o at w eigh t) {
th is . w eigh t = w eigh t;
}
8 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
S ee th e H i bern ate w ebsi te fo r m o re ex am p l es o f X D o c l et an d H i bern ate.
5 . 5 . 2 . U s i ng J D K 5 .0 A nnotati ons
J D K 5 .0 i n tro du c ed X D o c l et- styl e an n o tati o n s at th e l an gu age l ev el th at are typ e- safe an d c h ec k ed at c o m p i l e

ti m e. T h i s m ec h an i sm i s m o re p o w erfu l th an X D o c l et an n o tati o n s an d better su p p o rted by to o l s an d I D E s.
I n tel l i J I D E A , fo r ex am p l e, su p p o rts au to - c o m p l eti o n an d syn tax h i gh l i gh ti n g o f J D K 5 .0 an n o tati o n s. T h e n ew
rev i si o n o f th e E J B sp ec i fi c ati o n (J S R - 220 ) u ses J D K 5 .0 an n o tati o n s as th e p ri m ary m etadata m ec h an i sm fo r
en ti ty bean s. H i bern ate3 i m p l em en ts th e E ntityM anager o f J S R - 220 (th e p ersi sten c e A P I ). S u p p o rt fo r
m ap p i n g m etadata i s av ai l abl e v i a th e H ib e rnate A nnotations p ac k age as a sep arate do w n l o ad. B o th E J B 3
(J S R - 220 ) an d H i bern ate3 m etadata i s su p p o rted.
T h i s i s an ex am p l e o f a P O J O c l ass an n o tated as an E J B en ti ty bean :
@ E ntity( acces s = A cces s T ype. F I E L D )

pu b l ic cl as s C u s to mer impl ements Serial iz ab l e {
@ I d;
L o ng id;
String f irs tName;

String l as tName;
D ate b irth day;
@ T rans ient
I nteger age;
@ E mb edded
priv ate A ddres s h o meA ddres s ;
@ O neT o M any( cas cade=C as cadeT ype. A L L )

@ J o inC o l u mn( name=" C U ST O M E R _ I D " )
Set< O rder> o rders ;
/ / G etter/ s etter and b u s ines s meth o ds

}
N ote
S u p p o rt fo r J D K 5 .0 A n n o tati o n s (an d J S R - 220 ) i s c u rren tl y u n der dev el o p m en t. P l ease refer to
th e H i bern ate A n n o tati o n s m o du l e fo r m o re detai l s.
5 . 6 . G enerated p rop erties

G en erated p ro p erti es are p ro p erti es th at h av e th ei r v al u es gen erated by th e database. T yp i c al l y, H i bern ate
ap p l i c ati o n s n eeded to ref res h o bj ec ts th at c o n tai n an y p ro p erti es fo r w h i c h th e database w as gen erati n g
v al u es. M ark i n g p ro p erti es as gen erated, h o w ev er, l ets th e ap p l i c ati o n del egate th i s resp o n si bi l i ty to
H i bern ate. W h en H i bern ate i ssu es an S Q L I N S E R T o r U P D A T E fo r an en ti ty th at h as defi n ed gen erated
p ro p erti es, i t i m m edi atel y i ssu es a sel ec t afterw ards to retri ev e th e gen erated v al u es.
P ro p erti es m ark ed as gen erated m u st addi ti o n al l y be n o n - i n sertabl e an d n o n - u p dateabl e. O n l y v ersi o n s,

ti m estam p s, an d si m p l e p ro p erti es, c an be m ark ed as gen erated.
nev er (th e defau l t): th e gi v en p ro p erty v al u e i s n o t gen erated w i th i n th e database.
ins ert : th e gi v en p ro p erty v al u e i s gen erated o n i n sert, bu t i s n o t regen erated o n su bseq u en t u p dates.
P ro p erti es l i k e c reated- date fal l i n to th i s c atego ry. E v en th o u gh v ersi o n an d ti m estam p p ro p erti es c an be
m ark ed as gen erated, th i s o p ti o n i s n o t av ai l abl e.
8 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
al w ays : th e p ro p erty v al u e i s gen erated bo th o n i n sert an d o n u p date.
5 . 7 . A ux il iary d atabas e obj ects

A u x i l i ary database o bj ec ts al l o w fo r th e CR E A T E an d D R O P o f arbi trary database o bj ec ts. I n c o n j u n c ti o n w i th
H i bern ate' s sc h em a ev o l u ti o n to o l s, th ey h av e th e abi l i ty to fu l l y defi n e a u ser sc h em a w i th i n th e H i bern ate
m ap p i n g fi l es. A l th o u gh desi gn ed sp ec i fi c al l y fo r c reati n g an d dro p p i n g th i n gs l i k e tri ggers o r sto red
p ro c edu res, an y S Q L c o m m an d th at c an be ru n v i a a j av a. s q l . Statement. ex ecu te( ) m eth o d i s v al i d (fo r
ex am p l e, A L T E R s, I N S E R T S , etc .). T h ere are essen ti al l y tw o m o des fo r defi n i n g au x i l i ary database o bj ec ts:
T h e fi rst m o de i s to ex p l i c i tl y l i st th e CR E A T E an d D R O P c o m m an ds i n th e m ap p i n g fi l e:

...
< datab as e- o b j ect>
< create>C R E A T E T R I G G E R my_ trigger . . . < / create>
< dro p>D R O P T R I G G E R my_ trigger< / dro p>
< / datab as e- o b j ect>
T h e sec o n d m o de i s to su p p l y a c u sto m c l ass th at c o n stru c ts th e CR E A T E an d D R O P c o m m an ds. T h i s c u sto m

c l ass m u st i m p l em en t th e o rg. h ib ernate. mapping. A u x il iaryD atab as eO b j ect i n terfac e.

...
< def initio n cl as s =" M yT riggerD ef initio n" / >
A ddi ti o n al l y, th ese database o bj ec ts c an be o p ti o n al l y sc o p ed so th at th ey o n l y ap p l y w h en c ertai n di al ec ts

are u sed.

...
< def initio n cl as s =" M yT riggerD ef initio n" / >
< dial ect- s co pe name=" o rg. h ib ernate. dial ect. O racl e9 iD ial ect" / >
< dial ect- s co pe name=" o rg. h ib ernate. dial ect. O racl e10gD ial ect" / >
C h ap ter 6 . C ol l ection map p ing

6 .1 . P ersi sten t c o l l ec ti o n s
6 .2. Co l l ec ti o n m ap p i n gs
6 .2.1 . Co l l ec ti o n fo rei gn k eys
6 .2.2. Co l l ec ti o n el em en ts
6 .2.3 . I n dex ed c o l l ec ti o n s
6 .2.4 . Co l l ec ti o n s o f v al u es an d m an y- to - m an y asso c i ati o n s
6 .2.5 . O n e- to - m an y asso c i ati o n s
6 .3 . A dv an c ed c o l l ec ti o n m ap p i n gs
6 .3 .1 . S o rted c o l l ec ti o n s
6 .3 .2. B i di rec ti o n al asso c i ati o n s
6 .3 .3 . B i di rec ti o n al asso c i ati o n s w i th i n dex ed c o l l ec ti o n s
6 .3 .4 . T ern ary asso c i ati o n s
6 .3 .5 . U s ing an < idb ag>
8 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
6 .4 . Co l l ec ti o n ex am p l es
6 . 1 . P ers is tent col l ections

H i bern ate req u i res th at p ersi sten t c o l l ec ti o n - v al u ed fi el ds be dec l ared as an i n terfac e typ e. F o r ex am p l e:
pu b l ic cl as s P ro du ct {
priv ate String s erial Nu mb er;
priv ate Set parts = new H as h Set( );
pu b l ic Set getP arts ( ) { retu rn parts ; }

v o id s etP arts ( Set parts ) { th is . parts = parts ; }
pu b l ic String getSerial Nu mb er( ) { retu rn s erial Nu mb er; }
v o id s etSerial Nu mb er( String s n) { s erial Nu mb er = s n; }
}
T h e ac tu al i n terfac e m i gh t be j av a. u til . Set , j av a. u til . C o l l ectio n, j av a. u til . L is t , j av a. u til . M ap , j av a. u til . So rtedSet ,

j av a. u til . So rtedM ap o r an yth i n g yo u l i k e (" an yth i n g yo u l i k e" m ean s yo u w i l l h av e to w ri te an i m p l em en tati o n
o f o rg. h ib ernate. u s ertype. U s erC o l l ectio nT ype .)
N o ti c e h o w th e i n stan c e v ari abl e w as i n i ti al i z ed w i th an i n stan c e o f H as h Set . T h i s i s th e best w ay to i n i ti al i z e

c o l l ec ti o n v al u ed p ro p erti es o f n ew l y i n stan ti ated (n o n - p ersi sten t) i n stan c es. W h en yo u m ak e th e i n stan c e
p ersi sten t, by c al l i n g pers is t( ) fo r ex am p l e, H i bern ate w i l l ac tu al l y rep l ac e th e H as h Set w i th an i n stan c e o f
H i bern ate' s o w n i m p l em en tati o n o f Set . B e aw are o f th e fo l l o w i n g erro rs:
C at cat = new D o mes ticC at( );

C at k itten = new D o mes ticC at( );
....
Set k ittens = new H as h Set( );
k ittens . add( k itten);
cat. s etK ittens ( k ittens );
s es s io n. pers is t( cat);
k ittens = cat. getK ittens ( ); / / O k ay, k ittens co l l ectio n is a Set
( H as h Set) cat. getK ittens ( ); / / E rro r!
T h e p ersi sten t c o l l ec ti o n s i n j ec ted by H i bern ate beh av e l i k e H as h M ap, H as h Set , T reeM ap, T reeSet o r A rrayL is t ,
dep en di n g o n th e i n terfac e typ e.
Co l l ec ti o n s i n stan c es h av e th e u su al beh av i o r o f v al u e typ es. T h ey are au to m ati c al l y p ersi sted w h en

referen c ed by a p ersi sten t o bj ec t an d are au to m ati c al l y del eted w h en u n referen c ed. I f a c o l l ec ti o n i s p assed
fro m o n e p ersi sten t o bj ec t to an o th er, i ts el em en ts m i gh t be m o v ed fro m o n e tabl e to an o th er. T w o en ti ti es
c an n o t sh are a referen c e to th e sam e c o l l ec ti o n i n stan c e. D u e to th e u n derl yi n g rel ati o n al m o del , c o l l ec ti o n -
v al u ed p ro p erti es do n o t su p p o rt n u l l v al u e sem an ti c s. H i bern ate do es n o t di sti n gu i sh betw een a n u l l
c o l l ec ti o n referen c e an d an em p ty c o l l ec ti o n .
U se p ersi sten t c o l l ec ti o n s th e sam e w ay yo u u se o rdi n ary J av a c o l l ec ti o n s. H o w ev er, p l ease en su re yo u

u n derstan d th e sem an ti c s o f bi di rec ti o n al asso c i ati o n s (th ese are di sc u ssed l ater).
6 . 2 . C ol l ection map p ing s
T ip
T h ere are q u i te a ran ge o f m ap p i n gs th at c an be gen erated fo r c o l l ec ti o n s th at c o v er m an y
c o m m o n rel ati o n al m o del s. W e su ggest yo u ex p eri m en t w i th th e sc h em a gen erati o n to o l so
th at yo u u n derstan d h o w v ari o u s m ap p i n g dec l arati o n s tran sl ate to database tabl es.
T h e H i bern ate m ap p i n g el em en t u sed fo r m ap p i n g a c o l l ec ti o n dep en ds u p o n th e typ e o f i n terfac e. F o r

ex am p l e, a < s et> el em en t i s u sed fo r m ap p i n g p ro p erti es o f typ e Set .
8 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" P ro du ct" >

< id name=" s erial Nu mb er" co l u mn=" pro du ctSerial Nu mb er" / >
< s et name=" parts " >
< k ey co l u mn=" pro du ctSerial Nu mb er" no t- nu l l =" tru e" / >
< o ne- to - many cl as s =" P art" / >
< / s et>
< / cl as s >
A p art fro m < s et>, th ere i s al so < l is t>, < map>, , < array> an d < primitiv e- array> m ap p i n g el em en ts. T h e
< map> el em en t i s rep resen tati v e:
< map
tab l e=" tab l e_ name"
s ch ema=" s ch ema_ name"
l az y=" tru e| ex tra| f al s e"
inv ers e=" tru e| f al s e"
cas cade=" al l | no ne| s av e- u pdate| del ete| al l - del ete- o rph an| del ete- o rph an"
s o rt=" u ns o rted| natu ral | co mparato rC l as s "
o rder- b y=" co l u mn_ name as c| des c"
w h ere=" arb itrary s q l w h ere co nditio n"
f etch =" j o in| s el ect| s u b s el ect"
b atch - s iz e=" N"
mu tab l e=" tru e| f al s e"
>
< k ey . . . . / >
< map- k ey . . . . / >
< el ement . . . . / >
< / map>
name : th e c o l l ec ti o n p ro p erty n am e
tab l e (o p ti o n al - defau l ts to p ro p erty n am e): th e n am e o f th e c o l l ec ti o n tabl e. I t i s n o t u sed fo r

o n e- to - m an y asso c i ati o n s.
s ch ema (o p ti o n al ): th e n am e o f a tabl e sc h em a to o v erri de th e sc h em a dec l ared o n th e ro o t el em en t
l az y (o p ti o n al - defau l ts to tru e): di sabl es l az y fetc h i n g an d sp ec i fi es th at th e asso c i ati o n i s al w ays

eagerl y fetc h ed. I t c an al so be u sed to en abl e " ex tra- l az y" fetc h i n g w h ere m o st o p erati o n s do n o t
i n i ti al i z e th e c o l l ec ti o n . T h i s i s su i tabl e fo r l arge c o l l ec ti o n s.
inv ers e (o p ti o n al - defau l ts to f al s e ): m ark s th i s c o l l ec ti o n as th e " i n v erse" en d o f a bi di rec ti o n al
asso c i ati o n .
cas cade (o p ti o n al - defau l ts to no ne): en abl es o p erati o n s to c asc ade to c h i l d en ti ti es.
s o rt (o p ti o n al ): sp ec i fi es a so rted c o l l ec ti o n w i th natu ral so rt o rder o r a gi v en c o m p arato r c l ass.
o rder- b y (o p ti o n al , J D K 1 .4 o n l y): sp ec i fi es a tabl e c o l u m n o r c o l u m n s th at defi n e th e i terati o n o rder o f

th e M ap , Set o r bag, to geth er w i th an o p ti o n al as c o r des c.
w h ere (o p ti o n al ): sp ec i fi es an arbi trary S Q L W H E R E c o n di ti o n th at i s u sed w h en retri ev i n g o r rem o v i n g
th e c o l l ec ti o n . T h i s i s u sefu l i f th e c o l l ec ti o n n eeds to c o n tai n o n l y a su bset o f th e av ai l abl e data.
f etch (o p ti o n al , defau l ts to s el ect ): c h o o ses betw een o u ter- j o i n fetc h i n g, fetc h i n g by seq u en ti al sel ec t,
an d fetc h i n g by seq u en ti al su bsel ec t.
b atch - s iz e (o p ti o n al , defau l ts to 1): sp ec i fi es a " batc h si z e" fo r l az i l y fetc h i n g i n stan c es o f th i s
c o l l ec ti o n .
1 2 acces s (o p ti o n al - defau l ts to pro perty): th e strategy H i bern ate u ses fo r ac c essi n g th e c o l l ec ti o n
p ro p erty v al u e.
8 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
o ptimis tic- l o ck (o p ti o n al - defau l ts to tru e ): sp ec i fi es th at c h an ges to th e state o f th e c o l l ec ti o n resu l ts

i n i n c rem en ts o f th e o w n i n g en ti ty' s v ersi o n . F o r o n e- to - m an y asso c i ati o n s yo u m ay w an t to di sabl e
th i s setti n g.
mu tab l e (o p ti o n al - defau l ts to tru e ): a v al u e o f f al s e sp ec i fi es th at th e el em en ts o f th e c o l l ec ti o n n ev er
c h an ge. T h i s al l o w s fo r m i n o r p erfo rm an c e o p ti m i z ati o n i n so m e c ases.
6 . 2 . 1 . C ol l e c ti on f ore i g n k e y s
Co l l ec ti o n i n stan c es are di sti n gu i sh ed i n th e database by th e fo rei gn k ey o f th e en ti ty th at o w n s th e

c o l l ec ti o n . T h i s fo rei gn k ey i s referred to as th e c olle c tion k e y c olum n, o r c o l u m n s, o f th e c o l l ec ti o n tabl e. T h e
c o l l ec ti o n k ey c o l u m n i s m ap p ed by th e < k ey> el em en t.
T h ere c an be a n u l l abi l i ty c o n strai n t o n th e fo rei gn k ey c o l u m n . F o r m o st c o l l ec ti o n s, th i s i s i m p l i ed. F o r

u n i di rec ti o n al o n e- to - m an y asso c i ati o n s, th e fo rei gn k ey c o l u m n i s n u l l abl e by defau l t, so yo u m ay n eed to
sp ec i fy no t- nu l l =" tru e" .
< k ey co l u mn=" pro du ctSerial Nu mb er" no t- nu l l =" tru e" / >
T h e fo rei gn k ey c o n strai n t c an u se O N D E L E T E C A SC A D E .
< k ey co l u mn=" pro du ctSerial Nu mb er" o n- del ete=" cas cade" / >
S ee th e p rev i o u s c h ap ter fo r a fu l l defi n i ti o n o f th e < k ey> el em en t.
6 . 2 . 2 . C ol l e c ti on e l e me nts
Co l l ec ti o n s c an c o n tai n al m o st an y o th er H i bern ate typ e, i n c l u di n g: basi c typ es, c u sto m typ es, c o m p o n en ts
an d referen c es to o th er en ti ti es. T h i s i s an i m p o rtan t di sti n c ti o n . A n o bj ec t i n a c o l l ec ti o n m i gh t be h an dl ed
w i th " v al u e" sem an ti c s (i ts l i fe c yc l e fu l l y dep en ds o n th e c o l l ec ti o n o w n er), o r i t m i gh t be a referen c e to
an o th er en ti ty w i th i ts o w n l i fe c yc l e. I n th e l atter c ase, o n l y th e " l i n k " betw een th e tw o o bj ec ts i s c o n si dered
to be a state h el d by th e c o l l ec ti o n .
T h e c o n tai n ed typ e i s referred to as th e c olle c tion e le m e nt ty p e . Co l l ec ti o n el em en ts are m ap p ed by

< el ement> o r < co mpo s ite- el ement>, o r i n th e c ase o f en ti ty referen c es, w i th < o ne- to - many> o r
< many- to - many>. T h e fi rst tw o m ap el em en ts w i th v al u e sem an ti c s, th e n ex t tw o are u sed to m ap en ti ty
asso c i ati o n s.
6 . 2 . 3 . Ind e x e d c ol l e c ti ons
A l l c o l l ec ti o n m ap p i n gs, ex c ep t th o se w i th set an d bag sem an ti c s, n eed an ind e x c olum n i n th e c o l l ec ti o n

tabl e. A n i n dex c o l u m n i s a c o l u m n th at m ap s to an array i n dex , o r L is t i n dex , o r M ap k ey. T h e i n dex o f a M ap
m ay be o f an y basi c typ e, m ap p ed w i th < map- k ey>. I t c an be an en ti ty referen c e m ap p ed w i th
< map- k ey- many- to - many>, o r i t c an be a c o m p o si te typ e m ap p ed w i th < co mpo s ite- map- k ey>. T h e i n dex o f an
array o r l i st i s al w ays o f typ e integer an d i s m ap p ed u si n g th e < l is t- index > el em en t. T h e m ap p ed c o l u m n
c o n tai n s seq u en ti al i n tegers th at are n u m bered fro m z ero by defau l t.
< l is t- index
b as e=" 0| 1| . . . " / >
co l u mn_ name (req u i red): th e n am e o f th e c o l u m n h o l di n g th e c o l l ec ti o n i n dex v al u es.
b as e (o p ti o n al - defau l ts to 0): th e v al u e o f th e i n dex c o l u m n th at c o rresp o n ds to th e fi rst el em en t o f

th e l i st o r array.
8 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< map- k ey
type=" type_ name"
no de=" @ attrib u te- name"
l ength =" N" / >
co l u mn (o p ti o n al ): th e n am e o f th e c o l u m n h o l di n g th e c o l l ec ti o n i n dex v al u es.
f o rmu l a (o p ti o n al ): a S Q L fo rm u l a u sed to ev al u ate th e k ey o f th e m ap .
type (req u i red): th e typ e o f th e m ap k eys.
< map- k ey- many- to - many

/ >
co l u mn (o p ti o n al ): th e n am e o f th e fo rei gn k ey c o l u m n fo r th e c o l l ec ti o n i n dex v al u es.
f o rmu l a (o p ti o n al ): a S Q fo rm u l a u sed to ev al u ate th e fo rei gn k ey o f th e m ap k ey.
cl as s (req u i red): th e en ti ty c l ass u sed as th e m ap k ey.
I f yo u r tabl e do es n o t h av e an i n dex c o l u m n , an d yo u sti l l w i sh to u se L is t as th e p ro p erty typ e, yo u c an m ap

th e p ro p erty as a H i bern ate . A bag do es n o t retai n i ts o rder w h en i t i s retri ev ed fro m th e database,
bu t i t c an be o p ti o n al l y so rted o r o rdered.
6 . 2 . 4 . C ol l e c ti ons of v al u e s and many - to- many as s oc i ati ons
A n y c o l l ec ti o n o f v al u es o r m an y- to - m an y asso c i ati o n s req u i res a dedi c ated c olle c tion tab le w i th a fo rei gn
k ey c o l u m n o r c o l u m n s, c olle c tion e le m e nt c olum n o r c o l u m n s, an d p o ssi bl y an i n dex c o l u m n o r c o l u m n s.
F o r a c o l l ec ti o n o f v al u es u se th e < el ement> tag. F o r ex am p l e:
< el ement
type=" typename"
l ength =" L "
precis io n=" P "
s cal e=" S"
/ >
co l u mn (o p ti o n al ): th e n am e o f th e c o l u m n h o l di n g th e c o l l ec ti o n el em en t v al u es.
f o rmu l a (o p ti o n al ): an S Q L fo rm u l a u sed to ev al u ate th e el em en t.
type (req u i red): th e typ e o f th e c o l l ec ti o n el em en t.
A m any - to- m any as s oc iation i s sp ec i fi ed u si n g th e < many- to - many> el em en t.
9 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< many- to - many

f etch =" s el ect| j o in"
/ >
co l u mn (o p ti o n al ): th e n am e o f th e el em en t fo rei gn k ey c o l u m n .
f o rmu l a (o p ti o n al ): an S Q L fo rm u l a u sed to ev al u ate th e el em en t fo rei gn k ey v al u e.
cl as s (req u i red): th e n am e o f th e asso c i ated c l ass.
f etch (o p ti o n al - defau l ts to j o in): en abl es o u ter- j o i n o r seq u en ti al sel ec t fetc h i n g fo r th i s asso c i ati o n .
T h i s i s a sp ec i al c ase; fo r fu l l eager fetc h i n g i n a si n gl e SE L E C T o f an en ti ty an d i ts m an y- to - m an y
rel ati o n sh i p s to o th er en ti ti es, yo u w o u l d en abl e j o in fetc h i n g,n o t o n l y o f th e c o l l ec ti o n i tsel f, bu t al so
w i th th i s attri bu te o n th e < many- to - many> n ested el em en t.
u niq u e (o p ti o n al ): en abl es th e D D L gen erati o n o f a u n i q u e c o n strai n t fo r th e fo rei gn - k ey c o l u m n . T h i s
m ak es th e asso c i ati o n m u l ti p l i c i ty effec ti v el y o n e- to - m an y.
no t- f o u nd (o p ti o n al - defau l ts to ex ceptio n): sp ec i fi es h o w fo rei gn k eys th at referen c e m i ssi n g ro w s w i l l
be h an dl ed: igno re w i l l treat a m i ssi n g ro w as a n u l l asso c i ati o n .
entityname (o p ti o n al ): th e en ti ty n am e o f th e asso c i ated c l ass, as an al tern ati v e to cl as s .
pro perty- ref (o p ti o n al ): th e n am e o f a p ro p erty o f th e asso c i ated c l ass th at i s j o i n ed to th i s fo rei gn

k ey. I f n o t sp ec i fi ed, th e p ri m ary k ey o f th e asso c i ated c l ass i s u sed.
H ere are so m e ex am p l es.
A set o f stri n gs:
< s et name=" names " tab l e=" pers o n_ names " >
< k ey co l u mn=" pers o n_ id" / >
< el ement co l u mn=" pers o n_ name" type=" s tring" / >
< / s et>
A bag c o n tai n i n g i n tegers w i th an i terati o n o rder determ i n ed by th e o rder- b y attri bu te:

< k ey co l u mn=" item_ id" / >
< el ement co l u mn=" s iz e" type=" integer" / >

A n array o f en ti ti es, i n th i s c ase, a m an y- to - m an y asso c i ati o n :
< array name=" addres s es "

tab l e=" P ers o nA ddres s "
cas cade=" pers is t" >
< k ey co l u mn=" pers o nI d" / >
< l is t- index co l u mn=" s o rtO rder" / >
< many- to - many co l u mn=" addres s I d" cl as s =" A ddres s " / >
< / array>
A m ap fro m stri n g i n di c es to dates:
9 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< map name=" h o l idays "

tab l e=" h o l idays "
s ch ema=" db o "
o rder- b y=" h o l _ name as c" >
< k ey co l u mn=" id" / >
< map- k ey co l u mn=" h o l _ name" type=" s tring" / >
< el ement co l u mn=" h o l _ date" type=" date" / >
< / map>
A l i st o f c o m p o n en ts (th i s i s di sc u ssed i n th e n ex t c h ap ter):
< l is t name=" carC o mpo nents "

tab l e=" C arC o mpo nents " >
< k ey co l u mn=" carI d" / >
< l is t- index co l u mn=" s o rtO rder" / >
< co mpo s ite- el ement cl as s =" C arC o mpo nent" >
< pro perty name=" price" / >
< pro perty name=" type" / >
< pro perty name=" s erial Nu mb er" co l u mn=" s erial Nu m" / >
< / co mpo s ite- el ement>
< / l is t>
6 . 2 . 5 . O ne - to- many as s oc i ati ons
A one - to- m any as s oc iation l i n k s th e tabl es o f tw o c l asses v i a a fo rei gn k ey w i th n o i n terv en i n g c o l l ec ti o n

tabl e. T h i s m ap p i n g l o ses c ertai n sem an ti c s o f n o rm al J av a c o l l ec ti o n s:
A n i n stan c e o f th e c o n tai n ed en ti ty c l ass c an n o t bel o n g to m o re th an o n e i n stan c e o f th e c o l l ec ti o n .

A n i n stan c e o f th e c o n tai n ed en ti ty c l ass c an n o t ap p ear at m o re th an o n e v al u e o f th e c o l l ec ti o n i n dex .
A n asso c i ati o n fro m P ro du ct to P art req u i res th e ex i sten c e o f a fo rei gn k ey c o l u m n an d p o ssi bl y an i n dex
c o l u m n to th e P art tabl e. A < o ne- to - many> tag i n di c ates th at th i s i s a o n e- to - m an y asso c i ati o n .
< o ne- to - many

/ >
cl as s (req u i red): th e n am e o f th e asso c i ated c l ass.
no t- f o u nd (o p ti o n al - defau l ts to ex ceptio n): sp ec i fi es h o w c ac h ed i den ti fi ers th at referen c e m i ssi n g

ro w s w i l l be h an dl ed. igno re w i l l treat a m i ssi n g ro w as a n u l l asso c i ati o n .
entityname (o p ti o n al ): th e en ti ty n am e o f th e asso c i ated c l ass, as an al tern ati v e to cl as s .
T h e < o ne- to - many> el em en t do es n o t n eed to dec l are an y c o l u m n s. N o r i s i t n ec essary to sp ec i fy th e tab l e

n am e an yw h ere.
W arni ng
I f th e fo rei gn k ey c o l u m n o f a < o ne- to - many> asso c i ati o n i s dec l ared NO T NU L L , yo u m u st
dec l are th e < k ey> m ap p i n g no t- nu l l =" tru e" o r us e a b id ire c tional as s oc iation w i th th e c o l l ec ti o n
m ap p i n g m ark ed inv ers e=" tru e" . S ee th e di sc u ssi o n o f bi di rec ti o n al asso c i ati o n s l ater i n th i s
c h ap ter fo r m o re i n fo rm ati o n .
T h e fo l l o w i n g ex am p l e sh o w s a m ap o f P art en ti ti es by n am e, w h ere partName i s a p ersi sten t p ro p erty o f P art .
9 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
N o ti c e th e u se o f a fo rm u l a- based i n dex :
< map name=" parts "

cas cade=" al l " >
< k ey co l u mn=" pro du ctI d" no t- nu l l =" tru e" / >
< map- k ey f o rmu l a=" partName" / >
< o ne- to - many cl as s =" P art" / >
< / map>
6 . 3 . A d v anced col l ection map p ing s
6 . 3 . 1 . S orte d c ol l e c ti ons
H i bern ate su p p o rts c o l l ec ti o n s i m p l em en ti n g j av a. u til . So rtedM ap an d j av a. u til . So rtedSet . Y o u m u st sp ec i fy a

c o m p arato r i n th e m ap p i n g fi l e:
< s et name=" al ias es "

tab l e=" pers o n_ al ias es "
s o rt=" natu ral " >
< k ey co l u mn=" pers o n" / >
< el ement co l u mn=" name" type=" s tring" / >
< / s et>
< map name=" h o l idays " s o rt=" my. cu s to m. H o l idayC o mparato r" >
< k ey co l u mn=" year_ id" / >
< el ement co l u mn=" h o l _ date" type=" date" / >
< / map>
A l l o w ed v al u es o f th e s o rt attri bu te are u ns o rted, natu ral an d th e n am e o f a c l ass i m p l em en ti n g

j av a. u til . C o mparato r.
S o rted c o l l ec ti o n s ac tu al l y beh av e l i k e j av a. u til . T reeSet o r j av a. u til . T reeM ap.
I f yo u w an t th e database i tsel f to o rder th e c o l l ec ti o n el em en ts, u se th e o rder- b y attri bu te o f s et , b ag o r map

m ap p i n gs. T h i s so l u ti o n i s o n l y av ai l abl e u n der J D K 1 .4 o r h i gh er an d i s i m p l em en ted u si n g L ink edH as h Set o r
L ink edH as h M ap . T h i s p erfo rm s th e o rderi n g i n th e S Q L q u ery an d n o t i n th e m em o ry.
< s et name=" al ias es " tab l e=" pers o n_ al ias es " o rder- b y=" l o w er( name) as c" >
< k ey co l u mn=" pers o n" / >
< el ement co l u mn=" name" type=" s tring" / >
< / s et>
< map name=" h o l idays " o rder- b y=" h o l _ date, h o l _ name" >
< k ey co l u mn=" year_ id" / >
< el ement co l u mn=" h o l _ date type=" date" / >
< / map>
N ote
T h e v al u e o f th e o rder- b y attri bu te i s an S Q L o rderi n g, n o t an H Q L o rderi n g.
A sso c i ati o n s c an ev en be so rted by arbi trary c ri teri a at ru n ti m e u si n g a c o l l ec ti o n f il ter( ):
s o rtedU s ers = s . createF il ter( gro u p. getU s ers ( ), " o rder b y th is . name" ). l is t( );
9 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
6 . 3 . 2 . B i d i re c ti onal as s oc i ati ons
A b id ire c tional as s oc iation al l o w s n av i gati o n fro m bo th " en ds" o f th e asso c i ati o n . T w o k i n ds o f bi di rec ti o n al
asso c i ati o n are su p p o rted:
o n e- to - m an y
set o r bag v al u ed at o n e en d an d si n gl e- v al u ed at th e o th er
m an y- to - m an y
set o r bag v al u ed at bo th en ds
Y o u c an sp ec i fy a bi di rec ti o n al m an y- to - m an y asso c i ati o n by m ap p i n g tw o m an y- to - m an y asso c i ati o n s to th e

sam e database tabl e an d dec l ari n g o n e en d as inv e rs e . Y o u c an n o t sel ec t an i n dex ed c o l l ec ti o n .
H ere i s an ex am p l e o f a bi di rec ti o n al m an y- to - m an y asso c i ati o n th at i l l u strates h o w eac h c atego ry c an h av e

m an y i tem s an d eac h i tem c an be i n m an y c atego ri es:
< cl as s name=" C atego ry" >

< id name=" id" co l u mn=" C A T E G O R Y _ I D " / >
...

< k ey co l u mn=" C A T E G O R Y _ I D " / >
< many- to - many cl as s =" I tem" co l u mn=" I T E M _ I D " / >

< / cl as s >
< cl as s name=" I tem" >

< id name=" id" co l u mn=" I T E M _ I D " / >
...
< ! - - inv ers e end - - >


< k ey co l u mn=" I T E M _ I D " / >
< many- to - many cl as s =" C atego ry" co l u mn=" C A T E G O R Y _ I D " / >

< / cl as s >
Ch an ges m ade o n l y to th e i n v erse en d o f th e asso c i ati o n are not p ersi sted. T h i s m ean s th at H i bern ate h as
tw o rep resen tati o n s i n m em o ry fo r ev ery bi di rec ti o n al asso c i ati o n : o n e l i n k fro m A to B an d an o th er l i n k
fro m B to A . T h i s i s easi er to u n derstan d i f yo u th i n k abo u t th e J av a o bj ec t m o del an d h o w a m an y- to - m an y
rel ati o n sh i p i n J av ai s c reated:
catego ry. getI tems ( ). add( item); / / T h e catego ry no w " k no w s " ab o u t th e rel atio ns h ip
item. getC atego ries ( ). add( catego ry); / / T h e item no w " k no w s " ab o u t th e rel atio ns h ip
s es s io n. pers is t( item); / / T h e rel atio ns h ip w o n' t b e s av ed!

s es s io n. pers is t( catego ry); / / T h e rel atio ns h ip w il l b e s av ed
T h e n o n - i n v erse si de i s u sed to sav e th e i n - m em o ry rep resen tati o n to th e database.
Y o u c an defi n e a bi di rec ti o n al o n e- to - m an y asso c i ati o n by m ap p i n g a o n e- to - m an y asso c i ati o n to th e sam e

tabl e c o l u m n (s) as a m an y- to - o n e asso c i ati o n an d dec l ari n g th e m an y- v al u ed en d inv ers e=" tru e" .
9 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" P arent" >

< id name=" id" co l u mn=" parent_ id" / >
....
< s et name=" ch il dren" inv ers e=" tru e" >
< k ey co l u mn=" parent_ id" / >
< o ne- to - many cl as s =" C h il d" / >
< / s et>
< / cl as s >
< cl as s name=" C h il d" >

< id name=" id" co l u mn=" ch il d_ id" / >
....
< many- to - o ne name=" parent"
cl as s =" P arent"
co l u mn=" parent_ id"
no t- nu l l =" tru e" / >
< / cl as s >
M ap p i n g o n e en d o f an asso c i ati o n w i th inv ers e=" tru e" do es n o t affec t th e o p erati o n o f c asc ades as th ese are
o rth o go n al c o n c ep ts.
6 . 3 . 3 . B i d i re c ti onal as s oc i ati ons w i th i nd e x e d c ol l e c ti ons
A bi di rec ti o n al asso c i ati o n w h ere o n e en d i s rep resen ted as a < l is t> o r < map>, req u i res sp ec i al c o n si derati o n .
I f th ere i s a p ro p erty o f th e c h i l d c l ass th at m ap s to th e i n dex c o lu m n yo u c an u se inv ers e=" tru e" o n th e
c o l l ec ti o n m ap p i n g:

....
< map name=" ch il dren" inv ers e=" tru e" >
< map- k ey co l u mn=" name"
type=" s tring" / >
< / map>
< / cl as s >

....
cl as s =" P arent"
< / cl as s >
I f th ere i s n o su c h p ro p erty o n th e c h i l d c l ass, th e asso c i ati o n c an n o t be c o n si dered tru l y bi di rec ti o n al . T h at

i s, th ere i s i n fo rm ati o n av ai l abl e at o n e en d o f th e asso c i ati o n th at i s n o t av ai l abl e at th e o th er en d. I n th i s
c ase, yo u c an n o t m ap th e c o l l ec ti o n inv ers e=" tru e" . I n stead, yo u c o u l d u se th e fo l l o w i n g m ap p i n g:
9 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

....
< map name=" ch il dren" >
< k ey co l u mn=" parent_ id"
< map- k ey co l u mn=" name"
type=" s tring" / >
< / map>
< / cl as s >

....
cl as s =" P arent"
ins ert=" f al s e"
u pdate=" f al s e"
< / cl as s >
N o te th at i n th i s m ap p i n g, th e c o l l ec ti o n - v al u ed en d o f th e asso c i ati o n i s resp o n si bl e fo r u p dates to th e

fo rei gn k ey.
6 . 3 . 4 . T e rnary as s oc i ati ons
T h ere are th ree p o ssi bl e ap p ro ac h es to m ap p i n g a tern ary asso c i ati o n . O n e ap p ro ac h i s to u se a M ap w i th an

asso c i ati o n as i ts i n dex :
< map name=" co ntracts " >

< k ey co l u mn=" empl o yer_ id" no t- nu l l =" tru e" / >
< map- k ey- many- to - many co l u mn=" empl o yee_ id" cl as s =" E mpl o yee" / >
< o ne- to - many cl as s =" C o ntract" / >
< / map>
< map name=" co nnectio ns " >

< k ey co l u mn=" inco ming_ no de_ id" / >
< map- k ey- many- to - many co l u mn=" o u tgo ing_ no de_ id" cl as s =" No de" / >
< many- to - many co l u mn=" co nnectio n_ id" cl as s =" C o nnectio n" / >
< / map>
A sec o n d ap p ro ac h i s to rem o del th e asso c i ati o n as an en ti ty c l ass. T h i s i s th e m o st c o m m o n ap p ro ac h .
A fi n al al tern ati v e i s to u se c o m p o si te el em en ts, w h i c h w i l l be di sc u ssed l ater.
6 . 3 . 5 . U sing an < id b ag >
T h e m aj o ri ty o f th e m an y- to - m an y asso c i ati o n s an d c o l l ec ti o n s o f v al u es sh o w n p rev i o u sl y al l m ap to tabl es

w i th c o m p o si te k eys, ev en th o u gh i t h as been h av e su ggested th at en ti ti es sh o u l d h av e syn th eti c i den ti fi ers
(su rro gate k eys). A p u re asso c i ati o n tabl e do es n o t seem to ben efi t m u c h fro m a su rro gate k ey, al th o u gh a
c o l l ec ti o n o f c o m p o si te v al u es m ig h t. I t i s fo r th i s reaso n th at H i bern ate p ro v i des a featu re th at al l o w s yo u to
m ap m an y- to - m an y asso c i ati o n s an d c o l l ec ti o n s o f v al u es to a tabl e w i th a su rro gate k ey.
T h e < idb ag> el em en t l ets yo u m ap a L is t (o r C o l l ectio n) w i th bag sem an ti c s. F o r ex am p l e:
9 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< idb ag name=" l o v ers " tab l e=" L O V E R S" >

< co l l ectio n- id co l u mn=" I D " type=" l o ng" >
< / co l l ectio n- id>
< k ey co l u mn=" P E R SO N1" / >
< many- to - many co l u mn=" P E R SO N2 " cl as s =" P ers o n" f etch =" j o in" / >
< / idb ag>
A n < idb ag> h as a syn th eti c i d gen erato r, j u st l i k e an en ti ty c l ass. A di fferen t su rro gate k ey i s assi gn ed to
eac h c o l l ec ti o n ro w . H i bern ate do es n o t, h o w ev er, p ro v i de an y m ec h an i sm fo r di sc o v eri n g th e su rro gate k ey
v al u e o f a p arti c u l ar ro w .
T h e u p date p erfo rm an c e o f an < idb ag> su p ersedes a regu l ar . H i bern ate c an l o c ate i n di v i du al ro w s
effi c i en tl y an d u p date o r del ete th em i n di v i du al l y, si m i l ar to a l i st, m ap o r set.
I n th e c u rren t i m p l em en tati o n , th e nativ e i den ti fi er gen erati o n strategy i s n o t su p p o rted fo r < idb ag>
c o l l ec ti o n i den ti fi ers.
6 . 4 . C ol l ection ex amp l es
T h i s sec ti o n c o v ers c o l l ec ti o n ex am p l es.
T h e fo l l o w i n g c l ass h as a c o l l ec ti o n o f C h il d i n stan c es:
pack age eg;

pu b l ic cl as s P arent {
priv ate l o ng id;
priv ate Set ch il dren;
pu b l ic l o ng getI d( ) { retu rn id; }

priv ate v o id s etI d( l o ng id) { th is . id=id; }
priv ate Set getC h il dren( ) { retu rn ch il dren; }

priv ate v o id s etC h il dren( Set ch il dren) { th is . ch il dren=ch il dren; }
....
....
}
I f eac h c h i l d h as, at m o st, o n e p aren t, th e m o st n atu ral m ap p i n g i s a o n e- to - m an y asso c i ati o n :
9 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< id name=" id" >
< / id>
< s et name=" ch il dren" >
< / s et>
< / cl as s >

< id name=" id" >
< / id>
< pro perty name=" name" / >
< / cl as s >
T h i s m ap s to th e fo l l o w i n g tabl e defi n i ti o n s:
create tab l e parent ( id b igint no t nu l l primary k ey )

create tab l e ch il d ( id b igint no t nu l l primary k ey, name v arch ar( 2 55), parent_ id b igint )
al ter tab l e ch il d add co ns traint ch il df k 0 ( parent_ id) ref erences parent
I f th e p aren t i s re q uire d , u se a bi di rec ti o n al o n e- to - m an y asso c i ati o n :

< id name=" id" >
< / id>
< / s et>
< / cl as s >

< id name=" id" >
< / id>
< many- to - o ne name=" parent" cl as s =" P arent" co l u mn=" parent_ id" no t- nu l l =" tru e" / >
< / cl as s >
N o ti c e th e NO T NU L L c o n strai n t:

create tab l e ch il d ( id b igint no t nu l l
primary k ey,
name v arch ar( 2 55),
parent_ id b igint no t nu l l )
al ter tab l e ch il d add co ns traint ch il df k 0 ( parent_ id) ref erences parent
9 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
A l tern ati v el y, i f th i s asso c i ati o n m u st be u n i di rec ti o n al yo u c an dec l are th e NO T NU L L c o n strai n t o n th e < k ey>
m ap p i n g:

< id name=" id" >
< / id>
< k ey co l u mn=" parent_ id" no t- nu l l =" tru e" / >
< / s et>
< / cl as s >

< id name=" id" >
< / id>
< / cl as s >
O n th e o th er h an d, i f a c h i l d h as m u l ti p l e p aren ts, a m an y- to - m an y asso c i ati o n i s ap p ro p ri ate:

< id name=" id" >
< / id>
< s et name=" ch il dren" tab l e=" ch il ds et" >
< many- to - many cl as s =" C h il d" co l u mn=" ch il d_ id" / >
< / s et>
< / cl as s >

< id name=" id" >
< / id>
< / cl as s >
T abl e defi n i ti o n s:

create tab l e ch il d ( id b igint no t nu l l primary k ey, name v arch ar( 2 55) )
create tab l e ch il ds et ( parent_ id b igint no t nu l l ,
ch il d_ id b igint no t nu l l ,
primary k ey ( parent_ id, ch il d_ id ) )
al ter tab l e ch il ds et add co ns traint ch il ds etf k 0 ( parent_ id) ref erences parent
al ter tab l e ch il ds et add co ns traint ch il ds etf k 1 ( ch il d_ id) ref erences ch il d
F o r m o re ex am p l es an d a c o m p l ete ex p l an ati o n o f a p aren t/c h i l d rel ati o n sh i p m ap p i n g, see Ch ap ter 21 ,

E x am p le : P are nt/ C h ild fo r m o re i n fo rm ati o n .
E v en m o re c o m p l ex asso c i ati o n m ap p i n gs are c o v ered i n th e n ex t c h ap ter.
9 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
C h ap ter 7 . A s s ociation M ap p ing s

7 .1 . I n tro du c ti o n
7 .2. U n i di rec ti o n al asso c i ati o n s
7 .2.1 . M an y- to - o n e
7 .2.2. O n e- to - o n e
7 .2.3 . O n e- to - m an y
7 .3 . U n i di rec ti o n al asso c i ati o n s w i th j o i n tabl es
7 .3 .1 . O n e- to - m an y
7 .3 .2. M an y- to - o n e
7 .3 .3 . O n e- to - o n e
7 .3 .4 . M an y- to - m an y
7 .4 . B i di rec ti o n al asso c i ati o n s
7 .4 .2. O n e- to - o n e
7 .5 . B i di rec ti o n al asso c i ati o n s w i th j o i n tabl es
7 .5 .2. o n e to o n e
7 .5 .3 . M an y- to - m an y
7 .6 . M o re c o m p l ex asso c i ati o n m ap p i n gs
7 . 1 . I ntrod uction
A sso c i ati o n m ap p i n gs are o ften th e m o st di ffi c u l t th i n g to i m p l em en t c o rrec tl y. I n th i s sec ti o n w e ex am i n e
so m e c an o n i c al c ases o n e by o n e, starti n g w i th u n i di rec ti o n al m ap p i n gs an d th en bi di rec ti o n al c ases. W e w i l l
u se P ers o n an d A ddres s i n al l th e ex am p l es.
A sso c i ati o n s w i l l be c l assi fi ed by m u l ti p l i c i ty an d w h eth er o r n o t th ey m ap to an i n terv en i n g j o i n tabl e.
N u l l abl e fo rei gn k eys are n o t c o n si dered to be go o d p rac ti c e i n tradi ti o n al data m o del l i n g, so o u r ex am p l es

do n o t u se n u l l abl e fo rei gn k eys. T h i s i s n o t a req u i rem en t o f H i bern ate, an d th e m ap p i n gs w i l l w o rk i f yo u
dro p th e n u l l abi l i ty c o n strai n ts.
7 . 2 . U nid irectional as s ociations
7 . 2 . 1 . M any - to- one
A unid ire c tional m any - to- one as s oc iation i s th e m o st c o m m o n k i n d o f u n i di rec ti o n al asso c i ati o n .

< id name=" id" co l u mn=" pers o nI d" >
< / id>
< many- to - o ne name=" addres s "
co l u mn=" addres s I d"
< / cl as s >
< cl as s name=" A ddres s " >

< id name=" id" co l u mn=" addres s I d" >
< / id>
< / cl as s >
1 0 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
create tab l e P ers o n ( pers o nI d b igint no t nu l l primary k ey, addres s I d b igint no t nu l l )

create tab l e A ddres s ( addres s I d b igint no t nu l l primary k ey )
7 . 2 . 2 . O ne - to- one
A unid ire c tional one - to- one as s oc iation on a f ore ig n k e y i s al m o st i den ti c al . T h e o n l y di fferen c e i s th e c o l u m n
u n i q u e c o n strai n t.

< / id>
u niq u e=" tru e"
< / cl as s >

< / id>
< / cl as s >
create tab l e P ers o n ( pers o nI d b igint no t nu l l primary k ey, addres s I d b igint no t nu l l u niq u e )
A unid ire c tional one - to- one as s oc iation on a p rim ary k e y u su al l y u ses a sp ec i al i d gen erato r I n th i s ex am p l e,
h o w ev er, w e h av e rev ersed th e di rec ti o n o f th e asso c i ati o n :

< / id>
< / cl as s >

< param name=" pro perty" >pers o n< / param>
< / generato r>
< / id>
< o ne- to - o ne name=" pers o n" co ns trained=" tru e" / >
< / cl as s >
create tab l e P ers o n ( pers o nI d b igint no t nu l l primary k ey )

create tab l e A ddres s ( pers o nI d b igint no t nu l l primary k ey )
7 . 2 . 3 . O ne - to- many
A unid ire c tional one - to- m any as s oc iation on a f ore ig n k e y i s an u n u su al c ase, an d i s n o t rec o m m en ded.
1 0 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< / id>
< s et name=" addres s es " >
< k ey co l u mn=" pers o nI d"
< o ne- to - many cl as s =" A ddres s " / >
< / s et>
< / cl as s >

< / id>
< / cl as s >

create tab l e A ddres s ( addres s I d b igint no t nu l l primary k ey, pers o nI d b igint no t nu l l )
Y o u sh o u l d i n stead u se a j o i n tabl e fo r th i s k i n d o f asso c i ati o n .
7 . 3 . U nid irectional as s ociations w ith j oin tabl es
7 . 3 . 1 . O ne - to- many
A unid ire c tional one - to- m any as s oc iation on a j oin tab le i s th e p referred o p ti o n . S p ec i fyi n g u niq u e=" tru e" ,
c h an ges th e m u l ti p l i c i ty fro m m an y- to - m an y to o n e- to - m an y.

< / id>
< s et name=" addres s es " tab l e=" P ers o nA ddres s " >
< many- to - many co l u mn=" addres s I d"
u niq u e=" tru e"
cl as s =" A ddres s " / >
< / s et>
< / cl as s >

< / id>
< / cl as s >

create tab l e P ers o nA ddres s ( pers o nI d no t nu l l , addres s I d b igint no t nu l l primary k ey )
7 . 3 . 2 . M any - to- one
A unid ire c tional m any - to- one as s oc iation on a j oin tab le is c o m m o n w h en th e asso c i ati o n i s o p ti o n al . F o r
ex am p l e:
1 0 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< / id>
< j o in tab l e=" P ers o nA ddres s "
o ptio nal =" tru e" >
< k ey co l u mn=" pers o nI d" u niq u e=" tru e" / >
< / j o in>
< / cl as s >

< / id>
< / cl as s >

create tab l e P ers o nA ddres s ( pers o nI d b igint no t nu l l primary k ey, addres s I d b igint no t nu l l )
7 . 3 . 3 . O ne - to- one
A unid ire c tional one - to- one as s oc iation on a j oin tab le i s p o ssi bl e, bu t ex trem el y u n u su al .

< / id>
u niq u e=" tru e" / >
< / j o in>
< / cl as s >

< / id>
< / cl as s >

create tab l e P ers o nA ddres s ( pers o nI d b igint no t nu l l primary k ey, addres s I d b igint no t nu l l u niq u e )
7 . 3 . 4 . M any - to- many
F i n al l y, h ere i s an ex am p l e o f a unid ire c tional m any - to- m any as s oc iation.
1 0 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< / id>
< / s et>
< / cl as s >

< / id>
< / cl as s >

create tab l e P ers o nA ddres s ( pers o nI d b igint no t nu l l , addres s I d b igint no t nu l l , primary k ey ( pers o nI d, addres s I d) )
7 . 4 . B id irectional as s ociations
7 . 4 . 1 . one - to- many / many - to- one
A b id ire c tional m any - to- one as s oc iation i s th e m o st c o m m o n k i n d o f asso c i ati o n . T h e fo l l o w i n g ex am p l e

i l l u strates th e stan dard p aren t/c h i l d rel ati o n sh i p .

< / id>
< / cl as s >

< / id>
< s et name=" peo pl e" inv ers e=" tru e" >
< k ey co l u mn=" addres s I d" / >
< o ne- to - many cl as s =" P ers o n" / >
< / s et>
< / cl as s >
create tab l e P ers o n ( pers o nI d b igint no t nu l l primary k ey, addres s I d b igint no t nu l l )

I f yo u u se a L is t , o r o th er i n dex ed c o l l ec ti o n , set th e k ey c o l u m n o f th e fo rei gn k ey to no t nu l l . H i bern ate w i l l

m an age th e asso c i ati o n fro m th e c o l l ec ti o n s si de to m ai n tai n th e i n dex o f eac h el em en t, m ak i n g th e o th er
si de v i rtu al l y i n v erse by setti n g u pdate=" f al s e" an d ins ert=" f al s e" :
1 0 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< id name=" id" / >
...
ins ert=" f al s e"
< / cl as s >

< id name=" id" / >
...
< l is t name=" peo pl e" >
< k ey co l u mn=" addres s I d" no t- nu l l =" tru e" / >
< l is t- index co l u mn=" peo pl eI dx " / >
< o ne- to - many cl as s =" P ers o n" / >
< / l is t>
< / cl as s >
I f th e u n derl yi n g fo rei gn k ey c o l u m n i s NO T NU L L , i t i s i m p o rtan t th at yo u defi n e no t- nu l l =" tru e" o n th e < k ey>

el em en t o f th e c o l l ec ti o n m ap p i n g. D o n o t o n l y dec l are no t- nu l l =" tru e" o n a p o ssi bl e n ested < co l u mn>
el em en t, bu t o n th e < k ey> el em en t.
7 . 4 . 2 . O ne - to- one
A b id ire c tional one - to- one as s oc iation on a f ore ig n k e y i s c o m m o n :

< / id>
u niq u e=" tru e"
< / cl as s >

< / id>
< o ne- to - o ne name=" pers o n"
pro perty- ref =" addres s " / >
< / cl as s >
create tab l e P ers o n ( pers o nI d b igint no t nu l l primary k ey, addres s I d b igint no t nu l l u niq u e )
A b id ire c tional one - to- one as s oc iation on a p rim ary k e y u ses th e sp ec i al i d gen erato r:
1 0 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< / id>
< o ne- to - o ne name=" addres s " / >
< / cl as s >

< param name=" pro perty" >pers o n< / param>
< / generato r>
< / id>
< o ne- to - o ne name=" pers o n"
co ns trained=" tru e" / >
< / cl as s >

create tab l e A ddres s ( pers o nI d b igint no t nu l l primary k ey )
7 . 5 . B id irectional as s ociations w ith j oin tabl es
7 . 5 . 1 . one - to- many / many - to- one
T h e fo l l o w i n g i s an ex am p l e o f a b id ire c tional one - to- m any as s oc iation on a j oin tab le . T h e inv ers e=" tru e" c an
go o n ei th er en d o f th e asso c i ati o n , o n th e c o l l ec ti o n , o r o n th e j o i n .

< / id>
< s et name=" addres s es "
tab l e=" P ers o nA ddres s " >
u niq u e=" tru e"
< / s et>
< / cl as s >

< / id>
inv ers e=" tru e"
co l u mn=" pers o nI d"
< / j o in>
< / cl as s >
1 0 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

create tab l e P ers o nA ddres s ( pers o nI d b igint no t nu l l , addres s I d b igint no t nu l l primary k ey )
7 . 5 . 2 . one to one
A b id ire c tional one - to- one as s oc iation on a j oin tab le i s p o ssi bl e, bu t ex trem el y u n u su al .

< / id>
< / j o in>
< / cl as s >

< / id>
o ptio nal =" tru e"
inv ers e=" tru e" >
< k ey co l u mn=" addres s I d"
co l u mn=" pers o nI d"
< / j o in>
< / cl as s >

create tab l e P ers o nA ddres s ( pers o nI d b igint no t nu l l primary k ey, addres s I d b igint no t nu l l u niq u e )
7 . 5 . 3 . M any - to- many
H ere i s an ex am p l e o f a b id ire c tional m any - to- m any as s oc iation.
1 0 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< / id>
< / s et>
< / cl as s >

< / id>
< s et name=" peo pl e" inv ers e=" tru e" tab l e=" P ers o nA ddres s " >
< many- to - many co l u mn=" pers o nI d"
cl as s =" P ers o n" / >
< / s et>
< / cl as s >

create tab l e P ers o nA ddres s ( pers o nI d b igint no t nu l l , addres s I d b igint no t nu l l , primary k ey ( pers o nI d, addres s I d) )
7 . 6 . M ore comp l ex as s ociation map p ing s

M o re c o m p l ex asso c i ati o n j o i n s are e x tre m e ly rare. H i bern ate h an dl es m o re c o m p l ex si tu ati o n s by u si n g S Q L
fragm en ts em bedded i n th e m ap p i n g do c u m en t. F o r ex am p l e, i f a tabl e w i th h i sto ri c al ac c o u n t i n fo rm ati o n
data defi n es acco u ntNu mb er, ef f ectiv eE ndD ate an d ef f ectiv eStartD ate c o l u m n s, i t w o u l d be m ap p ed as fo l l o w s:
< pro perties name=" cu rrentA cco u ntK ey" >

< pro perty name=" acco u ntNu mb er" type=" s tring" no t- nu l l =" tru e" / >
< pro perty name=" cu rrentA cco u nt" type=" b o o l ean" >
< f o rmu l a>cas e w h en ef f ectiv eE ndD ate is nu l l th en 1 el s e 0 end< / f o rmu l a>
< / pro perty>
< / pro perties >
< pro perty name=" ef f ectiv eE ndD ate" type=" date" / >
< pro perty name=" ef f ectiv eStateD ate" type=" date" no t- nu l l =" tru e" / >
Y o u c an th en m ap an asso c i ati o n to th e c urre nt i n stan c e, th e o n e w i th n u l l ef f ectiv eE ndD ate, by u si n g:
< many- to - o ne name=" cu rrentA cco u ntI nf o "

pro perty- ref =" cu rrentA cco u ntK ey"
cl as s =" A cco u ntI nf o " >
< co l u mn name=" acco u ntNu mb er" / >
< f o rmu l a>' 1' < / f o rmu l a>
I n a m o re c o m p l ex ex am p l e, i m agi n e th at th e asso c i ati o n betw een E mpl o yee an d O rganiz atio n i s m ai n tai n ed i n
an E mpl o yment tabl e fu l l o f h i sto ri c al em p l o ym en t data. A n asso c i ati o n to th e em p l o yee' s m os t re c e nt
em p l o yer, th e o n e w i th th e m o st rec en t s tartD ate, c o u l d be m ap p ed i n th e fo l l o w i n g w ay:
1 0 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< j o in>
< k ey co l u mn=" empl o yeeI d" / >
< s u b s el ect>
s el ect empl o yeeI d, o rgI d
f ro m E mpl o yments
gro u p b y o rgI d
h av ing s tartD ate = max ( s tartD ate)
< / s u b s el ect>
< many- to - o ne name=" mo s tR ecentE mpl o yer"
cl as s =" O rganiz atio n"
co l u mn=" o rgI d" / >
< / j o in>
T h i s fu n c ti o n al i ty al l o w s a degree o f c reati v i ty an d fl ex i bi l i ty, bu t i t i s m o re p rac ti c al to h an dl e th ese k i n ds o f

c ases u si n g H Q L o r a c ri teri a q u ery.
C h ap ter 8 . C omp onent M ap p ing

8 .1 . D ep en den t o bj ec ts
8 .2. Co l l ec ti o n s o f dep en den t o bj ec ts
8 .3 . Co m p o n en ts as M ap i n di c es
8 .4 . Co m p o n en ts as c o m p o si te i den ti fi ers
8 .5 . D yn am i c c o m p o n en ts
T h e n o ti o n o f a c om p one nt i s re- u sed i n sev eral di fferen t c o n tex ts an d p u rp o ses th ro u gh o u t H i bern ate.
8 . 1 . Dep end ent obj ects

A c o m p o n en t i s a c o n tai n ed o bj ec t th at i s p ersi sted as a v al u e typ e an d n o t an en ti ty referen c e. T h e term
" c o m p o n en t" refers to th e o bj ec t- o ri en ted n o ti o n o f c o m p o si ti o n an d n o t to arc h i tec tu re- l ev el c o m p o n en ts.
F o r ex am p l e, yo u c an m o del a p erso n l i k e th i s:
1 0 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
priv ate j av a. u til . D ate b irth day;
priv ate Name name;
priv ate String k ey;
pu b l ic String getK ey( ) {
retu rn k ey;
}
priv ate v o id s etK ey( String k ey) {
th is . k ey=k ey;
}
pu b l ic j av a. u til . D ate getB irth day( ) {
retu rn b irth day;
}
pu b l ic v o id s etB irth day( j av a. u til . D ate b irth day) {
th is . b irth day = b irth day;
}
pu b l ic Name getName( ) {
retu rn name;
}
pu b l ic v o id s etName( Name name) {
th is . name = name;
}
......
......
}
pu b l ic cl as s Name {
ch ar initial ;
String f irs t;
String l as t;
pu b l ic String getF irs t( ) {
retu rn f irs t;
}
v o id s etF irs t( String f irs t) {
th is . f irs t = f irs t;
}
pu b l ic String getL as t( ) {
retu rn l as t;
}
v o id s etL as t( String l as t) {
th is . l as t = l as t;
}
pu b l ic ch ar getI nitial ( ) {
retu rn initial ;
}
v o id s etI nitial ( ch ar initial ) {
th is . initial = initial ;
}
}
N o w Name c an be p ersi sted as a c o m p o n en t o f P ers o n. Name defi n es getter an d setter m eth o ds fo r i ts

p ersi sten t p ro p erti es, bu t i t do es n o t n eed to dec l are an y i n terfac es o r i den ti fi er p ro p erti es.
O u r H i bern ate m ap p i n g w o u l d l o o k l i k e th i s:
1 1 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" eg. P ers o n" tab l e=" pers o n" >
< id name=" K ey" co l u mn=" pid" type=" s tring" >
< generato r cl as s =" u u id" / >
< / id>
< pro perty name=" b irth day" type=" date" / >
< co mpo nent name=" Name" cl as s =" eg. Name" > < ! - - cl as s attrib u te o ptio nal - - >
< pro perty name=" f irs t" / >
< pro perty name=" l as t" / >
< / co mpo nent>
< / cl as s >
T h e p erso n tabl e w o u l d h av e th e c o l u m n s pid , b irth day, initial , f irs t an d l as t .
L i k e v al u e typ es, c o m p o n en ts do n o t su p p o rt sh ared referen c es. I n o th er w o rds, tw o p erso n s c o u l d h av e th e

sam e n am e, bu t th e tw o p erso n o bj ec ts w o u l d c o n tai n tw o i n dep en den t n am e o bj ec ts th at w ere o n l y " th e
sam e" by v al u e. T h e n u l l v al u e sem an ti c s o f a c o m p o n en t are ad h oc . W h en rel o adi n g th e c o n tai n i n g o bj ec t,
H i bern ate w i l l assu m e th at i f al l c o m p o n en t c o l u m n s are n u l l , th en th e en ti re c o m p o n en t i s n u l l . T h i s is
su i tabl e fo r m o st p u rp o ses.
T h e p ro p erti es o f a c o m p o n en t c an be o f an y H i bern ate typ e (c o l l ec ti o n s, m an y- to - o n e asso c i ati o n s, o th er

c o m p o n en ts, etc ). N ested c o m p o n en ts sh o u l d not be c o n si dered an ex o ti c u sage. H i bern ate i s i n ten ded to
su p p o rt a fi n e- grai n ed o bj ec t m o del .
T h e < co mpo nent> el em en t al l o w s a < parent> su bel em en t th at m ap s a p ro p erty o f th e c o m p o n en t c l ass as a

referen c e bac k to th e c o n tai n i n g en ti ty.
< cl as s name=" eg. P ers o n" tab l e=" pers o n" >
< id name=" K ey" co l u mn=" pid" type=" s tring" >
< / id>
< pro perty name=" b irth day" type=" date" / >
< co mpo nent name=" Name" cl as s =" eg. Name" u niq u e=" tru e" >
< parent name=" namedP ers o n" / > < ! - - ref erence b ack to th e P ers o n - - >
< / co mpo nent>
< / cl as s >
8 . 2 . C ol l ections of d ep end ent obj ects

Co l l ec ti o n s o f c o m p o n en ts are su p p o rted (e.g. an array o f typ e Name). D ec l are yo u r c o m p o n en t c o l l ec ti o n by
rep l ac i n g th e < el ement> tag w i th a < co mpo s ite- el ement> tag:
< s et name=" s o meNames " tab l e=" s o me_ names " l az y=" tru e" >
< k ey co l u mn=" id" / >
< co mpo s ite- el ement cl as s =" eg. Name" > < ! - - cl as s attrib u te req u ired - - >
< / s et>
Important
I f yo u defi n e a Set o f c o m p o si te el em en ts, i t i s i m p o rtan t to i m p l em en t eq u al s ( ) an d h as h C o de( )
c o rrec tl y.
1 1 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
Co m p o si te el em en ts c an c o n tai n c o m p o n en ts bu t n o t c o l l ec ti o n s. I f yo u r c o m p o si te el em en t c o n tai n s
c o m p o n en ts, u se th e < nes ted- co mpo s ite- el ement> tag. T h i s c ase i s a c o l l ec ti o n o f c o m p o n en ts w h i c h
th em sel v es h av e c o m p o n en ts. Y o u m ay w an t to c o n si der i f a o n e- to - m an y asso c i ati o n i s m o re ap p ro p ri ate.
R em o del th e c o m p o si te el em en t as an en ti ty, bu t be aw are th at ev en th o u gh th e J av a m o del i s th e sam e,
th e rel ati o n al m o del an d p ersi sten c e sem an ti c s are sti l l sl i gh tl y di fferen t.
A c o m p o si te el em en t m ap p i n g do es n o t su p p o rt n u l l - abl e p ro p erti es i f yo u are u si n g a < s et>. T h ere i s n o

sep arate p ri m ary k ey c o l u m n i n th e c o m p o si te el em en t tabl e. H i bern ate u ses eac h c o l u m n ' s v al u e to i den ti fy
a rec o rd w h en del eti n g o bj ec ts, w h i c h i s n o t p o ssi bl e w i th n u l l v al u es. Y o u h av e to ei th er u se o n l y n o t- n u l l
p ro p erti es i n a c o m p o si te- el em en t o r c h o o se a < l is t>, < map>, o r < idb ag>.
A sp ec i al c ase o f a c o m p o si te el em en t i s a c o m p o si te el em en t w i th a n ested < many- to - o ne> el em en t. T h i s

m
ap p i n g al l o w s yo u to m ap ex tra c o l u m n s o f a m an y- to - m an y asso c i ati o n tabl e to th e c o m p o si te el em en t
c l ass. T h e fo l l o w i n g i s a m an y- to - m an y asso c i ati o n fro m O rder to I tem, w h ere pu rch as eD ate, price an d q u antity
are p ro p erti es o f th e asso c i ati o n :
< cl as s name=" eg. O rder" . . . . >

....
< s et name=" pu rch as edI tems " tab l e=" pu rch as e_ items " l az y=" tru e" >
< k ey co l u mn=" o rder_ id" >
< co mpo s ite- el ement cl as s =" eg. P u rch as e" >
< pro perty name=" pu rch as eD ate" / >
< pro perty name=" price" / >
< pro perty name=" q u antity" / >
< many- to - o ne name=" item" cl as s =" eg. I tem" / > < ! - - cl as s attrib u te is o ptio nal - - >
< / s et>
< / cl as s >
T h ere c an n o t be a referen c e to th e p u rc h ase o n th e o th er si de fo r bi di rec ti o n al asso c i ati o n n av i gati o n .

Co m p o n en ts are v al u e typ es an d do n o t al l o w sh ared referen c es. A si n gl e P u rch as e c an be i n th e set o f an
O rder, bu t i t c an n o t be referen c ed by th e I tem at th e sam e ti m e.
E v en tern ary (o r q u atern ary, etc ) asso c i ati o n s are p o ssi bl e:
< cl as s name=" eg. O rder" . . . . >

....
< s et name=" pu rch as edI tems " tab l e=" pu rch as e_ items " l az y=" tru e" >
< k ey co l u mn=" o rder_ id" >
< co mpo s ite- el ement cl as s =" eg. O rderL ine" >
< many- to - o ne name=" pu rch as eD etail s cl as s =" eg. P u rch as e" / >
< many- to - o ne name=" item" cl as s =" eg. I tem" / >
< / s et>
< / cl as s >
Co m p o si te el em en ts c an ap p ear i n q u eri es u si n g th e sam e syn tax as asso c i ati o n s to o th er en ti ti es.
8 . 3 . C omp onents as M ap ind ices

T h e < co mpo s ite- map- k ey> el em en t al l o w s yo u to m ap a c o m p o n en t c l ass as th e k ey o f a M ap. E n su re th at yo u
o v erri de h as h C o de( ) an d eq u al s ( ) c o rrec tl y o n th e c o m p o n en t c l ass.
8 . 4 . C omp onents as comp os ite id entifiers

Y o u c an u se a c o m p o n en t as an i den ti fi er o f an en ti ty c l ass. Y o u r c o m p o n en t c l ass m u st sati sfy c ertai n
req u i rem en ts:
I t m u st i m p l em en t j av a. io . Serial iz ab l e .
1 1 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I t m u st re- i m p l em en t eq u al s ( ) an d h as h C o de( ) c o n si sten tl y w i th th e database' s n o ti o n o f c o m p o si te k ey

eq u al i ty.
N ote
I n H i bern ate3 , al th o u gh th e sec o n d req u i rem en t i s n o t an abso l u tel y h ard req u i rem en t o f
H i bern ate, i t i s rec o m m en ded.
Y o u c an n o t u se an I dentif ierG enerato r to gen erate c o m p o si te k eys. I n stead th e ap p l i c ati o n m u st assi gn i ts o w n

i den ti fi ers.
U se th e < co mpo s ite- id> tag, w i th n ested < k ey- pro perty> el em en ts, i n p l ac e o f th e u su al < id> dec l arati o n . F o r
ex am p l e, th e O rderL ine c l ass h as a p ri m ary k ey th at dep en ds u p o n th e (c o m p o si te) p ri m ary k ey o f O rder.
< cl as s name=" O rderL ine" >
< co mpo s ite- id name=" id" cl as s =" O rderL ineI d" >
< k ey- pro perty name=" l ineI d" / >
< k ey- pro perty name=" o rderI d" / >
< k ey- pro perty name=" cu s to merI d" / >
< many- to - o ne name=" o rder" cl as s =" O rder"

ins ert=" f al s e" u pdate=" f al s e" >
< co l u mn name=" o rderI d" / >
< co l u mn name=" cu s to merI d" / >
....
< / cl as s >
A n y fo rei gn k eys referen c i n g th e O rderL ine tabl e are n o w c o m p o si te. D ec l are th i s i n yo u r m ap p i n gs fo r o th er

c l asses. A n asso c i ati o n to O rderL ine i s m ap p ed l i k e th i s:
< many- to - o ne name=" o rderL ine" cl as s =" O rderL ine" >

< ! - - th e " cl as s " attrib u te is o ptio nal , as u s u al - - >
< co l u mn name=" l ineI d" / >
T ip
T h e co l u mn el em en t i s an al tern ati v e to th e co l u mn attri bu te ev eryw h ere. U si n g th e co l u mn
el em en t j u st gi v es m o re dec l arati o n o p ti o n s, w h i c h are m o stl y u sefu l w h en u ti l i z i n g h b m2 ddl
A many- to - many asso c i ati o n to O rderL ine al so u ses th e c o m p o si te fo rei gn k ey:
1 1 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< s et name=" u ndel iv eredO rderL ines " >

< k ey co l u mn name=" w areh o u s eI d" / >
< many- to - many cl as s =" O rderL ine" >
< / many- to - many>
< / s et>
T h e c o l l ec ti o n o f O rderL ines i n O rder w o u l d u se:
< s et name=" o rderL ines " inv ers e=" tru e" >
< k ey>
< / k ey>
< o ne- to - many cl as s =" O rderL ine" / >
< / s et>
T h e < o ne- to - many> el em en t dec l ares n o c o l u m n s.
I f O rderL ine i tsel f o w n s a c o l l ec ti o n , i t al so h as a c o m p o si te fo rei gn k ey.
< cl as s name=" O rderL ine" >

....
....
< l is t name=" del iv eryA ttempts " >
< k ey> < ! - - a co l l ectio n inh erits th e co mpo s ite k ey type - - >
< / k ey>
< l is t- index co l u mn=" attemptI d" b as e=" 1" / >
< co mpo s ite- el ement cl as s =" D el iv eryA ttempt" >
...
< / s et>
< / cl as s >
8 . 5 . Dy namic comp onents

Y o u c an al so m ap a p ro p erty o f typ e M ap:
< dynamic- co mpo nent name=" u s erA ttrib u tes " >
< pro perty name=" f o o " co l u mn=" F O O " type=" s tring" / >
< pro perty name=" b ar" co l u mn=" B A R " type=" integer" / >
< many- to - o ne name=" b az " cl as s =" B az " co l u mn=" B A Z _ I D " / >
< / dynamic- co mpo nent>
T h e sem an ti c s o f a < dynamic- co mpo nent> m ap p i n g are i den ti c al to < co mpo nent>. T h e adv an tage o f th i s k i n d o f
m ap p i n g i s th e abi l i ty to determ i n e th e ac tu al p ro p erti es o f th e bean at dep l o ym en t ti m e j u st by edi ti n g th e
m ap p i n g do c u m en t. R u n ti m e m an i p u l ati o n o f th e m ap p i n g do c u m en t i s al so p o ssi bl e, u si n g a D O M p arser.
Y o u c an al so ac c ess, an d c h an ge, H i bern ate' s c o n fi gu rati o n - ti m e m etam o del v i a th e C o nf igu ratio n o bj ec t.
C h ap ter 9 . I nh eritance map p ing
1 1 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
9 .1 . T h e th ree strategi es
9 .1 .1 . T abl e p er c l ass h i erarc h y
9 .1 .2. T abl e p er su bc l ass
9 .1 .3 . T abl e p er su bc l ass: u si n g a di sc ri m i n ato r
9 .1 .4 . M i x i n g tabl e p er c l ass h i erarc h y w i th tabl e p er su bc l ass
9 .1 .5 . T abl e p er c o n c rete c l ass
9 .1 .6 . T abl e p er c o n c rete c l ass u si n g i m p l i c i t p o l ym o rp h i sm
9 .1 .7 . M i x i n g i m p l i c i t p o l ym o rp h i sm w i th o th er i n h eri tan c e m ap p i n gs
9 .2. L i m i tati o n s
9 . 1 . T h e th ree s trateg ies

H i bern ate su p p o rts th e th ree basi c i n h eri tan c e m ap p i n g strategi es:
tabl e p er c l ass h i erarc h y

tabl e p er su bc l ass
tabl e p er c o n c rete c l ass
I n addi ti o n , H i bern ate su p p o rts a fo u rth , sl i gh tl y di fferen t k i n d o f p o l ym o rp h i sm :
i m p l i c i t p o l ym o rp h i sm
I t i s p o ssi bl e to u se di fferen t m ap p i n g strategi es fo r di fferen t bran c h es o f th e sam e i n h eri tan c e h i erarc h y.

Y o u c an th en m ak e u se o f i m p l i c i t p o l ym o rp h i sm to ac h i ev e p o l ym o rp h i sm ac ro ss th e w h o l e h i erarc h y.
H o w ev er, H i bern ate do es n o t su p p o rt m i x i n g < s u b cl as s >, < j o ined- s u b cl as s > an d m ap p i n gs
u n der th e sam e ro o t < cl as s > el em en t. I t i s p o ssi bl e to m ix to geth er th e tabl e p er h i erarc h y an d tabl e p er
su bc l ass strategi es u n der th e th e sam e < cl as s > el em en t, by c o m bi n i n g th e < s u b cl as s > an d < j o in> el em en ts
(see bel o w fo r an ex am p l e).
I t i s p o ssi bl e to defi n e s u b cl as s , u nio n- s u b cl as s , an d j o ined- s u b cl as s m ap p i n gs i n sep arate m ap p i n g do c u m en ts

di rec tl y ben eath h ib ernate- mapping . T h i s al l o w s yo u to ex ten d a c l ass h i erarc h y by addi n g a n ew m ap p i n g fi l e.
Y o u m u st sp ec i fy an ex tends attri bu te i n th e su bc l ass m ap p i n g, n am i n g a p rev i o u sl y m ap p ed su p erc l ass.
P rev i o u sl y th i s featu re m ade th e o rderi n g o f th e m ap p i n g do c u m en ts i m p o rtan t. S i n c e H i bern ate3 , th e
o rderi n g o f m ap p i n g fi l es i s i rrel ev an t w h en u si n g th e ex ten ds k eyw o rd. T h e o rderi n g i n si de a si n gl e m ap p i n g
fi l e sti l l n eeds to be defi n ed as su p erc l asses befo re su bc l asses.

< s u b cl as s name=" D o mes ticC at" ex tends =" C at" dis criminato r- v al u e=" D " >
< pro perty name=" name" type=" s tring" / >
< / s u b cl as s >
9 . 1 . 1 . T ab l e pe r c l as s h i e rarc h y
S u p p o se w e h av e an i n terfac e P ayment w i th th e i m p l em en to rs C reditC ardP ayment , C as h P ayment , an d

C h eq u eP ayment . T h e tabl e p er h i erarc h y m ap p i n g w o u l d di sp l ay i n th e fo l l o w i n g w ay:
1 1 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" P ayment" tab l e=" P A Y M E NT " >

< id name=" id" type=" l o ng" co l u mn=" P A Y M E NT _ I D " >
< / id>
< dis criminato r co l u mn=" P A Y M E NT _ T Y P E " type=" s tring" / >
< pro perty name=" amo u nt" co l u mn=" A M O U NT " / >
...
< s u b cl as s name=" C reditC ardP ayment" dis criminato r- v al u e=" C R E D I T " >
< pro perty name=" creditC ardT ype" co l u mn=" C C T Y P E " / >
...
< / s u b cl as s >
< s u b cl as s name=" C as h P ayment" dis criminato r- v al u e=" C A SH " >
...
< / s u b cl as s >
< s u b cl as s name=" C h eq u eP ayment" dis criminato r- v al u e=" C H E Q U E " >
...
< / s u b cl as s >
< / cl as s >
E x ac tl y o n e tabl e i s req u i red. T h ere i s a l i m i tati o n o f th i s m ap p i n g strategy: c o l u m n s dec l ared by th e

su bc l asses, su c h as C C T Y P E , c an n o t h av e NO T NU L L c o n strai n ts.
9 . 1 . 2 . T ab l e pe r s u b c l as s
A tabl e p er su bc l ass m ap p i n g l o o k s l i k e th i s:

< / id>
...
< j o ined- s u b cl as s name=" C reditC ardP ayment" tab l e=" C R E D I T _ P A Y M E NT " >
< k ey co l u mn=" P A Y M E NT _ I D " / >
...
< j o ined- s u b cl as s name=" C as h P ayment" tab l e=" C A SH _ P A Y M E NT " >
...
< j o ined- s u b cl as s name=" C h eq u eP ayment" tab l e=" C H E Q U E _ P A Y M E NT " >
...
< / cl as s >
F o u r tabl es are req u i red. T h e th ree su bc l ass tabl es h av e p ri m ary k ey asso c i ati o n s to th e su p erc l ass tabl e so
th e rel ati o n al m o del i s ac tu al l y a o n e- to - o n e asso c i ati o n .
9 . 1 . 3 . T ab l e pe r s u b c l as s : u s i ng a d i s c ri mi nator
H i bern ate' s i m p l em en tati o n o f tabl e p er su bc l ass do es n o t req u i re a di sc ri m i n ato r c o l u m n . O th er

o bj ec t/rel ati o n al m ap p ers u se a di fferen t i m p l em en tati o n o f tabl e p er su bc l ass th at req u i res a typ e
di sc ri m i n ato r c o l u m n i n th e su p erc l ass tabl e. T h e ap p ro ac h tak en by H i bern ate i s m u c h m o re di ffi c u l t to
i m p l em en t, bu t argu abl y m o re c o rrec t fro m a rel ati o n al p o i n t o f v i ew . I f yo u w an t to u se a di sc ri m i n ato r
c o l u m n w i th th e tabl e p er su bc l ass strategy, yo u c an c o m bi n e th e u se o f < s u b cl as s > an d < j o in>, as fo l l o w s:
1 1 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< / id>
...
< j o in tab l e=" C R E D I T _ P A Y M E NT " >
...
< / j o in>
< / s u b cl as s >
< j o in tab l e=" C A SH _ P A Y M E NT " >
...
< / j o in>
< / s u b cl as s >
< j o in tab l e=" C H E Q U E _ P A Y M E NT " f etch =" s el ect" >
...
< / j o in>
< / s u b cl as s >
< / cl as s >
T h e o p ti o n al f etch =" s el ect" dec l arati o n tel l s H i bern ate n o t to fetc h th e C h eq u eP ayment su bc l ass data u si n g an
o u ter j o i n w h en q u eryi n g th e su p erc l ass.
9 . 1 . 4 . M i x i ng tab l e pe r c l as s h i e rarc h y w i th tab l e pe r s u b c l as s
Y o u c an ev en m i x th e tabl e p er h i erarc h y an d tabl e p er su bc l ass strategi es u si n g th e fo l l o w i n g ap p ro ac h :

< / id>
...
< j o in tab l e=" C R E D I T _ P A Y M E NT " >
...
< / j o in>
< / s u b cl as s >
...
< / s u b cl as s >
...
< / s u b cl as s >
< / cl as s >
F o r an y o f th ese m ap p i n g strategi es, a p o l ym o rp h i c asso c i ati o n to th e ro o t P ayment c l ass i s m ap p ed u si n g

< many- to - o ne>.
1 1 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< many- to - o ne name=" payment" co l u mn=" P A Y M E NT _ I D " cl as s =" P ayment" / >
9 . 1 . 5 . T ab l e pe r c onc re te c l as s
T h ere are tw o w ays w e c an m ap th e tabl e p er c o n c rete c l ass strategy. F i rst, yo u c an u se .
< cl as s name=" P ayment" >

< / id>
...

...

...

...
< / cl as s >
T h ree tabl es are i n v o l v ed fo r th e su bc l asses. E ac h tabl e defi n es c o l u m n s fo r al l p ro p erti es o f th e c l ass,

i n c l u di n g i n h eri ted p ro p erti es.
T h e l i m i tati o n o f th i s ap p ro ac h i s th at i f a p ro p erty i s m ap p ed o n th e su p erc l ass, th e c o l u m n n am e m u st be

th e sam e o n al l su bc l ass tabl es. T h e i den ti ty gen erato r strategy i s n o t al l o w ed i n u n i o n su bc l ass i n h eri tan c e.
T h e p ri m ary k ey seed h as to be sh ared ac ro ss al l u n i o n ed su bc l asses o f a h i erarc h y.
I f yo u r su p erc l ass i s abstrac t, m ap i t w i th ab s tract=" tru e" . I f i t i s n o t abstrac t, an addi ti o n al tabl e (i t defau l ts
to P A Y M E NT i n th e ex am p l e abo v e), i s n eeded to h o l d i n stan c es o f th e su p erc l ass.
9 . 1 . 6 . T ab l e pe r c onc re te c l as s u s i ng i mpl i c i t pol y morph i s m
A n al tern ati v e ap p ro ac h i s to m ak e u se o f i m p l i c i t p o l ym o rp h i sm :
1 1 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" C reditC ardP ayment" tab l e=" C R E D I T _ P A Y M E NT " >

< id name=" id" type=" l o ng" co l u mn=" C R E D I T _ P A Y M E NT _ I D " >
< / id>
< pro perty name=" amo u nt" co l u mn=" C R E D I T _ A M O U NT " / >
...
< / cl as s >
< cl as s name=" C as h P ayment" tab l e=" C A SH _ P A Y M E NT " >

< id name=" id" type=" l o ng" co l u mn=" C A SH _ P A Y M E NT _ I D " >
< / id>
< pro perty name=" amo u nt" co l u mn=" C A SH _ A M O U NT " / >
...
< / cl as s >
< cl as s name=" C h eq u eP ayment" tab l e=" C H E Q U E _ P A Y M E NT " >

< id name=" id" type=" l o ng" co l u mn=" C H E Q U E _ P A Y M E NT _ I D " >
< / id>
< pro perty name=" amo u nt" co l u mn=" C H E Q U E _ A M O U NT " / >
...
< / cl as s >
N o ti c e th at th e P ayment i n terfac e i s n o t m en ti o n ed ex p l i c i tl y. A l so n o ti c e th at p ro p erti es o f P ayment are

m ap p ed i n eac h o f th e su bc l asses. I f yo u w an t to av o i d du p l i c ati o n , c o n si der u si n g X M L en ti ti es (fo r ex am p l e,
[ < ! E NT I T Y al l pro perties SY ST E M " al l pro perties . x ml " > ] i n th e D O C T Y P E dec l arati o n an d & al l pro perties ; i n th e
m ap p i n g).
T h e di sadv an tage o f th i s ap p ro ac h i s th at H i bern ate do es n o t gen erate S Q L U NI O Ns w h en p erfo rm i n g

p o l ym o rp h i c q u eri es.
F o r th i s m ap p i n g strategy, a p o l ym o rp h i c asso c i ati o n to P ayment i s u su al l y m ap p ed u si n g < any>.
< any name=" payment" meta- type=" s tring" id- type=" l o ng" >
< meta- v al u e v al u e=" C R E D I T " cl as s =" C reditC ardP ayment" / >
< meta- v al u e v al u e=" C A SH " cl as s =" C as h P ayment" / >
< meta- v al u e v al u e=" C H E Q U E " cl as s =" C h eq u eP ayment" / >
< co l u mn name=" P A Y M E NT _ C L A SS" / >
< co l u mn name=" P A Y M E NT _ I D " / >
< / any>
9 . 1 . 7 . M i x i ng i mpl i c i t pol y morph i s m w i th oth e r i nh e ri tanc e mappi ng s
S i n c e th e su bc l asses are eac h m ap p ed i n th ei r o w n < cl as s > el em en t, an d si n c e P ayment i s j u st an i n terfac e),

eac h o f th e su bc l asses c o u l d easi l y be p art o f an o th er i n h eri tan c e h i erarc h y. Y o u c an sti l l u se p o l ym o rp h i c
q u eri es agai n st th e P ayment i n terfac e.
1 1 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" C reditC ardP ayment" tab l e=" C R E D I T _ P A Y M E NT " >

< id name=" id" type=" l o ng" co l u mn=" C R E D I T _ P A Y M E NT _ I D " >
< / id>
< dis criminato r co l u mn=" C R E D I T _ C A R D " type=" s tring" / >
< pro perty name=" amo u nt" co l u mn=" C R E D I T _ A M O U NT " / >
...
< s u b cl as s name=" M as terC ardP ayment" dis criminato r- v al u e=" M D C " / >
< s u b cl as s name=" V is aP ayment" dis criminato r- v al u e=" V I SA " / >
< / cl as s >
< cl as s name=" No nel ectro nicT rans actio n" tab l e=" NO NE L E C T R O NI C _ T X N" >
< id name=" id" type=" l o ng" co l u mn=" T X N_ I D " >
< / id>
...
< j o ined- s u b cl as s name=" C as h P ayment" tab l e=" C A SH _ P A Y M E NT " >
< pro perty name=" amo u nt" co l u mn=" C A SH _ A M O U NT " / >
...
< j o ined- s u b cl as s name=" C h eq u eP ayment" tab l e=" C H E Q U E _ P A Y M E NT " >
< pro perty name=" amo u nt" co l u mn=" C H E Q U E _ A M O U NT " / >
...
< / cl as s >
O n c e agai n , P ayment i s n o t m en ti o n ed ex p l i c i tl y. I f w e ex ec u te a q u ery agai n st th e P ayment i n terfac e, fo r

ex am p l e f ro m P ayment , H i bern ate au to m ati c al l y retu rn s i n stan c es o f C reditC ardP ayment (an d i ts su bc l asses,
si n c e th ey al so im p l em en t P ayment ), C as h P ayment an d C h eq u eP ayment , bu t n o t i n stan c es o f
No nel ectro nicT rans actio n.
9 . 2 . L imitations
T h ere are l i m i tati o n s to th e " i m p l i c i t p o l ym o rp h i sm " ap p ro ac h to th e tabl e p er c o n c rete- c l ass m ap p i n g
strategy. T h ere are so m ew h at l ess restri c ti v e l i m i tati o n s to m ap p i n gs.
T h e fo l l o w i n g tabl e sh o w s th e l i m i tati o n s o f tabl e p er c o n c rete- c l ass m ap p i n gs, an d o f i m p l i c i t p o l ym o rp h i sm ,

i n H i bern ate.
Table 9 .1. F eatu res of inh eritanc e m apping s
I nh eritanc e Poly m orph ic Poly m orph ic Poly m orph ic Poly m orph ic

Poly m orph ic load ( ) /g et( )
strateg y m any - to- one one- to- one one- to- m any m any - to- m any
tabl e p er
< many- to - o ne> < o ne- to - o ne> < o ne- to - many> < many- to - many> s . get( P ayment. cl as s , id)
c l ass- h i erarc h y
tabl e p er
< many- to - o ne> < o ne- to - o ne> < o ne- to - many> < many- to - many> s . get( P ayment. cl as s , id)
su bc l ass
tabl e p er < o ne- to - many>
c o n c rete- c l ass (fo r
< many- to - o ne> < o ne- to - o ne> < many- to - many> s . get( P ayment. cl as s , id)
(u n i o n - inv ers e=" tru e"
su bc l ass) o n l y)
tabl e p er
c o n c rete c l ass
< any> not s up p orte d not s up p orte d < many- to - any> s . createC riteria( P ayment. cl as s ). add( R es trictio ns . idE q
(i m p l i c i t
1 2 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I nh eritanc e Poly m orph ic Poly m orph ic Poly m orph ic Poly m orph ic

Poly m orph ic load ( ) /g et( )
strateg y m any - to- one one- to- one one- to- m any m any - to- m any
p o l ym o rp h i sm )
C h ap ter 1 0 . W ork ing w ith obj ects

1 0 .1 . H i bern ate o bj ec t states
1 0 .2. M ak i n g o bj ec ts p ersi sten t
1 0 .3 . L o adi n g an o bj ec t
1 0 .4 . Q u eryi n g
1 0 .4 .1 . E x ec u ti n g q u eri es
1 0 .4 .2. F i l teri n g c o l l ec ti o n s
1 0 .4 .3 . Cri teri a q u eri es
1 0 .4 .4 . Q u eri es i n n ati v e S Q L
1 0 .5 . M o di fyi n g p ersi sten t o bj ec ts
1 0 .6 . M o di fyi n g detac h ed o bj ec ts
1 0 .7 . A u to m ati c state detec ti o n
1 0 .8 . D el eti n g p ersi sten t o bj ec ts
1 0 .9 . R ep l i c ati n g o bj ec t betw een tw o di fferen t datasto res
1 0 .1 0 . F l u sh i n g th e S essi o n
1 0 .1 1 . T ran si ti v e p ersi sten c e
1 0 .1 2. U si n g m etadata
H i bern ate i s a fu l l o bj ec t/rel ati o n al m ap p i n g so l u ti o n th at n o t o n l y sh i el ds th e dev el o p er fro m th e detai l s o f

th e u n derl yi n g database m an agem en t system , bu t al so o ffers s tate m anag e m e nt o f o bj ec ts. T h i s i s, c o n trary
to th e m an agem en t o f S Q L s tatements i n c o m m o n J D B C/S Q L p ersi sten c e l ayers, a n atu ral o bj ec t- o ri en ted
v i ew o f p ersi sten c e i n J av a ap p l i c ati o n s.
I n o th er w o rds, H i bern ate ap p l i c ati o n dev el o p ers sh o u l d al w ays th i n k abo u t th e s tate o f th ei r o bj ec ts, an d
n o t n ec essari l y abo u t th e ex ec u ti o n o f S Q L statem en ts. T h i s p art i s tak en c are o f by H i bern ate an d i s o n l y
rel ev an t fo r th e ap p l i c ati o n dev el o p er w h en tu n i n g th e p erfo rm an c e o f th e system .
1 0 . 1 . Hibernate obj ect s tates

H i bern ate defi n es an d su p p o rts th e fo l l o w i n g o bj ec t states:
Trans ie nt - an o bj ec t i s tran si en t i f i t h as j u st been i n stan ti ated u si n g th e new o p erato r, an d i t i s n o t

asso c i ated w i th a H i bern ate Ses s io n. I t h as n o p ersi sten t rep resen tati o n in th e database an d n o i den ti fi er
v al u e h as been assi gn ed. T ran si en t i n stan c es w i l l be destro yed by th e garbage c o l l ec to r i f th e ap p l i c ati o n
do es n o t h o l d a referen c e an ym o re. U se th e H i bern ate Ses s io n to m ak e an o bj ec t p ersi sten t (an d l et
H i bern ate tak e c are o f th e S Q L statem en ts th at n eed to be ex ec u ted fo r th i s tran si ti o n ).
P e rs is te nt - a p ersi sten t i n stan c e h as a rep resen tati o n i n th e database an d an i den ti fi er v al u e. I t m i gh t
j u st h av e been sav ed o r l o aded, h o w ev er, i t i s by defi n i ti o n i n th e sc o p e o f a Ses s io n. H i bern ate w i l l
detec t an y c h an ges m ade to an o bj ec t i n p ersi sten t state an d syn c h ro n i z e th e state w i th th e database
w h en th e u n i t o f w o rk c o m p l etes. D ev el o p ers do n o t ex ec u te m an u al U P D A T E statem en ts, o r D E L E T E
statem en ts w h en an o bj ec t sh o u l d be m ade tran si en t.
D e tac h e d - a detac h ed i n stan c e i s an o bj ec t th at h as been p ersi sten t, bu t i ts Ses s io n h as been c l o sed. T h e
referen c e to th e o bj ec t i s sti l l v al i d, o f c o u rse, an d th e detac h ed i n stan c e m i gh t ev en be m o di fi ed i n th i s
state. A detac h ed i n stan c e c an be reattac h ed to a n ew Ses s io n at a l ater p o i n t i n ti m e, m ak i n g i t (an d al l
th e m o di fi c ati o n s) p ersi sten t agai n . T h i s featu re en abl es a p ro gram m i n g m o del fo r l o n g ru n n i n g u n i ts o f
w o rk th at req u i re u ser th i n k - ti m e. W e c al l th em ap p lic ation trans ac tions , i .e., a u n i t o f w o rk fro m th e
p o i n t o f v i ew o f th e u ser.
W e w i l l n o w di sc u ss th e states an d state tran si ti o n s (an d th e H i bern ate m eth o ds th at tri gger a tran si ti o n ) i n
m o re detai l .
1 2 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 0 . 2 . M ak ing obj ects p ers is tent

N ew l y i n stan ti ated i n stan c es o f a a p ersi sten t c l ass are c o n si dered trans ie nt by H i bern ate. W e c an m ak e a
tran si en t i n stan c e p e rs is te nt by asso c i ati n g i t w i th a sessi o n :
D o mes ticC at f ritz = new D o mes ticC at( );

f ritz . s etC o l o r( C o l o r. G I NG E R );
f ritz . s etSex ( ' M ' );
f ritz . s etName( " F ritz " );
L o ng generatedI d = ( L o ng) s es s . s av e( f ritz );
I f C at h as a gen erated i den ti fi er, th e i den ti fi er i s gen erated an d assi gn ed to th e cat w h en s av e( ) i s c al l ed. I f
C at h as an as s igned i den ti fi er, o r a c o m p o si te k ey, th e i den ti fi er sh o u l d be assi gn ed to th e cat i n stan c e befo re
c al l i n g s av e( ). Y o u c an al so u se pers is t( ) i n stead o f s av e( ), w i th th e sem an ti c s defi n ed i n th e E J B 3 earl y draft.
pers is t( ) m ak es a tran si en t i n stan c e p ersi sten t. H o w ev er, i t do es n o t gu aran tee th at th e i den ti fi er v al u e

w i l l be assi gn ed to th e p ersi sten t i n stan c e i m m edi atel y, th e assi gn m en t m i gh t h ap p en at fl u sh ti m e.
pers is t( ) al so gu aran tees th at i t w i l l n o t ex ec u te an I NSE R T statem en t i f i t i s c al l ed o u tsi de o f tran sac ti o n
bo u n dari es. T h i s i s u sefu l i n l o n g- ru n n i n g c o n v ersati o n s w i th an ex ten ded S essi o n /p ersi sten c e c o n tex t.
s av e( ) do es gu aran tee to retu rn an i den ti fi er. I f an I N S E R T h as to be ex ec u ted to get th e i den ti fi er ( e.g.
" i den ti ty" gen erato r, n o t " seq u en c e" ), th i s I N S E R T h ap p en s i m m edi atel y, n o m atter i f yo u are i n si de o r
o u tsi de o f a tran sac ti o n . T h i s i s p ro bl em ati c in a l o n g- ru n n i n g c o n v ersati o n w i th an ex ten ded
S essi o n /p ersi sten c e c o n tex t.
A l tern ati v el y, yo u c an assi gn th e i den ti fi er u si n g an o v erl o aded v ersi o n o f s av e( ).
D o mes ticC at pk = new D o mes ticC at( );

pk . s etC o l o r( C o l o r. T A B B Y );
pk . s etSex ( ' F ' );
pk . s etName( " P K " );
pk . s etK ittens ( new H as h Set( ) );
pk . addK itten( f ritz );
s es s . s av e( pk , new L o ng( 12 34) );
I f th e o bj ec t yo u m ak e p ersi sten t h as asso c i ated o bj ec ts (e.g. th e k ittens c o l l ec ti o n i n th e p rev i o u s ex am p l e),

th ese o bj ec ts c an be m ade p ersi sten t i n an y o rder yo u l i k e u n l ess yo u h av e a NO T NU L L c o n strai n t u p o n a
fo rei gn k ey c o l u m n . T h ere i s n ev er a ri sk o f v i o l ati n g fo rei gn k ey c o n strai n ts. H o w ev er, yo u m i gh t v i o l ate a
NO T NU L L c o n strai n t i f yo u s av e( ) th e o bj ec ts i n th e w ro n g o rder.
U su al l y yo u do n o t bo th er w i th th i s detai l , as yo u w i l l n o rm al l y u se H i bern ate' s trans itiv e p e rs is te nc e featu re

to sav e th e asso c i ated o bj ec ts au to m ati c al l y. T h en , ev en NO T NU L L c o n strai n t v i o l ati o n s do n o t o c c u r -
H i bern ate w i l l tak e c are o f ev eryth i n g. T ran si ti v e p ersi sten c e i s di sc u ssed l ater i n th i s c h ap ter.
1 0 . 3 . L oad ing an obj ect

T h e l o ad( ) m eth o ds o f Ses s io n p ro v i de a w ay o f retri ev i n g a p ersi sten t i n stan c e i f yo u k n o w i ts i den ti fi er.
l o ad( ) tak es a c l ass o bj ec t an d l o ads th e state i n to a n ew l y i n stan ti ated i n stan c e o f th at c l ass i n a p ersi sten t
state.
C at f ritz = ( C at) s es s . l o ad( C at. cl as s , generatedI d);
/ / yo u need to w rap primitiv e identif iers

l o ng id = 12 34;
D o mes ticC at pk = ( D o mes ticC at) s es s . l o ad( D o mes ticC at. cl as s , new L o ng( id) );
A l tern ati v el y, yo u c an l o ad state i n to a gi v en i n stan c e:
1 2 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
C at cat = new D o mes ticC at( );

/ / l o ad pk ' s s tate into cat
s es s . l o ad( cat, new L o ng( pk I d) );
Set k ittens = cat. getK ittens ( );
B e aw are th at l o ad( ) w i l l th ro w an u n rec o v erabl e ex c ep ti o n i f th ere i s n o m atc h i n g database ro w . I f th e c l ass

i s m ap p ed w i th a p ro x y, l o ad( ) j u st retu rn s an u n i n i ti al i z ed p ro x y an d do es n o t ac tu al l y h i t th e database u n ti l
yo u i n v o k e a m eth o d o f th e p ro x y. T h i s i s u sefu l i f yo u w i sh to c reate an asso c i ati o n to an o bj ec t w i th o u t
ac tu al l y l o adi n g i t fro m th e database. I t al so al l o w s m u l ti p l e i n stan c es to be l o aded as a batc h i f b atch - s iz e i s
defi n ed fo r th e c l ass m ap p i n g.
I f yo u are n o t c ertai n th at a m atc h i n g ro w ex i sts, yo u sh o u l d u se th e get( ) m eth o d w h i c h h i ts th e database

im m edi atel y an d retu rn s n u l l i f th ere i s n o m atc h i n g ro w .
C at cat = ( C at) s es s . get( C at. cl as s , id);

if ( cat==nu l l ) {
cat = new C at( );
s es s . s av e( cat, id);
}
retu rn cat;
Y o u c an ev en l o ad an o bj ec t u si n g an S Q L SE L E C T ... F O R U P D A T E , u si n g a L o ck M o de. S ee th e A P I
do c u m en tati o n fo r m o re i n fo rm ati o n .
C at cat = ( C at) s es s . get( C at. cl as s , id, L o ck M o de. U P G R A D E );
A n y asso c i ated i n stan c es o r c o n tai n ed c o l l ec ti o n s w i l l not be sel ec ted F O R U P D A T E , u n l ess yo u dec i de to

sp ec i fy l o ck o r al l as a c asc ade styl e fo r th e asso c i ati o n .
I t i s p o ssi bl e to re- l o ad an o bj ec t an d al l i ts c o l l ec ti o n s at an y ti m e, u si n g th e ref res h ( ) m eth o d. T h i s i s u sefu l

w h en database tri ggers are u sed to i n i ti al i z e so m e o f th e p ro p erti es o f th e o bj ec t.
s es s . s av e( cat);
s es s . f l u s h ( ); / / f o rce th e SQ L I NSE R T
s es s . ref res h ( cat); / / re- read th e s tate ( af ter th e trigger ex ecu tes )
H o w m u c h do es H i bern ate l o ad fro m th e database an d h o w m an y S Q L SE L E C T s w i l l i t u se? T h i s dep en ds o n

th e f e tc h ing s trate g y . T h i s i s ex p l ai n ed i n S ec ti o n 1 9 .1 , “ F etc h i n g strategi es” .
1 0 . 4 . Q uery ing
I f yo u do n o t k n o w th e i den ti fi ers o f th e o bj ec ts yo u are l o o k i n g fo r, yo u n eed a q u ery. H i bern ate su p p o rts an
easy- to - u se bu t p o w erfu l o bj ec t o ri en ted q u ery l an gu age (H Q L ). F o r p ro gram m ati c q u ery c reati o n , H i bern ate
su p p o rts a so p h i sti c ated Cri teri a an d E x am p l e q u ery featu re (Q B C an d Q B E ). Y o u c an al so ex p ress yo u r
q u ery i n th e n ati v e S Q L o f yo u r database, w i th o p ti o n al su p p o rt fro m H i bern ate fo r resu l t set c o n v ersi o n i n to
o bj ec ts.
1 0 . 4 . 1 . E x e c u ti ng q u e ri e s
H Q L an d n ati v e S Q L q u eri es are rep resen ted w i th an i n stan c e o f o rg. h ib ernate. Q u ery. T h i s i n terfac e o ffers
m eth o ds fo r p aram eter bi n di n g, resu l t set h an dl i n g, an d fo r th e ex ec u ti o n o f th e ac tu al q u ery. Y o u al w ays
o btai n a Q u ery u si n g th e c u rren t Ses s io n:
1 2 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
L is t cats = s es s io n. createQ u ery(

" f ro m C at as cat w h ere cat. b irth date < ?" )
. s etD ate( 0, date)
. l is t( );
L is t mo th ers = s es s io n. createQ u ery(

" s el ect mo th er f ro m C at as cat j o in cat. mo th er as mo th er w h ere cat. name = ?" )
. s etString( 0, name)
. l is t( );
L is t k ittens = s es s io n. createQ u ery(

" f ro m C at as cat w h ere cat. mo th er = ?" )
. s etE ntity( 0, pk )
. l is t( );
C at mo th er = ( C at) s es s io n. createQ u ery(

" s el ect cat. mo th er f ro m C at as cat w h ere cat = ?" )
. s etE ntity( 0, iz i)
. u niq u eR es u l t( );] ]
Q u ery mo th ers W ith K ittens = ( C at) s es s io n. createQ u ery(

" s el ect mo th er f ro m C at as mo th er l ef t j o in f etch mo th er. k ittens " );
Set u niq u eM o th ers = new H as h Set( mo th ers W ith K ittens . l is t( ));
A q u ery i s u su al l y ex ec u ted by i n v o k i n g l is t( ). T h e resu l t o f th e q u ery w i l l be l o aded c o m p l etel y i n to a

c o l l ec ti o n in m em o ry. E n ti ty i n stan c es retri ev ed by a q u ery are i n a p ersi sten t state. T h e u niq u eR es u l t( )
m eth o d o ffers a sh o rtc u t i f yo u k n o w yo u r q u ery w i l l o n l y retu rn a si n gl e o bj ec t. Q u eri es th at m ak e u se o f
eager fetc h i n g o f c o l l ec ti o n s u su al l y retu rn du p l i c ates o f th e ro o t o bj ec ts, bu t w i th th ei r c o l l ec ti o n s i n i ti al i z ed.
Y o u c an fi l ter th ese du p l i c ates th ro u gh a Set .
10 .4 .1.1. I tera ting resu lts
O c c asi o n al l y, yo u m i gh t be abl e to ac h i ev e better p erfo rm an c e by ex ec u ti n g th e q u ery u si n g th e iterate( )

m eth o d. T h i s w i l l u su al l y be th e c ase i f yo u ex p ec t th at th e ac tu al en ti ty i n stan c es retu rn ed by th e q u ery w i l l
al ready be i n th e sessi o n o r sec o n d- l ev el c ac h e. I f th ey are n o t al ready c ac h ed, iterate( ) w i l l be sl o w er th an
l is t( ) an d m i gh t req u i re m an y database h i ts fo r a si m p l e q u ery, u su al l y 1 fo r th e i n i ti al sel ec t w h i c h o n ly
retu rn s i den ti fi ers, an d n addi ti o n al sel ec ts to i n i ti al i z e th e ac tu al i n stan c es.
/ / f etch ids
I terato r iter = s es s . createQ u ery( " f ro m eg. Q u x q o rder b y q . l ik el ines s " ). iterate( );
w h il e ( iter. h as Nex t( ) ) {
Q u x q u x = ( Q u x ) iter. nex t( ); / / f etch th e o b j ect
/ / s o meth ing w e co u l dnt ex pres s in th e q u ery
if ( q u x . cal cu l ateC o mpl icatedA l go rith m( ) ) {
/ / del ete th e cu rrent ins tance
iter. remo v e( );
/ / do nt need to pro ces s th e res t
b reak ;
}
}
10 .4 .1.2 . Q u eries th a t retu rn tu p les
H i bern ate q u eri es so m eti m es retu rn tu p l es o f o bj ec ts. E ac h tu p l e i s retu rn ed as an array:
1 2 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I terato r k ittens A ndM o th ers = s es s . createQ u ery(

" s el ect k itten, mo th er f ro m C at k itten j o in k itten. mo th er mo th er" )
. l is t( )
. iterato r( );
w h il e ( k ittens A ndM o th ers . h as Nex t( ) ) {

O b j ect[ ] tu pl e = ( O b j ect[ ] ) k ittens A ndM o th ers . nex t( );
C at k itten = ( C at) tu pl e[ 0] ;
C at mo th er = ( C at) tu pl e[ 1] ;
....
}
10 .4 .1.3 . S c a la r resu lts
Q u eri es c an sp ec i fy a p ro p erty o f a c l ass i n th e s el ect c l au se. T h ey c an ev en c al l S Q L aggregate fu n c ti o n s.

P ro p erti es o r aggregates are c o n si dered " sc al ar" resu l ts an d n o t en ti ti es i n p ersi sten t state.
I terato r res u l ts = s es s . createQ u ery(

" s el ect cat. co l o r, min( cat. b irth date), co u nt( cat) f ro m C at cat " +
" gro u p b y cat. co l o r" )
. l is t( )
. iterato r( );
w h il e ( res u l ts . h as Nex t( ) ) {
O b j ect[ ] ro w = ( O b j ect[ ] ) res u l ts . nex t( );
C o l o r type = ( C o l o r) ro w [ 0] ;
D ate o l des t = ( D ate) ro w [ 1] ;
I nteger co u nt = ( I nteger) ro w [ 2 ] ;
.....
}
10 .4 .1.4 . B ind p a ra m eters
M eth o ds o n Q u ery are p ro v i ded fo r bi n di n g v al u es to n am ed p aram eters o r J D B C- styl e ? p aram eters.

C ontrary to J D B C , H ib e rnate num b e rs p aram e te rs f rom z e ro. N am ed p aram eters are i den ti fi ers o f th e fo rm
: name i n th e q u ery stri n g. T h e adv an tages o f n am ed p aram eters are as fo l l o w s:
n am ed p aram eters are i n sen si ti v e to th e o rder th ey o c c u r i n th e q u ery stri n g

th ey c an o c c u r m u l ti p l e ti m es i n th e sam e q u ery
th ey are sel f- do c u m en ti n g
/ / named parameter ( pref erred)

Q u ery q = s es s . createQ u ery( " f ro m D o mes ticC at cat w h ere cat. name = : name" );
q . s etString( " name" , " F ritz " );
I terato r cats = q . iterate( );
/ / po s itio nal parameter

Q u ery q = s es s . createQ u ery( " f ro m D o mes ticC at cat w h ere cat. name = ?" );
q . s etString( 0, " I z i" );
I terato r cats = q . iterate( );
1 2 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
/ / named parameter l is t
L is t names = new A rrayL is t( );
names . add( " I z i" );
names . add( " F ritz " );
Q u ery q = s es s . createQ u ery( " f ro m D o mes ticC at cat w h ere cat. name in ( : names L is t)" );
q . s etP arameterL is t( " names L is t" , names );
L is t cats = q . l is t( );
10 .4 .1.5. P a g ina tion
I f yo u n eed to sp ec i fy bo u n ds u p o n yo u r resu l t set, th at i s, th e m ax i m u m n u m ber o f ro w s yo u w an t to

retri ev e an d/o r th e fi rst ro w yo u w an t to retri ev e, yo u c an u se m eth o ds o f th e Q u ery i n terfac e:
Q u ery q = s es s . createQ u ery( " f ro m D o mes ticC at cat" );

q . s etF irs tR es u l t( 2 0);
q . s etM ax R es u l ts ( 10);
H i bern ate k n o w s h o w to tran sl ate th i s l i m i t q u ery i n to th e n ati v e S Q L o f yo u r D B M S .
10 .4 .1.6 . S c rolla b le itera tion
I f yo u r J D B C dri v er su p p o rts sc ro l l abl e R es u l tSet s, th e Q u ery i n terfac e c an be u sed to o btai n a Scro l l ab l eR es u l ts

o bj ec t th at al l o w s fl ex i bl e n av i gati o n o f th e q u ery resu l ts.
Q u ery q = s es s . createQ u ery( " s el ect cat. name, cat f ro m D o mes ticC at cat " +
" o rder b y cat. name" );
Scro l l ab l eR es u l ts cats = q . s cro l l ( );
if ( cats . f irs t( ) ) {
/ / f ind th e f irs t name o n each page o f an al ph ab etical l is t o f cats b y name

f irs tNames O f P ages = new A rrayL is t( );
do {
String name = cats . getString( 0);
f irs tNames O f P ages . add( name);
}
w h il e ( cats . s cro l l ( P A G E _ SI Z E ) );
/ / No w get th e f irs t page o f cats

pageO f C ats = new A rrayL is t( );
cats . b ef o reF irs t( );
int i=0;
w h il e( ( P A G E _ SI Z E > i+ + )& & cats . nex t( ) ) pageO f C ats . add( cats . get( 1) );
}
cats . cl o s e( )
N o te th at an o p en database c o n n ec ti o n an d c u rso r i s req u i red fo r th i s fu n c ti o n al i ty. U se

s etM ax R es u l t( )/s etF irs tR es u l t( ) i f yo u n eed o ffl i n e p agi n ati o n fu n c ti o n al i ty.
10 .4 .1.7 . Ex terna liz ing na m ed q u eries
Y o u c an al so defi n e n am ed q u eri es i n th e m ap p i n g do c u m en t. R em em ber to u se a C D A T A sec ti o n i f yo u r

q u ery c o n tai n s c h arac ters th at c o u l d be i n terp reted as m ark u p .
1 2 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< q u ery name=" B yNameA ndM ax imu mW eigh t" >< ! [ C D A T A [

f ro m eg. D o mes ticC at as cat
w h ere cat. name = ?
and cat. w eigh t > ?
] ] >< / q u ery>
P aram eter bi n di n g an d ex ec u ti n g i s do n e p ro gram ati c al l y:
Q u ery q = s es s . getNamedQ u ery( " B yNameA ndM ax imu mW eigh t" );

q . s etString( 0, name);
q . s etI nt( 1, minW eigh t);
T h e ac tu al p ro gram c o de i s i n dep en den t o f th e q u ery l an gu age th at i s u sed. Y o u c an al so defi n e n ati v e S Q L

q u eri es i n m etadata, o r m i grate ex i sti n g q u eri es to H i bern ate by p l ac i n g th em i n m ap p i n g fi l es.
A l so n o te th at a q u ery dec l arati o n i n si de a < h ib ernate- mapping> el em en t req u i res a gl o bal u n i q u e n am e fo r

th e q u ery, w h i l e a q u ery dec l arati o n i n si de a < cl as s > el em en t i s m ade u n i q u e au to m ati c al l y by p rep en di n g
th e fu l l y q u al i fi ed n am e o f th e c l ass. F o r ex am p l e eg. C at. B yNameA ndM ax imu mW eigh t .
1 0 . 4 . 2 . F i l te ri ng c ol l e c ti ons
A c o l l ec ti o n f ilte r i s a sp ec i al typ e o f q u ery th at c an be ap p l i ed to a p ersi sten t c o l l ec ti o n o r array. T h e q u ery

stri n g c an refer to th is , m ean i n g th e c u rren t c o l l ec ti o n el em en t.
C o l l ectio n b l ack K ittens = s es s io n. createF il ter(

pk . getK ittens ( ),
" w h ere th is . co l o r = ?" )
. s etP arameter( C o l o r. B L A C K , H ib ernate. cu s to m( C o l o rU s erT ype. cl as s ) )
. l is t( )
);
T h e retu rn ed c o l l ec ti o n i s c o n si dered a bag th at i s a c o p y o f th e gi v en c o l l ec ti o n . T h e o ri gi n al c o l l ec ti o n i s n o t

m o di fi ed. T h i s i s c o n trary to th e i m p l i c ati o n o f th e n am e " fi l ter" , bu t c o n si sten t w i th ex p ec ted beh av i o r.
O bserv e th at fi l ters do n o t req u i re a f ro m c l au se, al th o u gh th ey c an h av e o n e i f req u i red. F i l ters are n o t

l i m i ted to retu rn i n g th e c o l l ec ti o n el em en ts th em sel v es.
C o l l ectio n b l ack K ittenM ates = s es s io n. createF il ter(

pk . getK ittens ( ),
" s el ect th is . mate w h ere th is . co l o r = eg. C o l o r. B L A C K . intV al u e" )
. l is t( );
E v en an em p ty fi l ter q u ery i s u sefu l , e.g. to l o ad a su bset o f el em en ts i n a l arge c o l l ec ti o n :
C o l l ectio n tenK ittens = s es s io n. createF il ter(

mo th er. getK ittens ( ), " " )
. s etF irs tR es u l t( 0). s etM ax R es u l ts ( 10)
. l is t( );
1 0 . 4 . 3 . C ri te ri a q u e ri e s
H Q L i s ex trem el y p o w erfu l , bu t so m e dev el o p ers p refer to bu i l d q u eri es dyn am i c al l y u si n g an o bj ec t- o ri en ted

A P I , rath er th an bu i l di n g q u ery stri n gs. H i bern ate p ro v i des an i n tu i ti v e C riteria q u ery A P I fo r th ese c ases:
C riteria crit = s es s io n. createC riteria( C at. cl as s );

crit. add( R es trictio ns . eq ( " co l o r" , eg. C o l o r. B L A C K ) );
crit. s etM ax R es u l ts ( 10);
L is t cats = crit. l is t( );
1 2 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h e C riteria an d th e asso c i ated E x ampl e A P I are di sc u ssed i n m o re detai l i n Ch ap ter 1 5 , C rite ria Q ue rie s .
1 0 . 4 . 4 . Q u e ri e s i n nati v e S Q L
Y o u c an ex p ress a q u ery i n S Q L , u si n g createSQ L Q u ery( ) an d l et H i bern ate m an age th e m ap p i n g fro m resu l t

sets to o bj ec ts. Y o u c an at an y ti m e c al l s es s io n. co nnectio n( ) an d u se th e J D B C C o nnectio n di rec tl y. I f yo u
c h o o se to u se th e H i bern ate A P I , yo u m u st en c l o se S Q L al i ases i n brac es:
L is t cats = s es s io n. createSQ L Q u ery( " SE L E C T {cat. *} F R O M C A T {cat} W H E R E R O W NU M < 10" )

. addE ntity( " cat" , C at. cl as s )
. l is t( );
L is t cats = s es s io n. createSQ L Q u ery(

" SE L E C T {cat}. I D A S {cat. id}, {cat}. SE X A S {cat. s ex }, " +
" {cat}. M A T E A S {cat. mate}, {cat}. SU B C L A SS A S {cat. cl as s }, . . . " +
" F R O M C A T {cat} W H E R E R O W NU M < 10" )
. l is t( )
S Q L q u eri es c an c o n tai n n am ed an d p o si ti o n al p aram eters, j u st l i k e H i bern ate q u eri es. M o re i n fo rm ati o n

abo u t n ati v e S Q L q u eri es i n H i bern ate c an be fo u n d i n Ch ap ter 1 6 , N ativ e S Q L .
1 0 . 5 . M od ify ing p ers is tent obj ects

Trans ac tional p e rs is te nt ins tanc e s (i .e. o bj ec ts l o aded, sav ed, c reated o r q u eri ed by th e Ses s io n) c an be
m an i p u l ated by th e ap p l i c ati o n , an d an y c h an ges to p ersi sten t state w i l l be p ersi sted w h en th e Ses s io n i s
f lus h e d . T h i s i s di sc u ssed l ater i n th i s c h ap ter. T h ere i s n o n eed to c al l a p arti c u l ar m eth o d (l i k e u pdate( ),
w h i c h h as a di fferen t p u rp o se) to m ak e yo u r m o di fi c ati o n s p ersi sten t. T h e m o st strai gh tfo rw ard w ay to
u p date th e state o f an o bj ec t i s to l o ad( ) i t an d th en m an i p u l ate i t di rec tl y w h i l e th e Ses s io n i s o p en :
D o mes ticC at cat = ( D o mes ticC at) s es s . l o ad( C at. cl as s , new L o ng( 6 9 ) );
cat. s etName( " P K " );
s es s . f l u s h ( ); / / ch anges to cat are au to matical l y detected and pers is ted
S o m eti m es th i s p ro gram m i n g m o del i s i n effi c i en t, as i t req u i res i n th e sam e sessi o n bo th an S Q L SE L E C T to

l o ad an o bj ec t an d an S Q L U P D A T E to p ersi st i ts u p dated state. H i bern ate o ffers an al tern ate ap p ro ac h by
u si n g detac h ed i n stan c es.
Important
H i bern ate do es n o t o ffer i ts o w n A P I fo r di rec t ex ec u ti o n o f U P D A T E o r D E L E T E statem en ts.
H i bern ate i s a s tate m anag e m e nt serv i c e, yo u do n o t h av e to th i n k in s tate m e nts to u se i t.
J D B C i s a p erfec t A P I fo r ex ec u ti n g S Q L statem en ts, yo u c an get a J D B C C o nnectio n at an y ti m e
by c al l i n g s es s io n. co nnectio n( ). F u rth erm o re, th e n o ti o n o f m ass o p erati o n s c o n fl i c ts w i th
o bj ec t/rel ati o n al m ap p i n g fo r o n l i n e tran sac ti o n p ro c essi n g- o ri en ted ap p l i c ati o n s. F u tu re
v ersi o n s o f H i bern ate c an , h o w ev er, p ro v i de sp ec i al m ass o p erati o n fu n c ti o n s. S ee Ch ap ter 1 3 ,
B atc h p roc e s s ing fo r so m e p o ssi bl e batc h o p erati o n tri c k s.
1 0 . 6 . M od ify ing d etach ed obj ects

M an y ap p l i c ati o n s n eed to retri ev e an o bj ec t i n o n e tran sac ti o n , sen d i t to th e U I l ayer fo r m an i p u l ati o n , th en
sav e th e c h an ges i n a n ew tran sac ti o n . A p p l i c ati o n s th at u se th i s k i n d o f ap p ro ac h i n a h i gh - c o n c u rren c y
en v i ro n m en t u su al l y u se v ersi o n ed data to en su re i so l ati o n fo r th e " l o n g" u n i t o f w o rk .
H i bern ate su p p o rts th i s m o del by p ro v i di n g fo r reattac h m en t o f detac h ed i n stan c es u si n g th e Ses s io n. u pdate( )

o r Ses s io n. merge( ) m eth o ds:
1 2 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
/ / in th e f irs t s es s io n
C at cat = ( C at) f irs tSes s io n. l o ad( C at. cl as s , catI d);
C at po tential M ate = new C at( );
f irs tSes s io n. s av e( po tential M ate);
/ / in a h igh er l ayer o f th e appl icatio n

cat. s etM ate( po tential M ate);
/ / l ater, in a new s es s io n
s eco ndSes s io n. u pdate( cat); / / u pdate cat
s eco ndSes s io n. u pdate( mate); / / u pdate mate
I f th e C at w i th i den ti fi er catI d h ad al ready been l o aded by s eco ndSes s io n w h en th e ap p l i c ati o n tri ed to reattac h
i t, an ex c ep ti o n w o u l d h av e been th ro w n .
U se u pdate( ) i f yo u are c ertai n th at th e sessi o n do es n o t c o n tai n an al ready p ersi sten t i n stan c e w i th th e sam e
i den ti fi er. U se merge( ) i f yo u w an t to m erge yo u r m o di fi c ati o n s at an y ti m e w i th o u t c o n si derati o n o f th e state
o f th e sessi o n . I n o th er w o rds, u pdate( ) i s u su al l y th e fi rst m eth o d yo u w o u l d c al l i n a fresh sessi o n , en su ri n g
th at th e reattac h m en t o f yo u r detac h ed i n stan c es i s th e fi rst o p erati o n th at i s ex ec u ted.
T h e ap p l i c ati o n sh o u l d i n di v i du al l y u pdate( ) detac h ed i n stan c es th at are reac h abl e fro m th e gi v en detac h ed

i n stan c e only i f i t w an ts th ei r state to be u p dated. T h i s c an be au to m ated u si n g trans itiv e p e rs is te nc e . S ee
S ec ti o n 1 0 .1 1 , “ T ran si ti v e p ersi sten c e” fo r m o re i n fo rm ati o n .
T h e l o ck ( ) m eth o d al so al l o w s an ap p l i c ati o n to reasso c i ate an o bj ec t w i th a n ew sessi o n . H o w ev er, th e

detac h ed i n stan c e h as to be u n m o di fi ed.
/ / j u s t reas s o ciate:
s es s . l o ck ( f ritz , L o ck M o de. NO NE );
/ / do a v ers io n ch eck , th en reas s o ciate:
s es s . l o ck ( iz i, L o ck M o de. R E A D );
/ / do a v ers io n ch eck , u s ing SE L E C T . . . F O R U P D A T E , th en reas s o ciate:
s es s . l o ck ( pk , L o ck M o de. U P G R A D E );
N o te th at l o ck ( ) c an be u sed w i th v ari o u s L o ck M o de s. S ee th e A P I do c u m en tati o n an d th e c h ap ter o n

tran sac ti o n h an dl i n g fo r m o re i n fo rm ati o n . R eattac h m en t i s n o t th e o n l y u sec ase fo r l o ck ( ).
O th er m o del s fo r l o n g u n i ts o f w o rk are di sc u ssed i n S ec ti o n 1 1 .3 , “ O p ti m i sti c c o n c u rren c y c o n tro l ” .
1 0 . 7 . A utomatic s tate d etection

H i bern ate u sers h av e req u ested a gen eral p u rp o se m eth o d th at ei th er sav es a tran si en t i n stan c e by
gen erati n g a n ew i den ti fi er o r u p dates/reattac h es th e detac h ed i n stan c es asso c i ated w i th i ts c u rren t
i den ti fi er. T h e s av eO rU pdate( ) m eth o d i m p l em en ts th i s fu n c ti o n al i ty.
/ / in th e f irs t s es s io n
C at cat = ( C at) f irs tSes s io n. l o ad( C at. cl as s , catI D );
/ / in a h igh er tier o f th e appl icatio n

C at mate = new C at( );
cat. s etM ate( mate);
/ / l ater, in a new s es s io n
s eco ndSes s io n. s av eO rU pdate( cat); / / u pdate ex is ting s tate ( cat h as a no n- nu l l id)
s eco ndSes s io n. s av eO rU pdate( mate); / / s av e th e new ins tance ( mate h as a nu l l id)
T h e u sage an d sem an ti c s o f s av eO rU pdate( ) seem s to be c o n fu si n g fo r n ew u sers. F i rstl y, so l o n g as yo u are

n o t tryi n g to u se i n stan c es fro m o n e sessi o n in an o th er n ew sessi o n , yo u sh o u l d n o t n eed to u se u pdate( ),
s av eO rU pdate( ), o r merge( ). S o m e w h o l e ap p l i c ati o n s w i l l n ev er u se ei th er o f th ese m eth o ds.
1 2 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
U su al l y u pdate( ) o r s av eO rU pdate( ) are u sed i n th e fo l l o w i n g sc en ari o :
th e ap p l i c ati o n l o ads an o bj ec t i n th e fi rst sessi o n

th e o bj ec t i s p assed u p to th e U I ti er
so m e m o di fi c ati o n s are m ade to th e o bj ec t
th e o bj ec t i s p assed bac k do w n to th e bu si n ess l o gi c ti er
th e ap p l i c ati o n p ersi sts th ese m o di fi c ati o n s by c al l i n g u pdate( ) i n a sec o n d sessi o n
s av eO rU pdate( ) do es th e fo l l o w i n g:
i f th e o bj ec t i s al ready p ersi sten t i n th i s sessi o n , do n o th i n g

i f an o th er o bj ec t asso c i ated w i th th e sessi o n h as th e sam e i den ti fi er, th ro w an ex c ep ti o n
i f th e o bj ec t h as n o i den ti fi er p ro p erty, s av e( ) i t
i f th e o bj ec t' s i den ti fi er h as th e v al u e assi gn ed to a n ew l y i n stan ti ated o bj ec t, s av e( ) i t
i f th e o bj ec t i s v ersi o n ed by a < v ers io n> o r < times tamp>, an d th e v ersi o n p ro p erty v al u e i s th e sam e
v al u e assi gn ed to a n ew l y i n stan ti ated o bj ec t, s av e( ) i t
o th erw i se u pdate( ) th e o bj ec t
an d merge( ) i s v ery di fferen t:
i f th ere i s a p ersi sten t i n stan c e w i th th e sam e i den ti fi er c u rren tl y asso c i ated w i th th e sessi o n , c o p y th e
state o f th e gi v en o bj ec t o n to th e p ersi sten t i n stan c e
i f th ere i s n o p ersi sten t i n stan c e c u rren tl y asso c i ated w i th th e sessi o n , try to l o ad i t fro m th e database, o r
c reate a n ew p ersi sten t i n stan c e
th e p ersi sten t i n stan c e i s retu rn ed
th e gi v en i n stan c e do es n o t bec o m e asso c i ated w i th th e sessi o n , i t rem ai n s detac h ed
1 0 . 8 . Del eting p ers is tent obj ects

Ses s io n. del ete( ) w i l l rem o v e an o bj ec t' s state fro m th e database. Y o u r ap p l i c ati o n , h o w ev er, c an sti l l h o l d a
referen c e to a del eted o bj ec t. I t i s best to th i n k o f del ete( ) as m ak i n g a p ersi sten t i n stan c e, tran si en t.
s es s . del ete( cat);
Y o u c an del ete o bj ec ts i n an y o rder, w i th o u t ri sk o f fo rei gn k ey c o n strai n t v i o l ati o n s. I t i s sti l l p o ssi bl e to

v i o l ate a NO T NU L L c o n strai n t o n a fo rei gn k ey c o l u m n by del eti n g o bj ec ts i n th e w ro n g o rder, e.g. i f yo u
del ete th e p aren t, bu t fo rget to del ete th e c h i l dren .
1 0 . 9 . Rep l icating obj ect betw een tw o d ifferent d atas tores

I t i s so m eti m es u sefu l to be abl e to tak e a grap h o f p ersi sten t i n stan c es an d m ak e th em p ersi sten t i n a
di fferen t datasto re, w i th o u t regen erati n g i den ti fi er v al u es.
1 3 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
/ / retriev e a cat f ro m o ne datab as e

Ses s io n s es s io n1 = f acto ry1. o penSes s io n( );
T rans actio n tx 1 = s es s io n1. b eginT rans actio n( );
C at cat = s es s io n1. get( C at. cl as s , catI d);
tx 1. co mmit( );
s es s io n1. cl o s e( );
/ / reco ncil e w ith a s eco nd datab as e

Ses s io n s es s io n2 = f acto ry2 . o penSes s io n( );
T rans actio n tx 2 = s es s io n2 . b eginT rans actio n( );
s es s io n2 . repl icate( cat, R epl icatio nM o de. L A T E ST _ V E R SI O N);
tx 2 . co mmit( );
s es s io n2 . cl o s e( );
T h e R epl icatio nM o de determ i n es h o w repl icate( ) w i l l deal w i th c o n fl i c ts w i th ex i sti n g ro w s i n th e database:
R epl icatio nM o de. I G NO R E : i gn o res th e o bj ec t w h en th ere i s an ex i sti n g database ro w w i th th e sam e

i den ti fi er
R epl icatio nM o de. O V E R W R I T E : o v erw ri tes an y ex i sti n g database ro w w i th th e sam e i den ti fi er
R epl icatio nM o de. E X C E P T I O N: th ro w s an ex c ep ti o n i f th ere i s an ex i sti n g database ro w w i th th e sam e

i den ti fi er
R epl icatio nM o de. L A T E ST _ V E R SI O N: o v erw ri tes th e ro w i f i ts v ersi o n n u m ber i s earl i er th an th e v ersi o n
n u m ber o f th e o bj ec t, o r i gn o re th e o bj ec t o th erw i se
U sec ases fo r th i s featu re i n c l u de rec o n c i l i n g data en tered i n to di fferen t database i n stan c es, u p gradi n g system
c o n fi gu rati o n i n fo rm ati o n du ri n g p ro du c t u p grades, ro l l i n g bac k c h an ges m ade du ri n g n o n - A CI D tran sac ti o n s
an d m o re.
1 0 . 1 0 . F l us h ing th e S es s ion
S o m eti m es th e Ses s io n w i l l ex ec u te th e S Q L statem en ts n eeded to syn c h ro n i z e th e J D B C c o n n ec ti o n ' s state
w i th th e state o f o bj ec ts h el d i n m em o ry. T h i s p ro c ess, c al l ed f lus h , o c c u rs by defau l t at th e fo l l o w i n g p o i n ts:
befo re so m e q u ery ex ec u ti o n s
fro m o rg. h ib ernate. T rans actio n. co mmit( )
fro m Ses s io n. f l u s h ( )
T h e S Q L statem en ts are i ssu ed i n th e fo l l o w i n g o rder:
1 . al l en ti ty i n serti o n s i n th e sam e o rder th e c o rresp o n di n g o bj ec ts w ere sav ed u si n g Ses s io n. s av e( )
2. al l en ti ty u p dates
3 . al l c o l l ec ti o n del eti o n s
4 . al l c o l l ec ti o n el em en t del eti o n s, u p dates an d i n serti o n s
5 . al l c o l l ec ti o n i n serti o n s
6 . al l en ti ty del eti o n s i n th e sam e o rder th e c o rresp o n di n g o bj ec ts w ere del eted u si n g Ses s io n. del ete( )
A n ex c ep ti o n i s th at o bj ec ts u si n g nativ e I D gen erati o n are i n serted w h en th ey are sav ed.
E x c ep t w h en yo u ex p l i c i tl y f l u s h ( ), th ere are abso l u tel y n o gu aran tees abo u t w h e n th e Ses s io n ex ec u tes th e

J D B C c al l s, o n l y th e ord e r i n w h i c h th ey are ex ec u ted. H o w ev er, H i bern ate do es gu aran tee th at th e
Q u ery. l is t( . . ) w i l l n ev er retu rn stal e o r i n c o rrec t data.
I t i s p o ssi bl e to c h an ge th e defau l t beh av i o r so th at fl u sh o c c u rs l ess freq u en tl y. T h e F l u s h M o de c l ass defi n es

th ree di fferen t m o des: o n l y fl u sh at c o m m i t ti m e w h en th e H i bern ate T rans actio n A P I i s u sed, fl u sh
au to m ati c al l y u si n g th e ex p l ai n ed ro u ti n e, o r n ev er fl u sh u n l ess f l u s h ( ) i s c al l ed ex p l i c i tl y. T h e l ast m o de i s
u sefu l fo r l o n g ru n n i n g u n i ts o f w o rk , w h ere a Ses s io n i s k ep t o p en an d di sc o n n ec ted fo r a l o n g ti m e (see
S ec ti o n 1 1 .3 .2, “ E x ten ded sessi o n an d au to m ati c v ersi o n i n g” ).
1 3 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
s es s = s f . o penSes s io n( );
T rans actio n tx = s es s . b eginT rans actio n( );
s es s . s etF l u s h M o de( F l u s h M o de. C O M M I T ); / / al l o w q u eries to retu rn s tal e s tate
C at iz i = ( C at) s es s . l o ad( C at. cl as s , id);

iz i. s etName( iz niz i);
/ / migh t retu rn s tal e data

s es s . f ind( " f ro m C at as cat l ef t o u ter j o in cat. k ittens k itten" );
/ / ch ange to iz i is no t f l u s h ed!
...
tx . co mmit( ); / / f l u s h o ccu rs
s es s . cl o s e( );
D u ri n g fl u sh , an ex c ep ti o n m i gh t o c c u r (e.g. i f a D M L o p erati o n v i o l ates a c o n strai n t). S i n c e h an dl i n g

ex c ep ti o n s i n v o l v es so m e u n derstan di n g o f H i bern ate' s tran sac ti o n al beh av i o r, w e di sc u ss i t i n Ch ap ter 1 1 ,
Trans ac tions and C onc urre nc y .
1 0 . 1 1 . T rans itiv e p ers is tence

I t i s q u i te c u m berso m e to sav e, del ete, o r reattac h i n di v i du al o bj ec ts, esp ec i al l y i f yo u deal w i th a grap h o f
asso c i ated o bj ec ts. A c o m m o n c ase i s a p aren t/c h i l d rel ati o n sh i p . Co n si der th e fo l l o w i n g ex am p l e:
I f th e c h i l dren i n a p aren t/c h i l d rel ati o n sh i p w o u l d be v al u e typ ed (e.g. a c o l l ec ti o n o f addresses o r stri n gs),
th ei r l i fe c yc l e w o u l d dep en d o n th e p aren t an d n o fu rth er ac ti o n w o u l d be req u i red fo r c o n v en i en t
" c asc adi n g" o f state c h an ges. W h en th e p aren t i s sav ed, th e v al u e- typ ed c h i l d o bj ec ts are sav ed an d w h en
th e p aren t i s del eted, th e c h i l dren w i l l be del eted, etc . T h i s w o rk s fo r o p erati o n s su c h as th e rem o v al o f a
c h i l d fro m th e c o l l ec ti o n . S i n c e v al u e- typ ed o bj ec ts c an n o t h av e sh ared referen c es, H i bern ate w i l l detec t th i s
an d del ete th e c h i l d fro m th e database.
N o w c o n si der th e sam e sc en ari o w i th p aren t an d c h i l d o bj ec ts bei n g en ti ti es, n o t v al u e- typ es (e.g. c atego ri es

an d i tem s, o r p aren t an d c h i l d c ats). E n ti ti es h av e th ei r o w n l i fe c yc l e an d su p p o rt sh ared referen c es.
R em o v i n g an en ti ty fro m th e c o l l ec ti o n do es n o t m ean i t c an be del eted), an d th ere i s by defau l t n o
c asc adi n g o f state fro m o n e en ti ty to an y o th er asso c i ated en ti ti es. H i bern ate do es n o t i m p l em en t
p e rs is te nc e b y re ac h ab ility by defau l t.
F o r eac h basi c o p erati o n o f th e H i bern ate sessi o n - i n c l u di n g

pers is t( ), merge( ), s av eO rU pdate( ), del ete( ), l o ck ( ), ref res h ( ), ev ict( ), repl icate( ) - th ere i s a c o rresp o n di n g c asc ade
styl e. R esp ec ti v el y, th e c asc ade styl es are n am ed
create, merge, s av e- u pdate, del ete, l o ck , ref res h , ev ict, repl icate . I f yo u w an t an o p erati o n to be c asc aded al o n g
an asso c i ati o n , yo u m u st i n di c ate th at i n th e m ap p i n g do c u m en t. F o r ex am p l e:
< o ne- to - o ne name=" pers o n" cas cade=" pers is t" / >
Casc ade styl es m y be c o m bi n ed:
< o ne- to - o ne name=" pers o n" cas cade=" pers is t, del ete, l o ck " / >
Y o u c an ev en u se cas cade=" al l " to sp ec i fy th at all o p erati o n s sh o u l d be c asc aded al o n g th e asso c i ati o n . T h e

defau l t cas cade=" no ne" sp ec i fi es th at n o o p erati o n s are to be c asc aded.
A sp ec i al c asc ade styl e, del ete- o rph an, ap p l i es o n l y to o n e- to - m an y asso c i ati o n s, an d i n di c ates th at th e
del ete( ) o p erati o n sh o u l d be ap p l i ed to an y c h i l d o bj ec t th at i s rem o v ed fro m th e asso c i ati o n .
R ec o m m en dati o n s:
I t do es n o t u su al l y m ak e sen se to en abl e c asc ade o n a < many- to - o ne> o r < many- to - many> asso c i ati o n .
Casc ade i s o ften u sefu l fo r < o ne- to - o ne> an d < o ne- to - many> asso c i ati o n s.
1 3 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I f th e c h i l d o bj ec t' s l i fesp an i s bo u n ded by th e l i fesp an o f th e p aren t o bj ec t, m ak e i t a lif e c y c le ob j e c t by

sp ec i fyi n g cas cade=" al l , del ete- o rph an" .
O th erw i se, yo u m i gh t n o t n eed c asc ade at al l . B u t i f yo u th i n k th at yo u w i l l o ften be w o rk i n g w i th th e

p aren t an d c h i l dren to geth er i n th e sam e tran sac ti o n , an d yo u w an t to sav e yo u rsel f so m e typ i n g,
c o n si der u si n g cas cade=" pers is t, merge, s av e- u pdate" .
M ap p i n g an asso c i ati o n (ei th er a si n gl e v al u ed asso c i ati o n , o r a c o l l ec ti o n ) w i th cas cade=" al l " m ark s th e

asso c i ati o n as a p are nt/ c h ild styl e rel ati o n sh i p w h ere sav e/u p date/del ete o f th e p aren t resu l ts i n sav e/u p date
/del ete o f th e c h i l d o r c h i l dren .
F u rth erm o re, a m ere referen c e to a c h i l d fro m a p ersi sten t p aren t w i l l resu l t i n sav e/u p date o f th e c h i l d. T h i s
m etap h o r i s i n c o m p l ete, h o w ev er. A c h i l d w h i c h bec o m es u n referen c ed by i ts p aren t i s not au to m ati c al l y
del eted, ex c ep t i n th e c ase o f a < o ne- to - many> asso c i ati o n m ap p ed w i th cas cade=" del ete- o rph an" . T h e p rec i se
sem an ti c s o f c asc adi n g o p erati o n s fo r a p aren t/c h i l d rel ati o n sh i p are as fo l l o w s:
I f a p aren t i s p assed to pers is t( ), al l c h i l dren are p assed to pers is t( )
I f a p aren t i s p assed to merge( ), al l c h i l dren are p assed to merge( )
I f a p aren t i s p assed to s av e( ), u pdate( ) o r s av eO rU pdate( ), al l c h i l dren are p assed to s av eO rU pdate( )
I f a tran si en t o r detac h ed c h i l d bec o m es referen c ed by a p ersi sten t p aren t, i t i s p assed to s av eO rU pdate( )
I f a p aren t i s del eted, al l c h i l dren are p assed to del ete( )
I f a c h i l d i s dereferen c ed by a p ersi sten t p aren t, noth ing s p e c ial h ap p e ns - th e ap p l i c ati o n sh o u l d

ex p l i c i tl y del ete th e c h i l d i f n ec essary - u n l ess cas cade=" del ete- o rph an" , i n w h i c h c ase th e " o rp h an ed" c h i l d
i s del eted.
F i n al l y, n o te th at c asc adi n g o f o p erati o n s c an be ap p l i ed to an o bj ec t grap h at c all tim e o r at f lus h tim e . A l l

o p erati o n s, i f en abl ed, are c asc aded to asso c i ated en ti ti es reac h abl e w h en th e o p erati o n i s ex ec u ted.
H o w ev er, s av e- u pdate an d del ete- o rph an are tran si ti v e fo r al l asso c i ated en ti ti es reac h abl e du ri n g fl u sh o f th e
Ses s io n.
1 0 . 1 2 . U s ing metad ata

H i bern ate req u i res a ri c h m eta- l ev el m o del o f al l en ti ty an d v al u e typ es. T h i s m o del c an be u sefu l to th e
ap p l i c ati o n i tsel f. F o r ex am p l e, th e ap p l i c ati o n m i gh t u se H i bern ate' s m etadata to i m p l em en t a " sm art"
deep - c o p y al go ri th m th at u n derstan ds w h i c h o bj ec ts sh o u l d be c o p i ed (eg. m u tabl e v al u e typ es) an d w h i c h
o bj ec ts th at sh o u l d n o t (e.g. i m m u tabl e v al u e typ es an d, p o ssi bl y, asso c i ated en ti ti es).
H i bern ate ex p o ses m etadata v i a th e C l as s M etadata an d C o l l ectio nM etadata i n terfac es an d th e T ype h i erarc h y.
I n stan c es o f th e m etadata i n terfac es c an be o btai n ed fro m th e Ses s io nF acto ry.
C at f ritz = . . . . . . ;
C l as s M etadata catM eta = s es s io nf acto ry. getC l as s M etadata( C at. cl as s );
O b j ect[ ] pro pertyV al u es = catM eta. getP ro pertyV al u es ( f ritz );

String[ ] pro pertyNames = catM eta. getP ro pertyNames ( );
T ype[ ] pro pertyT ypes = catM eta. getP ro pertyT ypes ( );
/ / get a M ap o f al l pro perties w h ich are no t co l l ectio ns o r as s o ciatio ns

M ap namedV al u es = new H as h M ap( );
f o r ( int i=0; i< pro pertyNames . l ength ; i+ + ){
if ( ! pro pertyT ypes [ i] . is E ntityT ype( ) & & ! pro pertyT ypes [ i] . is C o l l ectio nT ype( ) ) {
namedV al u es . pu t( pro pertyNames [ i] , pro pertyV al u es [ i] );
}
}
C h ap ter 1 1 . T rans actions and C oncurrency
1 3 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 1 .1 . S essi o n an d tran sac ti o n sc o p es

1 1 .1 .1 . U n i t o f w o rk
1 1 .1 .2. L o n g c o n v ersati o n s
1 1 .1 .3 . Co n si deri n g o bj ec t i den ti ty
1 1 .1 .4 . Co m m o n i ssu es
1 1 .2. D atabase tran sac ti o n dem arc ati o n
1 1 .2.1 . N o n - m an aged en v i ro n m en t
1 1 .2.2. U si n g J T A
1 1 .2.3 . E x c ep ti o n h an dl i n g
1 1 .2.4 . T ran sac ti o n ti m eo u t
1 1 .3 . O p ti m i sti c c o n c u rren c y c o n tro l
1 1 .3 .1 . A p p l i c ati o n v ersi o n c h ec k i n g
1 1 .3 .2. E x ten ded sessi o n an d au to m ati c v ersi o n i n g
1 1 .3 .3 . D etac h ed o bj ec ts an d au to m ati c v ersi o n i n g
1 1 .3 .4 . Cu sto m i z i n g au to m ati c v ersi o n i n g
1 1 .4 . P essi m i sti c l o c k i n g
1 1 .5 . Co n n ec ti o n rel ease m o des
T h e m o st i m p o rtan t p o i n t abo u t H i bern ate an d c o n c u rren c y c o n tro l i s th at i t i s easy to u n derstan d. H i bern ate
di rec tl y u ses J D B C c o n n ec ti o n s an d J T A reso u rc es w i th o u t addi n g an y addi ti o n al l o c k i n g beh av i o r. I t i s
rec o m m en ded th at yo u sp en d so m e ti m e w i th th e J D B C, A N S I , an d tran sac ti o n i so l ati o n sp ec i fi c ati o n o f yo u r
database m an agem en t system .
H i bern ate do es n o t l o c k o bj ec ts i n m em o ry. Y o u r ap p l i c ati o n c an ex p ec t th e beh av i o r as defi n ed by th e

i so l ati o n l ev el o f yo u r database tran sac ti o n s. T h ro u gh Ses s io n, w h i c h i s al so a tran sac ti o n - sc o p ed c ac h e,
H i bern ate p ro v i des rep eatabl e reads fo r l o o k u p by i den ti fi er an d en ti ty q u eri es an d n o t rep o rti n g q u eri es th at
retu rn sc al ar v al u es.
I n addi ti o n to v ersi o n i n g fo r au to m ati c o p ti m i sti c c o n c u rren c y c o n tro l , H i bern ate al so o ffers, u si n g th e

SE L E C T F O R U P D A T E syn tax , a (m i n o r) A P I fo r p essi m i sti c l o c k i n g o f ro w s. O p ti m i sti c c o n c u rren c y c o n tro l an d
th i s A P I are di sc u ssed l ater i n th i s c h ap ter.
T h e di sc u ssi o n o f c o n c u rren c y c o n tro l i n H i bern ate begi n s w i th th e gran u l ari ty o f C o nf igu ratio n, Ses s io nF acto ry,
an d Ses s io n, as w el l as database tran sac ti o n s an d l o n g c o n v ersati o n s.
1 1 . 1 . S es s ion and trans action s cop es

A Ses s io nF acto ry i s an ex p en si v e- to - c reate, th readsafe o bj ec t, i n ten ded to be sh ared by al l ap p l i c ati o n
th reads. I t i s c reated o n c e, u su al l y o n ap p l i c ati o n startu p , fro m a C o nf igu ratio n i n stan c e.
A Ses s io n i s an i n ex p en si v e, n o n - th readsafe o bj ec t th at sh o u l d be u sed o n c e an d th en di sc arded fo r: a si n gl e

req u est, a c o n v ersati o n o r a si n gl e u n i t o f w o rk . A Ses s io n w i l l n o t o btai n a J D B C C o nnectio n, o r a D atas o u rce,
u n l ess i t i s n eeded. I t w i l l n o t c o n su m e an y reso u rc es u n ti l u sed.
I n o rder to redu c e l o c k c o n ten ti o n i n th e database, a database tran sac ti o n h as to be as sh o rt as p o ssi bl e.

L o n g database tran sac ti o n s w i l l p rev en t yo u r ap p l i c ati o n fro m sc al i n g to a h i gh l y c o n c u rren t l o ad. I t i s n o t
rec o m m en ded th at yo u h o l d a database tran sac ti o n o p en du ri n g u ser th i n k ti m e u n ti l th e u n i t o f w o rk i s
c o m p l ete.
W h at i s th e sc o p e o f a u n i t o f w o rk ? Can a si n gl e H i bern ate Ses s io n sp an sev eral database tran sac ti o n s, o r i s

th i s a o n e- to - o n e rel ati o n sh i p o f sc o p es? W h en sh o u l d yo u o p en an d c l o se a Ses s io n an d h o w do yo u
dem arc ate th e database tran sac ti o n bo u n dari es? T h ese q u esti o n s are addressed i n th e fo l l o w i n g sec ti o n s.
1 1 . 1 . 1 . U ni t of w ork
F i rst, l et' s defi n e a u n i t o f w o rk . A u n i t o f w o rk i s a desi gn p attern desc ri bed by M arti n F o w l er as “

[m ai n tai n i n g] a l i st o f o bj ec ts affec ted by a bu si n ess tran sac ti o n an d c o o rdi n ates th e w ri ti n g o u t o f c h an ges
an d th e reso l u ti o n o f c o n c u rren c y p ro bl em s. ” [P o E A A ] I n o th er w o rds, i ts a seri es o f o p erati o n s w e w i sh to
c arry o u t agai n st th e database to geth er. B asi c al l y, i t i s a tran sac ti o n , th o u gh fu l fi l l i n g a u n i t o f w o rk w i l l o ften
sp an m u l ti p l e p h ysi c al database tran sac ti o n s (see S ec ti o n 1 1 .1 .2, “ L o n g c o n v ersati o n s” ). S o real l y w e are
1 3 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
tal k i n g abo u t a m o re abstrac t n o ti o n o f a tran sac ti o n . T h e term " bu si n ess tran sac ti o n " i s al so so m eti m es
u sed i n l i eu o f u n i t o f w o rk .
D o n o t u se th e s e s s ion- p e r- op e ration an ti p attern : do n o t o p en an d c l o se a Ses s io n fo r ev ery si m p l e database

c al l i n a si n gl e th read. T h e sam e i s tru e fo r database tran sac ti o n s. D atabase c al l s i n an ap p l i c ati o n are m ade
u si n g a p l an n ed seq u en c e; th ey are gro u p ed i n to ato m i c u n i ts o f w o rk . T h i s al so m ean s th at au to - c o m m i t
after ev ery si n gl e S Q L statem en t i s u sel ess i n an ap p l i c ati o n as th i s m o de i s i n ten ded fo r ad- h o c S Q L c o n so l e
w o rk . H i bern ate di sabl es, o r ex p ec ts th e ap p l i c ati o n serv er to di sabl e, au to - c o m m i t m o de i m m edi atel y.
D atabase tran sac ti o n s are n ev er o p ti o n al . A l l c o m m u n i c ati o n w i th a database h as to o c c u r i n si de a
tran sac ti o n . A u to - c o m m i t beh av i o r fo r readi n g data sh o u l d be av o i ded, as m an y sm al l tran sac ti o n s are
u n l i k el y to p erfo rm better th an o n e c l earl y defi n ed u n i t o f w o rk . T h e l atter i s al so m o re m ai n tai n abl e an d
ex ten si bl e.
T h e m o st c o m m o n p attern i n a m u l ti - u ser c l i en t/serv er ap p l i c ati o n i s s e s s ion- p e r- re q ue s t. I n th i s m o del , a

req u est fro m th e c l i en t i s sen t to th e serv er, w h ere th e H i bern ate p ersi sten c e l ayer ru n s. A n ew H i bern ate
Ses s io n i s o p en ed, an d al l database o p erati o n s are ex ec u ted i n th i s u n i t o f w o rk . O n c o m p l eti o n o f th e w o rk ,
an d o n c e th e resp o n se fo r th e c l i en t h as been p rep ared, th e sessi o n i s fl u sh ed an d c l o sed. U se a si n gl e
database tran sac ti o n to serv e th e c l i en ts req u est, starti n g an d c o m m i tti n g i t w h en yo u o p en an d c l o se th e
Ses s io n. T h e rel ati o n sh i p betw een th e tw o i s o n e- to - o n e an d th i s m o del i s a p erfec t fi t fo r m an y ap p l i c ati o n s.
T h e c h al l en ge l i es i n th e i m p l em en tati o n . H i bern ate p ro v i des bu i l t- i n m an agem en t o f th e " c u rren t sessi o n " to

si m p l i fy th i s p attern . S tart a tran sac ti o n w h en a serv er req u est h as to be p ro c essed, an d en d th e tran sac ti o n
befo re th e resp o n se i s sen t to th e c l i en t. Co m m o n so l u ti o n s are Serv l etF il ter, A O P i n terc ep to r w i th a p o i n tc u t
o n th e serv i c e m eth o ds, o r a p ro x y/i n terc ep ti o n c o n tai n er. A n E J B c o n tai n er i s a stan dardi z ed w ay to
i m p l em en t c ro ss- c u tti n g asp ec ts su c h as tran sac ti o n dem arc ati o n o n E J B sessi o n bean s, dec l arati v el y w i th
CM T . I f yo u u se p ro gram m ati c tran sac ti o n dem arc ati o n , fo r ease o f u se an d c o de p o rtabi l i ty u se th e
H i bern ate T rans actio n A P I sh o w n l ater i n th i s c h ap ter.
Y o u r ap p l i c ati o n c o de c an ac c ess a " c u rren t sessi o n " to p ro c ess th e req u est by c al l i n g

s es s io nF acto ry. getC u rrentSes s io n( ). Y o u w i l l al w ays get a Ses s io n sc o p ed to th e c u rren t database tran sac ti o n .
T h i s h as to be c o n fi gu red fo r ei th er reso u rc e- l o c al o r J T A en v i ro n m en ts, see S ec ti o n 2.5 , “ Co n tex tu al
sessi o n s” .
Y o u c an ex ten d th e sc o p e o f a Ses s io n an d database tran sac ti o n u n ti l th e " v i ew h as been ren dered" . T h i s i s

esp ec i al l y u sefu l i n serv l et ap p l i c ati o n s th at u ti l i z e a sep arate ren deri n g p h ase after th e req u est h as been
p ro c essed. E x ten di n g th e database tran sac ti o n u n ti l v i ew ren deri n g, i s ac h i ev ed by i m p l em en ti n g yo u r o w n
i n terc ep to r. H o w ev er, th i s w i l l be di ffi c u l t i f yo u rel y o n E J B s w i th c o n tai n er- m an aged tran sac ti o n s. A
tran sac ti o n w i l l be c o m p l eted w h en an E J B m eth o d retu rn s, befo re ren deri n g o f an y v i ew c an start. S ee th e
H i bern ate w ebsi te an d fo ru m fo r ti p s an d ex am p l es rel ati n g to th i s O p e n S e s s ion in V ie w p attern .
1 1 . 1 . 2 . L ong c onv e rs ati ons
T h e sessi o n - p er- req u est p attern i s n o t th e o n l y w ay o f desi gn i n g u n i ts o f w o rk . M an y bu si n ess p ro c esses

req u i re a w h o l e seri es o f i n terac ti o n s w i th th e u ser th at are i n terl eav ed w i th database ac c esses. I n w eb an d
en terp ri se ap p l i c ati o n s, i t i s n o t ac c ep tabl e fo r a database tran sac ti o n to sp an a u ser i n terac ti o n . Co n si der
th e fo l l o w i n g ex am p l e:
T h e fi rst sc reen o f a di al o g o p en s. T h e data seen by th e u ser h as been l o aded i n a p arti c u l ar Ses s io n an d

database tran sac ti o n . T h e u ser i s free to m o di fy th e o bj ec ts.
T h e u ser c l i c k s " S av e" after 5 m i n u tes an d ex p ec ts th ei r m o di fi c ati o n s to be m ade p ersi sten t. T h e u ser
al so ex p ec ts th at th ey w ere th e o n l y p erso n edi ti n g th i s i n fo rm ati o n an d th at n o c o n fl i c ti n g m o di fi c ati o n
h as o c c u rred.
F ro m th e p o i n t o f v i ew o f th e u ser, w e c al l th i s u n i t o f w o rk a l o n g- ru n n i n g c onv e rs ation o r ap p lic ation

trans ac tion. T h ere are m an y w ays to i m p l em en t th i s i n yo u r ap p l i c ati o n .
A fi rst n ai v e i m p l em en tati o n m i gh t k eep th e Ses s io n an d database tran sac ti o n o p en du ri n g u ser th i n k ti m e,

w i th l o c k s h el d i n th e database to p rev en t c o n c u rren t m o di fi c ati o n an d to gu aran tee i so l ati o n an d ato m i c i ty.
T h i s i s an an ti - p attern , si n c e l o c k c o n ten ti o n w o u l d n o t al l o w th e ap p l i c ati o n to sc al e w i th th e n u m ber o f
c o n c u rren t u sers.
Y o u h av e to u se sev eral database tran sac ti o n s to i m p l em en t th e c o n v ersati o n . I n th i s c ase, m ai n tai n i n g
1 3 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
i so l ati o n o f bu si n ess p ro c esses bec o m es th e p arti al resp o n si bi l i ty o f th e ap p l i c ati o n ti er. A si n gl e c o n v ersati o n

u su al l y sp an s sev eral database tran sac ti o n s. I t w i l l be ato m i c i f o n l y o n e o f th ese database tran sac ti o n s (th e
l ast o n e) sto res th e u p dated data. A l l o th ers si m p l y read data (fo r ex am p l e, i n a w i z ard- styl e di al o g sp an n i n g
sev eral req u est/resp o n se c yc l es). T h i s i s easi er to i m p l em en t th an i t m i gh t so u n d, esp ec i al l y i f yo u u ti l i z e
so m e o f H i bern ate' s featu res:
A utom atic V e rs ioning : H i bern ate c an p erfo rm au to m ati c o p ti m i sti c c o n c u rren c y c o n tro l fo r yo u . I t c an
au to m ati c al l y detec t i f a c o n c u rren t m o di fi c ati o n o c c u rred du ri n g u ser th i n k ti m e. Ch ec k fo r th i s at th e
en d o f th e c o n v ersati o n .
D e tac h e d O b j e c ts : i f yo u dec i de to u se th e s e s s ion- p e r- re q ue s t p attern , al l l o aded i n stan c es w i l l be i n th e
detac h ed state du ri n g u ser th i n k ti m e. H i bern ate al l o w s yo u to reattac h th e o bj ec ts an d p ersi st th e
m o di fi c ati o n s. T h e p attern i s c al l ed s e s s ion- p e r- re q ue s t- w ith - d e tac h e d - ob j e c ts . A u to m ati c v ersi o n i n g i s
u sed to i so l ate c o n c u rren t m o di fi c ati o n s.
E x te nd e d ( or L ong ) S e s s ion: th e H i bern ate Ses s io n c an be di sc o n n ec ted fro m th e u n derl yi n g J D B C

c o n n ec ti o n after th e database tran sac ti o n h as been c o m m i tted an d rec o n n ec ted w h en a n ew c l i en t
req u est o c c u rs. T h i s p attern i s k n o w n as s e s s ion- p e r- c onv e rs ation an d m ak es ev en reattac h m en t
u n n ec essary. A u to m ati c v ersi o n i n g i s u sed to i so l ate c o n c u rren t m o di fi c ati o n s an d th e Ses s io n w i l l n o t be
al l o w ed to be fl u sh ed au to m ati c al l y, bu t ex p l i c i tl y.
B o th s e s s ion- p e r- re q ue s t- w ith - d e tac h e d - ob j e c ts an d s e s s ion- p e r- c onv e rs ation h av e adv an tages an d

di sadv an tages. T h ese di sadv an tages are di sc u ssed l ater i n th i s c h ap ter i n th e c o n tex t o f o p ti m i sti c
c o n c u rren c y c o n tro l .
1 1 . 1 . 3 . C ons i d e ri ng ob j e c t i d e nti ty
A n ap p l i c ati o n c an c o n c u rren tl y ac c ess th e sam e p ersi sten t state i n tw o di fferen t Ses s io ns. H o w ev er, an
i n stan c e o f a p ersi sten t c l ass i s n ev er sh ared betw een tw o Ses s io n i n stan c es. I t i s fo r th i s reaso n th at th ere
are tw o di fferen t n o ti o n s o f i den ti ty:
D atabase I den ti ty
f o o . getI d( ). eq u al s ( b ar. getI d( ) )
J V M I den ti ty
f o o ==b ar
F o r o bj ec ts attac h ed to a p artic ular Ses s io n (i .e., i n th e sc o p e o f a Ses s io n), th e tw o n o ti o n s are eq u i v al en t

an d J V M i den ti ty fo r database i den ti ty i s gu aran teed by H i bern ate. W h i l e th e ap p l i c ati o n m i gh t c o n c u rren tl y
ac c ess th e " sam e" (p ersi sten t i den ti ty) bu si n ess o bj ec t i n tw o di fferen t sessi o n s, th e tw o i n stan c es w i l l
ac tu al l y be " di fferen t" (J V M i den ti ty). Co n fl i c ts are reso l v ed u si n g an o p ti m i sti c ap p ro ac h an d au to m ati c
v ersi o n i n g at fl u sh /c o m m i t ti m e.
T h i s ap p ro ac h l eav es H i bern ate an d th e database to w o rry abo u t c o n c u rren c y. I t al so p ro v i des th e best

sc al abi l i ty, si n c e gu aran teei n g i den ti ty i n si n gl e- th readed u n i ts o f w o rk m ean s th at i t do es n o t n eed
ex p en si v e l o c k i n g o r o th er m ean s o f syn c h ro n i z ati o n . T h e ap p l i c ati o n do es n o t n eed to syn c h ro n i z e o n an y
bu si n ess o bj ec t, as l o n g as i t m ai n tai n s a si n gl e th read p er Ses s io n. W i th i n a Ses s io n th e ap p l i c ati o n c an safel y
u se == to c o m p are o bj ec ts.
H o w ev er, an ap p l i c ati o n th at u ses == o u tsi de o f a Ses s io n m i gh t p ro du c e u n ex p ec ted resu l ts. T h i s m i gh t

o c c u r ev en in so m e u n ex p ec ted p l ac es. F o r ex am p l e, i f yo u p u t tw o detac h ed i n stan c es i n to th e sam e Set ,
bo th m i gh t h av e th e sam e database i den ti ty (i .e., th ey rep resen t th e sam e ro w ). J V M i den ti ty, h o w ev er, i s
by defi n i ti o n n o t gu aran teed fo r i n stan c es i n a detac h ed state. T h e dev el o p er h as to o v erri de th e eq u al s ( ) an d
h as h C o de( ) m eth o ds i n p ersi sten t c l asses an d i m p l em en t th ei r o w n n o ti o n o f o bj ec t eq u al i ty. T h ere i s o n e
c av eat: n ev er u se th e database i den ti fi er to i m p l em en t eq u al i ty. U se a bu si n ess k ey th at i s a c o m bi n ati o n o f
u n i q u e, u su al l y i m m u tabl e, attri bu tes. T h e database i den ti fi er w i l l c h an ge i f a tran si en t o bj ec t i s m ade
p ersi sten t. I f th e tran si en t i n stan c e (u su al l y to geth er w i th detac h ed i n stan c es) i s h el d i n a Set , c h an gi n g th e
h ash c o de break s th e c o n trac t o f th e Set . A ttri bu tes fo r bu si n ess k eys do n o t h av e to be as stabl e as database
p ri m ary k eys; yo u o n l y h av e to gu aran tee stabi l i ty as l o n g as th e o bj ec ts are i n th e sam e Set . S ee th e
H i bern ate w ebsi te fo r a m o re th o ro u gh di sc u ssi o n o f th i s i ssu e. P l ease n o te th at th i s i s n o t a H i bern ate i ssu e,
bu t si m p l y h o w J av a o bj ec t i den ti ty an d eq u al i ty h as to be i m p l em en ted.
1 3 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 1 . 1 . 4 . C ommon i s s u e s
D o n o t u se th e an ti - p attern s s e s s ion- p e r- us e r- s e s s ion o r s e s s ion- p e r- ap p lic ation (th ere are, h o w ev er, rare
ex c ep ti o n s to th i s ru l e). S o m e o f th e fo l l o w i n g i ssu es m i gh t al so ari se w i th i n th e rec o m m en ded p attern s, so
en su re th at yo u u n derstan d th e i m p l i c ati o n s befo re m ak i n g a desi gn dec i si o n :
A Ses s io n i s n o t th readsafe. T h i n gs th at w o rk c o n c u rren tl y, l i k e H T T P req u ests, sessi o n bean s, o r S w i n g

w o rk ers, w i l l c au se rac e c o n di ti o n s i f a Ses s io n i n stan c e i s sh ared. I f yo u k eep yo u r H i bern ate Ses s io n i n
yo u r H ttpSes s io n (th i s i s di sc u ssed l ater i n th e c h ap ter), yo u sh o u l d c o n si der syn c h ro n i z i n g ac c ess to yo u r
H ttp sessi o n . O th erw i se, a u ser th at c l i c k s rel o ad fast en o u gh c an u se th e sam e Ses s io n i n tw o
c o n c u rren tl y ru n n i n g th reads.
A n ex c ep ti o n th ro w n by H i bern ate m ean s yo u h av e to ro l l bac k yo u r database tran sac ti o n an d c l o se th e
Ses s io n i m m edi atel y (th i s i s di sc u ssed i n m o re detai l l ater i n th e c h ap ter). I f yo u r Ses s io n i s bo u n d to th e
ap p l i c ati o n , yo u h av e to sto p th e ap p l i c ati o n . R o l l i n g bac k th e database tran sac ti o n do es n o t p u t yo u r
bu si n ess o bj ec ts bac k i n to th e state th ey w ere at th e start o f th e tran sac ti o n . T h i s m ean s th at th e
database state an d th e bu si n ess o bj ec ts w i l l be o u t o f syn c . U su al l y th i s i s n o t a p ro bl em , bec au se
ex c ep ti o n s are n o t rec o v erabl e an d yo u w i l l h av e to start o v er after ro l l bac k an yw ay.
T h e Ses s io n c ac h es ev ery o bj ec t th at i s i n a p ersi sten t state (w atc h ed an d c h ec k ed fo r di rty state by
H i bern ate). I f yo u k eep i t o p en fo r a l o n g ti m e o r si m p l y l o ad to o m u c h data, i t w i l l gro w en dl essl y u n ti l
yo u get an O u tO fM em o ryE x c ep ti o n . O n e so l u ti o n i s to c al l cl ear( ) an d ev ict( ) to m an age th e Ses s io n c ac h e,
bu t yo u sh o u l d c o n si der a S to red P ro c edu re i f yo u n eed m ass data o p erati o n s. S o m e so l u ti o n s are sh o w n
i n Ch ap ter 1 3 , B atc h p roc e s s ing . K eep i n g a Ses s io n o p en fo r th e du rati o n o f a u ser sessi o n al so m ean s a
h i gh er p ro babi l i ty o f stal e data.
1 1 . 2 . Databas e trans action d emarcation

D atabase, o r system , tran sac ti o n bo u n dari es are al w ays n ec essary. N o c o m m u n i c ati o n w i th th e database c an
o c c u r o u tsi de o f a database tran sac ti o n (th i s seem s to c o n fu se m an y dev el o p ers w h o are u sed to th e
au to - c o m m i t m o de). A l w ays u se c l ear tran sac ti o n bo u n dari es, ev en fo r read- o n l y o p erati o n s. D ep en di n g o n
yo u r i so l ati o n l ev el an d database c ap abi l i ti es th i s m i gh t n o t be req u i red, bu t th ere i s n o do w n si de i f yo u
al w ays dem arc ate tran sac ti o n s ex p l i c i tl y. Certai n l y, a si n gl e database tran sac ti o n i s go i n g to p erfo rm better
th an m an y sm al l tran sac ti o n s, ev en fo r readi n g data.
A H i bern ate ap p l i c ati o n c an ru n in n o n - m an aged (i .e., stan dal o n e, si m p l e W eb- o r S w i n g ap p l i c ati o n s) an d

m an aged J 2E E en v i ro n m en ts. I n a n o n - m an aged en v i ro n m en t, H i bern ate i s u su al l y resp o n si bl e fo r i ts o w n
database c o n n ec ti o n p o o l . T h e ap p l i c ati o n dev el o p er h as to m an u al l y set tran sac ti o n bo u n dari es (begi n ,
c o m m i t, o r ro l l bac k database tran sac ti o n s) th em sel v es. A m an aged en v i ro n m en t u su al l y p ro v i des c o n tai n er-
m an aged tran sac ti o n s (CM T ), w i th th e tran sac ti o n assem bl y defi n ed dec l arati v el y (i n dep l o ym en t desc ri p to rs
o f E J B sessi o n bean s, fo r ex am p l e). P ro gram m ati c tran sac ti o n dem arc ati o n i s th en n o l o n ger n ec essary.
H o w ev er, i t i s o ften desi rabl e to k eep yo u r p ersi sten c e l ayer p o rtabl e betw een n o n - m an aged reso u rc e- l o c al
en v i ro n m en ts, an d system s th at c an rel y o n J T A bu t u se B M T i n stead o f CM T . I n bo th c ases u se
p ro gram m ati c tran sac ti o n dem arc ati o n . H i bern ate o ffers a w rap p er A P I c al l ed T rans actio n th at tran sl ates i n to
th e n ati v e tran sac ti o n system o f yo u r dep l o ym en t en v i ro n m en t. T h i s A P I i s ac tu al l y o p ti o n al , bu t w e stro n gl y
en c o u rage i ts u se u n l ess yo u are i n a CM T sessi o n bean .
E n di n g a Ses s io n u su al l y i n v o l v es fo u r di sti n c t p h ases:
fl u sh th e sessi o n
c o m m i t th e tran sac ti o n
c l o se th e sessi o n
h an dl e ex c ep ti o n s
W e di sc u ssed F l u sh i n g th e sessi o n earl i er, so w e w i l l n o w h av e a c l o ser l o o k at tran sac ti o n dem arc ati o n an d
ex c ep ti o n h an dl i n g i n bo th m an aged an d n o n - m an aged en v i ro n m en ts.
1 1 . 2 . 1 . N on- manag e d e nv i ronme nt
1 3 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I f a H i bern ate p ersi sten c e l ayer ru n s i n a n o n - m an aged en v i ro n m en t, database c o n n ec ti o n s are u su al l y

h an dl ed by si m p l e (i .e., n o n - D ataS o u rc e) c o n n ec ti o n p o o l s fro m w h i c h H i bern ate o btai n s c o n n ec ti o n s as
n eeded. T h e sessi o n /tran sac ti o n h an dl i n g i di o m l o o k s l i k e th i s:
/ / No n- managed env iro nment idio m

Ses s io n s es s = f acto ry. o penSes s io n( );
T rans actio n tx = nu l l ;
try {
tx = s es s . b eginT rans actio n( );
/ / do s o me w o rk
...
tx . co mmit( );
}
catch ( R u ntimeE x ceptio n e) {
if ( tx ! = nu l l ) tx . ro l l b ack ( );
th ro w e; / / o r dis pl ay erro r mes s age
}
f inal l y {
}
Y o u do n o t h av e to f l u s h ( ) th e Ses s io n ex p l i c i tl y: th e c al l to co mmit( ) au to m ati c al l y tri ggers th e syn c h ro n i z ati o n

dep en di n g o n th e F l u sh M o de fo r th e sessi o n . A c al l to cl o s e( ) m ark s th e en d o f a sessi o n . T h e m ai n i m p l i c ati o n
o f cl o s e( ) i s th at th e J D B C c o n n ec ti o n w i l l be rel i n q u i sh ed by th e sessi o n . T h i s J av a c o de i s p o rtabl e an d ru n s
i n bo th n o n - m an aged an d J T A en v i ro n m en ts.
A s o u tl i n ed earl i er, a m u c h m o re fl ex i bl e so l u ti o n i s H i bern ate' s bu i l t- i n " c u rren t sessi o n " c o n tex t

m an agem en t:
/ / No n- managed env iro nment idio m w ith getC u rrentSes s io n( )

try {
f acto ry. getC u rrentSes s io n( ). b eginT rans actio n( );
...
f acto ry. getC u rrentSes s io n( ). getT rans actio n( ). co mmit( );

}
f acto ry. getC u rrentSes s io n( ). getT rans actio n( ). ro l l b ack ( );
}
Y o u w i l l n o t see th ese c o de sn i p p ets i n a regu l ar ap p l i c ati o n ; fatal (system ) ex c ep ti o n s sh o u l d al w ays be

c au gh t at th e " to p " . I n o th er w o rds, th e c o de th at ex ec u tes H i bern ate c al l s i n th e p ersi sten c e l ayer, an d th e
c o de th at h an dl es R u ntimeE x ceptio n (an d u su al l y c an o n l y c l ean u p an d ex i t), are i n di fferen t l ayers. T h e
c u rren t c o n tex t m an agem en t by H i bern ate c an si gn i fi c an tl y si m p l i fy th i s desi gn by ac c essi n g a Ses s io nF acto ry.
E x c ep ti o n h an dl i n g i s di sc u ssed l ater i n th i s c h ap ter.
Y o u sh o u l d sel ec t o rg. h ib ernate. trans actio n. J D B C T rans actio nF acto ry, w h i c h i s th e defau l t, an d fo r th e sec o n d
ex am p l e sel ec t " th read" as yo u r h ib ernate. cu rrent_ s es s io n_ co ntex t_ cl as s .
1 1 . 2 . 2 . U s i ng J T A
I f yo u r p ersi sten c e l ayer ru n s i n an ap p l i c ati o n serv er (fo r ex am p l e, beh i n d E J B sessi o n bean s), ev ery
dataso u rc e c o n n ec ti o n o btai n ed by H i bern ate w i l l au to m ati c al l y be p art o f th e gl o bal J T A tran sac ti o n . Y o u c an
al so i n stal l a stan dal o n e J T A i m p l em en tati o n an d u se i t w i th o u t E J B . H i bern ate o ffers tw o strategi es fo r J T A
i n tegrati o n .
1 3 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I f yo u u se bean - m an aged tran sac ti o n s (B M T ), H i bern ate w i l l tel l th e ap p l i c ati o n serv er to start an d en d a
B M T tran sac ti o n i f yo u u se th e T rans actio n A P I . T h e tran sac ti o n m an agem en t c o de i s i den ti c al to th e
n o n - m an aged en v i ro n m en t.
/ / B M T idio m
try {
tx = s es s . b eginT rans actio n( );
...
tx . co mmit( );
}
if ( tx ! = nu l l ) tx . ro l l b ack ( );
}
f inal l y {
}
I f yo u w an t to u se a tran sac ti o n - bo u n d Ses s io n, th at i s, th e getC u rrentSes s io n( ) fu n c ti o n al i ty fo r easy c o n tex t

p ro p agati o n , u se th e J T A U s erT rans actio n A P I di rec tl y:
/ / B M T idio m w ith getC u rrentSes s io n( )

try {
U s erT rans actio n tx = ( U s erT rans actio n)new I nitial C o ntex t( )
. l o o k u p( " j av a: co mp/ U s erT rans actio n" );
tx . b egin( );
/ / D o s o me w o rk o n Ses s io n b o u nd to trans actio n

f acto ry. getC u rrentSes s io n( ). l o ad( . . . );
f acto ry. getC u rrentSes s io n( ). pers is t( . . . );
tx . co mmit( );
}
tx . ro l l b ack ( );
}
W i th CM T , tran sac ti o n dem arc ati o n is c o m p l eted in sessi o n bean dep l o ym en t desc ri p to rs, n o t
p ro gram m ati c al l y. T h e c o de i s redu c ed to :
/ / C M T idio m
Ses s io n s es s = f acto ry. getC u rrentSes s io n( );
...
I n a CM T /E J B , ev en ro l l bac k h ap p en s au to m ati c al l y. A n u n h an dl ed R u ntimeE x ceptio n th ro w n by a sessi o n bean

m eth o d tel l s th e c o n tai n er to set th e gl o bal tran sac ti o n to ro l l bac k . Y ou d o not ne e d to us e th e H ib e rnate
T rans action A P I at all w ith B M T or C M T, and y ou g e t autom atic p rop ag ation of th e " c urre nt" S e s s ion b ound to
th e trans ac tion.
W h en c o n fi gu ri n g H i bern ate' s tran sac ti o n fac to ry, c h o o se o rg. h ib ernate. trans actio n. J T A T rans actio nF acto ry i f yo u
u se J T A di rec tl y (B M T ), an d o rg. h ib ernate. trans actio n. C M T T rans actio nF acto ry i n a CM T sessi o n bean . R em em ber
to al so set h ib ernate. trans actio n. manager_ l o o k u p_ cl as s . E n su re th at yo u r h ib ernate. cu rrent_ s es s io n_ co ntex t_ cl as s
1 3 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
i s ei th er u n set (bac k w ards c o m p ati bi l i ty), o r i s set to " j ta" .
T h e getC u rrentSes s io n( ) o p erati o n h as o n e do w n si de i n a J T A en v i ro n m en t. T h ere i s o n e c av eat to th e u se o f

af ter_ s tatement c o n n ec ti o n rel ease m o de, w h i c h i s th en u sed by defau l t. D u e to a l i m i tati o n o f th e J T A sp ec , i t
i s n o t p o ssi bl e fo r H i bern ate to au to m ati c al l y c l ean u p an y u n c l o sed Scro l l ab l eR es u l ts o r I terato r i n stan c es
retu rn ed by s cro l l ( ) o r iterate( ). Y o u m us t rel ease th e u n derl yi n g database c u rso r by c al l i n g
Scro l l ab l eR es u l ts . cl o s e( ) o r H ib ernate. cl o s e( I terato r) ex p l i c i tl y fro m a f inal l y bl o c k . M o st ap p l i c ati o n s c an easi l y
av o i d u si n g s cro l l ( ) o r iterate( ) fro m th e J T A o r CM T c o de.)
1 1 . 2 . 3 . E x c e pti on h and l i ng
I f th e Ses s io n th ro w s an ex c ep ti o n , i n c l u di n g an y SQ L E x ceptio n, i m m edi atel y ro l l bac k th e database

tran sac ti o n , c al l Ses s io n. cl o s e( ) an d di sc ard th e Ses s io n i n stan c e. Certai n m eth o ds o f Ses s io n w i l l not l eav e th e
sessi o n i n a c o n si sten t state. N o ex c ep ti o n th ro w n by H i bern ate c an be treated as rec o v erabl e. E n su re th at
th e Ses s io n w i l l be c l o sed by c al l i n g cl o s e( ) i n a f inal l y bl o c k .
T h e H ib ernateE x ceptio n, w h i c h w rap s m o st o f th e erro rs th at c an o c c u r i n a H i bern ate p ersi sten c e l ayer, i s an

u n c h ec k ed ex c ep ti o n . I t w as n o t i n o l der v ersi o n s o f H i bern ate. I n o u r o p i n i o n , w e sh o u l d n o t fo rc e th e
ap p l i c ati o n dev el o p er to c atc h an u n rec o v erabl e ex c ep ti o n at a l o w l ayer. I n m o st system s, u n c h ec k ed an d
fatal ex c ep ti o n s are h an dl ed i n o n e o f th e fi rst fram es o f th e m eth o d c al l stac k (i .e., i n h i gh er l ayers) an d
ei th er an erro r m essage i s p resen ted to th e ap p l i c ati o n u ser o r so m e o th er ap p ro p ri ate ac ti o n i s tak en . N o te
th at H i bern ate m i gh t al so th ro w o th er u n c h ec k ed ex c ep ti o n s th at are n o t a H ib ernateE x ceptio n. T h ese are n o t
rec o v erabl e an d ap p ro p ri ate ac ti o n sh o u l d be tak en .
H i bern ate w rap s SQ L E x ceptio ns th ro w n w h i l e i n terac ti n g w i th th e database i n a J D B C E x ceptio n. I n fac t,

H i bern ate w i l l attem p t to c o n v ert th e ex c ep ti o n i n to a m o re m ean i n gfu l su bc l ass o f J D B C E x ceptio n. T h e
u n derl yi n g SQ L E x ceptio n i s al w ays av ai l abl e v i a J D B C E x ceptio n. getC au s e( ). H i bern ate c o n v erts th e SQ L E x ceptio n
i n to an ap p ro p ri ate J D B C E x ceptio n su bc l ass u si n g th e SQ L E x ceptio nC o nv erter attac h ed to th e Ses s io nF acto ry. B y
defau l t, th e SQ L E x ceptio nC o nv erter i s defi n ed by th e c o n fi gu red di al ec t. H o w ev er, i t i s al so p o ssi bl e to p l u g i n a
c u sto m im p l em en tati o n . S ee th e j av ado c s fo r th e SQ L E x ceptio nC o nv erterF acto ry c l ass fo r detai l s. T h e stan dard
J D B C E x ceptio n su btyp es are:
J D B C C o nnectio nE x ceptio n: i n di c ates an erro r w i th th e u n derl yi n g J D B C c o m m u n i c ati o n .
SQ L G rammarE x ceptio n: i n di c ates a gram m ar o r syn tax p ro bl em w i th th e i ssu ed S Q L .
C o ns traintV io l atio nE x ceptio n: i n di c ates so m e fo rm o f i n tegri ty c o n strai n t v i o l ati o n .
L o ck A cq u is itio nE x ceptio n: i n di c ates an erro r ac q u i ri n g a l o c k l ev el n ec essary to p erfo rm th e req u ested

o p erati o n .
G enericJ D B C E x ceptio n: a gen eri c ex c ep ti o n w h i c h di d n o t fal l i n to an y o f th e o th er c atego ri es.
1 1 . 2 . 4 . T rans ac ti on ti me ou t
A n i m p o rtan t featu re p ro v i ded by a m an aged en v i ro n m en t l i k e E J B , th at i s n ev er p ro v i ded fo r n o n - m an aged

c o de, i s tran sac ti o n ti m eo u t. T ran sac ti o n ti m eo u ts en su re th at n o m i sbeh av i n g tran sac ti o n c an i n defi n i tel y ti e
u p reso u rc es w h i l e retu rn i n g n o resp o n se to th e u ser. O u tsi de a m an aged (J T A ) en v i ro n m en t, H i bern ate
c an n o t fu l l y p ro v i de th i s fu n c ti o n al i ty. H o w ev er, H i bern ate c an at l east c o n tro l data ac c ess o p erati o n s,
en su ri n g th at database l ev el deadl o c k s an d q u eri es w i th h u ge resu l t sets are l i m i ted by a defi n ed ti m eo u t. I n
a m an aged en v i ro n m en t, H i bern ate c an del egate tran sac ti o n ti m eo u t to J T A . T h i s fu n c ti o n al i ty i s abstrac ted
by th e H i bern ate T rans actio n o bj ec t.
1 4 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

try {
/ / s et trans actio n timeo u t to 3 s eco nds
s es s . getT rans actio n( ). s etT imeo u t( 3);
s es s . getT rans actio n( ). b egin( );
...
s es s . getT rans actio n( ). co mmit( )

}
s es s . getT rans actio n( ). ro l l b ack ( );
}
f inal l y {
}
s etT imeo u t( ) c an n o t be c al l ed i n a CM T bean , w h ere tran sac ti o n ti m eo u ts m u st be defi n ed dec l arati v el y.
1 1 . 3 . O p timis tic concurrency control

T h e o n l y ap p ro ac h th at i s c o n si sten t w i th h i gh c o n c u rren c y an d h i gh sc al abi l i ty, i s o p ti m i sti c c o n c u rren c y
c o n tro l w i th v ersi o n i n g. V ersi o n c h ec k i n g u ses v ersi o n n u m bers, o r ti m estam p s, to detec t c o n fl i c ti n g u p dates
an d to p rev en t l o st u p dates. H i bern ate p ro v i des th ree p o ssi bl e ap p ro ac h es to w ri ti n g ap p l i c ati o n c o de th at
u ses o p ti m i sti c c o n c u rren c y. T h e u se c ases w e di sc u ss are i n th e c o n tex t o f l o n g c o n v ersati o n s, bu t v ersi o n
c h ec k i n g al so h as th e ben efi t o f p rev en ti n g l o st u p dates i n si n gl e database tran sac ti o n s.
1 1 . 3 . 1 . A ppl i c ati on v e rs i on c h e c k i ng
I n an i m p l em en tati o n w i th o u t m u c h h el p fro m H i bern ate, eac h i n terac ti o n w i th th e database o c c u rs i n a n ew

Ses s io n an d th e dev el o p er i s resp o n si bl e fo r rel o adi n g al l p ersi sten t i n stan c es fro m th e database befo re
m an i p u l ati n g th em . T h e ap p l i c ati o n i s fo rc ed to c arry o u t i ts o w n v ersi o n c h ec k i n g to en su re c o n v ersati o n
tran sac ti o n i so l ati o n . T h i s ap p ro ac h i s th e l east effi c i en t i n term s o f database ac c ess. I t i s th e ap p ro ac h m o st
si m i l ar to en ti ty E J B s.
/ / fo o is an ins tance l o aded b y a prev io u s Ses s io n

s es s io n = f acto ry. o penSes s io n( );
T rans actio n t = s es s io n. b eginT rans actio n( );
int o l dV ers io n = f o o . getV ers io n( );

s es s io n. l o ad( f o o , f o o . getK ey( ) ); / / l o ad th e cu rrent s tate
if ( o l dV ers io n ! = f o o . getV ers io n( ) ) th ro w new Stal eO b j ectStateE x ceptio n( );
f o o . s etP ro perty( " b ar" );
t. co mmit( );
s es s io n. cl o s e( );
T h e v ers io n p ro p erty i s m ap p ed u si n g < v ers io n>, an d H i bern ate w i l l au to m ati c al l y i n c rem en t i t du ri n g fl u sh i f

th e en ti ty i s di rty.
I f yo u are o p erati n g i n a l o w - data- c o n c u rren c y en v i ro n m en t, an d do n o t req u i re v ersi o n c h ec k i n g, yo u c an

u se th i s ap p ro ac h an d sk i p th e v ersi o n c h ec k . I n th i s c ase, las t c om m it w ins i s th e defau l t strategy fo r l o n g
c o n v ersati o n s. B e aw are th at th i s m i gh t c o n fu se th e u sers o f th e ap p l i c ati o n , as th ey m i gh t ex p eri en c e l o st
u p dates w i th o u t erro r m essages o r a c h an c e to m erge c o n fl i c ti n g c h an ges.
M an u al v ersi o n c h ec k i n g i s o n l y feasi bl e i n tri v i al c i rc u m stan c es an d n o t p rac ti c al fo r m o st ap p l i c ati o n s. O ften

n o t o n l y si n gl e i n stan c es, bu t c o m p l ete grap h s o f m o di fi ed o bj ec ts, h av e to be c h ec k ed. H i bern ate o ffers
1 4 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
au to m ati c v ersi o n c h ec k i n g w i th ei th er an ex ten ded Ses s io n o r detac h ed i n stan c es as th e desi gn p aradi gm .
1 1 . 3 . 2 . E x te nd e d s e s s i on and au tomati c v e rs i oni ng
A si n gl e Ses s io n i n stan c e an d i ts p ersi sten t i n stan c es th at are u sed fo r th e w h o l e c o n v ersati o n are k n o w n as

s e s s ion- p e r- c onv e rs ation. H i bern ate c h ec k s i n stan c e v ersi o n s at fl u sh ti m e, th ro w i n g an ex c ep ti o n i f
c o n c u rren t m o di fi c ati o n i s detec ted. I t i s u p to th e dev el o p er to c atc h an d h an dl e th i s ex c ep ti o n . Co m m o n
o p ti o n s are th e o p p o rtu n i ty fo r th e u ser to m erge c h an ges o r to restart th e bu si n ess c o n v ersati o n w i th
n o n - stal e data.
T h e Ses s io n i s di sc o n n ec ted fro m an y u n derl yi n g J D B C c o n n ec ti o n w h en w ai ti n g fo r u ser i n terac ti o n . T h i s

ap p ro ac h i s th e m o st effi c i en t i n term s o f database ac c ess. T h e ap p l i c ati o n do es n o t v ersi o n c h ec k o r reattac h
detac h ed i n stan c es, n o r do es i t h av e to rel o ad i n stan c es i n ev ery database tran sac ti o n .
/ / fo o is an ins tance l o aded earl ier b y th e o l d s es s io n

T rans actio n t = s es s io n. b eginT rans actio n( ); / / O b tain a new J D B C co nnectio n, s tart trans actio n
s es s io n. f l u s h ( ); / / O nl y f o r l as t trans actio n in co nv ers atio n

t. co mmit( ); / / A ls o retu rn J D B C co nnectio n
s es s io n. cl o s e( ); / / O nl y f o r l as t trans actio n in co nv ers atio n
T h e f o o o bj ec t k n o w s w h i c h Ses s io n i t w as l o aded i n . B egi n n i n g a n ew database tran sac ti o n o n an o l d sessi o n

o btai n s a n ew c o n n ec ti o n an d resu m es th e sessi o n . Co m m i tti n g a database tran sac ti o n di sc o n n ec ts a sessi o n
fro m th e J D B C c o n n ec ti o n an d retu rn s th e c o n n ec ti o n to th e p o o l . A fter rec o n n ec ti o n , to fo rc e a v ersi o n c h ec k
o n data yo u are n o t u p dati n g, yo u c an c al l Ses s io n. l o ck ( ) w i th L o ck M o de. R E A D o n an y o bj ec ts th at m i gh t h av e
been u p dated by an o th er tran sac ti o n . Y o u do n o t n eed to l o c k an y data th at yo u are u p dati n g. U su al l y yo u
w o u l d set F l u s h M o de. M A NU A L o n an ex ten ded Ses s io n, so th at o n l y th e l ast database tran sac ti o n c yc l e i s
al l o w ed to ac tu al l y p ersi st al l m o di fi c ati o n s m ade i n th i s c o n v ersati o n . O n l y th i s l ast database tran sac ti o n w i l l
i n c l u de th e f l u s h ( ) o p erati o n , an d th en cl o s e( ) th e sessi o n to en d th e c o n v ersati o n .
T h i s p attern i s p ro bl em ati c i f th e Ses s io n i s to o bi g to be sto red du ri n g u ser th i n k ti m e (fo r ex am p l e, an

H ttpSes s io n sh o u l d be k ep t as sm al l as p o ssi bl e). A s th e Ses s io n i s al so th e fi rst- l ev el c ac h e an d c o n tai n s al l
l o aded o bj ec ts, w e c an p ro babl y u se th i s strategy o n l y fo r a few req u est/resp o n se c yc l es. U se a Ses s io n o n l y
fo r a si n gl e c o n v ersati o n as i t w i l l so o n h av e stal e data.
N ote
E arl i er v ersi o n s o f H i bern ate req u i red ex p l i c i t di sc o n n ec ti o n an d rec o n n ec ti o n o f a Ses s io n.
T h ese m eth o ds are dep rec ated, as begi n n i n g an d en di n g a tran sac ti o n h as th e sam e effec t.
K eep th e di sc o n n ec ted Ses s io n c l o se to th e p ersi sten c e l ayer. U se an E J B statefu l sessi o n bean to h o l d th e

Ses s io n i n a th ree- ti er en v i ro n m en t. D o n o t tran sfer i t to th e w eb l ayer, o r ev en seri al i z e i t to a sep arate ti er,
to sto re i t i n th e H ttpSes s io n.
T h e ex ten ded sessi o n p attern , o r s e s s ion- p e r- c onv e rs ation, i s m o re di ffi c u l t to i m p l em en t w i th au to m ati c

c u rren t sessi o n c o n tex t m an agem en t. Y o u n eed to su p p l y yo u r o w n i m p l em en tati o n o f th e
C u rrentSes s io nC o ntex t fo r th i s. S ee th e H i bern ate W i k i fo r ex am p l es.
1 1 . 3 . 3 . D e tac h e d ob j e c ts and au tomati c v e rs i oni ng
E ac h i n terac ti o n w i th th e p ersi sten t sto re o c c u rs i n a n ew Ses s io n. H o w ev er, th e sam e p ersi sten t i n stan c es
are reu sed fo r eac h i n terac ti o n w i th th e database. T h e ap p l i c ati o n m an i p u l ates th e state o f detac h ed
i n stan c es o ri gi n al l y l o aded i n an o th er Ses s io n an d th en reattac h es th em u si n g Ses s io n. u pdate( ),
Ses s io n. s av eO rU pdate( ), o r Ses s io n. merge( ).
1 4 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
/ / fo o is an ins tance l o aded b y a prev io u s Ses s io n

s es s io n = f acto ry. o penSes s io n( );
T rans actio n t = s es s io n. b eginT rans actio n( );
s es s io n. s av eO rU pdate( f o o ); / / U s e merge( ) if " f o o " migh t h av e b een l o aded al ready
t. co mmit( );
A gai n , H i bern ate w i l l c h ec k i n stan c e v ersi o n s du ri n g fl u sh , th ro w i n g an ex c ep ti o n i f c o n fl i c ti n g u p dates

o c c u rred.
Y o u c an al so c al l l o ck ( ) i n stead o f u pdate( ), an d u se L o ck M o de. R E A D (p erfo rm i n g a v ersi o n c h ec k an d byp assi n g

al l c ac h es) i f yo u are su re th at th e o bj ec t h as n o t been m o di fi ed.
1 1 . 3 . 4 . C u s tomi z i ng au tomati c v e rs i oni ng
Y o u c an di sabl e H i bern ate' s au to m ati c v ersi o n i n c rem en t fo r p arti c u l ar p ro p erti es an d c o l l ec ti o n s by setti n g

th e o ptimis tic- l o ck m ap p i n g attri bu te to f al s e. H i bern ate w i l l th en n o l o n ger i n c rem en t v ersi o n s i f th e p ro p erty
i s di rty.
L egac y database sc h em as are o ften stati c an d c an n o t be m o di fi ed. O r, o th er ap p l i c ati o n s m i gh t ac c ess th e

sam e database an d w i l l n o t k n o w h o w to h an dl e v ersi o n n u m bers o r ev en ti m estam p s. I n bo th c ases,
v ersi o n i n g c an n o t rel y o n a p arti c u l ar c o l u m n i n a tabl e. T o fo rc e a v ersi o n c h ec k w i th a c o m p ari so n o f th e
state o f al l fi el ds i n a ro w bu t w i th o u t a v ersi o n o r ti m estam p p ro p erty m ap p in g, tu rn o n o ptimis tic- l o ck =" al l "
in th e < cl as s > m ap p i n g. T h i s c o n c ep tu al l y o n l y w o rk s i f H i bern ate c an c o m p are th e o l d an d th e n ew state
(i .e., i f yo u u se a si n gl e l o n g Ses s io n an d n o t sessi o n - p er- req u est- w i th - detac h ed- o bj ec ts).
Co n c u rren t m o di fi c ati o n c an be p erm i tted i n i n stan c es w h ere th e c h an ges th at h av e been m ade do n o t

o v erl ap . I f yo u set o ptimis tic- l o ck =" dirty" w h en m ap p i n g th e < cl as s >, H i bern ate w i l l o n l y c o m p are di rty fi el ds
du ri n g fl u sh .
I n bo th c ases, w i th dedi c ated v ersi o n /ti m estam p c o l u m n s o r w i th a fu l l /di rty fi el d c o m p ari so n , H i bern ate
u ses a si n gl e U P D A T E statem en t, w i th an ap p ro p ri ate W H E R E c l au se, p er en ti ty to ex ec u te th e v ersi o n c h ec k
an d u p date th e i n fo rm ati o n . I f yo u u se tran si ti v e p ersi sten c e to c asc ade reattac h m en t to asso c i ated en ti ti es,
H i bern ate m ay ex ec u te u n n ec essary u p dates. T h i s i s u su al l y n o t a p ro bl em , bu t on up d ate tri ggers i n th e
database m i gh t be ex ec u ted ev en w h en n o c h an ges h av e been m ade to detac h ed i n stan c es. Y o u c an
c u sto m i z e th i s beh av i o r by setti n g s el ect- b ef o re- u pdate=" tru e" i n th e < cl as s > m ap p i n g, fo rc i n g H i bern ate to
SE L E C T th e i n stan c e to en su re th at c h an ges di d o c c u r befo re u p dati n g th e ro w .
1 1 . 4 . P es s imis tic l ock ing

I t i s n o t i n ten ded th at u sers sp en d m u c h ti m e w o rryi n g abo u t l o c k i n g strategi es. I t i s u su al l y en o u gh to
sp ec i fy an i so l ati o n l ev el fo r th e J D B C c o n n ec ti o n s an d th en si m p l y l et th e database do al l th e w o rk .
H o w ev er, adv an c ed u sers m ay w i sh to o btai n ex c l u si v e p essi m i sti c l o c k s o r re- o btai n l o c k s at th e start o f a
n ew tran sac ti o n .
H i bern ate w i l l al w ays u se th e l o c k i n g m ec h an i sm o f th e database; i t n ev er l o c k o bj ec ts i n m em o ry.
T h e L o ck M o de c l ass defi n es th e di fferen t l o c k l ev el s th at c an be ac q u i red by H i bern ate. A l o c k i s o btai n ed by

th e fo l l o w i n g m ec h an i sm s:
L o ck M o de. W R I T E i s ac q u i red au to m ati c al l y w h en H i bern ate u p dates o r i n serts a ro w .
L o ck M o de. U P G R A D E c an be ac q u i red u p o n ex p l i c i t u ser req u est u si n g SE L E C T ... F O R U P D A T E o n databases

w h i c h su p p o rt th at syn tax .
L o ck M o de. U P G R A D E _ NO W A I T c an be ac q u i red u p o n ex p l i c i t u ser req u est u si n g a
SE L E C T ... F O R U P D A T E NO W A I T u n der O rac l e.
L o ck M o de. R E A D i s ac q u i red au to m ati c al l y w h en H i bern ate reads data u n der R ep eatabl e R ead o r
S eri al i z abl e i so l ati o n l ev el . I t c an be reac q u i red by ex p l i c i t u ser req u est.
L o ck M o de. NO NE rep resen ts th e absen c e o f a l o c k . A l l o bj ec ts sw i tc h to th i s l o c k m o de at th e en d o f a
1 4 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T rans actio n. O bj ec ts asso c i ated w i th th e sessi o n v i a a c al l to u pdate( ) o r s av eO rU pdate( ) al so start o u t i n

th i s l o c k m o de.
T h e " ex p l i c i t u ser req u est" i s ex p ressed i n o n e o f th e fo l l o w i n g w ays:
A c al l to Ses s io n. l o ad( ), sp ec i fyi n g a L o ck M o de .
A c al l to Ses s io n. l o ck ( ).
A c al l to Q u ery. s etL o ck M o de( ).
I f Ses s io n. l o ad( ) i s c al l ed w i th U P G R A D E o r U P G R A D E _ NO W A I T , an d th e req u ested o bj ec t w as n o t yet l o aded by

th e sessi o n , th e o bj ec t i s l o aded u si n g SE L E C T . . . F O R U P D A T E . I f l o ad( ) i s c al l ed fo r an o bj ec t th at i s al ready
l o aded w i th a l ess restri c ti v e l o c k th an th e o n e req u ested, H i bern ate c al l s l o ck ( ) fo r th at o bj ec t.
Ses s io n. l o ck ( ) p erfo rm s a v ersi o n n u m ber c h ec k i f th e sp ec i fi ed l o c k m o de i s R E A D , U P G R A D E o r

U P G R A D E _ NO W A I T .I n th e c ase o f U P G R A D E o r U P G R A D E _ NO W A I T , SE L E C T . . . F O R U P D A T E i s u sed.
I f th e req u ested l o c k m o de i s n o t su p p o rted by th e database, H i bern ate u ses an ap p ro p ri ate al tern ate m o de
i n stead o f th ro w i n g an ex c ep ti o n . T h i s en su res th at ap p l i c ati o n s are p o rtabl e.
1 1 . 5 . C onnection rel eas e mod es

O n e o f th e l egac i es o f H i bern ate 2.x J D B C c o n n ec ti o n m an agem en t m ean t th at a Ses s io n w o u l d o btai n a
c o n n ec ti o n w h en i t w as fi rst req u i red an d th en m ai n tai n th at c o n n ec ti o n u n ti l th e sessi o n w as c l o sed.
H i bern ate 3 .x i n tro du c ed th e n o ti o n o f c o n n ec ti o n rel ease m o des th at w o u l d i n stru c t a sessi o n h o w to h an dl e
i ts J D B C c o n n ec ti o n s. T h e fo l l o w i n g di sc u ssi o n i s p erti n en t o n l y to c o n n ec ti o n s p ro v i ded th ro u gh a c o n fi gu red
C o nnectio nP ro v ider. U ser- su p p l i ed c o n n ec ti o n s are o u tsi de th e breadth o f th i s di sc u ssi o n . T h e di fferen t rel ease
m o des are i den ti fi ed by th e en u m erated v al u es o f o rg. h ib ernate. C o nnectio nR el eas eM o de :
O N_ C L O SE : i s th e l egac y beh av i o r desc ri bed abo v e. T h e H i bern ate sessi o n o btai n s a c o n n ec ti o n w h en it

fi rst n eeds to p erfo rm so m e J D B C ac c ess an d m ai n tai n s th at c o n n ec ti o n u n ti l th e sessi o n i s c l o sed.
A F T E R _ T R A NSA C T I O N: rel eases c o n n ec ti o n s after a o rg. h ib ernate. T rans actio n h as been c o m p l eted.
A F T E R _ ST A T E M E NT (al so referred to as aggressi v e rel ease): rel eases c o n n ec ti o n s after ev ery statem en t
ex ec u ti o n . T h i s aggressi v e rel easi n g i s sk i p p ed i f th at statem en t l eav es o p en reso u rc es asso c i ated w i th
th e gi v en sessi o n . Cu rren tl y th e o n l y si tu ati o n w h ere th i s o c c u rs i s th ro u gh th e u se o f
o rg. h ib ernate. Scro l l ab l eR es u l ts .
T h e c o n fi gu rati o n p aram eter h ib ernate. co nnectio n. rel eas e_ mo de i s u sed to sp ec i fy w h i c h rel ease m o de to u se.
T h e p o ssi bl e v al u es are as fo l l o w s:
au to (th e defau l t): th i s c h o ic e del egates to th e rel ease m o de retu rn ed by th e

o rg. h ib ernate. trans actio n. T rans actio nF acto ry. getD ef au l tR el eas eM o de( ) m eth o d. F o r J T A T ran sac ti o n F ac to ry, th i s
retu rn s Co n n ec ti o n R el easeM o de.A F T E R _ S T A T E M E N T ; fo r J D B CT ran sac ti o n F ac to ry, th i s retu rn s
Co n n ec ti o n R el easeM o de.A F T E R _ T R A N S A CT I O N . D o n o t c h an ge th i s defau l t beh av i o r as fai l u res du e to th e
v al u e o f th i s setti n g ten d to i n di c ate bu gs an d/o r i n v al i d assu m p ti o n s i n u ser c o de.
o n_ cl o s e: u ses Co n n ec ti o n R el easeM o de.O N _ CL O S E . T h i s setti n g i s l eft fo r bac k w ards c o m p ati bi l i ty, bu t i ts
u se i s di sc o u raged.
af ter_ trans actio n: u ses Co n n ec ti o n R el easeM o de.A F T E R _ T R A N S A CT I O N . T h i s setti n g sh o u l d n o t be u sed i n
J T A en v i ro n m en ts. A l so n o te th at w i th Co n n ec ti o n R el easeM o de.A F T E R _ T R A N S A CT I O N , i f a sessi o n i s
c o n si dered to be i n au to - c o m m i t m o de, c o n n ec ti o n s w i l l be rel eased as i f th e rel ease m o de w ere
A F T E R _ S T A T E M E N T .
af ter_ s tatement : u ses Co n n ec ti o n R el easeM o de.A F T E R _ S T A T E M E N T . A ddi ti o n al l y, th e c o n fi gu red
C o nnectio nP ro v ider i s c o n su l ted to see i f i t su p p o rts th i s setti n g (s u ppo rts A ggres s iv eR el eas e( )). I f n o t, th e
rel ease m o de i s reset to Co n n ec ti o n R el easeM o de.A F T E R _ T R A N S A CT I O N . T h i s setti n g i s o n l y safe i n
en v i ro n m en ts w h ere w e c an ei th er reac q u i re th e sam e u n derl yi n g J D B C c o n n ec ti o n eac h ti m e yo u m ak e
a c al l i n to C o nnectio nP ro v ider. getC o nnectio n( ) o r i n au to - c o m m i t en v i ro n m en ts w h ere i t do es n o t m atter i f
w e re- establ i sh th e sam e c o n n ec ti o n .
1 4 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
C h ap ter 1 2 . I ntercep tors and ev ents

1 2.1 . I n terc ep to rs
1 2.2. E v en t system
1 2.3 . H i bern ate dec l arati v e sec u ri ty
I t i s u sefu l fo r th e ap p l i c ati o n to reac t to c ertai n ev en ts th at o c c u r i n si de H i bern ate. T h i s al l o w s fo r th e

i m p l em en tati o n o f gen eri c fu n c ti o n al i ty an d th e ex ten si o n o f H i bern ate fu n c ti o n al i ty.
1 2 . 1 . I ntercep tors
T h e I ntercepto r i n terfac e p ro v i des c al l bac k s fro m th e sessi o n to th e ap p l i c ati o n , al l o w i n g th e ap p l i c ati o n to
i n sp ec t an d/o r m an i p u l ate p ro p erti es o f a p ersi sten t o bj ec t befo re i t i s sav ed, u p dated, del eted o r l o aded.
O n e p o ssi bl e u se fo r th i s i s to trac k au di ti n g i n fo rm ati o n . F o r ex am p l e, th e fo l l o w i n g I ntercepto r au to m ati c al l y
sets th e createT imes tamp w h en an A u ditab l e i s c reated an d u p dates th e l as tU pdateT imes tamp p ro p erty w h en an
A u ditab l e i s u p dated.
Y o u c an ei th er i m p l em en t I ntercepto r di rec tl y o r ex ten d E mptyI ntercepto r.
1 4 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
pack age o rg. h ib ernate. tes t;
impo rt j av a. io . Serial iz ab l e;
impo rt j av a. u til . I terato r;
impo rt o rg. h ib ernate. E mptyI ntercepto r;

impo rt o rg. h ib ernate. T rans actio n;
impo rt o rg. h ib ernate. type. T ype;
pu b l ic cl as s A u ditI ntercepto r ex tends E mptyI ntercepto r {
priv ate int u pdates ;

priv ate int creates ;
priv ate int l o ads ;
pu b l ic v o id o nD el ete( O b j ect entity,

Serial iz ab l e id,
O b j ect[ ] s tate,
String[ ] pro pertyNames ,
T ype[ ] types ) {
/ / do no th ing
}
pu b l ic b o o l ean o nF l u s h D irty( O b j ect entity,

O b j ect[ ] cu rrentState,
O b j ect[ ] prev io u s State,
T ype[ ] types ) {
if ( entity ins tanceo f A u ditab l e ) {

u pdates + + ;
f o r ( int i=0; i < pro pertyNames . l ength ; i+ + ){
if ( " l as tU pdateT imes tamp" . eq u al s ( pro pertyNames [ i] ) ) {
cu rrentState[ i] = new D ate( );
retu rn tru e;
}
}
}
retu rn f al s e;
}
pu b l ic b o o l ean o nL o ad( O b j ect entity,

T ype[ ] types ) {
l o ads + + ;
}
retu rn f al s e;
}
pu b l ic b o o l ean o nSav e( O b j ect entity,

T ype[ ] types ) {
1 4 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h ere are tw o k i n ds o f i n tec ep to rs: Ses s io n- sc o p ed an d Ses s io nF acto ry- sc o p ed.
A Ses s io n- sc o p ed i n terc ep to r i s sp ec i fi ed w h en a sessi o n i s o p en ed u si n g o n e o f th e o v erl o aded

S essi o n F ac to ry.o p en S essi o n () m eth o ds ac c ep ti n g an I ntercepto r.
Ses s io n s es s io n = s f . o penSes s io n( new A u ditI ntercepto r( ) );
A Ses s io nF acto ry- sc o p ed i n terc ep to r i s regi stered w i th th e C o nf igu ratio n o bj ec t p ri o r to bu i l di n g th e

Ses s io nF acto ry. U n l ess a sessi o n i s o p en ed ex p l i c i tl y sp ec i fyi n g th e i n terc ep to r to u se, th e su p p l i ed i n terc ep to r
w i l l be ap p l i ed to al l sessi o n s o p en ed fro m th at Ses s io nF acto ry. Ses s io nF acto ry- sc o p ed i n terc ep to rs m u st be
th read safe. E n su re th at yo u do n o t sto re sessi o n - sp ec i fi c states, si n c e m u l ti p l e sessi o n s w i l l u se th i s
i n terc ep to r p o ten ti al l y c o n c u rren tl y.
new C o nf igu ratio n( ). s etI ntercepto r( new A u ditI ntercepto r( ) );
1 2 . 2 . E v ent s y s tem
I f yo u h av e to reac t to p arti c u l ar ev en ts i n yo u r p ersi sten c e l ayer, yo u c an al so u se th e H i bern ate3 e v e nt
arc h i tec tu re. T h e ev en t system c an be u sed i n addi ti o n , o r as a rep l ac em en t, fo r i n terc ep to rs.
A l l th e m eth o ds o f th e Ses s io n i n terfac e c o rrel ate to an ev en t. Y o u h av e a L o adE v ent , a F l u s h E v ent , etc .

Co n su l t th e X M L c o n fi gu rati o n - fi l e D T D o r th e o rg. h ib ernate. ev ent p ac k age fo r th e fu l l l i st o f defi n ed ev en t
typ es. W h en a req u est i s m ade o f o n e o f th ese m eth o ds, th e H i bern ate Ses s io n gen erates an ap p ro p ri ate
ev en t an d p asses i t to th e c o n fi gu red ev en t l i sten ers fo r th at typ e. O u t- o f- th e- bo x , th ese l i sten ers i m p l em en t
th e sam e p ro c essi n g i n w h i c h th o se m eth o ds al w ays resu l ted. H o w ev er, yo u are free to i m p l em en t a
c u sto m i z ati o n o f o n e o f th e l i sten er i n terfac es (i .e., th e L o adE v ent i s p ro c essed by th e regi stered
im p l em en tati o n o f th e L o adE v entL is tener i n terfac e), i n w h ic h c ase th ei r i m p l em en tati o n w o u l d be resp o n si bl e
fo r p ro c essi n g an y l o ad( ) req u ests m ade o f th e Ses s io n.
T h e l i sten ers sh o u l d be c o n si dered si n gl eto n s. T h i s m ean s th ey are sh ared betw een req u ests, an d sh o u l d n o t
sav e an y state as i n stan c e v ari abl es.
A c u sto m l i sten er i m p l em en ts th e ap p ro p ri ate i n terfac e fo r th e ev en t i t w an ts to p ro c ess an d/o r ex ten d o n e

o f th e c o n v en i en c e base c l asses (o r ev en th e defau l t ev en t l i sten ers u sed by H i bern ate o u t- o f- th e- bo x as
th ese are dec l ared n o n - fi n al fo r th i s p u rp o se). Cu sto m l i sten ers c an ei th er be regi stered p ro gram m ati c al l y
th ro u gh th e C o nf igu ratio n o bj ec t, o r sp ec i fi ed i n th e H i bern ate c o n fi gu rati o n X M L . D ec l arati v e c o n fi gu rati o n
th ro u gh th e p ro p erti es fi l e i s n o t su p p o rted. H ere i s an ex am p l e o f a c u sto m l o ad ev en t l i sten er:
pu b l ic cl as s M yL o adL is tener impl ements L o adE v entL is tener {

/ / th is is th e s ingl e meth o d def ined b y th e L o adE v entL is tener interf ace
pu b l ic v o id o nL o ad( L o adE v ent ev ent, L o adE v entL is tener. L o adT ype l o adT ype)
th ro w s H ib ernateE x ceptio n {
if ( ! M ySecu rity. is A u th o riz ed( ev ent. getE ntityC l as s Name( ), ev ent. getE ntityI d( ) ) ) {
th ro w M ySecu rityE x ceptio n( " U nau th o riz ed acces s " );
}
}
}
Y o u al so n eed a c o n fi gu rati o n en try tel l i n g H i bern ate to u se th e l i sten er i n addi ti o n to th e defau l t l i sten er:

< s es s io n- f acto ry>
...
< ev ent type=" l o ad" >
< l is tener cl as s =" co m. eg. M yL o adL is tener" / >
< l is tener cl as s =" o rg. h ib ernate. ev ent. def . D ef au l tL o adE v entL is tener" / >
< / ev ent>
1 4 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I n stead, yo u c an regi ster i t p ro gram m ati c al l y:
C o nf igu ratio n cf g = new C o nf igu ratio n( );

L o adE v entL is tener[ ] s tack = { new M yL o adL is tener( ), new D ef au l tL o adE v entL is tener( ) };
cf g. E v entL is teners ( ). s etL o adE v entL is teners ( s tack );
L i sten ers regi stered dec l arati v el y c an n o t sh are i n stan c es. I f th e sam e c l ass n am e i s u sed i n m u l ti p l e
< l is tener/ > el em en ts, eac h referen c e w i l l resu l t i n a sep arate i n stan c e o f th at c l ass. I f yo u n eed to sh are
l i sten er i n stan c es betw een l i sten er typ es yo u m u st u se th e p ro gram m ati c regi strati o n ap p ro ac h .
W h y i m p l em en t an i n terfac e an d defi n e th e sp ec i fi c typ e du ri n g c o n fi gu rati o n ? A l i sten er i m p l em en tati o n

c o u l d i m p l em en t m u l ti p l e ev en t l i sten er i n terfac es. H av i n g th e typ e addi ti o n al l y defi n ed du ri n g regi strati o n
m ak es i t easi er to tu rn c u sto m l i sten ers o n o r o ff du ri n g c o n fi gu rati o n .
1 2 . 3 . Hibernate d ecl arativ e s ecurity

U su al l y, dec l arati v e sec u ri ty i n H i bern ate ap p l i c ati o n s i s m an aged i n a sessi o n fac ade l ayer. H i bern ate3
al l o w s c ertai n ac ti o n s to be p erm i ssi o n ed v i a J A CC, an d au th o ri z ed v i a J A A S . T h i s i s an o p ti o n al fu n c ti o n al i ty
th at i s bu i l t o n to p o f th e ev en t arc h i tec tu re.
F i rst, yo u m u st c o n fi gu re th e ap p ro p ri ate ev en t l i sten ers, to en abl e th e u se o f J A A S au th o ri z ati o n .
< l is tener type=" pre- del ete" cl as s =" o rg. h ib ernate. s ecu re. J A C C P reD el eteE v entL is tener" / >
< l is tener type=" pre- u pdate" cl as s =" o rg. h ib ernate. s ecu re. J A C C P reU pdateE v entL is tener" / >
< l is tener type=" pre- ins ert" cl as s =" o rg. h ib ernate. s ecu re. J A C C P reI ns ertE v entL is tener" / >
< l is tener type=" pre- l o ad" cl as s =" o rg. h ib ernate. s ecu re. J A C C P reL o adE v entL is tener" / >
N o te th at < l is tener type=" . . . " cl as s =" . . . " / > i s sh o rth an d fo r < ev ent type=" . . . " >< l is tener cl as s =" . . . " / >< / ev ent>
w h en th ere i s ex ac tl y o n e l i sten er fo r a p arti c u l ar ev en t typ e.
N ex t, w h i l e sti l l i n h ib ernate. cf g. x ml , bi n d th e p erm i ssi o n s to ro l es:
< grant ro l e=" admin" entityname=" U s er" actio ns =" ins ert, u pdate, read" / >
< grant ro l e=" s u " entityname=" U s er" actio ns =" *" / >
T h e ro l e n am es are th e ro l es u n dersto o d by yo u r J A CC p ro v i der.
C h ap ter 1 3 . B atch p roces s ing

1 3 .1 . B atc h i n serts
1 3 .2. B atc h u p dates
1 3 .3 . T h e S tatel essS essi o n i n terfac e
1 3 .4 . D M L - styl e o p erati o n s
A n ai v e ap p ro ac h to i n serti n g 1 0 0 ,0 0 0 ro w s i n th e database u si n g H i bern ate m i gh t l o o k l i k e th i s:
Ses s io n s es s io n = s es s io nF acto ry. o penSes s io n( );

T rans actio n tx = s es s io n. b eginT rans actio n( );
f o r ( int i=0; i< 100000; i+ + ){
C u s to mer cu s to mer = new C u s to mer( . . . . . );
s es s io n. s av e( cu s to mer);
}
tx . co mmit( );
T h i s w o u l d fal l o v er w i th an O u tO f M emo ryE x ceptio n so m ew h ere aro u n d th e 5 0 ,0 0 0 th ro w . T h at i s bec au se

H i bern ate c ac h es al l th e n ew l y i n serted C u s to mer i n stan c es i n th e sessi o n - l ev el c ac h e. I n th i s c h ap ter w e w i l l
sh o w yo u h o w to av o i d th i s p ro bl em .
1 4 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
I f yo u are u n dertak i n g batc h p ro c essi n g yo u w i l l n eed to en abl e th e u se o f J D B C batc h i n g. T h i s i s abso l u tel y

essen ti al i f yo u w an t to ac h i ev e o p ti m al p erfo rm an c e. S et th e J D B C batc h si z e to a reaso n abl e n u m ber
(1 0 - 5 0 , fo r ex am p l e):
h ib ernate. j db c. b atch _ s iz e 2 0
H i bern ate di sabl es i n sert batc h i n g at th e J D B C l ev el tran sp aren tl y i f yo u u se an identity i den ti fi er gen erato r.
Y o u c an al so do th i s k i n d o f w o rk in a p ro c ess w h ere i n terac ti o n w i th th e sec o n d- l ev el c ac h e i s c o m p l etel y

di sabl ed:
h ib ernate. cach e. u s e_ s eco nd_ l ev el _ cach e f al s e
H o w ev er, th i s i s n o t abso l u tel y n ec essary, si n c e w e c an ex p l i c i tl y set th e C ach eM o de to di sabl e i n terac ti o n

w i th th e sec o n d- l ev el c ac h e.
1 3 . 1 . B atch ins erts

W h en m ak i n g n ew o bj ec ts p ersi sten t f l u s h ( ) an d th en cl ear( ) th e sessi o n regu l arl y i n o rder to c o n tro l th e si z e
o f th e fi rst- l ev el c ac h e.

f o r ( int i=0; i< 100000; i+ + ){

C u s to mer cu s to mer = new C u s to mer( . . . . . );
s es s io n. s av e( cu s to mer);
if ( i % 2 0 == 0 ) { / / 2 0, s ame as th e J D B C b atch s iz e
/ / f l u s h a b atch o f ins erts and rel eas e memo ry:
s es s io n. f l u s h ( );
s es s io n. cl ear( );
}
}
tx . co mmit( );
1 3 . 2 . B atch up d ates
F o r retri ev i n g an d u p dati n g data, th e sam e i deas ap p l y. I n addi ti o n , yo u n eed to u se s cro l l ( ) to tak e
adv an tage o f serv ersi de c u rso rs fo r q u eri es th at retu rn m an y ro w s o f data.
1 4 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

Scro l l ab l eR es u l ts cu s to mers = s es s io n. getNamedQ u ery( " G etC u s to mers " )

. s etC ach eM o de( C ach eM o de. I G NO R E )
. s cro l l ( Scro l l M o de. F O R W A R D _ O NL Y );
int co u nt=0;
w h il e ( cu s to mers . nex t( ) ) {
C u s to mer cu s to mer = ( C u s to mer) cu s to mers . get( 0);
cu s to mer. u pdateStu f f ( . . . );
if ( + + co u nt % 2 0 == 0 ) {
/ / f l u s h a b atch o f u pdates and rel eas e memo ry:
s es s io n. cl ear( );
}
}
tx . co mmit( );
1 3 . 3 . T h e S tatel es s S es s ion interface

A l tern ati v el y, H i bern ate p ro v i des a c o m m an d- o ri en ted A P I th at c an be u sed fo r stream i n g data to an d fro m
th e database i n th e fo rm o f detac h ed o bj ec ts. A Statel es s Ses s io n h as n o p ersi sten c e c o n tex t asso c i ated w i th i t
an d do es n o t p ro v i de m an y o f th e h i gh er- l ev el l i fe c yc l e sem an ti c s. I n p arti c u l ar, a statel ess sessi o n do es n o t
i m p l em en t a fi rst- l ev el c ac h e n o r i n terac t w i th an y sec o n d- l ev el o r q u ery c ac h e. I t do es n o t i m p l em en t
tran sac ti o n al w ri te- beh i n d o r au to m ati c di rty c h ec k i n g. O p erati o n s p erfo rm ed u si n g a statel ess sessi o n n ev er
c asc ade to asso c i ated i n stan c es. Co l l ec ti o n s are i gn o red by a statel ess sessi o n . O p erati o n s p erfo rm ed v i a a
statel ess sessi o n byp ass H i bern ate' s ev en t m o del an d i n terc ep to rs. D u e to th e l ac k o f a fi rst- l ev el c ac h e,
S tatel ess sessi o n s are v u l n erabl e to data al i asi n g effec ts. A statel ess sessi o n i s a l o w er- l ev el abstrac ti o n th at
i s m u c h c l o ser to th e u n derl yi n g J D B C.
Statel es s Ses s io n s es s io n = s es s io nF acto ry. o penStatel es s Ses s io n( );

Scro l l ab l eR es u l ts cu s to mers = s es s io n. getNamedQ u ery( " G etC u s to mers " )

. s cro l l ( Scro l l M o de. F O R W A R D _ O NL Y );
w h il e ( cu s to mers . nex t( ) ) {
C u s to mer cu s to mer = ( C u s to mer) cu s to mers . get( 0);
cu s to mer. u pdateStu f f ( . . . );
s es s io n. u pdate( cu s to mer);
}
tx . co mmit( );
I n th i s c o de ex am p l e, th e C u s to mer i n stan c es retu rn ed by th e q u ery are i m m edi atel y detac h ed. T h ey are
n ev er asso c i ated w i th an y p ersi sten c e c o n tex t.
T h e ins ert( ), u pdate( ) an d del ete( ) o p erati o n s defi n ed by th e Statel es s Ses s io n i n terfac e are c o n si dered to be
di rec t database ro w - l ev el o p erati o n s. T h ey resu l t i n th e i m m edi ate ex ec u ti o n o f a S Q L I NSE R T , U P D A T E o r
D E L E T E resp ec ti v el y. T h ey h av e di fferen t sem an ti c s to th e s av e( ), s av eO rU pdate( ) an d del ete( ) o p erati o n s
defi n ed by th e Ses s io n i n terfac e.
1 3 . 4 . DM L - s ty l e op erations
A s al ready di sc u ssed, au to m ati c an d tran sp aren t o bj ec t/rel ati o n al m ap p i n g i s c o n c ern ed w i th th e
m an agem en t o f th e o bj ec t state. T h e o bj ec t state i s av ai l abl e i n m em o ry. T h i s m ean s th at m an i p u l ati n g data
1 5 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
di rec tl y i n th e database (u si n g th e S Q L D ata M anipu l atio n L angu age (D M L ) th e statem en ts: I NSE R T , U P D A T E ,
D E L E T E ) w i l l n o t affec t i n - m em o ry state. H o w ev er, H i bern ate p ro v i des m eth o ds fo r bu l k S Q L - styl e D M L
statem en t ex ec u ti o n th at i s p erfo rm ed th ro u gh th e H i bern ate Q u ery L an gu age (H Q L ).
T h e p seu do - syn tax fo r U P D A T E an d D E L E T E statem en ts i s:

( U P D A T E | D E L E T E ) F R O M ? E ntityName ( W H E R E w h ere_ co nditio ns )? .
S o m e p o i n ts to n o te:
I n th e fro m - c l au se, th e F R O M k eyw o rd i s o p ti o n al

T h ere c an o n l y be a si n gl e en ti ty n am ed i n th e fro m - c l au se. I t c an , h o w ev er, be al i ased. I f th e en ti ty
n am e i s al i ased, th en an y p ro p erty referen c es m u st be q u al i fi ed u si n g th at al i as. I f th e en ti ty n am e i s n o t
al i ased, th en i t i s i l l egal fo r an y p ro p erty referen c es to be q u al i fi ed.
N o j o i n s, ei th er i m p l i c i t o r ex p l i c i t, c an be sp ec i fi ed i n a bu l k H Q L q u ery. S u b- q u eri es c an be u sed i n th e
w h ere- c l au se, w h ere th e su bq u eri es th em sel v es m ay c o n tai n j o i n s.
T h e w h ere- c l au se i s al so o p ti o n al .
A s an ex am p l e, to ex ec u te an H Q L U P D A T E , u se th e Q u ery. ex ecu teU pdate( ) m eth o d. T h e m eth o d i s n am ed fo r

th o se fam i l i ar w i th J D B C' s P reparedStatement. ex ecu teU pdate( ):

String h q l U pdate = " u pdate C u s to mer c s et c. name = : new Name w h ere c. name = : o l dName" ;
/ / o r String h q l U pdate = " u pdate C u s to mer s et name = : new Name w h ere name = : o l dName" ;
int u pdatedE ntities = s . createQ u ery( h q l U pdate )
. s etString( " new Name" , new Name )
. s etString( " o l dName" , o l dName )
. ex ecu teU pdate( );
tx . co mmit( );
I n k eep i n g w i th th e E J B 3 sp ec i fi c ati o n , H Q L U P D A T E statem en ts, by defau l t, do n o t effec t th e v ersi o n o r th e

ti m estam p p ro p erty v al u es fo r th e affec ted en ti ti es. H o w ev er, yo u c an fo rc e H i bern ate to reset th e v ers io n o r
times tamp p ro p erty v al u es th ro u gh th e u se o f a v ers io ned u pdate . T h i s i s ac h i ev ed by addi n g th e V E R SI O NE D
k eyw o rd after th e U P D A T E k eyw o rd.

String h q l V ers io nedU pdate = " u pdate v ers io ned C u s to mer s et name = : new Name w h ere name = : o l dName" ;
int u pdatedE ntities = s . createQ u ery( h q l U pdate )
. s etString( " new Name" , new Name )
tx . co mmit( );
Cu sto m v ersi o n typ es, o rg. h ib ernate. u s ertype. U s erV ers io nT ype , are n o t al l o w ed i n c o n j u n c ti o n w i th a
u pdate v ers io ned statem en t.
T o ex ec u te an H Q L D E L E T E , u se th e sam e Q u ery. ex ecu teU pdate( ) m eth o d:
1 5 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

String h q l D el ete = " del ete C u s to mer c w h ere c. name = : o l dName" ;

/ / o r String h q l D el ete = " del ete C u s to mer w h ere name = : o l dName" ;
int del etedE ntities = s . createQ u ery( h q l D el ete )
tx . co mmit( );
T h e int v al u e retu rn ed by th e Q u ery. ex ecu teU pdate( ) m eth o d i n di c ates th e n u m ber o f en ti ti es effec ted by th e
o p erati o n . T h i s m ay o r m ay n o t c o rrel ate to th e n u m ber o f ro w s effec ted i n th e database. A n H Q L bu l k
o p erati o n m i gh t resu l t i n m u l ti p l e ac tu al S Q L statem en ts bei n g ex ec u ted (fo r j o i n ed- su bc l ass, fo r ex am p l e).
T h e retu rn ed n u m ber i n di c ates th e n u m ber o f ac tu al en ti ti es affec ted by th e statem en t. G o i n g bac k to th e
ex am p l e o f j o i n ed- su bc l ass, a del ete agai n st o n e o f th e su bc l asses m ay ac tu al l y resu l t i n del etes agai n st n o t
ju st th e tabl e to w h i c h th at su bc l ass i s m ap p ed, bu t al so th e " ro o t" tabl e an d p o ten ti al l y j o i n ed- su bc l ass
tabl es fu rth er do w n th e i n h eri tan c e h i erarc h y.
T h e p seu do - syn tax fo r I NSE R T statem en ts i s: I NSE R T I NT O E ntityName pro perties _ l is t s el ect_ s tatement . S o m e
p o i n ts to n o te:
O n l y th e I N S E R T I N T O ... S E L E CT ... fo rm i s su p p o rted; n o t th e I N S E R T I N T O ... V A L U E S ... fo rm .
T h e p ro p erti es_ l i st i s an al o go u s to th e co l u mn s pecif icatio n i n th e S Q L I NSE R T statem en t. F o r en ti ti es

i n v o l v ed i n m ap p ed i n h eri tan c e, o n l y p ro p erti es di rec tl y defi n ed o n th at gi v en c l ass- l ev el c an be u sed i n
th e p ro p erti es_ l i st. S u p erc l ass p ro p erti es are n o t al l o w ed an d su bc l ass p ro p erti es do n o t m ak e sen se. I n
o th er w o rds, I NSE R T statem en ts are i n h eren tl y n o n - p o l ym o rp h i c .
sel ec t_ statem en t c an be an y v al i d H Q L sel ec t q u ery, w i th th e c av eat th at th e retu rn typ es m u st m atc h

th e typ es ex p ec ted by th e i n sert. Cu rren tl y, th i s i s c h ec k ed du ri n g q u ery c o m p i l ati o n rath er th an al l o w i n g
th e c h ec k to rel egate to th e database. T h i s m i gh t, h o w ev er, c au se p ro bl em s betw een H i bern ate T ype s
w h i c h are e q uiv ale nt as o p p o sed to e q ual. T h i s m i gh t c au se i ssu es w i th m i sm atc h es betw een a p ro p erty
defi n ed as a o rg. h ib ernate. type. D ateT ype an d a p ro p erty defi n ed as a o rg. h ib ernate. type. T imes tampT ype , ev en
th o u gh th e database m i gh t n o t m ak e a di sti n c ti o n o r m i gh t be abl e to h an dl e th e c o n v ersi o n .
F o r th e i d p ro p erty, th e i n sert statem en t gi v es yo u tw o o p ti o n s. Y o u c an ei th er ex p l i c i tl y sp ec i fy th e i d
p ro p erty i n th e p ro p erti es_ l i st, i n w h i c h c ase i ts v al u e i s tak en fro m th e c o rresp o n di n g sel ec t ex p ressi o n ,
o r o m i t i t fro m th e p ro p erti es_ l i st, i n w h i c h c ase a gen erated v al u e i s u sed. T h i s l atter o p ti o n i s o n l y
av ai l abl e w h en u si n g i d gen erato rs th at o p erate i n th e database; attem p ti n g to u se th i s o p ti o n w i th an y
" i n m em o ry" typ e gen erato rs w i l l c au se an ex c ep ti o n du ri n g p arsi n g. F o r th e p u rp o ses o f th i s di sc u ssi o n ,
i n - database gen erato rs are c o n si dered to be o rg. h ib ernate. id. Seq u enceG enerato r (an d i ts su bc l asses) an d
an y i m p l em en ters o f o rg. h ib ernate. id. P o s tI ns ertI dentif ierG enerato r. T h e m o st n o tabl e ex c ep ti o n h ere i s
o rg. h ib ernate. id. T ab l eH iL o G enerato r, w h i c h c an n o t be u sed bec au se i t do es n o t ex p o se a sel ec tabl e w ay to
get i ts v al u es.
F o r p ro p erti es m ap p ed as ei th er v ers io n o r times tamp , th e i n sert statem en t gi v es yo u tw o o p ti o n s. Y o u c an
ei th er sp ec i fy th e p ro p erty i n th e p ro p erti es_ l i st, i n w h i c h c ase i ts v al u e i s tak en fro m th e c o rresp o n di n g
sel ec t ex p ressi o n s, o r o m i t i t fro m th e p ro p erti es_ l i st, i n w h ic h c ase th e s eed v al u e defi n ed by th e
o rg. h ib ernate. type. V ers io nT ype i s u sed.
T h e fo l l o w i n g i s an ex am p l e o f an H Q L I NSE R T statem en t ex ec u ti o n :

String h q l I ns ert = " ins ert into D el inq u entA cco u nt ( id, name) s el ect c. id, c. name f ro m C u s to mer c w h ere . . . " ;
int createdE ntities = s . createQ u ery( h q l I ns ert )
tx . co mmit( );
1 5 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
C h ap ter 1 4 . HQ L : T h e Hibernate Q uery L ang uag e

1 4 .1 . Case S en si ti v i ty
1 4 .2. T h e fro m c l au se
1 4 .3 . A sso c i ati o n s an d j o i n s
1 4 .4 . F o rm s o f j o i n syn tax
1 4 .5 . R eferri n g to i den ti fi er p ro p erty
1 4 .6 . T h e sel ec t c l au se
1 4 .7 . A ggregate fu n c ti o n s
1 4 .8 . P o l ym o rp h i c q u eri es
1 4 .9 .T h e w h ere c l au se
1 4 .1 0 . E x p ressi o n s
1 4 .1 1 . T h e o rder by c l au se
1 4 .1 2. T h e gro u p by c l au se
1 4 .1 3 . S u bq u eri es
1 4 .1 4 . H Q L ex am p l es
1 4 .1 5 . B u l k u p date an d del ete
1 4 .1 6 . T i p s & T ri c k s
1 4 .1 7 . Co m p o n en ts
1 4 .1 8 . R o w v al u e c o n stru c to r syn tax
H i bern ate u ses a p o w erfu l q u ery l an gu age (H Q L ) th at i s si m i l ar i n ap p earan c e to S Q L . Co m p ared w i th S Q L ,

h o w ev er, H Q L i s fu l l y o bj ec t- o ri en ted an d u n derstan ds n o ti o n s l i k e i n h eri tan c e, p o l ym o rp h i sm an d
asso c i ati o n .
1 4 . 1 . C as e S ens itiv ity

W i th th e ex c ep ti o n o f n am es o f J av a c l asses an d p ro p erti es, q u eri es are c ase- i n sen si ti v e. S o SeL eC T i s th e
sam e as s E L E ct i s th e sam e as SE L E C T , bu t o rg. h ib ernate. eg. F O O i s n o t o rg. h ib ernate. eg. F o o , an d f o o . b arSet i s n o t
f o o . B A R SE T .
T h i s m an u al u ses l o w erc ase H Q L k eyw o rds. S o m e u sers fi n d q u eri es w i th u p p erc ase k eyw o rds m o re
readabl e, bu t th i s c o n v en ti o n i s u n su i tabl e fo r q u eri es em bedded i n J av a c o de.
1 4 . 2 . T h e from cl aus e
T h e si m p l est p o ssi bl e H i bern ate q u ery i s o f th e fo rm :
f ro m eg. C at
T h i s retu rn s al l i n stan c es o f th e c l ass eg. C at . Y o u do n o t u su al l y n eed to q u al i fy th e c l ass n am e, si n c e

au to - impo rt i s th e defau l t. F o r ex am p l e:
f ro m C at
I n o rder to refer to th e C at i n o th er p arts o f th e q u ery, yo u w i l l n eed to assi gn an alias . F o r ex am p l e:
f ro m C at as cat
T h i s q u ery assi gn s th e al i as cat to C at i n stan c es, so yo u c an u se th at al i as l ater i n th e q u ery. T h e as k eyw o rd

i s o p ti o n al . Y o u c o u l d al so w ri te:
f ro m C at cat
M u l ti p l e c l asses c an ap p ear, resu l ti n g i n a c artesi an p ro du c t o r " c ro ss" j o i n .
1 5 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
f ro m F o rmu l a, P arameter
f ro m F o rmu l a as f o rm, P arameter as param
I t i s go o d p rac ti c e to n am e q u ery al i ases u si n g an i n i ti al l o w erc ase as th i s i s c o n si sten t w i th J av a n am i n g

stan dards fo r l o c al v ari abl es (e.g. do mes ticC at ).
1 4 . 3 . A s s ociations and j oins

Y o u c an al so assi gn al i ases to asso c i ated en ti ti es o r to el em en ts o f a c o l l ec ti o n o f v al u es u si n g a j o in. F o r
ex am p l e:
f ro m C at as cat
inner j o in cat. mate as mate
l ef t o u ter j o in cat. k ittens as k itten
f ro m C at as cat l ef t j o in cat. mate. k ittens as k ittens
f ro m F o rmu l a f o rm f u l l j o in f o rm. parameter param
T h e su p p o rted j o i n typ es are bo rro w ed fro m A N S I S Q L :
inner j o in
l ef t o u ter j o in
righ t o u ter j o in
f u l l j o in (n o t u su al l y u sefu l )
T h e inner j o in, l ef t o u ter j o in an d righ t o u ter j o in c o n stru c ts m ay be abbrev i ated.
f ro m C at as cat
j o in cat. mate as mate
l ef t j o in cat. k ittens as k itten
Y o u m ay su p p l y ex tra j o i n c o n di ti o n s u si n g th e H Q L w ith k eyw o rd.
f ro m C at as cat
l ef t j o in cat. k ittens as k itten
w ith k itten. b o dyW eigh t > 10. 0
A
" fetc h " j o i n al l o w s asso c i ati o n s o r c o l l ec ti o n s o f v al u es to be i n i ti al i z ed al o n g w i th th ei r p aren t o bj ec ts u si n g
a si n gl e sel ec t. T h i s i s p arti c u l arl y u sefu l i n th e c ase o f a c o l l ec ti o n . I t effec ti v el y o v erri des th e o u ter j o i n an d
l az y dec l arati o n s o f th e m ap p i n g fi l e fo r asso c i ati o n s an d c o l l ec ti o n s. S ee S ec ti o n 1 9 .1 , “ F etc h i n g strategi es”
fo r m o re i n fo rm ati o n .
f ro m C at as cat
inner j o in f etch cat. mate
l ef t j o in f etch cat. k ittens
A fetc h j o i n do es n o t u su al l y n eed to assi gn an al i as, bec au se th e asso c i ated o bj ec ts sh o u l d n o t be u sed i n th e

w h ere c l au se (o r an y o th er c l au se). T h e asso c i ated o bj ec ts are al so
n o t retu rn ed di rec tl y i n th e q u ery resu l ts.
I n stead, th ey m ay be ac c essed v i a th e p aren t o bj ec t. T h e o n l y reaso n yo u m i gh t n eed an al i as i s i f yo u are
rec u rsi v el y j o i n fetc h i n g a fu rth er c o l l ec ti o n :
f ro m C at as cat
inner j o in f etch cat. mate
l ef t j o in f etch cat. k ittens ch il d
l ef t j o in f etch ch il d. k ittens
1 5 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h e f etch c o n stru c t c an n o t be u sed i n q u eri es c al l ed u si n g iterate( ) (th o u gh s cro l l ( ) c an be u sed). F etch sh o u l d

be u sed to geth er w i th s etM ax R es u l ts ( ) o r s etF irs tR es u l t( ), as th ese o p erati o n s are based o n th e resu l t ro w s
w h i c h u su al l y c o n tai n du p l i c ates fo r eager c o l l ec ti o n fetc h i n g, h en c e, th e n u m ber o f ro w s i s n o t w h at yo u
w o u l d ex p ec t. F etch sh o u l d al so n o t be u sed to geth er w i th i m p ro m p tu w ith c o n di ti o n . I t i s p o ssi bl e to c reate a
c artesi an p ro du c t by j o i n fetc h i n g m o re th an o n e c o l l ec ti o n i n a q u ery, so tak e c are i n th i s c ase. J o i n fetc h i n g
m u l ti p l e c o l l ec ti o n ro l es c an p ro du c e u n ex p ec ted resu l ts fo r bag m ap p i n gs, so u ser di sc reti o n i s adv i sed w h en
fo rm u l ati n g q u eri es i n th i s c ase. F i n al l y, n o te th at f u l l j o in f etch an d righ t j o in f etch are n o t m ean i n gfu l .
I f yo u are u si n g p ro p erty- l ev el l az y fetc h i n g (w i th bytec o de i n stru m en tati o n ), i t i s p o ssi bl e to fo rc e H i bern ate

to fetc h th e l az y p ro p erti es i n th e fi rst q u ery i m m edi atel y u si n g f etch al l pro perties .
f ro m D o cu ment f etch al l pro perties o rder b y name
f ro m D o cu ment do c f etch al l pro perties w h ere l o w er( do c. name) l ik e ' % cats % '
1 4 . 4 . F orms of j oin s y ntax

H Q L su p p o rts tw o fo rm s o f asso c i ati o n j o i n i n g: impl icit an d ex pl icit .
T h e q u eri es sh o w n in th e p rev i o u s sec ti o n al l u se th e ex pl icit fo rm , th at i s, w h ere th e j o i n k eyw o rd i s

ex p l i c i tl y u sed i n th e fro m c l au se. T h i s i s th e rec o m m en ded fo rm .
T h e impl icit fo rm do es n o t u se th e j o i n k eyw o rd. I n stead, th e asso c i ati o n s are " dereferen c ed" u si n g
do t- n o tati o n . impl icit j o i n s c an ap p ear i n an y o f th e H Q L c l au ses. impl icit j o i n resu l t i n i n n er j o i n s i n th e
resu l ti n g S Q L statem en t.
f ro m C at as cat w h ere cat. mate. name l ik e ' % s % '
1 4 . 5 . Referring to id entifier p rop erty

T h ere are 2 w ays to refer to an en ti ty' s i den ti fi er p ro p erty:
T h e sp ec i al p ro p erty (l o w erc ase) id m ay be u sed to referen c e th e i den ti fi er p ro p erty o f an en ti ty p rov id e d

th at th e e ntity d oe s not d e f ine a non- id e ntif ie r p rop e rty nam e d id .
I f th e en ti ty defi n es a n am ed i den ti fi er p ro p erty, yo u c an u se th at p ro p erty n am e.
R eferen c es to c o m p o si te i den ti fi er p ro p erti es fo l l o w th e sam e n am i n g ru l es. I f th e en ti ty h as a n o n - i den ti fi er

p ro p erty n am ed i d, th e c o m p o si te i den ti fi er p ro p erty c an o n l y be referen c ed by i ts defi n ed n am ed.
O th erw i se, th e sp ec i al id p ro p erty c an be u sed to referen c e th e i den ti fi er p ro p erty.
Important
P l ease n o te th at, starti n g i n v ersi o n 3 .2.2, th i s h as c h an ged si gn i fi c an tl y. I n p rev i o u s v ersi o n s,
id alw ay s referred to th e i den ti fi er p ro p erty regardl ess o f i ts ac tu al n am e. A ram i fi c ati o n o f th at
dec i si o n w as th at n o n - i den ti fi er p ro p erti es n am ed id c o u l d n ev er be referen c ed i n H i bern ate
q u eri es.
1 4 . 6 . T h e s el ect cl aus e
T h e s el ect c l au se p i c k s w h i c h o bj ec ts an d p ro p erti es to retu rn i n th e q u ery resu l t set. Co n si der th e fo l l o w i n g:
s el ect mate
f ro m C at as cat
inner j o in cat. mate as mate
T h e q u ery w i l l sel ec t mate s o f o th er C at s. Y o u c an ex p ress th i s q u ery m o re c o m p ac tl y as:
1 5 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
s el ect cat. mate f ro m C at cat
Q u eri es c an retu rn p ro p erti es o f an y v al u e typ e i n c l u di n g p ro p erti es o f c o m p o n en t typ e:
s el ect cat. name f ro m D o mes ticC at cat

w h ere cat. name l ik e ' f ri% '
s el ect cu s t. name. f irs tName f ro m C u s to mer as cu s t
Q u eri es c an retu rn m u l ti p l e o bj ec ts an d/o r p ro p erti es as an array o f typ e O b j ect[ ] :
s el ect mo th er, o f f s pr, mate. name

f ro m D o mes ticC at as mo th er
inner j o in mo th er. mate as mate
l ef t o u ter j o in mo th er. k ittens as o f f s pr
O r as a L is t :
s el ect new l is t( mo th er, o f f s pr, mate. name)

inner j o in mo th er. mate as mate
l ef t o u ter j o in mo th er. k ittens as o f f s pr
O r - assu m i n g th at th e c l ass F amil y h as an ap p ro p ri ate c o n stru c to r - as an ac tu al typ esafe J av a o bj ec t:
s el ect new F amil y( mo th er, mate, o f f s pr)

j o in mo th er. mate as mate
l ef t j o in mo th er. k ittens as o f f s pr
Y o u c an assi gn al i ases to sel ec ted ex p ressi o n s u si n g as :
s el ect max ( b o dyW eigh t) as max , min( b o dyW eigh t) as min, co u nt( *) as n
f ro m C at cat
T h isism o st u sefu l w h en u sed to geth er w i th s el ect new map :
s el ect new map( max ( b o dyW eigh t) as max , min( b o dyW eigh t) as min, co u nt( *) as n )
f ro m C at cat
T h i s q u ery retu rn s a M ap fro m al i ases to sel ec ted v al u es.
1 4 . 7 . A g g reg ate functions

H Q L q u eri es c an ev en retu rn th e resu l ts o f aggregate fu n c ti o n s o n p ro p erti es:
s el ect av g( cat. w eigh t), s u m( cat. w eigh t), max ( cat. w eigh t), co u nt( cat)
f ro m C at cat
T h e su p p o rted aggregate fu n c ti o n s are:
av g( . . . ), s u m( . . . ), min( . . . ), max ( . . . )
co u nt( *)
co u nt( . . . ), co u nt( dis tinct . . . ), co u nt( al l . . . )
Y o u c an u se ari th m eti c o p erato rs, c o n c aten ati o n , an d rec o gn i z ed S Q L fu n c ti o n s i n th e sel ec t c l au se:
1 5 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
s el ect cat. w eigh t + s u m( k itten. w eigh t)

f ro m C at cat
j o in cat. k ittens k itten
gro u p b y cat. id, cat. w eigh t
s el ect f irs tName| | ' ' | | initial | | ' ' | | u pper( l as tName) f ro m P ers o n
T h e dis tinct an d al l k eyw o rds c an be u sed an d h av e th e sam e sem an ti c s as i n S Q L .
s el ect dis tinct cat. name f ro m C at cat
s el ect co u nt( dis tinct cat. name), co u nt( cat) f ro m C at cat
1 4 . 8 . P ol y morp h ic q ueries
A q u ery l i k e:
f ro m C at as cat
retu rn s i n stan c es n o t o n l y o f C at , bu t al so o f su bc l asses l i k e D o mes ticC at . H i bern ate q u eri es c an n am e any

J av a c l ass o r i n terfac e i n th e f ro m c l au se. T h e q u ery w i l l retu rn i n stan c es o f al l p ersi sten t c l asses th at ex ten d
th at c l ass o r i m p l em en t th e i n terfac e. T h e fo l l o w i n g q u ery w o u l d retu rn al l p ersi sten t o bj ec ts:
f ro m j av a. l ang. O b j ect o
T h e i n terfac e Named m i gh t be i m p l em en ted by v ari o u s p ersi sten t c l asses:
f ro m Named n, Named m w h ere n. name = m. name
T h ese l ast tw o q u eri es w i l l req u i re m o re th an o n e S Q L SE L E C T . T h i s m ean s th at th e o rder b y c l au se do es n o t

c o rrec tl y o rder th e w h o l e resu l t set. I t al so m ean s yo u c an n o t c al l th ese q u eri es u si n g Q u ery. s cro l l ( ).
1 4 . 9 . T h e w h ere cl aus e
T h e w h ere c l au se al l o w s yo u to refi n e th e l i st o f i n stan c es retu rn ed. I f n o al i as ex i sts, yo u c an refer to
p ro p erti es by n am e:
f ro m C at w h ere name=' F ritz '
I f th ere i s an al i as, u se a q u al i fi ed p ro p erty n am e:
f ro m C at as cat w h ere cat. name=' F ritz '
T h i s retu rn s i n stan c es o f C at n am ed ' F ri tz ' .
T h e fo l l o w i n g q u ery:
s el ect f o o
f ro m F o o f o o , B ar b ar
w h ere f o o . s tartD ate = b ar. date
retu rn s al l i n stan c es o f F o o w i th an i n stan c e o f b ar w i th a date p ro p erty eq u al to th e s tartD ate p ro p erty o f th e

F o o . Co m p o u n d p ath ex p ressi o n s m ak e th e w h ere c l au se ex trem el y p o w erfu l . Co n si der th e fo l l o w i n g:
f ro m C at cat w h ere cat. mate. name is no t nu l l
T h i s q u ery tran sl ates to an S Q L q u ery w i th a tabl e (i n n er) j o i n . F o r ex am p l e:
1 5 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
f ro m F o o fo o
w h ere f o o . b ar. b az . cu s to mer. addres s . city is no t nu l l
w o u l d resu l t i n a q u ery th at w o u l d req u i re fo u r tabl e j o i n s i n S Q L .
T h e = o p erato r c an be u sed to c o m p are n o t o n l y p ro p erti es, bu t al so i n stan c es:
f ro m C at cat, C at riv al w h ere cat. mate = riv al . mate
s el ect cat, mate

f ro m C at cat, C at mate
w h ere cat. mate = mate
T h e sp ec i al p ro p erty (l o w erc ase) id c an be u sed to referen c e th e u n i q u e i den ti fi er o f an o bj ec t. S ee

S ec ti o n 1 4 .5 , “ R eferri n g to i den ti fi er p ro p erty” fo r m o re i n fo rm ati o n .
f ro m C at as cat w h ere cat. id = 12 3
f ro m C at as cat w h ere cat. mate. id = 6 9
T h e sec o n d q u ery i s effi c i en t an d do es n o t req u i re a tabl e j o i n .
P ro p erti es o f c o m p o si te i den ti fi ers c an al so be u sed. Co n si der th e fo l l o w i n g ex am p l e w h ere P ers o n h as

c o m p o si te i den ti fi ers c o n si sti n g o f co u ntry an d medicareNu mb er:
f ro m b ank . P ers o n pers o n

w h ere pers o n. id. co u ntry = ' A U '
and pers o n. id. medicareNu mb er = 12 3456
f ro m b ank . A cco u nt acco u nt

w h ere acco u nt. o w ner. id. co u ntry = ' A U '
and acco u nt. o w ner. id. medicareNu mb er = 12 3456
O n c e agai n , th e sec o n d q u ery do es n o t req u i re a tabl e j o i n .
S ee S ec ti o n 1 4 .5 , “ R eferri n g to i den ti fi er p ro p erty” fo r m o re i n fo rm ati o n regardi n g referen c i n g i den ti fi er

p ro p erti es)
T h e sp ec i al p ro p erty cl as s ac c esses th e di sc ri m i n ato r v al u e o f an i n stan c e i n th e c ase o f p o l ym o rp h i c

p ersi sten c e. A J av a c l ass n am e em bedded i n th e w h ere c l au se w i l l be tran sl ated to i ts di sc ri m i n ato r v al u e.
f ro m C at cat w h ere cat. cl as s = D o mes ticC at
Y o u c an al so u se c o m p o n en ts o r c o m p o si te u ser typ es, o r p ro p erti es o f sai d c o m p o n en t typ es. S ee

S ec ti o n 1 4 .1 7 , “ Co m p o n en ts” fo r m o re i n fo rm ati o n .
A n " an y" typ e h as th e sp ec i al p ro p erti es id an d cl as s th at al l o w s yo u to ex p ress a j o i n in th e fo l l o w i n g w ay

(w h ere A u ditL o g. item i s a p ro p erty m ap p ed w i th < any>):
f ro m A u ditL o g l o g, P ayment payment

w h ere l o g. item. cl as s = ' P ayment' and l o g. item. id = payment. id
T h e l o g. item. cl as s an d payment. cl as s w o u l d refer to th e v al u es o f c o m p l etel y di fferen t database c o l u m n s i n th e

abo v e q u ery.
1 4 . 1 0 . E x p res s ions
E x p ressi o n s u sed i n th e w h ere c l au se i n c l u de th e fo l l o w i n g:
m ath em ati c al o p erato rs: + , - , *, /
1 5 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
bi n ary c o m p ari so n o p erato rs: =, >=, < =, < >, ! =, l ik e
l o gi c al o p erati o n s and, o r, no t
P aren th eses ( ) th at i n di c ates gro u p i n g

in, no t in, b etw een, is nu l l , is no t nu l l , is empty, is no t empty, memb er o f an d no t memb er o f
" S im p l e" c ase, cas e . . . w h en . . . th en . . . el s e . . . end, an d " searc h ed" c ase, cas e w h en . . . th en . . . el s e . . . end
stri n g c o n c aten ati o n . . . | | . . . o r co ncat( . . . , . . . )
cu rrent_ date( ), cu rrent_ time( ), an d cu rrent_ times tamp( )
s eco nd( . . . ), minu te( . . . ), h o u r( . . . ), day( . . . ), mo nth ( . . . ), an d year( . . . )
A n y fu n c ti o n o r o p erato r defi n ed by E J B - Q L 3 .0 :
s u b s tring( ), trim( ), l o w er( ), u pper( ), l ength ( ), l o cate( ), ab s ( ), s q rt( ), b it_ l ength ( ), mo d( )
co al es ce( ) an d nu l l if ( )
s tr( ) fo r c o n v erti n g n u m eri c o r tem p o ral v al u es to a readabl e stri n g
cas t( . . . as . . . ), w h ere th e sec o n d argu m en t i s th e n am e o f a H i bern ate typ e, an d ex tract( . . . f ro m . . . ) i f A N S I

cas t( ) an d ex tract( ) i s su p p o rted by th e u n derl yi n g database
th e H Q L index ( ) fu n c ti o n , th at ap p l i es to al i ases o f a j o i n ed i n dex ed c o l l ec ti o n
H Q L fu n c ti o n s th at tak e c o l l ec ti o n - v al u ed p ath ex p ressi o n s:

s iz e( ), minel ement( ), max el ement( ), minindex ( ), max index ( ), al o n g w i th th e sp ec i al el ements ( ) an d indices
fu n c ti o n s th at c an be q u an ti fi ed u si n g s o me, al l , ex is ts , any, in.
A n y database- su p p o rted S Q L sc al ar fu n c ti o n l i k e s ign( ), tru nc( ), rtrim( ), an d s in( )
J D B C- styl e p o si ti o n al p aram eters ?
n am ed p aram eters : name , : s tart_ date , an d : x 1
S Q L l i teral s ' f o o ' , 6 9 , 6 . 6 6 E + 2 , ' 19 7 0- 01- 01 10: 00: 01. 0'
J av a pu b l ic s tatic f inal c o n stan ts eg. C o l o r. T A B B Y
in an d b etw een c an be u sed as fo l l o w s:
f ro m D o mes ticC at cat w h ere cat. name b etw een ' A ' and ' B '
f ro m D o mes ticC at cat w h ere cat. name in ( ' F o o ' , ' B ar' , ' B az ' )
T h e n egated fo rm s c an be w ri tten as fo l l o w s:
f ro m D o mes ticC at cat w h ere cat. name no t b etw een ' A ' and ' B '
f ro m D o mes ticC at cat w h ere cat. name no t in ( ' F o o ' , ' B ar' , ' B az ' )
S i m i l arl y, is nu l l an d is no t nu l l c an be u sed to test fo r n u l l v al u es.
B o o l ean s c an be easi l y u sed i n ex p ressi o n s by dec l ari n g H Q L q u ery su bsti tu ti o n s i n H i bern ate c o n fi gu rati o n :
< pro perty name=" h ib ernate. q u ery. s u b s titu tio ns " >tru e 1, f al s e 0< / pro perty>
T h i s w i l l rep l ac e th e k eyw o rds tru e an d f al s e w i th th e l i teral s 1 an d 0 i n th e tran sl ated S Q L fro m th i s H Q L :
f ro m C at cat w h ere cat. al iv e = tru e
Y o u c an test th e si z e o f a c o l l ec ti o n w i th th e sp ec i al p ro p erty s iz e o r th e sp ec i al s iz e( ) fu n c ti o n .
f ro m C at cat w h ere cat. k ittens . s iz e > 0
f ro m C at cat w h ere s iz e( cat. k ittens ) > 0
F o r i n dex ed c o l l ec ti o n s, yo u c an refer to th e m i n i m u m an d m ax i m u m i n di c es u si n g minindex an d max index
1 5 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
fu n c ti o n s. S i m i l arl y, yo u c an refer to th e m i n i m u m an d m ax i m u m el em en ts o f a c o l l ec ti o n o f basi c typ e u si n g

th e minel ement an d max el ement fu n c ti o n s. F o r ex am p l e:
f ro m C al endar cal w h ere max el ement( cal . h o l idays ) > cu rrent_ date
f ro m O rder o rder w h ere max index ( o rder. items ) > 100
f ro m O rder o rder w h ere minel ement( o rder. items ) > 10000
T h e S Q L fu n c ti o n s any, s o me, al l , ex is ts , in are su p p o rted w h en p assed th e el em en t o r i n dex set o f a c o l l ec ti o n

(el ements an d indices fu n c ti o n s) o r th e resu l t o f a su bq u ery (see bel o w ):
s el ect mo th er f ro m C at as mo th er, C at as k it
w h ere k it in el ements ( f o o . k ittens )
s el ect p f ro m NameL is t l is t, P ers o n p

w h ere p. name = s o me el ements ( l is t. names )
f ro m C at cat w h ere ex is ts el ements ( cat. k ittens )
f ro m P l ayer p w h ere 3 > al l el ements ( p. s co res )
f ro m Sh o w s h o w w h ere ' f iz ard' in indices ( s h o w . acts )
N o te th at th ese c o n stru c ts - s iz e , el ements , indices , minindex , max index , minel ement , max el ement - c an o n l y be
u sed i n th e w h ere c l au se i n H i bern ate3 .
E l em en ts o f i n dex ed c o l l ec ti o n s (arrays, l i sts, an d m ap s) c an be referred to by i n dex i n a w h ere c l au se o n l y:
f ro m O rder o rder w h ere o rder. items [ 0] . id = 12 34
s el ect pers o n f ro m P ers o n pers o n, C al endar cal endar

w h ere cal endar. h o l idays [ ' natio nal day' ] = pers o n. b irth D ay
and pers o n. natio nal ity. cal endar = cal endar
s el ect item f ro m I tem item, O rder o rder

w h ere o rder. items [ o rder. del iv eredI temI ndices [ 0] ] = item and o rder. id = 11

w h ere o rder. items [ max index ( o rder. items ) ] = item and o rder. id = 11
T h e ex p ressi o n i n si de [ ] c an ev en be an ari th m eti c ex p ressi o n :

w h ere o rder. items [ s iz e( o rder. items ) - 1 ] = item
H Q L al so p ro v i des th e bu i l t- i n index ( ) fu n c ti o n fo r el em en ts o f a o n e- to - m an y asso c i ati o n o r c o l l ec ti o n o f

v al u es.
s el ect item, index ( item) f ro m O rder o rder

j o in o rder. items item
w h ere index ( item) < 5
S c al ar S Q L fu n c ti o n s su p p o rted by th e u n derl yi n g database c an be u sed:
f ro m D o mes ticC at cat w h ere u pper( cat. name) l ik e ' F R I % '
Co n si der h o w m u c h l o n ger an d l ess readabl e th e fo l l o w i n g q u ery w o u l d be i n S Q L :
1 6 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
s el ect cu s t
f ro m P ro du ct pro d,
Sto re s to re
inner j o in s to re. cu s to mers cu s t
w h ere pro d. name = ' w idget'
and s to re. l o catio n. name in ( ' M el b o u rne' , ' Sydney' )
and pro d = al l el ements ( cu s t. cu rrentO rder. l ineI tems )
H int: so m eth i n g l i k e
SE L E C T cu s t. name, cu s t. addres s , cu s t. ph o ne, cu s t. id, cu s t. cu rrent_ o rder

F R O M cu s to mers cu s t,
s to res s to re,
l o catio ns l o c,
s to re_ cu s to mers s c,
pro du ct pro d
W H E R E pro d. name = ' w idget'
A ND s to re. l o c_ id = l o c. id
A ND l o c. name I N ( ' M el b o u rne' , ' Sydney' )
A ND s c. s to re_ id = s to re. id
A ND s c. cu s t_ id = cu s t. id
A ND pro d. id = A L L (
SE L E C T item. pro d_ id
F R O M l ine_ items item, o rders o
W H E R E item. o rder_ id = o . id
A ND cu s t. cu rrent_ o rder = o . id
)
1 4 . 1 1 . T h e ord er by cl aus e
T h e l i st retu rn ed by a q u ery c an be o rdered by an y p ro p erty o f a retu rn ed c l ass o r c o m p o n en ts:
f ro m D o mes ticC at cat

o rder b y cat. name as c, cat. w eigh t des c, cat. b irth date
T h e o p ti o n al as c o r des c i n di c ate asc en di n g o r desc en di n g o rder resp ec ti v el y.
1 4 . 1 2 . T h e g roup by cl aus e
A q u ery th at retu rn s aggregate v al u es c an be gro u p ed by an y p ro p erty o f a retu rn ed c l ass o r c o m p o n en ts:
s el ect cat. co l o r, s u m( cat. w eigh t), co u nt( cat)

f ro m C at cat
gro u p b y cat. co l o r
s el ect f o o . id, av g( name), max ( name)

f ro m F o o fo o j o in f o o . names name
gro u p b y f o o . id
A h av ing c l au se i s al so al l o w ed.
s el ect cat. co l o r, s u m( cat. w eigh t), co u nt( cat)

f ro m C at cat
gro u p b y cat. co l o r
h av ing cat. co l o r in ( eg. C o l o r. T A B B Y , eg. C o l o r. B L A C K )
S Q L fu n c ti o n s an d aggregate fu n c ti o n s are al l o w ed i n th e h av ing an d o rder b y c l au ses i f th ey are su p p o rted by

th e u n derl yi n g database (i .e., n o t i n M yS Q L ).
1 6 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
s el ect cat
f ro m C at cat
j o in cat. k ittens k itten
gro u p b y cat. id, cat. name, cat. o th er, cat. pro perties
h av ing av g( k itten. w eigh t) > 100
o rder b y co u nt( k itten) as c, s u m( k itten. w eigh t) des c
N ei th er th e gro u p b y c l au se n o r th e o rder b y c l au se c an c o n tai n ari th m eti c ex p ressi o n s. H i bern ate al so do es

n o t c u rren tl y ex p an d a gro u p ed en ti ty, so yo u c an n o t w ri te gro u p b y cat i f al l p ro p erti es o f cat are
n o n - aggregated. Y o u h av e to l i st al l n o n - aggregated p ro p erti es ex p l i c i tl y.
1 4 . 1 3 . S ubq ueries
F o r databases th at su p p o rt su bsel ec ts, H i bern ate su p p o rts su bq u eri es w i th i n q u eri es. A su bq u ery m u st be
su rro u n ded by p aren th eses (o ften by an S Q L aggregate fu n c ti o n c al l ). E v en c o rrel ated su bq u eri es
(su bq u eri es th at refer to an al i as i n th e o u ter q u ery) are al l o w ed.
f ro m C at as f atcat
w h ere f atcat. w eigh t > (
s el ect av g( cat. w eigh t) f ro m D o mes ticC at cat
)
f ro m D o mes ticC at as cat

w h ere cat. name = s o me (
s el ect name. nick Name f ro m Name as name
)
f ro m C at as cat
w h ere no t ex is ts (
f ro m C at as mate w h ere mate. mate = cat
)
f ro m D o mes ticC at as cat

w h ere cat. name no t in (
s el ect name. nick Name f ro m Name as name
)
s el ect cat. id, ( s el ect max ( k it. w eigh t) f ro m cat. k itten k it)
f ro m C at as cat
N o te th at H Q L su bq u eri es c an o c c u r o n l y i n th e sel ec t o r w h ere c l au ses.
N o te th at su bq u eri es c an al so u ti l i z e ro w v al u e co ns tru cto r syn tax . S ee S ec ti o n 1 4 .1 8 , “ R o w v al u e c o n stru c to r

syn tax ” fo r m o re i n fo rm ati o n .
1 4 . 1 4 . HQ L ex amp l es
H i bern ate q u eri es c an be q u i te p o w erfu l an d c o m p l ex . I n fac t, th e p o w er o f th e q u ery l an gu age i s o n e o f
H i bern ate' s m ai n stren gth s. T h e fo l l o w i n g ex am p l e q u eri es are si m i l ar to q u eri es th at h av e been u sed o n
rec en t p ro j ec ts. P l ease n o te th at m o st q u eri es yo u w i l l w ri te w i l l be m u c h si m p l er th an th e fo l l o w i n g
ex am p l es.
T h e fo l l o w i n g q u ery retu rn s th e o rder i d, n u m ber o f i tem s, th e gi v en m i n i m u m to tal v al u e an d th e to tal v al u e

o f th e o rder fo r al l u n p ai d o rders fo r a p arti c u l ar c u sto m er. T h e resu l ts are o rdered by to tal v al u e. I n
determ i n i n g th e p ri c es, i t u ses th e c u rren t c atal o g. T h e resu l ti n g S Q L q u ery, agai n st th e O R D E R , O R D E R _ L I NE ,
P R O D U C T ,C A T A L O G an d P R I C E tabl es h as fo u r i n n er j o i n s an d an (u n c o rrel ated) su bsel ec t.
1 6 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
s el ect o rder. id, s u m( price. amo u nt), co u nt( item)

f ro m O rder as o rder
j o in o rder. l ineI tems as item
j o in item. pro du ct as pro du ct,
C atal o g as catal o g
j o in catal o g. prices as price
w h ere o rder. paid = f al s e
and o rder. cu s to mer = : cu s to mer
and price. pro du ct = pro du ct
and catal o g. ef f ectiv eD ate < s ys date
and catal o g. ef f ectiv eD ate >= al l (
s el ect cat. ef f ectiv eD ate
f ro m C atal o g as cat
w h ere cat. ef f ectiv eD ate < s ys date
)
gro u p b y o rder
h av ing s u m( price. amo u nt) > : minA mo u nt
o rder b y s u m( price. amo u nt) des c
W h at a m o n ster! A c tu al l y, i n real l i fe, I ' m n o t v ery k een o n su bq u eri es, so m y q u ery w as real l y m o re l i k e
th i s:
s el ect o rder. id, s u m( price. amo u nt), co u nt( item)

f ro m O rder as o rder
j o in o rder. l ineI tems as item
j o in item. pro du ct as pro du ct,
C atal o g as catal o g
j o in catal o g. prices as price
w h ere o rder. paid = f al s e
and o rder. cu s to mer = : cu s to mer
and price. pro du ct = pro du ct
and catal o g = : cu rrentC atal o g
gro u p b y o rder
h av ing s u m( price. amo u nt) > : minA mo u nt
o rder b y s u m( price. amo u nt) des c
T h e n ex t q u ery c o u n ts th e n u m ber o f p aym en ts i n eac h statu s, ex c l u di n g al l p aym en ts i n th e

A W A I T I NG _ A P P R O V A L statu s w h ere th e m o st rec en t statu s c h an ge w as m ade by th e c u rren t u ser. I t tran sl ates
to an S Q L q u ery w i th tw o i n n er j o i n s an d a c o rrel ated su bsel ec t agai n st th e P A Y M E NT , P A Y M E NT _ ST A T U S an d
P A Y M E NT _ ST A T U S_ C H A NG E tabl es.
s el ect co u nt( payment), s tatu s . name

f ro m P ayment as payment
j o in payment. cu rrentStatu s as s tatu s
j o in payment. s tatu s C h anges as s tatu s C h ange
w h ere payment. s tatu s . name < > P aymentStatu s . A W A I T I NG _ A P P R O V A L
o r(
s tatu s C h ange. timeStamp = (
s el ect max ( ch ange. timeStamp)
f ro m P aymentStatu s C h ange ch ange
w h ere ch ange. payment = payment
)
and s tatu s C h ange. u s er < > : cu rrentU s er
)
gro u p b y s tatu s . name, s tatu s . s o rtO rder
o rder b y s tatu s . s o rtO rder
I f th e s tatu s C h anges c o l l ec ti o n w as m ap p ed as a l i st, i n stead o f a set, th e q u ery w o u l d h av e been m u c h

si m p l er to w ri te.
1 6 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
s el ect co u nt( payment), s tatu s . name

f ro m P ayment as payment
j o in payment. cu rrentStatu s as s tatu s
w h ere payment. s tatu s . name < > P aymentStatu s . A W A I T I NG _ A P P R O V A L
o r payment. s tatu s C h anges [ max I ndex ( payment. s tatu s C h anges ) ] . u s er < > : cu rrentU s er
gro u p b y s tatu s . name, s tatu s . s o rtO rder
o rder b y s tatu s . s o rtO rder
T h e n ex t q u ery u ses th e M S S Q L S erv er is Nu l l ( ) fu n c ti o n to retu rn al l th e ac c o u n ts an d u n p ai d p aym en ts fo r

th e o rgan i z ati o n to w h i c h th e c u rren t u ser bel o n gs. I t tran sl ates to an S Q L q u ery w i th th ree i n n er j o i n s, an
o u ter j o i n an d a su bsel ec t agai n st th e A C C O U NT , P A Y M E NT , P A Y M E NT _ ST A T U S, A C C O U NT _ T Y P E , O R G A NI Z A T I O N
an d O R G _ U SE R tabl es.
s el ect acco u nt, payment

f ro m A cco u nt as acco u nt
l ef t o u ter j o in acco u nt. payments as payment
w h ere : cu rrentU s er in el ements ( acco u nt. h o l der. u s ers )
and P aymentStatu s . U NP A I D = is Nu l l ( payment. cu rrentStatu s . name, P aymentStatu s . U NP A I D )
o rder b y acco u nt. type. s o rtO rder, acco u nt. acco u ntNu mb er, payment. du eD ate
F o r so m e databases, w e w o u l d n eed to do aw ay w i th th e (c o rrel ated) su bsel ec t.
s el ect acco u nt, payment

f ro m A cco u nt as acco u nt
j o in acco u nt. h o l der. u s ers as u s er
l ef t o u ter j o in acco u nt. payments as payment
w h ere : cu rrentU s er = u s er
and P aymentStatu s . U NP A I D = is Nu l l ( payment. cu rrentStatu s . name, P aymentStatu s . U NP A I D )
o rder b y acco u nt. type. s o rtO rder, acco u nt. acco u ntNu mb er, payment. du eD ate
1 4 . 1 5 . B ul k up d ate and d el ete

H Q L n o w su p p o rts u pdate, del ete an d ins ert . . . s el ect . . . statem en ts. S ee S ec ti o n 1 3 .4 , “ D M L - styl e o p erati o n s”
fo r m o re i n fo rm ati o n .
1 4 . 1 6 . T ip s & T rick s
Y o u c an c o u n t th e n u m ber o f q u ery resu l ts w i th o u t retu rn i n g th em :
( ( I nteger) s es s io n. createQ u ery( " s el ect co u nt( *) f ro m . . . . " ). iterate( ). nex t( ) ). intV al u e( )
T o o rder a resu l t by th e si z e o f a c o l l ec ti o n , u se th e fo l l o w i n g q u ery:
s el ect u s r. id, u s r. name

f ro m U s er as u s r
l ef t j o in u s r. mes s ages as ms g
gro u p b y u s r. id, u s r. name
o rder b y co u nt( ms g)
I f yo u r database su p p o rts su bsel ec ts, yo u c an p l ac e a c o n di ti o n u p o n sel ec ti o n si z e i n th e w h ere c l au se o f

yo u r q u ery:
f ro m U s er u s r w h ere s iz e( u s r. mes s ages ) >= 1
I f yo u r database do es n o t su p p o rt su bsel ec ts, u se th e fo l l o w i n g q u ery:
1 6 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

f ro m U s er u s r. name
j o in u s r. mes s ages ms g
h av ing co u nt( ms g) >= 1
A s th i s so l u ti o n c an n o t retu rn a U s er w i th z ero m essages bec au se o f th e i n n er j o i n , th e fo l l o w i n g fo rm i s al so

u sefu l :

f ro m U s er as u s r
l ef t j o in u s r. mes s ages as ms g
h av ing co u nt( ms g) = 0
P ro p erti es o f a J av aB ean c an be bo u n d to n am ed q u ery p aram eters:
Q u ery q = s . createQ u ery( " f ro m f o o F o o as f o o w h ere f o o . name=: name and f o o . s iz e=: s iz e" );
q . s etP ro perties ( f o o B ean); / / f o o B ean h as getName( ) and getSiz e( )
L is t f o o s = q . l is t( );
Co l l ec ti o n s are p ageabl e by u si n g th e Q u ery i n terfac e w i th a fi l ter:
Q u ery q = s . createF il ter( co l l ectio n, " " ); / / th e triv ial f il ter

q . s etM ax R es u l ts ( P A G E _ SI Z E );
q . s etF irs tR es u l t( P A G E _ SI Z E * pageNu mb er);
L is t page = q . l is t( );
Co l l ec ti o n el em en ts c an be o rdered o r gro u p ed u si n g a q u ery fi l ter:
C o l l ectio n o rderedC o l l ectio n = s . f il ter( co l l ectio n, " o rder b y th is . amo u nt" );

C o l l ectio n co u nts = s . f il ter( co l l ectio n, " s el ect th is . type, co u nt( th is ) gro u p b y th is . type" );
Y o u c an fi n d th e si z e o f a c o l l ec ti o n w i th o u t i n i ti al i z i n g i t:
( ( I nteger) s es s io n. createQ u ery( " s el ect co u nt( *) f ro m . . . . " ). iterate( ). nex t( ) ). intV al u e( );
1 4 . 1 7 . C omp onents
Co m p o n en ts c an be u sed si m i l arl y to th e si m p l e v al u e typ es th at are u sed i n H Q L q u eri es. T h ey c an ap p ear
i n th e s el ect c l au se as fo l l o w s:
s el ect p. name f ro m P ers o n p
s el ect p. name. f irs t f ro m P ers o n p
w h ere th e P erso n ' s n am e p ro p erty i s a c o m p o n en t. Co m p o n en ts c an al so be u sed i n th e w h ere c l au se:
f ro m P ers o n p w h ere p. name = : name
f ro m P ers o n p w h ere p. name. f irs t = : f irs tName
Co m p o n en ts c an al so be u sed i n th e o rder b y c l au se:
f ro m P ers o n p o rder b y p. name
f ro m P ers o n p o rder b y p. name. f irs t
1 6 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
A n o th er c o m m o n u se o f c o m p o n en ts i s i n ro w v al u e c o n stru c to rs.
1 4 . 1 8 . Row v al ue cons tructor s y ntax

H Q L su p p o rts th e u se o f A N S I S Q L ro w v al u e co ns tru cto r syn tax , so m eti m es referred to A S tu pl e syn tax , ev en
th o u gh th e u n derl yi n g database m ay n o t su p p o rt th at n o ti o n . H ere, w e are gen eral l y referri n g to m u l ti -
v al u ed c o m p ari so n s, typ i c al l y asso c i ated w i th c o m p o n en ts. Co n si der an en ti ty P erso n w h i c h defi n es a n am e
c o m p o n en t:
f ro m P ers o n p w h ere p. name. f irs t=' J o h n' and p. name. l as t=' J ingl eh eimer- Sch midt'
T h at i s v al i d syn tax al th o u gh i t i s a l i ttl e v erbo se. Y o u c an m ak e th i s m o re c o n c i se by u si n g

ro w v al u e co ns tru cto r syn tax :
f ro m P ers o n p w h ere p. name=( ' J o h n' , ' J ingl eh eimer- Sch midt' )
I t c an al so be u sefu l to sp ec i fy th i s i n th e s el ect c l au se:
s el ect p. name f ro m P ers o n p
U si n g ro w v al u e co ns tru cto r syn tax c an al so be ben efi c i al w h en u si n g su bq u eri es th at n eed to c o m p are agai n st
m u l ti p l e v al u es:
f ro m C at as cat
w h ere no t ( cat. name, cat. co l o r ) in (
s el ect cat. name, cat. co l o r f ro m D o mes ticC at cat
)
O n e th i n g to c o n si der w h en dec i di n g i f yo u w an t to u se th i s syn tax , i s th at th e q u ery w i l l be dep en den t u p o n

th e o rderi n g o f th e c o m p o n en t su b- p ro p erti es i n th e m etadata.
C h ap ter 1 5 . C riteria Q ueries

1 5 .1 . Creati n g a C riteria i n stan c e
1 5 .2. N arro w i n g th e resu l t set
1 5 .3 . O rderi n g th e resu l ts
1 5 .4 . A sso c i ati o n s
1 5 .5 . D yn am i c asso c i ati o n fetc h i n g
1 5 .6 . E x am p l e q u eri es
1 5 .7 . P ro j ec ti o n s, aggregati o n an d gro u p i n g
1 5 .8 . D etac h ed q u eri es an d su bq u eri es
1 5 .9 . Q u eri es by n atu ral i den ti fi er
H i bern ate featu res an i n tu i ti v e, ex ten si bl e c ri teri a q u ery A P I .
1 5 . 1 . C reating a C riteria ins tance

T h e i n terfac e o rg. h ib ernate. C riteria rep resen ts a q u ery agai n st a p arti c u l ar p ersi sten t c l ass. T h e Ses s io n i s a
fac to ry fo r C riteria i n stan c es.
C riteria crit = s es s . createC riteria( C at. cl as s );

crit. s etM ax R es u l ts ( 50);
L is t cats = crit. l is t( );
1 6 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 5 . 2 . N arrow ing th e res ul t s et

A n i n di v i du al q u ery c ri teri o n i s an i n stan c e o f th e i n terfac e o rg. h ib ernate. criterio n. C riterio n. T h e c l ass
o rg. h ib ernate. criterio n. R es trictio ns defi n es fac to ry m eth o ds fo r o btai n i n g c ertai n bu i l t- i n C riterio n typ es.
L is t cats = s es s . createC riteria( C at. cl as s )

. add( R es trictio ns . l ik e( " name" , " F ritz % " ))
. add( R es trictio ns . b etw een( " w eigh t" , minW eigh t, max W eigh t) )
. l is t( );
R estri c ti o n s c an be gro u p ed l o gi c al l y.

. add( R es trictio ns . o r(
R es trictio ns . eq ( " age" , new I nteger( 0) ),
R es trictio ns . is Nu l l ( " age" )
))
. l is t( );

. add( R es trictio ns . in( " name" , new String[ ] { " F ritz " , " I z i" , " P k " } ) )
. add( R es trictio ns . dis j u nctio n( )
. add( R es trictio ns . is Nu l l ( " age" ) )
. add( R es trictio ns . eq ( " age" , new I nteger( 0) ) )
. add( R es trictio ns . eq ( " age" , new I nteger( 1) ) )
. add( R es trictio ns . eq ( " age" , new I nteger( 2 ) ) )
))
. l is t( );
T h ere are a ran ge o f bu i l t- i n c ri teri o n typ es (R es trictio ns su bc l asses). O n e o f th e m o st u sefu l al l o w s yo u to

sp ec i fy S Q L di rec tl y.

. add( R es trictio ns . s q l R es trictio n( " l o w er( {al ias }. name) l ik e l o w er( ?)" , " F ritz % " , H ib ernate. ST R I NG ) )
. l is t( );
T h e {al ias } p l ac eh o l der w i th be rep l ac ed by th e ro w al i as o f th e q u eri ed en ti ty.
Y o u c an al so o btai n a c ri teri o n fro m a P ro perty i n stan c e. Y o u c an c reate a P ro perty by c al l i n g

P ro perty. f o rName( ):
P ro perty age = P ro perty. f o rName( " age" );

. add( R es trictio ns . dis j u nctio n( )
. add( age. is Nu l l ( ) )
. add( age. eq ( new I nteger( 0) ) )
. add( age. eq ( new I nteger( 1) ) )
. add( age. eq ( new I nteger( 2 ) ) )
))
. add( P ro perty. f o rName( " name" ). in( new String[ ] { " F ritz " , " I z i" , " P k " } ) )
. l is t( );
1 5 . 3 . O rd ering th e res ul ts
Y o u c an o rder th e resu l ts u si n g o rg. h ib ernate. criterio n. O rder.
1 6 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

. add( R es trictio ns . l ik e( " name" , " F % " )
. addO rder( O rder. as c( " name" ) )
. addO rder( O rder. des c( " age" ) )
. s etM ax R es u l ts ( 50)
. l is t( );

. add( P ro perty. f o rName( " name" ). l ik e( " F % " ))
. addO rder( P ro perty. f o rName( " name" ). as c( ) )
. addO rder( P ro perty. f o rName( " age" ). des c( ) )
. l is t( );
1 5 . 4 . A s s ociations
B y n av i gati n g asso c i ati o n s u si n g createC riteria( ) yo u c an sp ec i fy c o n strai n ts u p o n rel ated en ti ti es:

. add( R es trictio ns . l ik e( " name" , " F % " ))
. createC riteria( " k ittens " )
. add( R es trictio ns . l ik e( " name" , " F % " ))
. l is t( );
T h e sec o n d createC riteria( ) retu rn s a n ew i n stan c e o f C riteria th at refers to th e el em en ts o f th e k ittens

c o l l ec ti o n .
T h ere i s al so an al tern ate fo rm th at i s u sefu l i n c ertai n c i rc u m stan c es:

. createA l ias ( " k ittens " , " k t" )
. createA l ias ( " mate" , " mt" )
. add( R es trictio ns . eq P ro perty( " k t. name" , " mt. name" ) )
. l is t( );
(createA l ias ( ) do es n o t c reate a n ew i n stan c e o f C riteria.)
T h e k i tten s c o l l ec ti o n s h el d by th e C at i n stan c es retu rn ed by th e p rev i o u s tw o q u eri es are not p refi l tered by

th e c ri teri a. I f yo u w an t to retri ev e j u st th e k i tten s th at m atc h th e c ri teri a, yo u m u st u se a R es u l tT rans f o rmer.

. createC riteria( " k ittens " , " k t" )
. add( R es trictio ns . eq ( " name" , " F % " ))
. s etR es u l tT rans f o rmer( C riteria. A L I A S_ T O _ E NT I T Y _ M A P )
. l is t( );
I terato r iter = cats . iterato r( );
w h il e ( iter. h as Nex t( ) ) {
M ap map = ( M ap) iter. nex t( );
C at cat = ( C at) map. get( C riteria. R O O T _ A L I A S);
C at k itten = ( C at) map. get( " k t" );
}
1 5 . 5 . Dy namic as s ociation fetch ing

Y o u c an sp ec i fy asso c i ati o n fetc h i n g sem an ti c s at ru n ti m e u si n g s etF etch M o de( ).
1 6 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

. s etF etch M o de( " mate" , F etch M o de. E A G E R )
. s etF etch M o de( " k ittens " , F etch M o de. E A G E R )
. l is t( );
T h i s q u ery w i l l fetc h bo th mate an d k ittens by o u ter j o i n . S ee S ec ti o n 1 9 .1 , “ F etc h i n g strategi es” fo r m o re

i n fo rm ati o n .
1 5 . 6 . E x amp l e q ueries
T h e c l ass o rg. h ib ernate. criterio n. E x ampl e al l o w s yo u to c o n stru c t a q u ery c ri teri o n fro m a gi v en i n stan c e.
C at cat = new C at( );

cat. s etSex ( ' F ' );
cat. s etC o l o r( C o l o r. B L A C K );
L is t res u l ts = s es s io n. createC riteria( C at. cl as s )
. add( E x ampl e. create( cat) )
. l is t( );
V ersi o n p ro p erti es, i den ti fi ers an d asso c i ati o n s are i gn o red. B y defau l t, n u l l v al u ed p ro p erti es are ex c l u ded.
Y o u c an adj u st h o w th e E x ampl e i s ap p l i ed.
E x ampl e ex ampl e = E x ampl e. create( cat)

. ex cl u deZ ero es ( ) / / ex cl u de z ero v al u ed pro perties
. ex cl u deP ro perty( " co l o r" ) / / ex cl u de th e pro perty named " co l o r"
. igno reC as e( ) / / perf o rm cas e ins ens itiv e s tring co mparis o ns
. enab l eL ik e( ); / / u s e l ik e f o r s tring co mparis o ns
. add( ex ampl e)
. l is t( );
Y o u c an ev en u se ex am p l es to p l ac e c ri teri a u p o n asso c i ated o bj ec ts.

. add( E x ampl e. create( cat) )
. createC riteria( " mate" )
. add( E x ampl e. create( cat. getM ate( ) ) )
. l is t( );
1 5 . 7 . P roj ections , ag g reg ation and g roup ing

T h e c l ass o rg. h ib ernate. criterio n. P ro j ectio ns i s a fac to ry fo r P ro j ectio n i n stan c es. Y o u c an ap p l y a p ro j ec ti o n to a
q u ery by c al l i n g s etP ro j ectio n( ).

. s etP ro j ectio n( P ro j ectio ns . ro w C o u nt( ) )
. add( R es trictio ns . eq ( " co l o r" , C o l o r. B L A C K ) )
. l is t( );
1 6 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

. s etP ro j ectio n( P ro j ectio ns . pro j ectio nL is t( )
. add( P ro j ectio ns . ro w C o u nt( ) )
. add( P ro j ectio ns . av g( " w eigh t" ) )
. add( P ro j ectio ns . max ( " w eigh t" ) )
. add( P ro j ectio ns . gro u pP ro perty( " co l o r" ) )
)
. l is t( );
T h ere i s n o ex p l i c i t " gro u p by" n ec essary i n a c ri teri a q u ery. Certai n p ro j ec ti o n typ es are defi n ed to be
g roup ing p roj e c tions , w h i c h al so ap p ear i n th e S Q L gro u p b y c l au se.
A n al i as c an be assi gn ed to a p ro j ec ti o n so th at th e p ro j ec ted v al u e c an be referred to in restri c ti o n s o r

o rderi n gs. H ere are tw o di fferen t w ays to do th i s:

. s etP ro j ectio n( P ro j ectio ns . al ias ( P ro j ectio ns . gro u pP ro perty( " co l o r" ), " co l r" ) )
. addO rder( O rder. as c( " co l r" ) )
. l is t( );

. s etP ro j ectio n( P ro j ectio ns . gro u pP ro perty( " co l o r" ). as ( " co l r" ) )
. addO rder( O rder. as c( " co l r" ) )
. l is t( );
T h e al ias ( ) an d as ( ) m eth o ds si m p l y w rap a p ro j ec ti o n i n stan c e i n an o th er, al i ased, i n stan c e o f P ro j ectio n. A s a

sh o rtc u t, yo u c an assi gn an al i as w h en yo u add th e p ro j ec ti o n to a p ro j ec ti o n l i st:

. add( P ro j ectio ns . ro w C o u nt( ), " catC o u ntB yC o l o r" )
. add( P ro j ectio ns . av g( " w eigh t" ), " av gW eigh t" )
. add( P ro j ectio ns . max ( " w eigh t" ), " max W eigh t" )
. add( P ro j ectio ns . gro u pP ro perty( " co l o r" ), " co l o r" )
)
. addO rder( O rder. des c( " catC o u ntB yC o l o r" ) )
. addO rder( O rder. des c( " av gW eigh t" ) )
. l is t( );
L is t res u l ts = s es s io n. createC riteria( D o mes tic. cl as s , " cat" )

. createA l ias ( " k ittens " , " k it" )
. add( P ro j ectio ns . pro perty( " cat. name" ), " catName" )
. add( P ro j ectio ns . pro perty( " k it. name" ), " k itName" )
)
. addO rder( O rder. as c( " catName" ) )
. addO rder( O rder. as c( " k itName" ) )
. l is t( );
Y o u c an al so u se P ro perty. f o rName( ) to ex p ress p ro j ec ti o n s:

. s etP ro j ectio n( P ro perty. f o rName( " name" ) )
. add( P ro perty. f o rName( " co l o r" ). eq ( C o l o r. B L A C K ) )
. l is t( );
1 7 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

. add( P ro j ectio ns . ro w C o u nt( ). as ( " catC o u ntB yC o l o r" ) )
. add( P ro perty. f o rName( " w eigh t" ). av g( ). as ( " av gW eigh t" ) )
. add( P ro perty. f o rName( " w eigh t" ). max ( ). as ( " max W eigh t" ) )
. add( P ro perty. f o rName( " co l o r" ). gro u p( ). as ( " co l o r" )
)
. addO rder( O rder. des c( " catC o u ntB yC o l o r" ) )
. addO rder( O rder. des c( " av gW eigh t" ) )
. l is t( );
1 5 . 8 . Detach ed q ueries and s ubq ueries

T h e D etach edC riteria c l ass al l o w s yo u to c reate a q u ery o u tsi de th e sc o p e o f a sessi o n an d th en ex ec u te i t
u si n g an arbi trary Ses s io n.
D etach edC riteria q u ery = D etach edC riteria. f o rC l as s ( C at. cl as s )

. add( P ro perty. f o rName( " s ex " ). eq ( ' F ' ) );
Ses s io n s es s io n = . . . . ;
T rans actio n tx n = s es s io n. b eginT rans actio n( );
L is t res u l ts = q u ery. getE x ecu tab l eC riteria( s es s io n). s etM ax R es u l ts ( 100). l is t( );
tx n. co mmit( );
A D etach edC riteria c an al so be u sed to ex p ress a su bq u ery. Cri teri o n i n stan c es i n v o l v i n g su bq u eri es c an be
o btai n ed v i a Su b q u eries o r P ro perty.
D etach edC riteria av gW eigh t = D etach edC riteria. f o rC l as s ( C at. cl as s )

. s etP ro j ectio n( P ro perty. f o rName( " w eigh t" ). av g( ) );
s es s io n. createC riteria( C at. cl as s )
. add( P ro perty. f o rName( " w eigh t" ). gt( av gW eigh t) )
. l is t( );
D etach edC riteria w eigh ts = D etach edC riteria. f o rC l as s ( C at. cl as s )

. s etP ro j ectio n( P ro perty. f o rName( " w eigh t" ) );
s es s io n. createC riteria( C at. cl as s )
. add( Su b q u eries . geA l l ( " w eigh t" , w eigh ts ) )
. l is t( );
Co rrel ated su bq u eri es are al so p o ssi bl e:
D etach edC riteria av gW eigh tF o rSex = D etach edC riteria. f o rC l as s ( C at. cl as s , " cat2 " )
. s etP ro j ectio n( P ro perty. f o rName( " w eigh t" ). av g( ) )
. add( P ro perty. f o rName( " cat2 . s ex " ). eq P ro perty( " cat. s ex " ) );
s es s io n. createC riteria( C at. cl as s , " cat" )
. add( P ro perty. f o rName( " w eigh t" ). gt( av gW eigh tF o rSex ) )
. l is t( );
1 5 . 9 . Q ueries by natural id entifier

F o r m o st q u eri es, i n c l u di n gc ri teri a q u eri es, th e q u ery c ac h e i s n o t effi c i en t bec au se q u ery c ac h e i n v al i dati o n
o c c u rs to o freq u en tl y. H o w ev er, th ere i s a sp ec i al k i n d o f q u ery w h ere yo u c an o p ti m i z e th e c ac h e
i n v al i dati o n al go ri th m : l o o k u p s by a c o n stan t n atu ral k ey. I n so m e ap p l i c ati o n s, th i s k i n d o f q u ery o c c u rs
freq u en tl y. T h e c ri teri a A P I p ro v i des sp ec i al p ro v i si o n fo r th i s u se c ase.
F i rst, m ap th e n atu ral k ey o f yo u r en ti ty u si n g < natu ral - id> an d en abl e u se o f th e sec o n d- l ev el c ac h e.
1 7 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" U s er" >

< cach e u s age=" read- w rite" / >
< id name=" id" >
< generato r cl as s =" increment" / >
< / id>
< natu ral - id>
< pro perty name=" o rg" / >
< / natu ral - id>
< pro perty name=" pas s w o rd" / >
< / cl as s >
T h i s fu n c ti o n al i ty i s n o t i n ten ded fo r u se w i th en ti ti es w i th m utab le n atu ral k eys.
O n c e yo u h av e en abl ed th e H i bern ate q u ery c ac h e, th e R es trictio ns . natu ral I d( ) al l o w s yo u to m ak e u se o f th e

m o re effi c i en t c ac h e al go ri th m .
s es s io n. createC riteria( U s er. cl as s )

. add( R es trictio ns . natu ral I d( )
. s et( " name" , " gav in" )
. s et( " o rg" , " h b " )
). s etC ach eab l e( tru e)
. u niq u eR es u l t( );
C h ap ter 1 6 . N ativ e S Q L
1 6 .1 . U si n g a SQ L Q u ery
1 6 .1 .1 . S c al ar q u eri es
1 6 .1 .2. E n ti ty q u eri es
1 6 .1 .3 . H an dl i n g asso c i ati o n s an d c o l l ec ti o n s
1 6 .1 .4 . R etu rn i n g m u l ti p l e en ti ti es
1 6 .1 .5 . R etu rn i n g n o n - m an aged en ti ti es
1 6 .1 .6 . H an dl i n g i n h eri tan c e
1 6 .1 .7 . P aram eters
1 6 .2. N am ed S Q L q u eri es
1 6 .2.1 . U si n g retu rn - p ro p erty to ex p l i c i tl y sp ec i fy c o l u m n /al i as n am es
1 6 .2.2. U si n g sto red p ro c edu res fo r q u eryi n g
1 6 .3 . Cu sto m S Q L fo r c reate, u p date an d del ete
1 6 .4 . Cu sto m S Q L fo r l o adi n g
Y o u c an al so ex p ress q u eri es i n th e n ati v e S Q L di al ec t o f yo u r database. T h i s i s u sefu l i f yo u w an t to u ti l i z e

database- sp ec i fi c featu res su c h as q u ery h i n ts o r th e C O NNE C T k eyw o rd i n O rac l e. I t al so p ro v i des a c l ean
m i grati o n p ath fro m a di rec t S Q L /J D B C based ap p l i c ati o n to H i bern ate.
H i bern ate3 al l o w s yo u to sp ec i fy h an dw ri tten S Q L , i n c l u di n g sto red p ro c edu res, fo r al l c reate, u p date, del ete,
an d l o ad o p erati o n s.
1 6 . 1 . U s ing a SQ L Q u ery
E x ec u ti o n o f n ati v e S Q L q u eri es i s c o n tro l l ed v i a th e SQ L Q u ery i n terfac e, w h i c h i s o btai n ed by c al l i n g
Ses s io n. createSQ L Q u ery( ). T h e fo l l o w i n g sec ti o n s desc ri be h o w to u se th i s A P I fo r q u eryi n g.
1 6 . 1 . 1 . S c al ar q u e ri e s
T h e m o st basi c S Q L q u ery i s to get a l i st o f sc al ars (v al u es).
1 7 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
s es s . createSQ L Q u ery( " SE L E C T * F R O M C A T S" ). l is t( );

s es s . createSQ L Q u ery( " SE L E C T I D , NA M E , B I R T H D A T E F R O M C A T S" ). l is t( );
T h ese w i l l retu rn a L i st o f O bj ec t arrays (O bj ec t[] ) w i th sc al ar v al u es fo r eac h c o l u m n i n th e CA T S tabl e.

H i bern ate w i l l u se R esu l tS etM etadata to dedu c e th e ac tu al o rder an d typ es o f th e retu rn ed sc al ar v al u es.
T o av o i d th e o v erh ead o f u si n g R es u l tSetM etadata , o r si m p l y to be m o re ex p l i c i t i n w h at i s retu rn ed, o n e c an

u se addScal ar( ):
s es s . createSQ L Q u ery( " SE L E C T * F R O M C A T S" )

. addScal ar( " I D " , H ib ernate. L O NG )
. addScal ar( " NA M E " , H ib ernate. ST R I NG )
. addScal ar( " B I R T H D A T E " , H ib ernate. D A T E )
T h i s q u ery sp ec i fi ed:
th e S Q L q u ery stri n g
th e c o l u m n s an d typ es to retu rn
T h i s w i l l retu rn O bj ec t arrays, bu t n o w i t w i l l n o t u se R es u l tSetM etadata bu t w i l l i n stead ex p l i c i tl y get th e I D ,

N A M E an d B I R T H D A T E c o l u m n as resp ec ti v el y a L o n g, S tri n g an d a S h o rt fro m th e u n derl yi n g resu l tset. T h i s
al so m ean s th at o n l y th ese th ree c o l u m n s w i l l be retu rn ed, ev en th o u gh th e q u ery i s u si n g * an d c o u l d retu rn
m o re th an th e th ree l i sted c o l u m n s.
I t i s p o ssi bl e to l eav e o u t th e typ e i n fo rm ati o n fo r al l o r so m e o f th e sc al ars.
s es s . createSQ L Q u ery( " SE L E C T * F R O M C A T S" )

. addScal ar( " I D " , H ib ernate. L O NG )
. addScal ar( " NA M E " )
. addScal ar( " B I R T H D A T E " )
T h i s i s essen ti al l y th e sam e q u ery as befo re, bu t n o w R es u l tSetM etaD ata i s u sed to determ i n e th e typ e o f
N A M E an d B I R T H D A T E , w h ere as th e typ e o f I D i s ex p l i c i tl y sp ec i fi ed.
H o w th e j av a.sq l .T yp es retu rn ed fro m R esu l tS etM etaD ata i s m ap p ed to H i bern ate typ es i s c o n tro l l ed by th e
D i al ec t. I f a sp ec i fi c typ e i s n o t m ap p ed, o r do es n o t resu l t i n th e ex p ec ted typ e, i t i s p o ssi bl e to c u sto m i z e i t
v i a c al l s to regis terH ib ernateT ype i n th e D i al ec t.
1 6 . 1 . 2 . E nti ty q u e ri e s
T h e abo v e q u eri es w ere al l abo u t retu rn i n g sc al ar v al u es, basi c al l y retu rn i n g th e " raw " v al u es fro m th e
resu l tset. T h e fo l l o w i n g sh o w s h o w to get en ti ty o bj ec ts fro m a n ati v e sq l q u ery v i a addE ntity( ).
s es s . createSQ L Q u ery( " SE L E C T * F R O M C A T S" ). addE ntity( C at. cl as s );

s es s . createSQ L Q u ery( " SE L E C T I D , NA M E , B I R T H D A T E F R O M C A T S" ). addE ntity( C at. cl as s );
th e en ti ty retu rn ed by th e q u ery
A ssu m i n g th at Cat i s m ap p ed as a c l ass w i th th e c o l u m n sI D , N A M E an d B I R T H D A T E th e abo v e q u eri es w i l l

bo th retu rn a L i st w h ere eac h el em en t i s a Cat en ti ty.
I f th e en ti ty i s m ap p ed w i th a many- to - o ne to an o th er en ti ty i t i s req u i red to al so retu rn th i s w h en p erfo rm i n g

th e n ati v e q u ery, o th erw i se a database sp ec i fi c " c o l u m n n o t fo u n d" erro r w i l l o c c u r. T h e addi ti o n al c o l u m n s
w i l l au to m ati c al l y be retu rn ed w h en u si n g th e * n o tati o n , bu t w e p refer to be ex p l i c i t as i n th e fo l l o w i n g
ex am p l e fo r a many- to - o ne to a D o g :
s es s . createSQ L Q u ery( " SE L E C T I D , NA M E , B I R T H D A T E , D O G _ I D F R O M C A T S" ). addE ntity( C at. cl as s );
1 7 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h i s w i l l al l o w c at.getD o g() to fu n c ti o n p ro p erl y.
1 6 . 1 . 3 . H and l i ng as s oc i ati ons and c ol l e c ti ons
I t i s p o ssi bl e to eagerl y j o i n i n th e D o g to av o i d th e p o ssi bl e ex tra ro u n dtri p fo r i n i ti al i z i n g th e p ro x y. T h i s i s

do n e v i a th e addJ o in( ) m eth o d, w h i c h al l o w s yo u to j o i n i n an asso c i ati o n o r c o l l ec ti o n .
s es s . createSQ L Q u ery( " SE L E C T c. I D , NA M E , B I R T H D A T E , D O G _ I D , D _ I D , D _ NA M E F R O M C A T S c, D O G S d W H E R E c. D O G _ I D = d. D _ I D " )

. addJ o in( " cat. do g" );
I n th i s ex am p l e, th e retu rn ed C at ' s w i l l h av e th ei r do g p ro p erty fu l l y i n i ti al i z ed w i th o u t an y ex tra ro u n dtri p to

th e database. N o ti c e th at yo u added an al i as n am e (" c at" ) to be abl e to sp ec i fy th e target p ro p erty p ath o f
th e j o i n . I t i s p o ssi bl e to do th e sam e eager j o i n i n g fo r c o l l ec ti o n s, e.g. i f th e C at h ad a o n e- to - m an y to D o g
i n stead.
s es s . createSQ L Q u ery( " SE L E C T I D , NA M E , B I R T H D A T E , D _ I D , D _ NA M E , C A T _ I D F R O M C A T S c, D O G S d W H E R E c. I D = d. C A T _ I D " )

. addJ o in( " cat. do gs " );
A t th i s stage yo u are reac h i n g th e l i m i ts o f w h at i s p o ssi bl e w i th n ati v e q u eri es, w i th o u t starti n g to en h an c e

th e sq l q u eri es to m ak e th em u sabl e i n H i bern ate. P ro bl em s c an ari se w h en retu rn i n g m u l ti p l e en ti ti es o f th e
sam e typ e o r w h en th e defau l t al i as/c o l u m n n am es are n o t en o u gh .
1 6 . 1 . 4 . R e tu rni ng mu l ti pl e e nti ti e s
U n ti l n o w , th e resu l t set c o l u m n n am es are assu m ed to be th e sam e as th e c o l u m n n am es sp ec i fi ed i n th e

m ap p i n g do c u m en t. T h i s c an be p ro bl em ati c fo r S Q L q u eri es th at j o i n m u l ti p l e tabl es, si n c e th e sam e c o l u m n
n am es c an ap p ear i n m o re th an o n e tabl e.
Co l u m n al i as i n j ec ti o n i s n eeded i n th e fo l l o w i n g q u ery (w h i c h m o st l i k el y w i l l fai l ):
s es s . createSQ L Q u ery( " SE L E C T c. *, m. * F R O M C A T S c, C A T S m W H E R E c. M O T H E R _ I D = c. I D " )

. addE ntity( " mo th er" , C at. cl as s )
T h e q u ery w as i n ten ded to retu rn tw o Cat i n stan c es p er ro w : a c at an d i ts m o th er. T h e q u ery w i l l , h o w ev er,

fai l bec au se th ere i s a c o n fl i c t o f n am es; th e i n stan c es are m ap p ed to th e sam e c o l u m n n am es. A l so , o n
so m e databases th e retu rn ed c o l u m n al i ases w i l l m o st l i k el y be o n th e fo rm " c .I D " , " c .N A M E " , etc . w h i c h are
n o t eq u al to th e c o l u m n s sp ec i fi ed i n th e m ap p i n gs (" I D " an d " N A M E " ).
T h e fo l l o w i n g fo rm i s n o t v u l n erabl e to c o l u m n n am e du p l i c ati o n :
s es s . createSQ L Q u ery( " SE L E C T {cat. *}, {mo th er. *} F R O M C A T S c, C A T S m W H E R E c. M O T H E R _ I D = c. I D " )

. addE ntity( " mo th er" , C at. cl as s )
th e S Q L q u ery stri n g, w i th p l ac eh o l ders fo r H i bern ate to i n j ec t c o l u m n al i ases
th e en ti ti es retu rn ed by th e q u ery
T h e { c at.* } an d { m o th er.* } n o tati o n u sed abo v e i s a sh o rth an d fo r " al l p ro p erti es" . A l tern ati v el y, yo u c an
l i st th e c o l u m n s ex p l i c i tl y, bu t ev en i n th i s c ase H i bern ate i n j ec ts th e S Q L c o l u m n al i ases fo r eac h p ro p erty.
T h e p l ac eh o l der fo r a c o l u m n al i as i s j u st th e p ro p erty n am e q u al i fi ed by th e tabl e al i as. I n th e fo l l o w i n g
ex am p l e, yo u retri ev e Cats an d th ei r m o th ers fro m a di fferen t tabl e (c at_ l o g) to th e o n e dec l ared i n th e
m ap p i n g m etadata. Y o u c an ev en u se th e p ro p erty al i ases i n th e w h ere c l au se.
1 7 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
String s q l = " SE L E C T I D as {c. id}, NA M E as {c. name}, " +

" B I R T H D A T E as {c. b irth D ate}, M O T H E R _ I D as {c. mo th er}, {mo th er. *} " +
" F R O M C A T _ L O G c, C A T _ L O G mW H E R E {c. mo th er} = c. I D " ;
L is t l o ggedC ats = s es s . createSQ L Q u ery( s q l )

. addE ntity( " mo th er" , C at. cl as s ). l is t( )
16 .1.4 .1. A lia s a nd p rop erty ref erenc es
I n m o st c ases th e abo v e al i as i n j ec ti o n i s n eeded. F o r q u eri es rel ati n g to m o re c o m p l ex m ap p i n gs, l i k e

c o m p o si te p ro p erti es, i n h eri tan c e di sc ri m i n ato rs, c o l l ec ti o n s etc ., yo u c an u se sp ec i fi c al i ases th at al l o w
H i bern ate to i n j ec t th e p ro p er al i ases.
T h e fo l l o w i n g tabl e sh o w s th e di fferen t w ays yo u c an u se th e al i as i n j ec ti o n . P l ease n o te th at th e al i as n am es

i n th e resu l t are si m p l y ex am p l es; eac h al i as w i l l h av e a u n i q u e an d p ro babl y di fferen t n am e w h en u sed.
Table 16 .1. A lias inj ec tion nam es
Desc ription S y ntax E x am ple
A si m p l e
{[ al ias name] . [ pro pertyname] A _ NA M E as {item. name}
p ro p erty
A c o m p o si te
{[ al ias name] . [ co mpo nentname] . [ pro pertyname] } C U R R E NC Y as {item. amo u nt. cu rrency}, V A L U E as {item. amo u nt. v al u e}
p ro p erty
D i sc ri m i n ato r
{[ al ias name] . cl as s } D I SC as {item. cl as s }
o f an en ti ty
A l l p ro p erti es
{[ al ias name] . *} {item. *}
o f an en ti ty
A c o l l ec ti o n
{[ al ias name] . k ey} O R G I D as {co l l . k ey}
k ey
T h e i d o f an
{[ al ias name] . id} E M P I D as {co l l . id}
c o l l ec ti o n
T h e el em en t
o f an {[ al ias name] . el ement} X I D as {co l l . el ement}
c o l l ec ti o n
p ro p erty o f
th e el em en t
{[ al ias name] . el ement. [ pro pertyname] } NA M E as {co l l . el ement. name}
in th e
c o l l ec ti o n
o f th e
{[ al ias name] . el ement. *} {co l l . el ement. *}
el em en t in
th e c o l l ec ti o n
o f th e th e {[ al ias name] . *} {co l l . *}
c o l l ec ti o n
1 6 . 1 . 5 . R e tu rni ng non- manag e d e nti ti e s
I t i s p o ssi bl e to ap p l y a R esu l tT ran sfo rm er to n ati v e S Q L q u eri es, al l o w i n g i t to retu rn n o n - m an aged en ti ti es.
s es s . createSQ L Q u ery( " SE L E C T NA M E , B I R T H D A T E F R O M C A T S" )

. s etR es u l tT rans f o rmer( T rans f o rmers . al ias T o B ean( C atD T O . cl as s ))
1 7 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
a resu l t tran sfo rm er
T h e abo v e q u ery w i l l retu rn a l i st o f C atD T O w h i c h h as been i n stan ti ated an d i n j ec ted th e v al u es o f N A M E an d

B I R T H N A M E i n to i ts c o rresp o n di n g p ro p erti es o r fi el ds.
1 6 . 1 . 6 . H and l i ng i nh e ri tanc e
N ati v e S Q L q u eri es w h i c h q u ery fo r en ti ti es th at are m ap p ed as p art o f an i n h eri tan c e m u st i n c l u de al l

p ro p erti es fo r th e basec l ass an d al l i ts su bc l asses.
1 6 . 1 . 7 . P arame te rs
N ati v e S Q L q u eri es su p p o rt p o si ti o n al as w el l as n am ed p aram eters:
Q u ery q u ery = s es s . createSQ L Q u ery( " SE L E C T * F R O M C A T SW H E R E NA M E l ik e ?" ). addE ntity( C at. cl as s );

L is t pu s L is t = q u ery. s etString( 0, " P u s % " ). l is t( );
q u ery = s es s . createSQ L Q u ery( " SE L E C T *F R O M C A T SW H E R E NA M E l ik e : name" ). addE ntity( C at. cl as s );

L is t pu s L is t = q u ery. s etString( " name" , " P u s % " ). l is t( );
1 6 . 2 . N amed S Q L q ueries
N am ed S Q L q u eri es c an be defi n ed i n th e m ap p i n g do c u m en t an d c al l ed i n ex ac tl y th e sam e w ay as a n am ed
H Q L q u ery. I n th i s c ase, yo u do not n eed to c al l addE ntity( ).
< s q l - q u ery name=" pers o ns " >

< retu rn al ias =" pers o n" cl as s =" eg. P ers o n" / >
SE L E C T pers o n. NA M E A S {pers o n. name},
pers o n. A G E A S {pers o n. age},
pers o n. SE X A S {pers o n. s ex }
F R O M P E R SO N pers o n
W H E R E pers o n. NA M E L I K E : nameP attern
< / s q l - q u ery>
L is t peo pl e = s es s . getNamedQ u ery( " pers o ns " )

. s etString( " nameP attern" , nameP attern)
. l is t( );
T h e < retu rn- j o in> el em en t i s u se to jo in asso c i ati o n s an d th e < l o ad- co l l ectio n> el em en t i s u sed to defi n e
q u eri es w h i c h i n i ti al i z e c o l l ec ti o n s,
1 7 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< s q l - q u ery name=" pers o ns W ith " >

< retu rn- j o in al ias =" addres s " pro perty=" pers o n. mail ingA ddres s " / >
pers o n. SE X A S {pers o n. s ex },
addres s . ST R E E T A S {addres s . s treet},
addres s . C I T Y A S {addres s . city},
addres s . ST A T E A S {addres s . s tate},
addres s . Z I P A S {addres s . z ip}
J O I N A D D R E SS addres s
O N pers o n. I D = addres s . P E R SO N_ I D A ND addres s . T Y P E =' M A I L I NG '
A n am ed S Q L q u ery m ay retu rn a sc al ar v al u e. Y o u m u st dec l are th e c o l u m n al i as an d H i bern ate typ e u si n g

th e < retu rn- s cal ar> el em en t:
< s q l - q u ery name=" mySq l Q u ery" >

< retu rn- s cal ar co l u mn=" name" type=" s tring" / >
< retu rn- s cal ar co l u mn=" age" type=" l o ng" / >
SE L E C T p. NA M E A S name,
p. A G E A S age,
F R O M P E R SO N p W H E R E p. NA M E L I K E ' H ib er% '
Y o u c an ex tern al i z e th e resu l tset m ap p i n g i n fo rm ati o n i n a < res u l ts et> el em en t w h i c h w i l l al l o w yo u to ei th er

reu se th em ac ro ss sev eral n am ed q u eri es o r th ro u gh th e s etR es u l tSetM apping( ) A P I .
< res u l ts et name=" pers o nA ddres s " >

< retu rn- j o in al ias =" addres s " pro perty=" pers o n. mail ingA ddres s " / >
< / res u l ts et>
< s q l - q u ery name=" pers o ns W ith " res u l ts et- ref =" pers o nA ddres s " >
pers o n. SE X A S {pers o n. s ex },
addres s . ST R E E T A S {addres s . s treet},
addres s . C I T Y A S {addres s . city},
addres s . ST A T E A S {addres s . s tate},
addres s . Z I P A S {addres s . z ip}
J O I N A D D R E SS addres s
O N pers o n. I D = addres s . P E R SO N_ I D A ND addres s . T Y P E =' M A I L I NG '
Y o u c an , al tern ati v el y, u se th e resu l tset m ap p i n g i n fo rm ati o n i n yo u r h bm fi l es di rec tl y i n j av a c o de.
L is t cats = s es s . createSQ L Q u ery(

" s el ect {cat. *}, {k itten. *} f ro m cats cat, cats k itten w h ere k itten. mo th er = cat. id"
)
. s etR es u l tSetM apping( " catA ndK itten" )
. l is t( );
1 6 . 2 . 1 . U s i ng re tu rn- prope rty to e x pl i c i tl y s pe c i f y c ol u mn/ al i as name s
1 7 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
Y o u c an ex p l i c i tl y tel l H i bern ate w h at c o l u m n al i ases to u se w i th < retu rn- pro perty>, i n stead o f u si n g th e
{}- syn tax to l et H i bern ate i n j ec t i ts o w n al i ases.F o r ex am p l e:
< s q l - q u ery name=" mySq l Q u ery" >

< retu rn al ias =" pers o n" cl as s =" eg. P ers o n" >
< retu rn- pro perty name=" name" co l u mn=" myName" / >
< retu rn- pro perty name=" age" co l u mn=" myA ge" / >
< retu rn- pro perty name=" s ex " co l u mn=" mySex " / >
< / retu rn>
SE L E C T pers o n. NA M E A S myName,
pers o n. A G E A S myA ge,
pers o n. SE X A S mySex ,
F R O M P E R SO N pers o n W H E R E pers o n. NA M E L I K E : name
< retu rn- pro perty> al so w o rk s w i th m u l ti p l e c o l u m n s. T h i s so l v es a l i m i tati o n w i th th e {}- syn tax w h i c h c an n o t

al l o w fi n e grai n ed c o n tro l o f m u l ti - c o l u m n p ro p erti es.
< s q l - q u ery name=" o rganiz atio nC u rrentE mpl o yments " >
< retu rn al ias =" emp" cl as s =" E mpl o yment" >
< retu rn- pro perty name=" s al ary" >
< retu rn- co l u mn name=" V A L U E " / >
< retu rn- co l u mn name=" C U R R E NC Y " / >
< / retu rn- pro perty>
< retu rn- pro perty name=" endD ate" co l u mn=" myE ndD ate" / >
< / retu rn>
SE L E C T E M P L O Y E E A S {emp. empl o yee}, E M P L O Y E R A S {emp. empl o yer},
ST A R T D A T E A S {emp. s tartD ate}, E ND D A T E A S {emp. endD ate},
R E G I O NC O D E as {emp. regio nC o de}, E I D A S {emp. id}, V A L U E , C U R R E NC Y
F R O M E M P L O Y M E NT
W H E R E E M P L O Y E R = : id A ND E ND D A T E I S NU L L
O R D E R B Y ST A R T D A T E A SC
I n th i s ex am p l e < retu rn- pro perty> w as u sed i n c o m bi n ati o n w i th th e {}- syn tax fo r i n j ec ti o n . T h i s al l o w s u sers
to c h o o se h o w th ey w an t to refer c o l u m n an d p ro p erti es.
I f yo u r m ap p i n g h as a di sc ri m i n ato r yo u m u st u se < retu rn- dis criminato r> to sp ec i fy th e di sc ri m i n ato r c o l u m n .
1 6 . 2 . 2 . U s i ng s tore d proc e d u re s f or q u e ry i ng
H i bern ate3 p ro v i des su p p o rt fo r q u eri es v i a sto red p ro c edu res an d fu n c ti o n s. M o st o f th e fo l l o w i n g

do c u m en tati o n i s eq u i v al en t fo r bo th . T h e sto red p ro c edu re/fu n c ti o n m u st retu rn a resu l tset as th e fi rst
o u t- p aram eter to be abl e to w o rk w i th H i bern ate. A n ex am p l e o f su c h a sto red fu n c ti o n i n O rac l e 9 an d
h i gh er i s as fo l l o w s:
C R E A T E O R R E P L A C E F U NC T I O N s el ectA l l E mpl o yments

R E T U R N SY S_ R E F C U R SO R
A S
s t_ cu rs o r SY S_ R E F C U R SO R ;
B E G I N
O P E N s t_ cu rs o r F O R
SE L E C T E M P L O Y E E , E M P L O Y E R ,
ST A R T D A T E , E ND D A T E ,
R E G I O NC O D E , E I D , V A L U E , C U R R E NC Y
F R O M E M P L O Y M E NT ;
R E T U R N s t_ cu rs o r;
E ND ;
T o u se th i s q u ery i n H i bern ate yo u n eed to m ap i t v i a a n am ed q u ery.
1 7 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< s q l - q u ery name=" s el ectA l l E mpl o yees _ SP " cal l ab l e=" tru e" >
< retu rn al ias =" emp" cl as s =" E mpl o yment" >
< retu rn- pro perty name=" empl o yee" co l u mn=" E M P L O Y E E " / >
< retu rn- pro perty name=" empl o yer" co l u mn=" E M P L O Y E R " / >
< retu rn- pro perty name=" s tartD ate" co l u mn=" ST A R T D A T E " / >
< retu rn- pro perty name=" endD ate" co l u mn=" E ND D A T E " / >
< retu rn- pro perty name=" regio nC o de" co l u mn=" R E G I O NC O D E " / >
< retu rn- pro perty name=" id" co l u mn=" E I D " / >
< retu rn- pro perty name=" s al ary" >
< retu rn- co l u mn name=" V A L U E " / >
< retu rn- co l u mn name=" C U R R E NC Y " / >
< / retu rn- pro perty>
< / retu rn>
{ ? = cal l s el ectA l l E mpl o yments ( ) }
S to red p ro c edu res c u rren tl y o n l y retu rn sc al ars an d en ti ti es. < retu rn- j o in> an d < l o ad- co l l ectio n> are n o t
su p p o rted.
16 .2 .2 .1. Ru les/ lim ita tions f or u sing stored p roc ed u res
Y o u c an n o t u se sto red p ro c edu res w i th H i bern ate u n l ess yo u fo l l o w so m e p ro c edu re/fu n c ti o n ru l es. I f th ey do
n o t fo l l o w th o se ru l es th ey are n o t u sabl e w i th H i bern ate. I f yo u sti l l w an t to u se th ese p ro c edu res yo u h av e
to ex ec u te th em v i a s es s io n. co nnectio n( ). T h e ru l es are di fferen t fo r eac h database, si n c e database v en do rs
h av e di fferen t sto red p ro c edu re sem an ti c s/syn tax .
S to red p ro c edu re q u eri es c an n o t be p aged w i th s etF irs tR es u l t( )/ s etM ax R es u l ts ( ).
T h e rec o m m en ded c al l fo rm is stan dard S Q L 9 2: { ? = cal l f u nctio nName( < parameters >) } o r
{ ? = cal l pro cedu reName( < parameters >}. N ati v e c al l syn tax i s n o t su p p o rted.
F o r O rac l e th e fo l l o w i n g ru l es ap p l y:
A fu n c ti o n m u st retu rn a resu l t set. T h e fi rst p aram eter o f a p ro c edu re m u st be an O U T th at retu rn s a

resu l t set. T h i s i s do n e by u si n g a SY S_ R E F C U R SO R typ e i n O rac l e 9 o r 1 0 . I n O rac l e yo u n eed to defi n e a
R E F C U R SO R typ e. S ee O rac l e l i teratu re fo r fu rth er i n fo rm ati o n .
F o r S ybase o r M S S Q L serv er th e fo l l o w i n g ru l es ap p l y:
T h e p ro c edu re m u st retu rn a resu l t set. N o te th at si n c e th ese serv ers c an retu rn m u l ti p l e resu l t sets an d
u p date c o u n ts, H i bern ate w i l l i terate th e resu l ts an d tak e th e fi rst resu l t th at i s a resu l t set as i ts retu rn
v al u e. E v eryth i n g el se w i l l be di sc arded.
I f yo u c an en abl e SE T NO C O U NT O N i n yo u r p ro c edu re i t w i l l p ro babl y be m o re effi c i en t, bu t th i s i s n o t a
req u i rem en t.
1 6 . 3 . C us tom S Q L for create, up d ate and d el ete

H i bern ate3 c an u se c u sto m S Q L statem en ts fo r c reate, u p date, an d del ete o p erati o n s. T h e c l ass an d
c o l l ec ti o n p ersi sters i n H i bern ate al ready c o n tai n a set o f c o n fi gu rati o n ti m e gen erated stri n gs (i n sertsq l ,
del etesq l , u p datesq l etc .). T h e m ap p i n g tags < s q l - ins ert>, < s q l - del ete>, an d < s q l - u pdate> o v erri de th ese
stri n gs:
1 7 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< id name=" id" >
< / id>
< pro perty name=" name" no t- nu l l =" tru e" / >
< s q l - ins ert>I NSE R T I NT O P E R SO N ( NA M E , I D ) V A L U E S ( U P P E R ( ?), ? )< / s q l - ins ert>
< s q l - u pdate>U P D A T E P E R SO N SE T NA M E =U P P E R ( ?) W H E R E I D =?< / s q l - u pdate>
< s q l - del ete>D E L E T E F R O M P E R SO N W H E R E I D =?< / s q l - del ete>
< / cl as s >
T h e S Q L i s di rec tl y ex ec u ted i n yo u r database, so yo u c an u se an y di al ec t yo u l i k e. T h i s w i l l redu c e th e

p o rtabi l i ty o f yo u r m ap p i n g i f yo u u se database sp ec i fi c S Q L .
S to red p ro c edu res are su p p o rted i f th e cal l ab l e attri bu te i s set:

< id name=" id" >
< / id>
< s q l - ins ert cal l ab l e=" tru e" >{cal l createP ers o n ( ?, ?)}< / s q l - ins ert>
< s q l - del ete cal l ab l e=" tru e" >{? = cal l del eteP ers o n ( ?)}< / s q l - del ete>
< s q l - u pdate cal l ab l e=" tru e" >{? = cal l u pdateP ers o n ( ?, ?)}< / s q l - u pdate>
< / cl as s >
T h e o rder o f th e p o si ti o n al p aram eters i s v i tal , as th ey m u st be i n th e sam e seq u en c e as H i bern ate ex p ec ts

th em .
Y o u c an v i ew th e ex p ec ted o rder by en abl i n g debu g l o ggi n g fo r th e o rg. h ib ernate. pers is ter. entity l ev el . W i th
th i s l ev el en abl ed, H i bern ate w i l l p ri n t o u t th e stati c S Q L th at i s u sed to c reate, u p date, del ete etc . en ti ti es.
T o v i ew th e ex p ec ted seq u en c e, do n o t i n c l u de yo u r c u sto m S Q L i n th e m ap p i n g fi l es, as th i s w i l l o v erri de th e
H i bern ate gen erated stati c S Q L .
T h e sto red p ro c edu res are i n m o st c ases req u i red to retu rn th e n u m ber o f ro w s i n serted, u p dated an d
del eted, as H i bern ate h as so m e ru n ti m e c h ec k s fo r th e su c c ess o f th e statem en t. H i bern ate al w ays regi sters
th e fi rst statem en t p aram eter as a n u m eri c o u tp u t p aram eter fo r th e CU D o p erati o n s:
C R E A T E O R R E P L A C E F U NC T I O N u pdateP ers o n ( u id I N NU M B E R , u name I N V A R C H A R 2 )

R E T U R N NU M B E R I S
B E G I N
u pdate P E R SO N
s et
NA M E = u name,
w h ere
I D = u id;
retu rn SQ L % R O W C O U NT ;
E ND u pdateP ers o n;
1 6 . 4 . C us tom S Q L for l oad ing

Y o u c an al so dec l are yo u r o w n S Q L (o r H Q L ) q u eri es fo r en ti ty l o adi n g:
1 8 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< s q l - q u ery name=" pers o n" >

< retu rn al ias =" pers " cl as s =" P ers o n" l o ck - mo de=" u pgrade" / >
SE L E C T NA M E A S {pers . name}, I D A S {pers . id}
F R O M P E R SO N
W H E R E I D =?
F O R U P D A T E
T h i s i s j u st a n am ed q u ery dec l arati o n , as di sc u ssed earl i er. Y o u c an referen c e th i s n am ed q u ery i n a c l ass

m ap p i n g:

< id name=" id" >
< / id>
< l o ader q u ery- ref =" pers o n" / >
< / cl as s >
T h i s ev en w o rk s w i th sto red p ro c edu res.
Y o u c an ev en defi n e a q u ery fo r c o l l ec ti o n l o adi n g:
< s et name=" empl o yments " inv ers e=" tru e" >
< k ey/ >
< o ne- to - many cl as s =" E mpl o yment" / >
< l o ader q u ery- ref =" empl o yments " / >
< / s et>
< s q l - q u ery name=" empl o yments " >

< l o ad- co l l ectio n al ias =" emp" ro l e=" P ers o n. empl o yments " / >
SE L E C T {emp. *}
F R O M E M P L O Y M E NT emp
W H E R E E M P L O Y E R = : id
O R D E R B Y ST A R T D A T E A SC , E M P L O Y E E A SC
Y o u c an al so defi n e an en ti ty l o ader th at l o ads a c o l l ec ti o n by j o i n fetc h i n g:
< s q l - q u ery name=" pers o n" >

< retu rn al ias =" pers " cl as s =" P ers o n" / >
< retu rn- j o in al ias =" emp" pro perty=" pers . empl o yments " / >
SE L E C T NA M E A S {pers . *}, {emp. *}
F R O M P E R SO N pers
L E F T O U T E R J O I N E M P L O Y M E NT emp
O N pers . I D = emp. P E R SO N_ I D
W H E R E I D =?
C h ap ter 1 7 . F il tering d ata

1 7 .1 . H i bern ate fi l ters
H i bern ate3 p ro v i des an i n n o v ati v e n ew ap p ro ac h to h an dl i n g data w i th " v i si bi l i ty" ru l es. A H ib e rnate f ilte r i s a
gl o bal , n am ed, p aram eteri z ed fi l ter th at c an be en abl ed o r di sabl ed fo r a p arti c u l ar H i bern ate sessi o n .
1 8 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 7 . 1 . Hibernate fil ters

H i bern ate3 h as th e abi l i ty to p re- defi n e fi l ter c ri teri a an d attac h th o se fi l ters at bo th a c l ass l ev el an d a
c o l l ec ti o n l ev el . A fi l ter c ri teri a al l o w s yo u to defi n e a restri c ti o n c l au se si m i l ar to th e ex i sti n g " w h ere"
attri bu te av ai l abl e o n th e c l ass an d v ari o u s c o l l ec ti o n el em en ts. T h ese fi l ter c o n di ti o n s, h o w ev er, c an be
p aram eteri z ed. T h e ap p l i c ati o n c an th en dec i de at ru n ti m e w h eth er c ertai n fi l ters sh o u l d be en abl ed an d
w h at th ei r p aram eter v al u es sh o u l d be. F i l ters c an be u sed l i k e database v i ew s, bu t th ey are p aram eteri z ed
i n si de th e ap p l i c ati o n .
I n o rder to u se fi l ters, th ey m u st fi rst be defi n ed an d th en attac h ed to th e ap p ro p ri ate m ap p i n g el em en ts. T o

defi n e a fi l ter, u se th e < f il ter- def / > el em en t w i th i n a < h ib ernate- mapping/ > el em en t:
< f il ter- def name=" myF il ter" >

< f il ter- param name=" myF il terP aram" type=" s tring" / >
< / f il ter- def >
T h i s fi l ter c an th en be attac h ed to a c l ass:
< cl as s name=" myC l as s " . . . >

...
< f il ter name=" myF il ter" co nditio n=" : myF il terP aram = M Y _ F I L T E R E D _ C O L U M N" / >
< / cl as s >
O r, to a c o l l ec ti o n :
< s et . . . >
< f il ter name=" myF il ter" co nditio n=" : myF il terP aram = M Y _ F I L T E R E D _ C O L U M N" / >
< / s et>
O r, to bo th o r m u l ti p l es o f eac h at th e sam e ti m e.
T h e m eth o ds o n Ses s io n are: enab l eF il ter( String f il terName), getE nab l edF il ter( String f il terName), an d
dis ab l eF il ter( String f il terName). B y defau l t, fi l ters are not en abl ed fo r a gi v en sessi o n . F i l ters m u st be en abl ed
th ro u gh u se o f th e Ses s io n. enab l eF il ter( ) m eth o d, w h i c h retu rn s an i n stan c e o f th e F il ter i n terfac e. I f yo u u sed
th e si m p l e fi l ter defi n ed abo v e, i t w o u l d l o o k l i k e th i s:
s es s io n. enab l eF il ter( " myF il ter" ). s etP arameter( " myF il terP aram" , " s o me- v al u e" );
M eth o ds o n th e o rg.h i bern ate.F i l ter i n terfac e do al l o w th e m eth o d- c h ai n i n g c o m m o n to m u c h o f H i bern ate.
T h e fo l l o w i n g i s a fu l l ex am p l e, u si n g tem p o ral data w i th an effec ti v e rec o rd date p attern :
1 8 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< f il ter- def name=" ef f ectiv eD ate" >

< f il ter- param name=" as O f D ate" type=" date" / >
< / f il ter- def >
< cl as s name=" E mpl o yee" . . . >

...
< many- to - o ne name=" department" co l u mn=" dept_ id" cl as s =" D epartment" / >
< pro perty name=" ef f ectiv eStartD ate" type=" date" co l u mn=" ef f _ s tart_ dt" / >
< pro perty name=" ef f ectiv eE ndD ate" type=" date" co l u mn=" ef f _ end_ dt" / >
...
< !- -
No te th at th is as s u mes no n- terminal reco rds h av e an ef f _ end_ dt s et to
a max db date f o r s impl icity- s ak e
- - >
< f il ter name=" ef f ectiv eD ate"
co nditio n=" : as O f D ate B E T W E E N ef f _ s tart_ dt and ef f _ end_ dt" / >
< / cl as s >
< cl as s name=" D epartment" . . . >

...
< s et name=" empl o yees " l az y=" tru e" >
< k ey co l u mn=" dept_ id" / >
< o ne- to - many cl as s =" E mpl o yee" / >
< f il ter name=" ef f ectiv eD ate"
co nditio n=" : as O f D ate B E T W E E N ef f _ s tart_ dt and ef f _ end_ dt" / >
< / s et>
< / cl as s >
I n o rder to en su re th at yo u are p ro v i ded w i th c u rren tl y effec ti v e rec o rds, en abl e th e fi l ter o n th e sessi o n
p ri o r to retri ev i n g em p l o yee data:
Ses s io n s es s io n = . . . ;
s es s io n. enab l eF il ter( " ef f ectiv eD ate" ). s etP arameter( " as O f D ate" , new D ate( ));
L is t res u l ts = s es s io n. createQ u ery( " f ro m E mpl o yee as e w h ere e. s al ary > : targetSal ary" )
. s etL o ng( " targetSal ary" , new L o ng( 1000000))
. l is t( );
E v en th o u gh a sal ary c o n strai n t w as m en ti o n ed ex p l i c i tl y o n th e resu l ts i n th e abo v e H Q L , bec au se o f th e

en abl ed fi l ter, th e q u ery w i l l retu rn o n l y c u rren tl y ac ti v e em p l o yees w h o h av e a sal ary greater th an o n e
m i l l i o n do l l ars.
I f yo u w an t to u se fi l ters w i th o u ter j o i n i n g, ei th er th ro u gh H Q L o r l o ad fetc h i n g, be c arefu l o f th e di rec ti o n o f

th e c o n di ti o n ex p ressi o n . I t i s safest to set th i s u p fo r l eft o u ter j o i n i n g. P l ac e th e p aram eter fi rst fo l l o w ed by
th e c o l u m n n am e(s) after th e o p erato r.
A fter bei n g defi n ed, a fi l ter m i gh t be attac h ed to m u l ti p l e en ti ti es an d/o r c o l l ec ti o n s eac h w i th i ts o w n

c o n di ti o n . T h i s c an be p ro bl em ati c w h en th e c o n di ti o n s are th e sam e eac h ti m e. U si n g < f il ter- def / > al l o w s yo u
to defi n i n e a defau l t c o n di ti o n , ei th er as an attri bu te o r CD A T A :
< f il ter- def name=" myF il ter" co nditio n=" ab c > x yz " >. . . < / f il ter- def >
< f il ter- def name=" myO th erF il ter" >ab c=x yz < / f il ter- def >
T h i s defau l t c o n di ti o n w i l l be u sed w h en ev er th e fi l ter i s attac h ed to so m eth i n g w i th o u t sp ec i fyi n g a c o n di ti o n .

T h i s m ean s yo u c an gi v e a sp ec i fi c c o n di ti o n as p art o f th e attac h m en t o f th e fi l ter th at o v erri des th e defau l t
c o n di ti o n i n th at p arti c u l ar c ase.
C h ap ter 1 8 . X M L M ap p ing
1 8 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 8 .1 . W o rk i n g w i th X M L data
1 8 .1 .1 . S p ec i fyi n g X M L an d c l ass m ap p i n g to geth er
1 8 .1 .2. S p ec i fyi n g o n l y an X M L m ap p i n g
1 8 .2. X M L m ap p i n g m etadata
1 8 .3 . M an i p u l ati n g X M L data
X M L M ap p ing is an e x p e rim e ntal f e ature in H ib e rnate 3 . 0 and is c urre ntly und e r ac tiv e d e v e lop m e nt.
1 8 .1 . W ork ing w ith X M L d ata

H i bern ate al l o w s yo u to w o rk w i th p ersi sten t X M L data i n m u c h th e sam e w ay yo u w o rk w i th p ersi sten t
P O J O s. A p arsed X M L tree c an be th o u gh t o f as an o th er w ay o f rep resen ti n g th e rel ati o n al data at th e o bj ec t
l ev el , i n stead o f P O J O s.
H i bern ate su p p o rts do m 4 j as A P I fo r m an i p u l ati n g X M L trees. Y o u c an w ri te q u eri es th at retri ev e do m 4 j trees

fro m th e database an d h av e an y m o di fi c ati o n yo u m ak e to th e tree au to m ati c al l y syn c h ro n i z ed to th e
database. Y o u c an ev en tak e an X M L do c u m en t, p arse i t u si n g do m 4 j , an d w ri te i t to th e database w i th an y
o f H i bern ate' s basi c o p erati o n s: pers is t( ), s av eO rU pdate( ), merge( ), del ete( ), repl icate( ) (m ergi n g i s n o t yet
su p p o rted).
T h i s featu re h as m an y ap p l i c ati o n s i n c l u di n g data i m p o rt/ex p o rt, ex tern al i z ati o n o f en ti ty data v i a J M S o r

S O A P an d X S L T - based rep o rti n g.
A si n gl e m ap p i n g c an be u sed to si m u l tan eo u sl y m ap p ro p erti es o f a c l ass an d n o des o f an X M L do c u m en t to

th e database, o r, i f th ere i s n o c l ass to m ap , i t c an be u sed to m ap j u st th e X M L .
1 8 . 1 . 1 . S pe c i f y i ng X M L and c l as s mappi ng tog e th e r
H ere i s an ex am p l e o f m ap p i n g a P O J O an d X M L si m u l tan eo u sl y:
< cl as s name=" A cco u nt"

tab l e=" A C C O U NT S"
no de=" acco u nt" >
< id name=" acco u ntI d"

co l u mn=" A C C O U NT _ I D "
no de=" @ id" / >
< many- to - o ne name=" cu s to mer"

co l u mn=" C U ST O M E R _ I D "
no de=" cu s to mer/ @ id"
emb ed- x ml =" f al s e" / >
< pro perty name=" b al ance"

co l u mn=" B A L A NC E "
no de=" b al ance" / >
...
< / cl as s >
1 8 . 1 . 2 . S pe c i f y i ng onl y an X M L mappi ng
H ere i s an ex am p l e w h ere th ere i s n o P O J O c l ass:
1 8 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s entityname=" A cco u nt"

tab l e=" A C C O U NT S"
no de=" acco u nt" >
< id name=" id"

co l u mn=" A C C O U NT _ I D "
no de=" @ id"
type=" s tring" / >
< many- to - o ne name=" cu s to merI d"

co l u mn=" C U ST O M E R _ I D "
no de=" cu s to mer/ @ id"
emb ed- x ml =" f al s e"
entityname=" C u s to mer" / >
< pro perty name=" b al ance"

co l u mn=" B A L A NC E "
no de=" b al ance"
type=" b ig_ decimal " / >
...
< / cl as s >
T h i s m ap p i n g al l o w s yo u to ac c ess th e data as a do m 4 j tree, o r as a grap h o f p ro p erty n am e/v al u e p ai rs o r

j av a M aps. T h e p ro p erty n am es are p u rel y l o gi c al c o n stru c ts th at c an be referred to i n H Q L q u eri es.
1 8 . 2 . X M L map p ing metad ata

A ran ge o f H i bern ate m ap p i n g el em en ts ac c ep t th e no de attri bu te. T h i s l ets yo u sp ec i fy th e n am e o f an X M L
attri bu te o r el em en t th at h o l ds th e p ro p erty o r en ti ty data. T h e fo rm at o f th e no de attri bu te m u st be o n e o f
th e fo l l o w i n g:
" el ement- name" : m ap to th e n am ed X M L el em en t

" @ attrib u te- name" : m ap to th e n am ed X M L attri bu te
" ." :m ap to th e p aren t el em en t
" el ement- name/ @ attrib u te- name" : m ap to th e n am ed attri bu te o f th e n am ed el em en t
F o r c o l l ec ti o n s an d si n gl e v al u ed asso c i ati o n s, th ere i s an addi ti o n al emb ed- x ml attri bu te. I f emb ed- x ml =" tru e" ,
th e defau l t, th e X M L tree fo r th e asso c i ated en ti ty (o r c o l l ec ti o n o f v al u e typ e) w i l l be em bedded di rec tl y i n
th e X M L tree fo r th e en ti ty th at o w n s th e asso c i ati o n . O th erw i se, i f emb ed- x ml =" f al s e" , th en o n l y th e
referen c ed i den ti fi er v al u e w i l l ap p ear i n th e X M L fo r si n gl e p o i n t asso c i ati o n s an d c o l l ec ti o n s w i l l n o t ap p ear
at al l .
D o n o t l eav e emb ed- x ml =" tru e" fo r to o m an y asso c i ati o n s, si n c e X M L do es n o t deal w el l w i th c i rc u l ari ty.
1 8 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" C u s to mer"

tab l e=" C U ST O M E R "
no de=" cu s to mer" >
< id name=" id"

co l u mn=" C U ST _ I D "
no de=" @ id" / >
< map name=" acco u nts "

no de=" . "
emb ed- x ml =" tru e" >
< k ey co l u mn=" C U ST O M E R _ I D "
< map- k ey co l u mn=" SH O R T _ D E SC "
no de=" @ s h o rt- des c"
type=" s tring" / >
< o ne- to - many entityname=" A cco u nt"
emb ed- x ml =" f al s e"
no de=" acco u nt" / >
< / map>
< co mpo nent name=" name"

no de=" name" >
< pro perty name=" f irs tName"
no de=" f irs t- name" / >
< pro perty name=" initial "
no de=" initial " / >
< pro perty name=" l as tName"
no de=" l as t- name" / >
< / co mpo nent>
...
< / cl as s >
I n th i s c ase, th e c o l l ec ti o n o f ac c o u n t i ds i s em bedded, bu t n o t th e ac tu al ac c o u n t data. T h e fo l l o w i n g H Q L

q u ery:
f ro m C u s to mer c l ef t j o in f etch c. acco u nts w h ere c. l as tName l ik e : l as tName
w o u l d retu rn datasets su c h as th i s:
< cu s to mer id=" 12 3456 7 89 " >

< acco u nt s h o rt- des c=" Sav ings " >9 87 6 32 56 7 < / acco u nt>
< acco u nt s h o rt- des c=" C redit C ard" >9 856 12 32 3< / acco u nt>
< name>
< f irs t- name>G av in< / f irs t- name>
< initial >A < / initial >
< l as t- name>K ing< / l as t- name>
< / name>
...
< / cu s to mer>
I f yo u set emb ed- x ml =" tru e" o n th e < o ne- to - many> m ap p i n g, th e data m i gh t l o o k m o re l i k e th i s:
1 8 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cu s to mer id=" 12 3456 7 89 " >

< acco u nt id=" 9 87 6 32 56 7 " s h o rt- des c=" Sav ings " >
< cu s to mer id=" 12 3456 7 89 " / >
100. 2 9 
< / acco u nt>
< acco u nt id=" 9 856 12 32 3" s h o rt- des c=" C redit C ard" >
< cu s to mer id=" 12 3456 7 89 " / >
- 2 37 0. 34
< / acco u nt>
< name>
< f irs t- name>G av in< / f irs t- name>
< initial >A < / initial >
< l as t- name>K ing< / l as t- name>
< / name>
...
< / cu s to mer>
1 8 . 3 . M anip ul ating X M L d ata

Y o u c an al so re- read an d u p date X M L do c u m en ts i n th e ap p l i c ati o n . Y o u c an do th i s by o btai n i n g a do m 4 j
sessi o n :
D o cu ment do c = . . . . ;
Ses s io n s es s io n = f acto ry. o penSes s io n( );

Ses s io n do m4j Ses s io n = s es s io n. getSes s io n( E ntityM o de. D O M 4J );
L is t res u l ts = do m4j Ses s io n

. createQ u ery( " f ro m C u s to mer c l ef t j o in f etch c. acco u nts w h ere c. l as tName l ik e : l as tName" )
. l is t( );
f o r ( int i=0; i< res u l ts . s iz e( ); i+ + ){
/ / add th e cu s to mer data to th e X M L do cu ment
E l ement cu s to mer = ( E l ement) res u l ts . get( i);
do c. add( cu s to mer);
}
tx . co mmit( );
Ses s io n s es s io n = f acto ry. o penSes s io n( );

Ses s io n do m4j Ses s io n = s es s io n. getSes s io n( E ntityM o de. D O M 4J );
E l ement cu s t = ( E l ement) do m4j Ses s io n. get( " C u s to mer" , cu s to merI d);

f o r ( int i=0; i< res u l ts . s iz e( ); i+ + ){
E l ement cu s to mer = ( E l ement) res u l ts . get( i);
/ / ch ange th e cu s to mer name in th e X M L and datab as e
E l ement name = cu s to mer. el ement( " name" );
name. el ement( " f irs t- name" ). s etT ex t( f irs tName);
name. el ement( " initial " ). s etT ex t( initial );
name. el ement( " l as t- name" ). s etT ex t( l as tName);
}
tx . co mmit( );
W h en im p l em en ti n g X M L - based data i m p o rt/ex p o rt, i t i s u sefu l to c o m bi n e th i s featu re w i th H i bern ate' s

repl icate( ) o p erati o n .
1 8 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
C h ap ter 1 9 . I mp rov ing p erformance

1 9 .1 . F etc h i n g strategi es
1 9 .1 .1 . W o rk i n g w i th l az y asso c i ati o n s
1 9 .1 .2. T u n i n g fetc h strategi es
1 9 .1 .3 . S i n gl e- en ded asso c i ati o n p ro x i es
1 9 .1 .4 . I n i ti al i z i n g c o l l ec ti o n s an d p ro x i es
1 9 .1 .5 . U si n g batc h fetc h i n g
1 9 .1 .6 . U si n g su bsel ec t fetc h i n g
1 9 .1 .7 . U si n g l az y p ro p erty fetc h i n g
1 9 .2. T h e S ec o n d L ev el Cac h e
1 9 .2.1 . Cac h e m ap p i n gs
1 9 .2.2. S trategy: read o n l y
1 9 .2.3 . S trategy: read/w ri te
1 9 .2.4 . S trategy: n o n stri c t read/w ri te
1 9 .2.5 . S trategy: tran sac ti o n al
1 9 .2.6 . Cac h e- p ro v i der/c o n c u rren c y- strategy c o m p ati bi l i ty
1 9 .3 . M an agi n g th e c ac h es
1 9 .4 . T h e Q u ery Cac h e
1 9 .5 . U n derstan di n g Co l l ec ti o n p erfo rm an c e
1 9 .5 .1 . T ax o n o m y
1 9 .5 .2. L i sts, m ap s, i dbags an d sets are th e m o st effi c i en t c o l l ec ti o n s to u p date
1 9 .5 .3 . B ags an d l i sts are th e m o st effi c i en t i n v erse c o l l ec ti o n s
1 9 .5 .4 . O n e sh o t del ete
1 9 .6 . M o n i to ri n g p erfo rm an c e
1 9 .6 .1 . M o n i to ri n g a S essi o n F ac to ry
1 9 .6 .2. M etri c s
1 9 . 1 . F etch ing s trateg ies

H i bern ate u ses a f e tc h ing s trate g y to retri ev e asso c i ated o bj ec ts i f th e ap p l i c ati o n n eeds to n av i gate th e
asso c i ati o n . F etc h strategi es c an be dec l ared i n th e O /R m ap p i n g m etadata, o r o v erri dden by a p arti c u l ar
H Q L o r C riteria q u ery.
H i bern ate3 defi n es th e fo l l o w i n g fetc h i n g strategi es:
J oin f e tc h ing : H i bern ate retri ev es th e asso c i ated i n stan c e o r c o l l ec ti o n in th e sam e SE L E C T , u si n g an

O U T E R J O I N.
S e le c t f e tc h ing : a sec o n d SE L E C T i s u sed to retri ev e th e asso c i ated en ti ty o r c o l l ec ti o n . U n l ess yo u

ex p l i c i tl y di sabl e l az y fetc h i n g by sp ec i fyi n g l az y=" f al s e" , th i s sec o n d sel ec t w i l l o n l y be ex ec u ted w h en yo u
ac c ess th e asso c i ati o n .
S ub s e le c t f e tc h ing : a sec o n d SE L E C T i s u sed to retri ev e th e asso c i ated c o l l ec ti o n s fo r al l en ti ti es retri ev ed
in a p rev i o u s q u ery o r fetc h . U n l ess yo u ex p l i c i tl y di sabl e l az y fetc h i n g by sp ec i fyi n g l az y=" f al s e" , th i s
sec o n d sel ec t w i l l o n l y be ex ec u ted w h en yo u ac c ess th e asso c i ati o n .
B atc h f e tc h ing : an o p ti m i z ati o n strategy fo r sel ec t fetc h i n g. H i bern ate retri ev es a batc h o f en ti ty
i n stan c es o r c o l l ec ti o n s i n a si n gl e SE L E C T by sp ec i fyi n g a l i st o f p ri m ary o r fo rei gn k eys.
H i bern ate al so di sti n gu i sh es betw een :
I m m e d iate f e tc h ing : an asso c i ati o n , c o l l ec ti o n o r attri bu te i s fetc h ed i m m edi atel y w h en th e o w n er i s

l o aded.
L az y c olle c tion f e tc h ing : a c o l l ec ti o n i s fetc h ed w h en th e ap p l i c ati o n i n v o k es an o p erati o n u p o n th at
c o l l ec ti o n . T h i s i s th e defau l t fo r c o l l ec ti o n s.
" E x tra- laz y " c olle c tion f e tc h ing : i n di v i du al el em en ts o f th e c o l l ec ti o n are ac c essed fro m th e database as
n eeded. H i bern ate tri es n o t to fetc h th e w h o l e c o l l ec ti o n i n to m em o ry u n l ess abso l u tel y n eeded. I t i s
1 8 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
su i tabl e fo r l arge c o l l ec ti o n s.
P rox y f e tc h ing : a si n gl e- v al u ed asso c i ati o n i s fetc h ed w h en a m eth o d o th er th an th e i den ti fi er getter i s
i n v o k ed u p o n th e asso c i ated o bj ec t.
" N o- p rox y " f e tc h ing : a si n gl e- v al u ed asso c i ati o n i s fetc h ed w h en th e i n stan c e v ari abl e i s ac c essed.
Co m p ared to p ro x y fetc h i n g, th i s ap p ro ac h i s l ess l az y; th e asso c i ati o n i s fetc h ed ev en w h en o n l y th e
i den ti fi er i s ac c essed. I t i s al so m o re tran sp aren t, si n c e n o p ro x y i s v i si bl e to th e ap p l i c ati o n . T h i s
ap p ro ac h req u i res bu i l dti m e bytec o de i n stru m en tati o n an d i s rarel y n ec essary.
L az y attrib ute f e tc h ing : an attri bu te o r si n gl e v al u ed asso c i ati o n i s fetc h ed w h en th e i n stan c e v ari abl e i s
ac c essed. T h i s ap p ro ac h req u i res bu i l dti m e bytec o de i n stru m en tati o n an d i s rarel y n ec essary.
W e h av e tw o o rth o go n al n o ti o n s h ere: w h e n i s th e asso c i ati o n fetc h ed an d h ow i s i t fetc h ed. I t i s i m p o rtan t

th at yo u do n o t c o n fu se th em . W e u se f etch to tu n e p erfo rm an c e. W e c an u se l az y to defi n e a c o n trac t fo r
w h at data i s al w ays av ai l abl e i n an y detac h ed i n stan c e o f a p arti c u l ar c l ass.
1 9 .1 .1 . W ork i ng w i th l az y as s oc i ati ons
B y defau l t, H i bern ate3 u ses l az y sel ec t fetc h i n g fo r c o l l ec ti o n s an d l az y p ro x y fetc h i n g fo r si n gl e- v al u ed

asso c i ati o n s. T h ese defau l ts m ak e sen se fo r m o st asso c i ati o n s i n th e m aj o ri ty o f ap p l i c ati o n s.
I f yo u set h ib ernate. def au l t_ b atch _ f etch _ s iz e , H i bern ate w i l l u se th e batc h fetc h o p ti m i z ati o n fo r l az y fetc h i n g.
T h i s o p ti m i z ati o n c an al so be en abl ed at a m o re gran u l ar l ev el .
P l ease be aw are th at ac c ess to a l az y asso c i ati o n o u tsi de o f th e c o n tex t o f an o p en H i bern ate sessi o n w ill
resu l t i n an ex c ep ti o n . F o r ex am p l e:
s = s es s io ns . o penSes s io n( );
T rans actio n tx = s . b eginT rans actio n( );
U s er u = ( U s er) s . createQ u ery( " f ro m U s er u w h ere u . name=: u s erName" )

. s etString( " u s erName" , u s erName). u niq u eR es u l t( );
M ap permis s io ns = u . getP ermis s io ns ( );
tx . co mmit( );
s . cl o s e( );
I nteger acces s L ev el = ( I nteger) permis s io ns . get( " acco u nts " ); / / E rro r!
S i n c e th e p erm i ssi o n s c o l l ec ti o n w as n o t i n i ti al i z ed w h en th e Ses s io n w as c l o sed, th e c o l l ec ti o n w i l l n o t be abl e

to l o ad i ts state. H ib e rnate d oe s not s up p ort laz y initializ ation f or d e tac h e d ob j e c ts . T h i s c an be fi x ed by
m o v i n g th e c o de th at reads fro m th e c o l l ec ti o n to j u st befo re th e tran sac ti o n i s c o m m i tted.
A l tern ati v el y, yo u c an u se a n o n - l az y c o l l ec ti o n o r asso c i ati o n , by sp ec i fyi n g l az y=" f al s e" fo r th e asso c i ati o n

m ap p i n g. H o w ev er, i t i s i n ten ded th at l az y i n i ti al i z ati o n be u sed fo r al m o st al l c o l l ec ti o n s an d asso c i ati o n s. I f
yo u defi n e to o m an y n o n - l az y asso c i ati o n s i n yo u r o bj ec t m o del , H i bern ate w i l l fetc h th e en ti re database i n to
m em o ry i n ev ery tran sac ti o n .
O n th e o th er h an d, yo u c an u se j o i n fetc h i n g, w h i c h i s n o n - l az y by n atu re, i n stead o f sel ec t fetc h i n g i n a

p arti c u l ar tran sac ti o n . W e w i l l n o w ex p l ai n h o w to c u sto m i z e th e fetc h i n g strategy. I n H i bern ate3 , th e
m ec h an i sm s fo r c h o o si n g a fetc h strategy are i den ti c al fo r si n gl e- v al u ed asso c i ati o n s an d c o l l ec ti o n s.
1 9 . 1 . 2 . T u ni ng f e tc h s trate g i e s
S el ec t fetc h i n g (th e defau l t) i s ex trem el y v u l n erabl e to N + 1 sel ec ts p ro bl em s, so w e m i gh t w an t to en abl e

j o i n fetc h i n g i n th e m ap p i n g do c u m en t:
1 8 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< s et name=" permis s io ns "

f etch =" j o in" >
< k ey co l u mn=" u s erI d" / >
< o ne- to - many cl as s =" P ermis s io n" / >
< / s et
< many- to - o ne name=" mo th er" cl as s =" C at" f etch =" j o in" / >
T h e f etch strategy defi n ed i n th e m ap p i n g do c u m en t affec ts:
retri ev al v i a get( ) o r l o ad( )
retri ev al th at h ap p en s i m p l i c i tl y w h en an asso c i ati o n i s n av i gated

C riteria q u eri es
H Q L q u eri es i f s u b s el ect fetc h i n g i s u sed
I rresp ec ti v e o f th e fetc h i n g strategy yo u u se, th e defi n ed n o n - l az y grap h i s gu aran teed to be l o aded i n to

m em o ry. T h i s m i gh t, h o w ev er, resu l t i n sev eral i m m edi ate sel ec ts bei n g u sed to ex ec u te a p arti c u l ar H Q L
q u ery.
U su al l y, th e m ap p i n g do c u m en t i s n o t u sed to c u sto m i z e fetc h i n g. I n stead, w e k eep th e defau l t beh av i o r, an d

o v erri de i t fo r a p arti c u l ar tran sac ti o n , u si n g l ef t j o in f etch i n H Q L . T h i s tel l s H i bern ate to fetc h th e asso c i ati o n
eagerl y in th e fi rst sel ec t, u si n g an o u ter jo in . I n th e C riteria q u ery A P I , yo u w o u ld u se
s etF etch M o de( F etch M o de. J O I N).
I f yo u w an t to c h an ge th e fetc h i n g strategy u sed by get( ) o r l o ad( ), yo u c an u se a C riteria q u ery. F o r ex am p l e:
U s er u s er = ( U s er) s es s io n. createC riteria( U s er. cl as s )

. s etF etch M o de( " permis s io ns " , F etch M o de. J O I N)
. add( R es trictio ns . idE q ( u s erI d) )
. u niq u eR es u l t( );
T h i s i s H i bern ate' s eq u i v al en t o f w h at so m eO R M so l u ti o n s c al l a " fetc h p l an " .
A c o m p l etel y di fferen t ap p ro ac h to p ro bl em s w i th N + 1 sel ec ts i s to u se th e sec o n d- l ev el c ac h e.
1 9 . 1 . 3 . S i ng l e - e nd e d as s oc i ati on prox i e s
L az y fetc h i n g fo r c o l l ec ti o n s i s i m p l em en ted u si n g H i bern ate' s o w n i m p l em en tati o n o f p ersi sten t c o l l ec ti o n s.

H o w ev er, a di fferen t m ec h an i sm i s n eeded fo r l az y beh av i o r i n si n gl e- en ded asso c i ati o n s. T h e target en ti ty
o f th e asso c i ati o n m u st be p ro x i ed. H i bern ate i m p l em en ts l az y i n i ti al i z i n g p ro x i es fo r p ersi sten t o bj ec ts u si n g
ru n ti m e bytec o de en h an c em en t w h i c h i s ac c essed v i a th e CG L I B l i brary.
A t startu p , H i bern ate3 gen erates p ro x i es by defau l t fo r al l p ersi sten t c l asses an d u ses th em to en abl e l az y
fetc h i n g o f many- to - o ne an d o ne- to - o ne asso c i ati o n s.
T h e m ap p i n g fi l e m ay dec l are an i n terfac e to u se as th e p ro x y i n terfac e fo r th at c l ass, w i th th e pro x y

attri bu te. B y defau l t, H i bern ate u ses a su bc l ass o f th e c l ass. Th e p rox ie d c las s m us t im p le m e nt a d e f ault
c ons truc tor w ith at le as t p ac k ag e v is ib ility . Th is c ons truc tor is re c om m e nd e d f or all p e rs is te nt c las s e s .
T h ere are p o ten ti al p ro bl em s to n o te w h en ex ten di n g th i s ap p ro ac h to p o l ym o rp h i c c l asses.F o r ex am p l e:
< cl as s name=" C at" pro x y=" C at" >

......
< s u b cl as s name=" D o mes ticC at" >
.....
< / s u b cl as s >
< / cl as s >
F i rstl y, i n stan c es o f C at w i l l n ev er be c astabl e to D o mes ticC at , ev en i f th e u n derl yi n g i n stan c e i s an i n stan c e o f

D o mes ticC at :
1 9 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
C at cat = ( C at) s es s io n. l o ad( C at. cl as s , id); / / ins tantiate a pro x y ( do es no t h it th e db )

if ( cat. is D o mes ticC at( ) ) { / / h it th e db to initial iz e th e pro x y
D o mes ticC at dc = ( D o mes ticC at) cat; / / E rro r!
....
}
S ec o n dl y, i t i s p o ssi bl e to break p ro x y ==:
C at cat = ( C at) s es s io n. l o ad( C at. cl as s , id); / / ins tantiate a C at pro x y

D o mes ticC at dc =
( D o mes ticC at) s es s io n. l o ad( D o mes ticC at. cl as s , id); / / acq u ire new D o mes ticC at pro x y!
Sys tem. o u t. printl n( cat==dc); / / f al s e
H o w ev er, th e si tu ati o n i s n o t q u i te as bad as i t l o o k s. E v en th o u gh w e n o w h av e tw o referen c es to di fferen t

p ro x y o bj ec ts, th e u n derl yi n g i n stan c e w i l l sti l l be th e sam e o bj ec t:
cat. s etW eigh t( 11. 0); / / h it th e db to initial iz e th e pro x y

Sys tem. o u t. printl n( dc. getW eigh t( ) ); / / 11. 0
T h i rd, yo u c an n o t u se a CG L I B p ro x y fo r a f inal c l ass o r a c l ass w i th an y f inal m eth o ds.
F i n al l y, i f yo u r p ersi sten t o bj ec t ac q u i res an y reso u rc es u p o n i n stan ti ati o n (e.g. i n i n i ti al i z ers o r defau l t

c o n stru c to r), th en th o se reso u rc es w i l l al so be ac q u i red by th e p ro x y. T h e p ro x y c l ass i s an ac tu al su bc l ass o f
th e p ersi sten t c l ass.
T h ese p ro bl em s are al l du e to fu n dam en tal l i m i tati o n s i n J av a' s si n gl e i n h eri tan c e m o del . T o av o i d th ese
p ro bl em s yo u r p ersi sten t c l asses m u st eac h i m p l em en t an i n terfac e th at dec l ares i ts bu si n ess m eth o ds. Y o u
sh o u l d sp ec i fy th ese i n terfac es i n th e m ap p i n g fi l e w h ere C atI mpl i m p l em en ts th e i n terfac e C at an d
D o mes ticC atI mpl i m p l em en ts th e i n terfac e D o mes ticC at . F o r ex am p l e:
< cl as s name=" C atI mpl " pro x y=" C at" >

......
< s u b cl as s name=" D o mes ticC atI mpl " pro x y=" D o mes ticC at" >
.....
< / s u b cl as s >
< / cl as s >
T h en p ro x i es fo r i n stan c es o f C at an d D o mes ticC at c an be retu rn ed by l o ad( ) o r iterate( ).
C at cat = ( C at) s es s io n. l o ad( C atI mpl . cl as s , catid);

I terato r iter = s es s io n. createQ u ery( " f ro m C atI mpl as cat w h ere cat. name=' f ritz ' " ). iterate( );
C at f ritz = ( C at) iter. nex t( );
N ote
l is t( ) do es n o t u su al l y retu rn p ro x i es.
R el ati o n sh i p s are al so l az i l y i n i ti al i z ed. T h i s m ean s yo u m u st dec l are an y p ro p erti es to be o f typ e C at , n o t

C atI mpl .
Certai n o p erati o n s do not req u i re p ro x y i n i ti al i z ati o n :
eq u al s ( ): i f th e p ersi sten t c l ass do es n o t o v erri de eq u al s ( )
h as h C o de( ): i f th e p ersi sten t c l ass do es n o t o v erri de h as h C o de( )
T h e i den ti fi er getter m eth o d
H i bern ate w i l l detec t p ersi sten t c l asses th at o v erri de eq u al s ( ) o r h as h C o de( ).
B y c h o o si n g l az y=" no - pro x y" i n stead o f th e defau l t l az y=" pro x y" , yo u c an av o i d p ro bl em s asso c i ated w i th
1 9 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
typ ec asti n g. H o w ev er, bu i l dti m e bytec o de i n stru m en tati o n i s req u i red, an d al l o p erati o n s w i l l resu l t i n
i m m edi ate p ro x y i n i ti al i z ati o n .
1 9 . 1 . 4 . Ini ti al i z i ng c ol l e c ti ons and prox i e s
A L az yI nitial iz atio nE x ceptio n w i l l be th ro w n by H i bern ate i f an u n i n i ti al i z ed c o l l ec ti o n o r p ro x y i s ac c essed

o u tsi de o f th e sc o p e o f th e Ses s io n, i .e., w h en th e en ti ty o w n i n g th e c o l l ec ti o n o r h av i n g th e referen c e to th e
p ro x y i s i n th e detac h ed state.
S o m eti m es a p ro x y o r c o l l ec ti o n n eeds to be i n i ti al i z ed befo re c l o si n g th e Ses s io n. Y o u c an fo rc e i n i ti al i z ati o n

by c al l i n g cat. getSex ( ) o r cat. getK ittens ( ). s iz e( ), fo r ex am p l e. H o w ev er, th i s c an be c o n fu si n g to readers o f th e
c o de an d i t i s n o t c o n v en i en t fo r gen eri c c o de.
T h e stati c m eth o ds H ib ernate. initial iz e( ) an d H ib ernate. is I nitial iz ed( ), p ro v i de th e ap p l i c ati o n w i th a c o n v en i en t

w ay o f w o rk i n g w i th l az i l y i n i ti al i z ed c o l l ec ti o n s o r p ro x i es. H ib ernate. initial iz e( cat) w i l l fo rc e th e i n i ti al i z ati o n o f
a p ro x y, cat , as l o n g as i ts Ses s io n i s sti l l o p en . H ib ernate. initial iz e( cat. getK ittens ( ) ) h as a si m i l ar effec t fo r th e
c o l l ec ti o n o f k i tten s.
A n o th er o p ti o n i s to k eep th e Ses s io n o p en u n ti l al l req u i red c o l l ec ti o n s an d p ro x i es h av e been l o aded. I n

so m e ap p l i c ati o n arc h i tec tu res, p arti c u l arl y w h ere th e c o de th at ac c esses data u si n g H i bern ate, an d th e c o de
th at u ses i t are i n di fferen t ap p l i c ati o n l ayers o r di fferen t p h ysi c al p ro c esses, i t c an be a p ro bl em to en su re
th at th e Ses s io n i s o p en w h en a c o l l ec ti o n i s i n i ti al i z ed. T h ere are tw o basi c w ays to deal w i th th i s i ssu e:
I n a w eb- based ap p l i c ati o n , a serv l et fi l ter c an be u sed to c l o se th e Ses s io n o n l y at th e en d o f a u ser

req u est, o n c e th e ren deri n g o f th e v i ew i s c o m p l ete (th e O p e n S e s s ion in V ie w p attern ). O f c o u rse, th i s
p l ac es h eav y dem an ds o n th e c o rrec tn ess o f th e ex c ep ti o n h an dl i n g o f yo u r ap p l i c ati o n i n frastru c tu re. I t
i s v i tal l y i m p o rtan t th at th e Ses s io n i s c l o sed an d th e tran sac ti o n en ded befo re retu rn i n g to th e u ser, ev en
w h en an ex c ep ti o n o c c u rs du ri n g ren deri n g o f th e v i ew . S ee th e H i bern ate W i k i fo r ex am p l es o f th i s
" O p en S essi o n i n V i ew " p attern .
I n an ap p l i c ati o n w i th a sep arate bu si n ess ti er, th e bu si n ess l o gi c m u st " p rep are" al l c o l l ec ti o n s th at th e
w eb ti er n eeds befo re retu rn i n g. T h i s m ean s th at th e bu si n ess ti er sh o u l d l o ad al l th e data an d retu rn al l
th e data al ready i n i ti al i z ed to th e p resen tati o n /w eb ti er th at i s req u i red fo r a p arti c u l ar u se c ase. U su al l y,
th e ap p l i c ati o n c al l s H ib ernate. initial iz e( ) fo r eac h c o l l ec ti o n th at w i l l be n eeded i n th e w eb ti er (th i s c al l
m u st o c c u r befo re th e sessi o n i s c l o sed) o r retri ev es th e c o l l ec ti o n eagerl y u si n g a H i bern ate q u ery w i th a
F E T C H c l au se o r a F etch M o de. J O I N i n C riteria. T h i s i s u su al l y easi er i f yo u ado p t th e C om m and p attern
i n stead o f a S e s s ion F ac ad e .
Y o u c an al so attac h a p rev i o u sl y l o aded o bj ec t to a n ew Ses s io n w i th merge( ) o r l o ck ( ) befo re ac c essi n g
u n i n i ti al i z ed c o l l ec ti o n s o r o th er p ro x i es. H i bern ate do es n o t, an d c ertai n l y s h ould n o t, do th i s
au to m ati c al l y si n c e i t w o u l d i n tro du c e i m p ro m p tu tran sac ti o n sem an ti c s.
S o m eti m es yo u do n o t w an t to i n i ti al i z e a l arge c o l l ec ti o n , bu t sti l l n eed so m e i n fo rm ati o n abo u t i t, l i k e i ts

si z e, fo r ex am p l e, o r a su bset o f th e data.
Y o u c an u se a c o l l ec ti o n fi l ter to get th e si z e o f a c o l l ec ti o n w i th o u t i n i ti al i z i n g i t:
( ( I nteger) s . createF il ter( co l l ectio n, " s el ect co u nt( *)" ). l is t( ). get( 0) ). intV al u e( )
T h e createF il ter( ) m eth o d i s al so u sed to effi c i en tl y retri ev e su bsets o f a c o l l ec ti o n w i th o u t n eedi n g to i n i ti al i z e

th e w h o l e c o l l ec ti o n :
s . createF il ter( l az yC o l l ectio n, " " ). s etF irs tR es u l t( 0). s etM ax R es u l ts ( 10). l is t( );
1 9 . 1 . 5 . U s i ng b atc h f e tc h i ng
U si n g batc h fetc h i n g, H i bern ate c an l o ad sev eral u n i n i ti al i z ed p ro x i es i f o n e p ro x y i s ac c essed. B atc h fetc h i n g

i s an o p ti m i z ati o n o f th e l az y sel ec t fetc h i n g strategy. T h ere are tw o w ays yo u c an c o n fi gu re batc h fetc h i n g:
o n th e c l ass l ev el an d th e c o l l ec ti o n l ev el .
B atc h fetc h i n g fo r c l asses/en ti ti es i s easi er to u n derstan d. Co n si der th e fo l l o w i n g ex am p l e: at ru n ti m e yo u

h av e 25 C at i n stan c es l o aded i n a Ses s io n, an d eac h C at h as a referen c e to i ts o w ner, a P ers o n. T h e P ers o n c l ass
1 9 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
i s m ap p ed w i th a p ro x y, l az y=" tru e" . I f yo u n o w i terate th ro u gh al l c ats an d c al l getO w ner( ) o n eac h , H i bern ate
w i l l , by defau l t, ex ec u te 25 SE L E C T statem en ts to retri ev e th e p ro x i ed o w n ers. Y o u c an tu n e th i s beh av i o r by
sp ec i fyi n g a b atch - s iz e i n th e m ap p i n g o f P ers o n:
< cl as s name=" P ers o n" b atch - s iz e=" 10" >. . . < / cl as s >
H i bern ate w i l l n o w ex ec u te o n l y th ree q u eri es: th e p attern i s 1 0 , 1 0 , 5 .
Y o u c an al so en abl e batc h fetc h i n g o f c o l l ec ti o n s. F o r ex am p l e, i f eac h P ers o n h as a l az y c o l l ec ti o n o f C at s, an d

1 0 p erso n s are c u rren tl y l o aded i n th e Ses s io n, i terati n g th ro u gh al l p erso n s w i l l gen erate 1 0 SE L E C T s, o n e fo r
ev ery c al l to getC ats ( ). I f yo u en abl e batc h fetc h i n g fo r th e cats c o l l ec ti o n i n th e m ap p i n g o f P ers o n, H i bern ate
c an p re- fetc h c o l l ec ti o n s:

< s et name=" cats " b atch - s iz e=" 3" >
...
< / s et>
< / cl as s >
W i th a b atch - s iz e o f 3 , H i bern ate w i l l l o ad 3 , 3 , 3 , 1 c o l l ec ti o n s i n fo u r SE L E C T s. A gai n , th e v al u e o f th e

attri bu te dep en ds o n th e ex p ec ted n u m ber o f u n i n i ti al i z ed c o l l ec ti o n s i n a p arti c u l ar Ses s io n.
B atc h fetc h i n g o f c o l l ec ti o n s i s p arti c u l arl y u sefu l i f yo u h av e a n ested tree o f i tem s, i .e. th e typ i c al bi l l - o f-
m ateri al s p attern . H o w ev er, a ne s te d s e t o r a m ate rializ e d p ath m i gh t be a better o p ti o n fo r read- m o stl y
trees.
1 9 . 1 . 6 . U s i ng s u b s e l e c t f e tc h i ng
I f o n e l az y c o l l ec ti o n o r si n gl e- v al u ed p ro x y h as to be fetc h ed, H i bern ate w i l l l o ad al l o f th em , re- ru n n i n g th e

o ri gi n al q u ery i n a su bsel ec t. T h i s w o rk s i n th e sam e w ay as batc h - fetc h i n g bu t w i th o u t th e p i ec em eal
l o adi n g.
1 9 . 1 . 7 . U s i ng l az y prope rty f e tc h i ng
H i bern ate3 su p p o rts th e l az y fetc h i n g o f i n di v i du al p ro p erti es. T h i s o p ti m i z ati o n tec h n i q u e i s al so k n o w n as

f e tc h g roup s . P l ease n o te th at th i s i s m o stl y a m ark eti n g featu re; o p ti m i z i n g ro w reads i s m u c h m o re
i m p o rtan t th an o p ti m i z ati o n o f c o l u m n reads. H o w ev er, o n l y l o adi n g so m e p ro p erti es o f a c l ass c o u l d be
u sefu l i n ex trem e c ases. F o r ex am p l e, w h en l egac y tabl es h av e h u n dreds o f c o l u m n s an d th e data m o del
c an n o t be i m p ro v ed.
T o en abl e l az y p ro p erty l o adi n g, set th e l az y attri bu te o n yo u r p arti c u l ar p ro p erty m ap p i n gs:
< cl as s name=" D o cu ment" >

< id name=" id" >
< / id>
< pro perty name=" name" no t- nu l l =" tru e" l ength =" 50" / >
< pro perty name=" s u mmary" no t- nu l l =" tru e" l ength =" 2 00" l az y=" tru e" / >
< pro perty name=" tex t" no t- nu l l =" tru e" l ength =" 2 000" l az y=" tru e" / >
< / cl as s >
L az y p ro p erty l o adi n g req u i res bu i l dti m e bytec o de i n stru m en tati o n . I f yo u r p ersi sten t c l asses are n o t
en h an c ed, H i bern ate w i l l i gn o re l az y p ro p erty setti n gs an d retu rn to i m m edi ate fetc h i n g.
F o r bytec o de i n stru m en tati o n , u se th e fo l l o w i n g A n t task :
1 9 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< target name=" ins tru ment" depends =" co mpil e" >
< tas k def name=" ins tru ment" cl as s name=" o rg. h ib ernate. to o l . ins tru ment. I ns tru mentT as k " >
< cl as s path path =" $ {j ar. path }" / >
< cl as s path path =" $ {cl as s es . dir}" / >
< cl as s path ref id=" l ib . cl as s . path " / >
< / tas k def >
< ins tru ment v erb o s e=" tru e" >

< f il es et dir=" $ {tes tcl as s es . dir}/ o rg/ h ib ernate/ au ctio n/ mo del " >
< incl u de name=" *. cl as s " / >
< / f il es et>
< / ins tru ment>
< / target>
A di fferen t w ay o f av o i di n g u n n ec essary c o l u m n reads, at l east fo r read- o n l y tran sac ti o n s, i s to u se th e

p ro j ec ti o n featu res o f H Q L o r Cri teri a q u eri es. T h i s av o i ds th e n eed fo r bu i l dti m e bytec o de p ro c essi n g an d i s
c ertai n l y a p referred so l u ti o n .
Y o u c an fo rc e th e u su al eager fetc h i n g o f p ro p erti es u si n g f etch al l pro perties i n H Q L .
1 9 . 2 . T h e S econd L ev el C ach e
A H i bern ate Ses s io n i s a tran sac ti o n - l ev el c ac h e o f p ersi sten t data. I t i s p o ssi bl e to c o n fi gu re a c l u ster o r
J V M - l ev el (Ses s io nF acto ry- l ev el ) c ac h e o n a c l ass- by- c l ass an d c o l l ec ti o n - by- c o l l ec ti o n basi s. Y o u c an ev en
p l u g i n a c l u stered c ac h e. B e aw are th at c ac h es are n o t aw are o f c h an ges m ade to th e p ersi sten t sto re by
an o th er ap p l i c ati o n . T h ey c an , h o w ev er, be c o n fi gu red to regu l arl y ex p i re c ac h ed data.
Y o u h av e th e o p ti o n to tel l H i bern ate w h i c h c ac h i n g i m p l em en tati o n to u se by sp ec i fyi n g th e n am e o f a c l ass

th at i m p l em en ts o rg. h ib ernate. cach e. C ach eP ro v ider u si n g th e p ro p erty h ib ernate. cach e. pro v ider_ cl as s . H i bern ate i s
bu n dl ed w i th a n u m ber o f bu i l t- i n i n tegrati o n s w i th th e o p en - so u rc e c ac h e p ro v i ders th at are l i sted bel o w .
Y o u c an al so i m p l em en t yo u r o w n an d p l u g i t i n as o u tl i n ed abo v e. N o te th at v ersi o n s p ri o r to 3 .2 u se
E h Cac h e as th e defau l t c ac h e p ro v i der.
Table 19 .1. Cac h e Prov id ers
Q u ery
Clu ster
Cac h e Prov id er c lass Ty pe Cac h e
S af e
S u pported
H ash tabl e
(n o t i n ten ded
o rg. h ib ernate. cach e. H as h tab l eC ach eP ro v ider m em o ry yes
fo r p ro du c ti o n
u se)
m em o ry,
E H Cac h e o rg. h ib ernate. cach e. E h C ach eP ro v ider yes
di sk
m em o ry,
O S Cac h e o rg. h ib ernate. cach e. O SC ach eP ro v ider yes
di sk
yes
c l u stered (i p
S w arm Cac h e o rg. h ib ernate. cach e. Sw armC ach eP ro v ider (c l u stered
m u l ti c ast)
i n v al i dati o n )
c l u stered (i p
J B o ss Cac h e yes yes (c l o c k
o rg. h ib ernate. cach e. T reeC ach eP ro v ider m u l ti c ast),
1 .x (rep l i c ati o n ) syn c req .)
tran sac ti o n al
yes
c l u stered (i p
J B o ss Cac h e (rep l i c ati o n yes (c l o c k
o rg. h ib ernate. cach e. j b c2 . J B o s s C ach eR egio nF acto ry m u l ti c ast),
2 o r syn c req .)
tran sac ti o n al
i n v al i dati o n )
1 9 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 9 . 2 . 1 . C ac h e mappi ng s
T h e < cach e> el em en t o f a c l ass o r c o l l ec ti o n m ap p i n g h as th e fo l l o w i n g fo rm :
< cach e
u s age=" trans actio nal | read- w rite| no ns trict- read- w rite| read- o nl y"
regio n=" R egio nName"
incl u de=" al l | no n- l az y"
/ >
u s age (req u i red) sp ec i fi es th e c ac h i n g strategy: trans actio nal , read- w rite , no ns trict- read- w rite o r read- o nl y
regio n (o p ti o n al : defau l ts to th e c l ass o r c o l l ec ti o n ro l e n am e): sp ec i fi es th e n am e o f th e sec o n d l ev el

c ac h e regi o n
incl u de (o p ti o n al : defau l ts to al l ) no n- l az y: sp ec i fi es th at p ro p erti es o f th e en ti ty m ap p ed w i th
l az y=" tru e" c an n o t be c ac h ed w h en attri bu te- l ev el l az y fetc h i n g i s en abl ed
A l tern ati v el y, yo u c an sp ec i fy < cl as s - cach e> an d < co l l ectio n- cach e> el em en ts i n h ib ernate. cf g. x ml .
T h e u s age attri bu te sp ec i fi es a c ac h e c onc urre nc y s trate g y .
1 9 . 2 . 2 . S trate g y : re ad onl y
I f yo u r ap p l i c ati o n n eeds to read, bu t n o t m o di fy, i n stan c es o f a p ersi sten t c l ass, a read- o nl y c ac h e c an be

u sed. T h i s i s th e si m p l est an d o p ti m al p erfo rm i n g strategy. I t i s ev en safe fo r u se i n a c l u ster.
< cl as s name=" eg. I mmu tab l e" mu tab l e=" f al s e" >
< cach e u s age=" read- o nl y" / >
....
< / cl as s >
1 9 . 2 . 3 . S trate g y : re ad / w ri te
I f th e ap p l i c ati o n n eeds to u p date data, a read- w rite c ac h e m i gh t be ap p ro p ri ate. T h i s c ac h e strategy sh o u l d

n ev er be u sed i f seri al i z abl e tran sac ti o n i so l ati o n l ev el i s req u i red. I f th e c ac h e i s u sed i n a J T A en v i ro n m en t,
yo u m u st sp ec i fy th e p ro p erty h ib ernate. trans actio n. manager_ l o o k u p_ cl as s an d n am i n g a strategy fo r o btai n i n g
th e J T A T rans actio nM anager. I n o th er en v i ro n m en ts, yo u sh o u l d en su re th at th e tran sac ti o n i s c o m p l eted w h en
Ses s io n. cl o s e( ) o r Ses s io n. dis co nnect( ) i s c al l ed. I f yo u w an t to u se th i s strategy i n a c l u ster, yo u sh o u l d en su re
th at th e u n derl yi n g c ac h e i m p l em en tati o n su p p o rts l o c k i n g. T h e bu i l t- i n c ac h e p ro v i ders d o not su p p o rt
l o c k i n g.
< cl as s name=" eg. C at" . . . . >

....
< s et name=" k ittens " . . . >
....
< / s et>
< / cl as s >
1 9 . 2 . 4 . S trate g y : nons tri c t re ad / w ri te
I f th e ap p l i c ati o n o n l y o c c asi o n al l y n eeds to u p date data (i .e. i f i t i s ex trem el y u n l i k el y th at tw o tran sac ti o n s

w o u l d try to u p date th e sam e i tem si m u l tan eo u sl y), an d stri c t tran sac ti o n i so l ati o n i s n o t req u i red, a
no ns trict- read- w rite c ac h e m i gh t be ap p ro p ri ate. I f th e c ac h e i s u sed i n a J T A en v i ro n m en t, yo u m u st sp ec i fy
h ib ernate. trans actio n. manager_ l o o k u p_ cl as s . I n o th er en v i ro n m en ts, yo u sh o u l d en su re th at th e tran sac ti o n is
c o m p l eted w h en Ses s io n. cl o s e( ) o r Ses s io n. dis co nnect( ) i s c al l ed.
1 9 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 9 . 2 . 5 . S trate g y : trans ac ti onal
T h e trans actio nal c ac h e strategy p ro v i des su p p o rt fo r fu l l y tran sac ti o n al c ac h e p ro v i ders su c h as J B o ss

T reeCac h e. S u c h a c ac h e c an
o n ly be u sed in a J T A en v i ro n m en t an d yo u m u st sp ec i fy
h ib ernate. trans actio n. manager_ l o o k u p_ cl as s .
1 9 . 2 . 6 . C ac h e - prov i d e r/ c onc u rre nc y - s trate g y c ompati b i l i ty
Important
N o n e o f th e c ac h e p ro v i ders su p p o rt al l o f th e c ac h e c o n c u rren c y strategi es.
T h e fo l l o w i n g tabl e sh o w s w h i c h p ro v i ders are c o m p ati bl e w i th w h i c h c o n c u rren c y strategi es.
Table 19 .2 . Cac h e Conc u rrenc y S trateg y S u pport
nonstric t-
Cac h e read - only read - w rite transac tional
read - w rite
H ash tabl e (n o t i n ten ded fo r p ro du c ti o n
yes yes yes
u se)
E H Cac h e yes yes yes
O S Cac h e yes yes yes
S w arm Cac h e yes yes
J B o ss Cac h e 1 .x yes yes
J B o ss Cac h e 2 yes yes
1 9 . 3 . M anag ing th e cach es

W h en ev er yo u p ass an o bj ec t to s av e( ), u pdate( ) o r s av eO rU pdate( ), an d w h en ev er yo u retri ev e an o bj ec t
u si n g l o ad( ), get( ), l is t( ), iterate( ) o r s cro l l ( ), th at o bj ec t i s added to th e i n tern al c ac h e o f th e Ses s io n.
W h en f l u s h ( ) i s su bseq u en tl y c al l ed, th e state o f th at o bj ec t w i l l be syn c h ro n i z ed w i th th e database. I f yo u do

n o t w an t th i s syn c h ro n i z ati o n to o c c u r, o r i f yo u are p ro c essi n g a h u ge n u m ber o f o bj ec ts an d n eed to
m an age m em o ry effi c i en tl y, th e ev ict( ) m eth o d c an be u sed to rem o v e th e o bj ec t an d i ts c o l l ec ti o n s fro m th e
fi rst- l ev el c ac h e.
Scro l l ab l eR es u l t cats = s es s . createQ u ery( " f ro m C at as cat" ). s cro l l ( ); / / a h u ge res u l t s et

w h il e ( cats . nex t( ) ) {
C at cat = ( C at) cats . get( 0);
do So meth ingW ith A C at( cat);
s es s . ev ict( cat);
}
T h e Ses s io n al so p ro v i des a co ntains ( ) m eth o d to determ i n e i f an i n stan c e bel o n gs to th e sessi o n c ac h e.
T o ev i c t al l o bj ec ts fro m th e sessi o n c ac h e, c al l Ses s io n. cl ear( )
F o r th e sec o n d- l ev el c ac h e, th ere are m eth o ds defi n ed o n Ses s io nF acto ry fo r ev i c ti n g th e c ac h ed state o f an

i n stan c e, en ti re c l ass, c o l l ec ti o n i n stan c e o r en ti re c o l l ec ti o n ro l e.
s es s io nF acto ry. ev ict( C at. cl as s , catI d); / / ev ict a particu l ar C at

s es s io nF acto ry. ev ict( C at. cl as s ); / / ev ict al l C ats
s es s io nF acto ry. ev ictC o l l ectio n( " C at. k ittens " , catI d); / / ev ict a particu l ar co l l ectio n o f k ittens
s es s io nF acto ry. ev ictC o l l ectio n( " C at. k ittens " ); / / ev ict al l k itten co l l ectio ns
1 9 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h e C ach eM o de c o n tro l s h o w a p arti c u l ar sessi o n i n terac ts w i th th e sec o n d- l ev el c ac h e:
C ach eM o de. NO R M A L : w i l l read i tem s fro m an d w ri te i tem s to th e sec o n d- l ev el c ac h e
C ach eM o de. G E T : w i l l read i tem s fro m th e sec o n d- l ev el c ac h e. D o n o t w ri te to th e sec o n d- l ev el c ac h e

ex c ep t w h en u p dati n g data
C ach eM o de. P U T : w i l l w ri te i tem s to th e sec o n d- l ev el c ac h e. D o n o t read fro m th e sec o n d- l ev el c ac h e
C ach eM o de. R E F R E SH : w i l l w ri te i tem s to th e sec o n d- l ev el c ac h e. D o n o t read fro m th e sec o n d- l ev el c ac h e.

B yp ass th e effec t o f h ib ernate. cach e. u s e_ minimal _ pu ts fo rc i n g a refresh o f th e sec o n d- l ev el c ac h e fo r al l
i tem s read fro m th e database
T o bro w se th e c o n ten ts o f a sec o n d- l ev el o r q u ery c ac h e regi o n , u se th e Statis tics A P I :
M ap cach eE ntries = s es s io nF acto ry. getStatis tics ( )

. getSeco ndL ev el C ach eStatis tics ( regio nName)
. getE ntries ( );
Y o u w i l l n eed to en abl e stati sti c s an d, o p ti o n al l y, fo rc e H i bern ate to k eep th e c ac h e en tri es i n a m o re

readabl e fo rm at:
h ib ernate. generate_ s tatis tics tru e

h ib ernate. cach e. u s e_ s tru ctu red_ entries tru e
1 9 . 4 . T h e Q uery C ach e
Q u ery resu l t sets c an al so be c ac h ed. T h i s i s o n l y u sefu l fo r q u eri es th at are ru n freq u en tl y w i th th e sam e
p aram eters. Y o u w i l l fi rst n eed to en abl e th e q u ery c ac h e:
h ib ernate. cach e. u s e_ q u ery_ cach e tru e
T h i s setti n g c reates tw o n ew c ac h e regi o n s: o n e h o l di n g c ac h ed q u ery resu l t sets

(o rg. h ib ernate. cach e. StandardQ u eryC ach e ), th e o th er h o l di n g ti m estam p s o f th e m o st rec en t u p dates to
q u eryabl e tabl es (o rg. h ib ernate. cach e. U pdateT imes tamps C ach e ). N o te th at th e q u ery c ac h e do es n o t c ac h e th e
state o f th e ac tu al en ti ti es i n th e resu l t set; i t c ac h es o n l y i den ti fi er v al u es an d resu l ts o f v al u e typ e. T h e
q u ery c ac h e sh o u l d al w ays be u sed i n c o n j u n c ti o n w i th th e sec o n d- l ev el c ac h e.
M o st q u eri es do n o t ben efi t fro m c ac h i n g, so by defau l t, q u eri es are n o t c ac h ed. T o en abl e c ac h i n g, c al l

Q u ery. s etC ach eab l e( tru e). T h i s c al l al l o w s th e q u ery to l o o k fo r ex i sti n g c ac h e resu l ts o r add i ts resu l ts to th e
c ac h e w h en i t i s ex ec u ted.
I f yo u req u i re fi n e- grai n ed c o n tro l o v er q u ery c ac h e ex p i rati o n p o l i c i es, yo u c an sp ec i fy a n am ed c ac h e

regi o n fo r a p arti c u l ar q u ery by c al l i n g Q u ery. s etC ach eR egio n( ).
L is t b l o gs = s es s . createQ u ery( " f ro m B l o g b l o g w h ere b l o g. b l o gger = : b l o gger" )

. s etE ntity( " b l o gger" , b l o gger)
. s etC ach eab l e( tru e)
. s etC ach eR egio n( " f ro ntpages " )
. l is t( );
I f th e q u ery sh o u l d fo rc e a refresh o f i ts q u ery c ac h e regi o n , yo u sh o u l d c al l

Q u ery. s etC ach eM o de( C ach eM o de. R E F R E SH ). T h i s i s p arti c u l arl y u sefu l i n c ases w h ere u n derl yi n g data m ay h av e
been u p dated v i a a sep arate p ro c ess (i .e., n o t m o di fi ed th ro u gh H i bern ate) an d al l o w s th e ap p l i c ati o n to
sel ec ti v el y refresh p arti c u l ar q u ery resu l t sets. T h i s i s a m o re effi c i en t al tern ati v e to ev i c ti o n o f a q u ery c ac h e
regi o n v i a Ses s io nF acto ry. ev ictQ u eries ( ).
1 9 . 5 . U nd ers tand ing C ol l ection p erformance

I n th e p rev i o u s sec ti o n s w e h av e c o v ered c o l l ec ti o n s an d th ei r ap p l i c ati o n s. I n th i s sec ti o n w e ex p l o re so m e
1 9 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
m o re i ssu es i n rel ati o n to c o l l ec ti o n s at ru n ti m e.
1 9 . 5 . 1 . T ax onomy
H i bern ate defi n es th ree basi c k i n ds o f c o l l ec ti o n s:
c o l l ec ti o n s o f v al u es
o n e- to - m an y asso c i ati o n s
m an y- to - m an y asso c i ati o n s
T h i s c l assi fi c ati o n di sti n gu i sh es th e v ari o u s tabl e an d fo rei gn k ey rel ati o n sh i p s bu t do es n o t tel l u s q u i te

ev eryth i n g w e n eed to k n o w abo u t th e rel ati o n al m o del . T o fu l l y u n derstan d th e rel ati o n al stru c tu re an d
p erfo rm an c e c h arac teri sti c s, w e m u st al so c o n si der th e stru c tu re o f th e p ri m ary k ey th at i s u sed by
H i bern ate to u p date o r del ete c o l l ec ti o n ro w s. T h i s su ggests th e fo l l o w i n g c l assi fi c ati o n :
i n dex ed c o l l ec ti o n s
sets
bags
A l l i n dex ed c o l l ec ti o n s (m ap s, l i sts, an d arrays) h av e a p ri m ary k ey c o n si sti n g o f th e < k ey> an d < index >
c o l u m n s. I n th i s c ase, c o l l ec ti o n u p dates are ex trem el y effi c i en t. T h e p ri m ary k ey c an be effi c i en tl y i n dex ed
an d a p arti c u l ar ro w c an be effi c i en tl y l o c ated w h en H i bern ate tri es to u p date o r del ete i t.
S ets h av e a p ri m ary k ey c o n si sti n g o f < k ey> an d el em en t c o l u m n s. T h i s c an be l ess effi c i en t fo r so m e typ es

o f c o l l ec ti o n el em en t, p arti c u l arl y c o m p o si te el em en ts o r l arge tex t o r bi n ary fi el ds, as th e database m ay n o t
be abl e to i n dex a c o m p l ex p ri m ary k ey as effi c i en tl y. H o w ev er, fo r o n e- to - m an y o r m an y- to - m an y
asso c i ati o n s, p arti c u l arl y i n th e c ase o f syn th eti c i den ti fi ers, i t i s l i k el y to be j u st as effi c i en t. I f yo u w an t
Sch emaE x po rt to ac tu al l y c reate th e p ri m ary k ey o f a < s et>, yo u m u st dec l are al l c o l u m n s as no t- nu l l =" tru e" .
< idb ag> m ap p i n gs defi n e a su rro gate k ey, so th ey are effi c i en t to u p date. I n fac t, th ey are th e best c ase.
B ags are th e w o rst c ase si n c e th ey p erm i t du p l i c ate el em en t v al u es an d, as th ey h av e n o i n dex c o l u m n , n o

p ri m ary k ey c an be defi n ed. H i bern ate h as n o w ay o f di sti n gu i sh i n g betw een du p l i c ate ro w s. H i bern ate
reso l v es th i s p ro bl em by c o m p l etel y rem o v i n g i n a si n gl e D E L E T E an d rec reati n g th e c o l l ec ti o n w h en ev er i t
c h an ges. T h i s c an be i n effi c i en t.
F o r a o n e- to - m an y asso c i ati o n , th e " p ri m ary k ey" m ay n o t be th e p h ysi c al p ri m ary k ey o f th e database

tabl e. E v en i n th i s c ase, th e abo v e c l assi fi c ati o n i s sti l l u sefu l . I t refl ec ts h o w H i bern ate " l o c ates" i n di v i du al
ro w s o f th e c o l l ec ti o n .
1 9 . 5 . 2 . L i s ts , maps , i d b ag s and s e ts are th e mos t e f f i c i e nt c ol l e c ti ons to

u pd ate
F ro m th e di sc u ssi o n abo v e, i t sh o u l d be c l ear th at i n dex ed c o l l ec ti o n s an d sets al l o w th e m o st effi c i en t

o p erati o n i n term s o f addi n g, rem o v i n g an d u p dati n g el em en ts.
T h ere i s, argu abl y, o n e m o re adv an tage th at i n dex ed c o l l ec ti o n s h av e o v er sets fo r m an y- to - m an y

asso c i ati o n s o r c o l l ec ti o n s o f v al u es. B ec au se o f th e stru c tu re o f a Set , H i bern ate do es n o t U P D A T E a ro w
w h en an el em en t i s " c h an ged" . Ch an ges to a Set al w ays w o rk v i a I NSE R T an d D E L E T E o f i n di v i du al ro w s. O n c e
agai n , th i s c o n si derati o n do es n o t ap p l y to o n e- to - m an y asso c i ati o n s.
A fter o bserv i n g th at arrays c an n o t be l az y, yo u c an c o n c l u de th at l i sts, m ap s an d i dbags are th e m o st

p erfo rm an t (n o n - i n v erse) c o l l ec ti o n typ es, w i th sets n o t far beh i n d. Y o u c an ex p ec t sets to be th e m o st
c o m m o n k i n d o f c o l l ec ti o n i n H i bern ate ap p l i c ati o n s. T h i s i s bec au se th e " set" sem an ti c s are m o st n atu ral i n
th e rel ati o n al m o del .
H o w ev er, i n w el l - desi gn ed H i bern ate do m ai n m o del s, m o st c o l l ec ti o n s are i n fac t o n e- to - m an y asso c i ati o n s

w i th inv ers e=" tru e" . F o r th ese asso c i ati o n s, th e u p date i s h an dl ed by th e m an y- to - o n e en d o f th e asso c i ati o n ,
an d so c o n si derati o n s o f c o l l ec ti o n u p date p erfo rm an c e si m p l y do n o t ap p l y.
1 9 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
1 9 . 5 . 3 . B ag s and l i s ts are th e mos t e f f i c i e nt i nv e rs e c ol l e c ti ons
T h ere i s a p arti c u l ar c ase, h o w ev er, i n w h i c h bags, an d al so l i sts, are m u c h m o re p erfo rm an t th an sets. F o r a

c o l l ec ti o n w i th inv ers e=" tru e" , th e stan dard bi di rec ti o n al o n e- to - m an y rel ati o n sh i p i di o m , fo r ex am p l e, w e c an
add el em en ts to a bag o r l i st w i th o u t n eedi n g to i n i ti al i z e (fetc h ) th e bag el em en ts. T h i s i s bec au se, u n l i k e a
s et , C o l l ectio n. add( ) o r C o l l ectio n. addA l l ( ) m u st al w ays retu rn tru e fo r a bag o r L is t . T h i s c an m ak e th e fo l l o w i n g
c o m m o n c o de m u c h faster:
P arent p = ( P arent) s es s . l o ad( P arent. cl as s , id);

C h il d c = new C h il d( );
c. s etP arent( p);
p. getC h il dren( ). add( c); / / no need to f etch th e co l l ectio n!
s es s . f l u s h ( );
1 9 . 5 . 4 . O ne s h ot d e l e te
D el eti n g c o l l ec ti o n el em en ts o n e by o n e c an so m eti m es be ex trem el y i n effi c i en t. H i bern ate k n o w s n o t to do

th at i n th e c ase o f an n ew l y- em p ty c o l l ec ti o n (i f yo u c al l ed l is t. cl ear( ), fo r ex am p l e). I n th i s c ase, H i bern ate
w i l l i ssu e a si n gl e D E L E T E .
S u p p o se yo u added a si n gl e el em en t to a c o l l ec ti o n o f si z e tw en ty an d th en rem o v e tw o el em en ts. H i bern ate

w i l l i ssu e o n e I NSE R T statem en t an d tw o D E L E T E statem en ts, u n l ess th e c o l l ec ti o n i s a bag. T h i s i s c ertai n l y
desi rabl e.
H o w ev er, su p p o se th at w e rem o v e ei gh teen el em en ts, l eav i n g tw o an d th en add th ee n ew el em en ts. T h ere

are tw o p o ssi bl e w ays to p ro c eed
del ete ei gh teen ro w s o n e by o n e an d th en i n sert th ree ro w s

rem o v e th e w h o l e c o l l ec ti o n i n o n e S Q L D E L E T E an d i n sert al l fi v e c u rren t el em en ts o n e by o n e
H i bern ate c an n o t k n o w th at th e sec o n d o p ti o n i s p ro babl y q u i c k er. I t w o u l d p ro babl y be u n desi rabl e fo r

H i bern ate to be th at i n tu i ti v e as su c h beh av i o r m i gh t c o n fu se database tri ggers, etc .
F o rtu n atel y, yo u c an fo rc e th i s beh av i o r (i .e. th e sec o n d strategy) at an y ti m e by di sc ardi n g (i .e.

dereferen c i n g) th e o ri gi n al c o l l ec ti o n an d retu rn i n g a n ew l y i n stan ti ated c o l l ec ti o n w i th al l th e c u rren t
el em en ts.
O n e- sh o t- del ete do es n o t ap p l y to c o l l ec ti o n s m ap p ed inv ers e=" tru e" .
1 9 . 6 . M onitoring p erformance
O p ti m i z ati o n i s n o t m u c h u se w i th o u t m o n i to ri n g an d ac c ess to p erfo rm an c e n u m bers. H i bern ate p ro v i des a
fu l l ran ge o f fi gu res abo u t i ts i n tern al o p erati o n s. S tati sti c s i n H i bern ate are av ai l abl e p er Ses s io nF acto ry.
1 9 . 6 . 1 . M oni tori ng a S e s s i onF ac tory
Y o u c an ac c ess Ses s io nF acto ry m etri c s i n tw o w ays. Y o u r fi rst o p ti o n i s to c al l s es s io nF acto ry. getStatis tics ( ) an d
read o r di sp l ay th e Statis tics yo u rsel f.
H i bern ate c an al so u se J M X to p u bl i sh m etri c s i f yo u en abl e th e Statis tics Serv ice M B ean . Y o u c an en abl e a
si n gl e M B ean fo r al l yo u r Ses s io nF acto ry o r o n e p er fac to ry. S ee th e fo l l o w i n g c o de fo r m i n i m al i sti c
c o n fi gu rati o n ex am p l es:
1 9 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
/ / M B ean s erv ice regis tratio n f o r a s pecif ic Ses s io nF acto ry

H as h tab l e tb = new H as h tab l e( );
tb . pu t( " type" , " s tatis tics " );
tb . pu t( " s es s io nF acto ry" , " myF inancial A pp" );
O b j ectName o n = new O b j ectName( " h ib ernate" , tb ); / / M B ean o b j ect name
Statis tics Serv ice s tats = new Statis tics Serv ice( ); / / M B ean impl ementatio n
s tats . s etSes s io nF acto ry( s es s io nF acto ry); / / B ind th e s tats to a Ses s io nF acto ry
s erv er. regis terM B ean( s tats , o n); / / R egis ter th e M b ean o n th e s erv er
/ / M B ean s erv ice regis tratio n f o r al l Ses s io nF acto ry' s

H as h tab l e tb = new H as h tab l e( );
tb . pu t( " type" , " s tatis tics " );
tb . pu t( " s es s io nF acto ry" , " al l " );
O b j ectName o n = new O b j ectName( " h ib ernate" , tb ); / / M B ean o b j ect name
Statis tics Serv ice s tats = new Statis tics Serv ice( ); / / M B ean impl ementatio n
s erv er. regis terM B ean( s tats , o n); / / R egis ter th e M B ean o n th e s erv er
Y o u c an ac ti v ate an d deac ti v ate th e m o n i to ri n g fo r a Ses s io nF acto ry:
at c o n fi gu rati o n ti m e, set h ib ernate. generate_ s tatis tics to f al s e
at ru n ti m e: s f . getStatis tics ( ). s etStatis tics E nab l ed( tru e) o r h ib ernateStats B ean. s etStatis tics E nab l ed( tru e)
S tati sti c s c an be reset p ro gram m ati c al l y u si n g th e cl ear( ) m eth o d. A su m m ary c an be sen t to a l o gger (i n fo
l ev el ) u si n g th e l o gSu mmary( ) m eth o d.
1 9 . 6 . 2 . M e tri c s
H i bern ate p ro v i des a n u m ber o f m etri c s, fro m basi c i n fo rm ati o n to m o re sp ec i al i z ed i n fo rm ati o n th at i s o n l y

rel ev an t i n c ertai n sc en ari o s. A l l av ai l abl e c o u n ters are desc ri bed i n th e Statis tics i n terfac e A P I , i n th ree
c atego ri es:
M etri c s rel ated to th e gen eral Ses s io n u sage, su c h as n u m ber o f o p en sessi o n s, retri ev ed J D B C
c o n n ec ti o n s, etc .
M etri c s rel ated to th e en ti ti es, c o l l ec ti o n s, q u eri es, an d c ac h es as a w h o l e (ak a gl o bal m etri c s).
D etai l ed m etri c s rel ated to a p arti c u l ar en ti ty, c o l l ec ti o n , q u ery o r c ac h e regi o n .
F o r ex am p l e, yo u c an c h ec k th e c ac h e h i t, m i ss, an d p u t rati o o f en ti ti es, c o l l ec ti o n s an d q u eri es, an d th e

av erage ti m e a q u ery n eeds. B e aw are th at th e n u m ber o f m i l l i sec o n ds i s su bj ec t to ap p ro x i m ati o n i n J av a.
H i bern ate i s ti ed to th e J V M p rec i si o n an d o n so m e p l atfo rm s th i s m i gh t o n l y be ac c u rate to 1 0 sec o n ds.
S i m p l e getters are u sed to ac c ess th e gl o bal m etri c s (i .e. n o t ti ed to a p arti c u l ar en ti ty, c o l l ec ti o n , c ac h e

regi o n , etc .). Y o u c an ac c ess th e m etri c s o f a p arti c u l ar en ti ty, c o l l ec ti o n o r c ac h e regi o n th ro u gh i ts n am e,
an d th ro u gh i ts H Q L o r S Q L rep resen tati o n fo r q u eri es. P l ease refer to th e Statis tics , E ntityStatis tics ,
C o l l ectio nStatis tics , Seco ndL ev el C ach eStatis tics , an d Q u eryStatis tics A P I J av ado c fo r m o re i n fo rm ati o n . T h e
fo l l o w i n g c o de i s a si m p l e ex am p l e:
2 0 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
Statis tics s tats = H ib ernateU til . s es s io nF acto ry. getStatis tics ( );
do u b l e q u eryC ach eH itC o u nt = s tats . getQ u eryC ach eH itC o u nt( );

do u b l e q u eryC ach eM is s C o u nt = s tats . getQ u eryC ach eM is s C o u nt( );
do u b l e q u eryC ach eH itR atio =
q u eryC ach eH itC o u nt / ( q u eryC ach eH itC o u nt + q u eryC ach eM is s C o u nt);
l o g. inf o ( " Q u ery H it ratio : " + q u eryC ach eH itR atio );
E ntityStatis tics entityStats =

s tats . getE ntityStatis tics ( C at. cl as s . getName( ) );
l o ng ch anges =
entityStats . getI ns ertC o u nt( )
+ entityStats . getU pdateC o u nt( )
+ entityStats . getD el eteC o u nt( );
l o g. inf o ( C at. cl as s . getName( ) + " ch anged " + ch anges + " times " );
Y o u c an w o rk o n al l en ti ti es, c o l l ec ti o n s, q u eri es an d regi o n c ac h es, by retri ev i n g th e l i st o f n am es o f en ti ti es,

c o l l ec ti o n s, q u eri es an d regi o n c ac h es u si n g th e fo l l o w i n g m eth o ds: getQ u eries ( ), getE ntityNames ( ),
getC o l l ectio nR o l eNames ( ), an d getSeco ndL ev el C ach eR egio nNames ( ).
C h ap ter 2 0 . T ool s et G uid e

20 .1 . A u to m ati c sc h em a gen erati o n
20 .1 .1 . Cu sto m i z i n g th e sc h em a
20 .1 .2. R u n n i n g th e to o l
20 .1 .3 . P ro p erti es
20 .1 .4 . U si n g A n t
20 .1 .5 . I n c rem en tal sc h em a u p dates
20 .1 .6 . U si n g A n t fo r i n c rem en tal sc h em a u p dates
20 .1 .7 . S c h em a v al i dati o n
20 .1 .8 . U si n g A n t fo r sc h em a v al i dati o n
R o u n dtri p en gi n eeri n g w i th H i bern ate i s p o ssi bl e u si n g a set o f E c l i p se p l u gi n s, c o m m an dl i n e to o l s, an d A n t

task s.
H ib e rnate Tools c u rren tl y i n c l u de p l u gi n s fo r th e E c l i p se I D E as w el l as A n t task s fo r rev erse en gi n eeri n g o f

ex i sti n g databases:
M ap p ing E d itor: an edi to r fo r H i bern ate X M L m ap p i n g fi l es th at su p p o rts au to - c o m p l eti o n an d syn tax

h i gh l i gh ti n g. I t al so su p p o rts sem an ti c au to - c o m p l eti o n fo r c l ass n am es an d p ro p erty/fi el d n am es,
m ak i n g i t m o re v ersati l e th an a n o rm al X M L edi to r.
C ons ole : th e c o n so l e i s a n ew v i ew i n E c l i p se. I n addi ti o n to a tree o v erv i ew o f yo u r c o n so l e
c o n fi gu rati o n s, yo u are al so p ro v i ded w i th an i n terac ti v e v i ew o f yo u r p ersi sten t c l asses an d th ei r
rel ati o n sh i p s. T h e c o n so l e al l o w s yo u to ex ec u te H Q L q u eri es agai n st yo u r database an d bro w se th e
resu l t di rec tl y i n E c l i p se.
D e v e lop m e nt W iz ard s : sev eral w i z ards are p ro v i ded w i th th e H i bern ate E c l i p se to o l s. Y o u c an u se a
w i z ard to q u ic k l y gen erate H i bern ate c o n fi gu rati o n (c fg.x m l ) fi l es, o r to rev erse en gi n eer an ex i sti n g
database sc h em a i n to P O J O so u rc e fi l es an d H i bern ate m ap p i n g fi l es. T h e rev erse en gi n eeri n g w i z ard
su p p o rts c u sto m i z abl e tem p l ates.
P l ease refer to th e H ib e rnate Tools p ac k age do c u m en tati o n fo r m o re i n fo rm ati o n .
H o w ev er, th e H i bern ate m ai n p ac k age c o m es bu n dl ed w i th an i n tegrated to o l : S c h e m aE x p ort ak a h b m2 ddl .I t

c an ev en be u sed fro m " i n si de" H i bern ate.
2 0 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
2 0 . 1 . A utomatic s ch ema g eneration

D D L c an be gen erated fro m yo u r m ap p i n g fi l es by a H i bern ate u ti l i ty. T h e gen erated sc h em a i n c l u des
referen ti al i n tegri ty c o n strai n ts, p ri m ary an d fo rei gn k eys, fo r en ti ty an d c o l l ec ti o n tabl es. T abl es an d
seq u en c es are al so c reated fo r m ap p ed i den ti fi er gen erato rs.
Y o u m us t sp ec i fy a S Q L D ial ect v i a th e h ib ernate. dial ect p ro p erty w h en u si n g th i s to o l , as D D L i s h i gh l y v en do r-

sp ec i fi c .
F i rst, yo u m u st c u sto m i z e yo u r m ap p i n g fi l es to im p ro v e th e gen erated sc h em a. T h e n ex t sec ti o n c o v ers

sc h em a c u sto m i z ati o n .
2 0 . 1 . 1 . C u s tomi z i ng th e s c h e ma
M an y H i bern ate m ap p i n g el em en ts defi n e o p ti o n al attri bu tes n am ed l ength , precis io n an d s cal e. Y o u c an set

th e l en gth , p rec i si o n an d sc al e o f a c o l u m n w i th th i s attri bu te.
< pro perty name=" z ip" l ength =" 5" / >
< pro perty name=" b al ance" precis io n=" 12 " s cal e=" 2 " / >
S o m e tags al so ac c ep t a no t- nu l l attri bu te fo r gen erati n g a NO T NU L L c o n strai n t o n tabl e c o l u m n s, an d a

u niq u e attri bu te fo r gen erati n g U NI Q U E c o n strai n t o n tabl e c o l u m n s.
< many- to - o ne name=" b ar" co l u mn=" b arI d" no t- nu l l =" tru e" / >
< el ement co l u mn=" s erial Nu mb er" type=" l o ng" no t- nu l l =" tru e" u niq u e=" tru e" / >
A u niq u e- k ey attri bu te c an be u sed to gro u p c o lu m n s in a si n gl e, u n i q u e k ey c o n strai n t. Cu rren tl y, th e

sp ec i fi ed v al u e o f th e u niq u e- k ey attri bu te i s not u sed to n am e th e c o n strai n t i n th e gen erated D D L . I t i s o n l y
u sed to gro u p th e c o l u m n s i n th e m ap p i n g fi l e.
< many- to - o ne name=" o rg" co l u mn=" o rgI d" u niq u e- k ey=" O rgE mpl o yeeI d" / >
< pro perty name=" empl o yeeI d" u niq u e- k ey=" O rgE mpl o yee" / >
A n index attri bu te sp ec i fi es th e n am e o f an i n dex th at w i l l be c reated u si n g th e m ap p ed c o l u m n o r c o l u m n s.

M u l ti p l e c o l u m n s c an be gro u p ed i n to th e sam e i n dex by si m p l y sp ec i fyi n g th e sam e i n dex n am e.
< pro perty name=" l as tName" index =" C u s tName" / >

< pro perty name=" f irs tName" index =" C u s tName" / >
A f o reign- k ey attri bu te c an be u sed to o v erri de th e n am e o f an y gen erated fo rei gn k ey c o n strai n t.
< many- to - o ne name=" b ar" co l u mn=" b arI d" f o reign- k ey=" F K F o o B ar" / >
M an y m ap p i n g el em en ts al so ac c ep t a c h i l d < co l u mn> el em en t. T h i s i s p arti c u l arl y u sefu l fo r m ap p i n g m u l ti -

c o l u m n typ es:
< pro perty name=" name" type=" my. cu s to mtypes . Name" / >
< co l u mn name=" l as t" no t- nu l l =" tru e" index =" b ar_ idx " l ength =" 30" / >
< co l u mn name=" f irs t" no t- nu l l =" tru e" index =" b ar_ idx " l ength =" 2 0" / >
< co l u mn name=" initial " / >
< / pro perty>
T h e def au l t attri bu te al l o w s yo u to sp ec i fy a defau l t v al u e fo r a c o l u m n .Y o u sh o u l d assi gn th e sam e v al u e to

th e m ap p ed p ro p erty befo re sav i n g a n ew i n stan c e o f th e m ap p ed c l ass.
2 0 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< pro perty name=" credits " type=" integer" ins ert=" f al s e" >
< co l u mn name=" credits " def au l t=" 10" / >
< / pro perty>
< v ers io n name=" v ers io n" type=" integer" ins ert=" f al s e" >
< co l u mn name=" v ers io n" def au l t=" 0" / >
< / pro perty>
T h e s q l - type attri bu te al l o w s th e u ser to o v erri de th e defau l t m ap p i n g o f a H i bern ate typ e to S Q L datatyp e.
< pro perty name=" b al ance" type=" f l o at" >

< co l u mn name=" b al ance" s q l - type=" decimal ( 13, 3)" / >
< / pro perty>
T h e ch eck attri bu te al l o w s yo u to sp ec i fy a c h ec k c o n strai n t.
< pro perty name=" f o o " type=" integer" >

< co l u mn name=" f o o " ch eck =" f o o > 10" / >
< / pro perty>
< cl as s name=" F o o " tab l e=" f o o s " ch eck =" b ar < 100. 0" >
...
< pro perty name=" b ar" type=" f l o at" / >
< / cl as s >
T h e fo l l o w i n g tabl e su m m ari z es th ese o p ti o n al attri bu tes.
Table 2 0 .1. S u m m ary
A ttribu te V alu es I nterpretation
l ength n u m ber c o lu m n l en gth

precis io n n u m ber c o lu m n dec i m al p rec i si o n
s cal e n u m ber c o lu m n dec i m al sc al e
no t- nu l l tru e| f al s e sp ec i fi es th at th e c o l u m n sh o u l d be n o n - n u l l abl e
u niq u e tru e| f al s e sp ec i fi es th at th e c o l u m n sh o u l d h av e a u n i q u e c o n strai n t
index index _ name sp ec i fi es th e n am e o f a (m u l ti - c o l u m n ) i n dex
u niq u e- k ey u niq u e_ k ey_ name sp ec i fi es th e n am e o f a m u l ti - c o l u m n u n i q u e c o n strai n t
sp ec i fi es th e n am e o f th e fo rei gn k ey c o n strai n t gen erated fo r an
asso c i ati o n , fo r a < o ne- to - o ne>, < many- to - o ne>, < k ey>, o r < many- to - many>
f o reign- k ey f o reign_ k ey_ name
m ap p i n g el em en t. N o te th at inv ers e=" tru e" si des w i l l n o t be c o n si dered by
Sch emaE x po rt .
s q l - type SQ L co l u mn type o v erri des th e defau l t c o l u m n typ e (attri bu te o f < co l u mn> el em en t o n l y)

def au l t S Q L ex p ressi o n sp ec i fy a defau l t v al u e fo r th e c o l u m n
ch eck S Q L ex p ressi o n c reate an S Q L c h ec k c o n strai n t o n ei th er c o l u m n o r tabl e
T h e < co mment> el em en t al l o w s yo u to sp ec i fy c o m m en ts fo r th e gen erated sc h em a.
< cl as s name=" C u s to mer" tab l e=" C u rC u s t" >

< co mment>C u rrent cu s to mers o nl y< / co mment>
...
< / cl as s >
2 0 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< pro perty name=" b al ance" >

< co l u mn name=" b al " >
< co mment>B al ance in U SD < / co mment>
< / co l u mn>
< / pro perty>
T h i s resu l ts i n a co mment o n tab l e o r co mment o n co l u mn statem en t i n th e gen erated D D L w h ere su p p o rted.
2 0 . 1 . 2 . R u nni ng th e tool
T h e Sch emaE x po rt to o l w ri tes a D D L sc ri p t to stan dard o u t an d/o r ex ec u tes th e D D L statem en ts.
T h e fo l l o w i n g tabl e di sp l ays th e Sch emaE x po rt c o m m an d l i n e o p ti o n s
j av a - cp h ib e rnate _ c las s p ath s o rg. h ib ernate. to o l . h b m2 ddl . Sch emaE x po rt op tions m ap p ing _ f ile s
Table 2 0 .2 . S c h em aE x p ort Com m and L ine O ptions
O ption Desc ription

- - q u iet do n o t o u tp u t th e sc ri p t to stdo u t
- - dro p o n l y dro p th e tabl es
- - create o n l y c reate th e tabl es
- - tex t do n o t ex p o rt to th e database
- - o u tpu t=my_ s ch ema. ddl o u tp u t th e ddl sc ri p t to a fi l e
- - naming=eg. M yNamingStrategy sel ec t a NamingStrategy
- - co nf ig=h ib ernate. cf g. x ml read H i bern ate c o n fi gu rati o n fro m an X M L fi l e
- - pro perties =h ib ernate. pro perties read database p ro p erti es fro m a fi l e
- - f o rmat fo rm at th e gen erated S Q L n i c el y i n th e sc ri p t
- - del imiter=; set an en d o f l i n e del i m i ter fo r th e sc ri p t
Y o u c an ev en em bed Sch emaE x po rt i n yo u r ap p l i c ati o n :
C o nf igu ratio n cf g = . . . . ;
new Sch emaE x po rt( cf g). create( f al s e, tru e);
2 0 . 1 . 3 . P rope rti e s
D atabase p ro p erti es c an be sp ec i fi ed:
as system p ro p erti es w i th - D 
i n h ib ernate. pro perties
i n a n am ed p ro p erti es fi l e w i th - - pro perties
T h e n eeded p ro p erti es are:
Table 2 0 .3. S c h em aE x port Connec tion Properties
Property N am e Desc ription
h ib ernate. co nnectio n. driv er_ cl as s j dbc dri v er c l ass

h ib ernate. co nnectio n. u rl j dbc u rl
h ib ernate. co nnectio n. u s ername database u ser
h ib ernate. co nnectio n. pas s w o rd u ser p assw o rd
2 0 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
Property N am e Desc ription

h ib ernate. dial ect di al ec t
2 0 . 1 . 4 . U s i ng A nt
Y o u c an c al l Sch emaE x po rt fro m yo u r A n t bu i l d sc ri p t:
< target name=" s ch emaex po rt" >

< tas k def name=" s ch emaex po rt"
cl as s name=" o rg. h ib ernate. to o l . h b m2 ddl . Sch emaE x po rtT as k "
cl as s path ref =" cl as s . path " / >
< s ch emaex po rt
pro perties =" h ib ernate. pro perties "
q u iet=" no "
tex t=" no "
dro p=" no "
del imiter=" ;"
o u tpu t=" s ch emaex po rt. s q l " >
< f il es et dir=" s rc" >
< incl u de name=" **/ *. h b m. x ml " / >
< / f il es et>
< / s ch emaex po rt>
< / target>
2 0 . 1 . 5 . Inc re me ntal s c h e ma u pd ate s
T h e Sch emaU pdate to o l w i l l u p date an ex i sti n g sc h em a w i th " i n c rem en tal " c h an ges. T h e Sch emaU pdate
dep en ds u p o n th e J D B C m etadata A P I an d, as su c h , w i l l n o t w o rk w i th al l J D B C dri v ers.
j av a - cp h ib e rnate _ c las s p ath s o rg. h ib ernate. to o l . h b m2 ddl . Sch emaU pdate op tions m ap p ing _ f ile s
Table 2 0 .4 . S c h em aU p d ate Com m and L ine O ptions

- - q u iet do n o t o u tp u t th e sc ri p t to stdo u t
- - tex t do n o t ex p o rt th e sc ri p t to th e database
- - co nf ig=h ib ernate. cf g. x ml sp ec i fy a . cf g. x ml fi l e
Y o u c an em bed Sch emaU pdate i n yo u r ap p l i c ati o n :
new Sch emaU pdate( cf g). ex ecu te( f al s e);
2 0 . 1 . 6 . U s i ng A nt f or i nc re me ntal s c h e ma u pd ate s
Y o u c an c al l Sch emaU pdate fro m th e A n t sc ri p t:
2 0 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< target name=" s ch emau pdate" >

< tas k def name=" s ch emau pdate"
cl as s name=" o rg. h ib ernate. to o l . h b m2 ddl . Sch emaU pdateT as k "
< s ch emau pdate

pro perties =" h ib ernate. pro perties "
q u iet=" no " >
< / f il es et>
< / s ch emau pdate>
< / target>
2 0 . 1 . 7 . S c h e ma v al i d ati on
T h e Sch emaV al idato r to o l w i l l v al i date th at th e ex i sti n g database sc h em a " m atc h es" yo u r m ap p i n g do c u m en ts.
T h e Sch emaV al idato r dep en ds h eav i l y u p o n th e J D B C m etadata A P I an d, as su c h , w i l l n o t w o rk w i th al l J D B C
dri v ers. T h i s to o l i s ex trem el y u sefu l fo r testi n g.
j av a - cp h ib e rnate _ c las s p ath s o rg. h ib ernate. to o l . h b m2 ddl . Sch emaV al idato r op tions m ap p ing _ f ile s
Table 2 0 .5 . S c h em aV alid ator Com m and L ine O ptions

- - co nf ig=h ib ernate. cf g. x ml sp ec i fy a . cf g. x ml fi l e
Y o u c an em bed Sch emaV al idato r i n yo u r ap p l i c ati o n :
new Sch emaV al idato r( cf g). v al idate( );
2 0 . 1 . 8 . U s i ng A nt f or s c h e ma v al i d ati on
Y o u c an c al l Sch emaV al idato r fro m th e A n t sc ri p t:
< target name=" s ch emav al idate" >

< tas k def name=" s ch emav al idato r"
cl as s name=" o rg. h ib ernate. to o l . h b m2 ddl . Sch emaV al idato rT as k "
< s ch emav al idato r

pro perties =" h ib ernate. pro perties " >
< / f il es et>
< / s ch emav al idato r>
< / target>
C h ap ter 2 1 . E x amp l e: P arent/ C h il d
2 0 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
21 .1 . A n o te abo u t c o l l ec ti o n s
21 .2. B i di rec ti o n al o n e- to - m an y
21 .3 . Casc adi n g l i fe c yc l e
21 .4 . Casc ades an d u ns av ed- v al u e
21 .5 . Co n c l u si o n
O n e o f th e fi rst th i n gs th at n ew u sers w an t to do w i th H i bern ate i s to m o del a p aren t/c h i l d typ e rel ati o n sh i p .
T h ere are tw o di fferen t ap p ro ac h es to th i s. T h e m o st c o n v en i en t ap p ro ac h , esp ec i al l y fo r n ew u sers, i s to
m o del bo th P arent an d C h il d as en ti ty c l asses w i th a < o ne- to - many> asso c i ati o n fro m P arent to C h il d. T h e
al tern ati v e ap p ro ac h i s to dec l are th e C h il d as a < co mpo s ite- el ement>. T h e defau l t sem an ti c s o f a
o n e- to - m an y asso c i ati o n i n H i bern ate are m u c h l ess c l o se to th e u su al sem an ti c s o f a p aren t/c h i l d
rel ati o n sh i p th an th o se o f a c o m p o si te el em en t m ap p i n g. W e w i l l ex p l ai n h o w to u se a b id ire c tional
one - to- m any as s oc iation w ith c as c ad e s to m o del a p aren t/c h i l d rel ati o n sh i p effi c i en tl y an d el egan tl y.
2 1 .1 . A note about col l ections

H i bern ate c o l l ec ti o n s are c o n si dered to be a l o gi c al p art o f th ei r o w n i n g en ti ty an d n o t o f th e c o n tai n ed
en ti ti es. B e aw are th at th i s i s a c ri ti c al di sti n c ti o n th at h as th e fo l l o w i n g c o n seq u en c es:
W h en yo u rem o v e/add an o bj ec t fro m /to a c o l l ec ti o n , th e v ersi o n n u m ber o f th e c o l l ec ti o n o w n er i s

i n c rem en ted.
I f an o bj ec t th at w as rem o v ed fro m a c o l l ec ti o n i s an i n stan c e o f a v al u e typ e (e.g. a c o m p o si te
el em en t), th at o bj ec t w i l l c ease to be p ersi sten t an d i ts state w i l l be c o m p l etel y rem o v ed fro m th e
database. L i k ew i se, addi n g a v al u e typ e i n stan c e to th e c o l l ec ti o n w i l l c au se i ts state to be i m m edi atel y
p ersi sten t.
Co n v ersel y, i f an en ti ty i s rem o v ed fro m a c o l l ec ti o n (a o n e- to - m an y o r m an y- to - m an y asso c i ati o n ), i t
w i l l n o t be del eted by defau l t. T h i s beh av i o r i s c o m p l etel y c o n si sten t; a c h an ge to th e i n tern al state o f
an o th er en ti ty sh o u l d n o t c au se th e asso c i ated en ti ty to v an i sh . L i k ew i se, addi n g an en ti ty to a c o l l ec ti o n
do es n o t c au se th at en ti ty to bec o m e p ersi sten t, by defau l t.
A ddi n g an en ti ty to a c o l l ec ti o n , by defau l t, m erel y c reates a l i n k betw een th e tw o en ti ti es. R em o v i n g th e

en ti ty w i l l rem o v e th e l i n k . T h i s i s ap p ro p ri ate fo r al l so rts o f c ases. H o w ev er, i t i s n o t ap p ro p ri ate i n th e
c ase o f a p aren t/c h i l d rel ati o n sh i p . I n th i s c ase, th e l i fe o f th e c h i l d i s bo u n d to th e l i fe c yc l e o f th e p aren t.
2 1 . 2 . B id irectional one- to- many

S u p p o se w e start w i th a si m p l e < o ne- to - many> asso c i ati o n fro m P arent to C h il d .

< / s et>
I f w e w ere to ex ec u te th e fo l l o w i n g c o de:
P arent p = . . . . . ;
p. getC h il dren( ). add( c);
s es s io n. s av e( c);
H i bern ate w o u l d i ssu e tw o S Q L statem en ts:
an I NSE R T to c reate th e rec o rd fo r c

an U P D A T E to c reate th e l i n k fro m p to c
T h i s i s n o t o n l y i n effi c i en t, bu t al so v i o l ates an y NO T NU L L c o n strai n t o n th e parent_ id c o l u m n . Y o u c an fi x th e

n u l l abi l i ty c o n strai n t v i o l ati o n by sp ec i fyi n g no t- nu l l =" tru e" i n th e c o l l ec ti o n m ap p i n g:
2 0 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< k ey co l u mn=" parent_ id" no t- nu l l =" tru e" / >
< / s et>
H o w ev er, th i s i s n o t th e rec o m m en ded so l u ti o n .
T h e u n derl yi n g c au se o f th i s beh av i o r i s th at th e l i n k (th e fo rei gn k ey parent_ id ) fro m p to c i s n o t c o n si dered

p art o f th e state o f th e C h il d o bj ec t an d i s th erefo re n o t c reated i n th e I NSE R T . T h e so l u ti o n i s to m ak e th e l i n k
p art o f th e C h il d m ap p i n g.
< many- to - o ne name=" parent" co l u mn=" parent_ id" no t- nu l l =" tru e" / >
Y o u al so n eed to add th e parent p ro p erty to th e C h il d c l ass.
N o w th at th e C h il d en ti ty i s m an agi n g th e state o f th e l i n k , w e tel l th e c o l l ec ti o n n o t to u p date th e l i n k . W e

u se th e inv ers e attri bu te to do th i s:

< / s et>
T h e fo l l o w i n g c o de w o u l d be u sed to add a n ew C h il d:
P arent p = ( P arent) s es s io n. l o ad( P arent. cl as s , pid);

c. s etP arent( p);
p. getC h il dren( ). add( c);
O n l y o n e S Q L I NSE R T w o u l d n o w be i ssu ed.
Y o u c o u l d al so c reate an addC h il d( ) m eth o d o f P arent .
pu b l ic v o id addC h il d( C h il d c) {
c. s etP arent( th is );
ch il dren. add( c);
}
T h e c o de to add a C h il d l o o k s l i k e th i s:

p. addC h il d( c);
2 1 . 3 . C as cad ing l ife cy cl e

Y o u c an address th e fru strati o n s o f th e ex p l i c i t c al l to s av e( ) by u si n g c asc ades.
< s et name=" ch il dren" inv ers e=" tru e" cas cade=" al l " >
< / s et>
T h i s si m p l i fi es th e c o de abo v e to :
2 0 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

p. addC h il d( c);
S im i l arl y, w e do n o t n eed to i terate o v er th e c h i l dren w h en sav i n g o r del eti n g a P arent . T h e fo l l o w i n g

rem o v es p an d al l i ts c h i l dren fro m th e database.

s es s io n. del ete( p);
H o w ev er, th e fo l l o w i n g c o de:

C h il d c = ( C h il d) p. getC h il dren( ). iterato r( ). nex t( );
p. getC h il dren( ). remo v e( c);
c. s etP arent( nu l l );
w i l l n o t rem o v e c fro m th e database. I n th i s c ase, i t w i l l o n l y rem o v e th e l i n k to p an d c au se a NO T NU L L

c o n strai n t v i o l ati o n . Y o u n eed to ex p l i c i tl y del ete( ) th e C h il d.

C h il d c = ( C h il d) p. getC h il dren( ). iterato r( ). nex t( );
p. getC h il dren( ). remo v e( c);
s es s io n. del ete( c);
I n o u r c ase, a C h il d c an n o t ex i st w i th o u t i ts p aren t. S o i f w e rem o v e a C h il d fro m th e c o l l ec ti o n , w e do w an t i t

to be del eted. T o do th i s, w e m u st u se cas cade=" al l - del ete- o rph an" .
< s et name=" ch il dren" inv ers e=" tru e" cas cade=" al l - del ete- o rph an" >
< / s et>
E v en th o u gh th e c o l l ec ti o n m ap p i n g sp ec i fi es inv ers e=" tru e" , c asc ades are sti l l p ro c essed by i terati n g th e
c o l l ec ti o n el em en ts. I f yo u n eed an o bj ec t be sav ed, del eted o r u p dated by c asc ade, yo u m u st add i t to th e
c o l l ec ti o n . I t i s n o t en o u gh to si m p l y c al l s etP arent( ).
2 1 . 4 . C as cad es and u ns av ed - v al u e
S u p p o se w e l o aded u p a P arent i n o n e Ses s io n, m ade so m e c h an ges i n a U I ac ti o n an d w an ted to p ersi st th ese
c h an ges i n a n ew sessi o n by c al l i n g u pdate( ). T h e P arent w i l l c o n tai n a c o l l ec ti o n o f c h i l dren an d, si n c e th e
c asc adi n g u p date i s en abl ed, H i bern ate n eeds to k n o w w h i c h c h i l dren are n ew l y i n stan ti ated an d w h i c h
rep resen t ex i sti n g ro w s i n th e database. W e w i l l al so assu m e th at bo th P arent an d C h il d h av e gen erated
i den ti fi er p ro p erti es o f typ e L o ng. H i bern ate w i l l u se th e i den ti fi er an d v ersi o n /ti m estam p p ro p erty v al u e to
determ i n e w h i c h o f th e c h i l dren are n ew . (S ee S ec ti o n 1 0 .7 , “ A u to m ati c state detec ti o n ” .) I n H ib e rnate 3 , it is
no long e r ne c e s s ary to s p e c if y an u ns av ed - v alu e e x p lic itly .
T h e fo l l o w i n g c o de w i l l u p date parent an d ch il d an d i n sert new C h il d:
/ / parent and ch il d w ere b o th l o aded in a prev io u s s es s io n

parent. addC h il d( ch il d);
C h il d new C h il d = new C h il d( );
parent. addC h il d( new C h il d);
s es s io n. u pdate( parent);
2 0 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
T h i s m ay be su i tabl e fo r th e c ase o f a gen erated i den ti fi er, bu t w h at abo u t assi gn ed i den ti fi ers an d c o m p o si te
i den ti fi ers? T h i s i s m o re di ffi c u l t, si n c e H i bern ate c an n o t u se th e i den ti fi er p ro p erty to di sti n gu i sh betw een a
n ew l y i n stan ti ated o bj ec t, w i th an i den ti fi er assi gn ed by th e u ser, an d an o bj ec t l o aded i n a p rev i o u s sessi o n .
I n th i s c ase, H i bern ate w i l l ei th er u se th e ti m estam p o r v ersi o n p ro p erty, o r w i l l ac tu al l y q u ery th e
sec o n d- l ev el c ac h e o r, w o rst c ase, th e database, to see i f th e ro w ex i sts.
2 1 . 5 . C oncl us ion
T h e sec ti o n s w e h av e j u st c o v ered c an be a bi t c o n fu si n g. H o w ev er, i n p rac ti c e, i t al l w o rk s o u t n i c el y. M o st
H i bern ate ap p l i c ati o n s u se th e p aren t/c h i l d p attern i n m an y p l ac es.
W e m en ti o n ed an al tern ati v e i n th e fi rst p aragrap h . N o n e o f th e abo v e i ssu es ex i st i n th e c ase o f

< co mpo s ite- el ement> m ap p i n gs, w h i c h h av e ex ac tl y th e sem an ti c s o f a p aren t/c h i l d rel ati o n sh i p .
U n fo rtu n atel y, th ere are tw o bi g l i m i tati o n s w i th c o m p o si te el em en t c l asses: c o m p o si te el em en ts c an n o t o w n
c o l l ec ti o n s an d th ey sh o u l d n o t be th e c h i l d o f an y en ti ty o th er th an th e u n i q u e p aren t.
C h ap ter 2 2 . E x amp l e: W ebl og A p p l ication

22.1 . P ersi sten t Cl asses
22.2. H i bern ate M ap p i n gs
22.3 . H i bern ate Co de
2 2 . 1 . P ers is tent C l as s es
T h e p ersi sten t c l asses h ere rep resen t a w ebl o g an d an i tem p o sted i n a w ebl o g. T h ey are to be m o del l ed as a
stan dard p aren t/c h i l d rel ati o n sh i p , bu t w e w i l l u se an o rdered bag, i n stead o f a set:
pack age eg;
impo rt j av a. u til . L is t;
pu b l ic cl as s B l o g {
priv ate L o ng _ id;
priv ate String _ name;
priv ate L is t _ items ;
retu rn _ id;
}
pu b l ic L is t getI tems ( ) {
retu rn _ items ;
}
pu b l ic String getName( ) {
retu rn _ name;
}
pu b l ic v o id s etI d( L o ng l o ng1) {
_ id = l o ng1;
}
pu b l ic v o id s etI tems ( L is t l is t) {
_ items = l is t;
}
pu b l ic v o id s etName( String s tring) {
_ name = s tring;
}
}
2 1 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
pack age eg;
impo rt j av a. tex t. D ateF o rmat;

impo rt j av a. u til . C al endar;
pu b l ic cl as s B l o gI tem {
priv ate L o ng _ id;
priv ate C al endar _ datetime;
priv ate String _ tex t;
priv ate String _ titl e;
priv ate B l o g _ b l o g;
pu b l ic B l o g getB l o g( ) {
retu rn _ b l o g;
}
pu b l ic C al endar getD atetime( ) {
retu rn _ datetime;
}
retu rn _ id;
}
pu b l ic String getT ex t( ) {
retu rn _ tex t;
}
pu b l ic String getT itl e( ) {
retu rn _ titl e;
}
pu b l ic v o id s etB l o g( B l o g b l o g) {
_ b l o g = b l o g;
}
pu b l ic v o id s etD atetime( C al endar cal endar) {
_ datetime = cal endar;
}
pu b l ic v o id s etI d( L o ng l o ng1) {
_ id = l o ng1;
}
pu b l ic v o id s etT ex t( String s tring) {
_ tex t = s tring;
}
pu b l ic v o id s etT itl e( String s tring) {
_ titl e = s tring;
}
}
2 2 . 2 . Hibernate M ap p ing s
T h e X M L m ap p i n gs are n o w strai gh tfo rw ard. F o r ex am p l e:
2 1 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< ?x ml v ers io n=" 1. 0" ?>

< cl as s
name=" B l o g"
tab l e=" B L O G S" >
< id
name=" id"
co l u mn=" B L O G _ I D " >
< / id>
< pro perty

name=" name"
co l u mn=" NA M E "

< k ey co l u mn=" B L O G _ I D " / >

< o ne- to - many cl as s =" B l o gI tem" / >

< / cl as s >
2 1 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< ?x ml v ers io n=" 1. 0" ?>

< cl as s
name=" B l o gI tem"
tab l e=" B L O G _ I T E M S"
dynamic- u pdate=" tru e" >
< id
name=" id"
co l u mn=" B L O G _ I T E M _ I D " >
< / id>
< pro perty

name=" titl e"
co l u mn=" T I T L E "
< pro perty

name=" tex t"
co l u mn=" T E X T "
< pro perty

name=" datetime"
co l u mn=" D A T E _ T I M E "
< many- to - o ne
name=" b l o g"
co l u mn=" B L O G _ I D "
< / cl as s >
2 2 . 3 . Hibernate C od e
T h e fo l l o w i n g c l ass dem o n strates so m e o f th e k i n ds o f th i n gs w e c an do w i th th ese c l asses u si n g H i bern ate:
2 1 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
pack age eg;
impo rt j av a. u til . A rrayL is t;

impo rt j av a. u til . C al endar;
impo rt j av a. u til . I terato r;
impo rt j av a. u til . L is t;
impo rt o rg. h ib ernate. H ib ernateE x ceptio n;

impo rt o rg. h ib ernate. Q u ery;
impo rt o rg. h ib ernate. Ses s io n;
impo rt o rg. h ib ernate. Ses s io nF acto ry;
impo rt o rg. h ib ernate. T rans actio n;
impo rt o rg. h ib ernate. cf g. C o nf igu ratio n;
impo rt o rg. h ib ernate. to o l . h b m2 ddl . Sch emaE x po rt;
pu b l ic cl as s B l o gM ain {
priv ate Ses s io nF acto ry _ s es s io ns ;
pu b l ic v o id co nf igu re( ) th ro w s H ib ernateE x ceptio n {

_ s es s io ns = new C o nf igu ratio n( )
. addC l as s ( B l o g. cl as s )
. addC l as s ( B l o gI tem. cl as s )
}
pu b l ic v o id ex po rtT ab l es ( ) th ro w s H ib ernateE x ceptio n {

. addC l as s ( B l o g. cl as s )
. addC l as s ( B l o gI tem. cl as s );
new Sch emaE x po rt( cf g). create( tru e, tru e);
}
pu b l ic B l o g createB l o g( String name) th ro w s H ib ernateE x ceptio n {
B l o g b l o g = new B l o g( );
b l o g. s etName( name);
b l o g. s etI tems ( new A rrayL is t( ) );
Ses s io n s es s io n = _ s es s io ns . o penSes s io n( );
try {
tx = s es s io n. b eginT rans actio n( );
s es s io n. pers is t( b l o g);
tx . co mmit( );
}
catch ( H ib ernateE x ceptio n h e) {
if ( tx ! =nu l l ) tx . ro l l b ack ( );
th ro w h e;
}
f inal l y {
}
retu rn b l o g;
}
pu b l ic B l o gI tem createB l o gI tem( B l o g b l o g, String titl e, String tex t)

th ro w s H ib ernateE x ceptio n {
B l o gI tem item = new B l o gI tem( );

item. s etT itl e( titl e);
2 1 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
C h ap ter 2 3 . E x amp l e: V arious M ap p ing s

23 .1 . E m p l o yer/E m p l o yee
23 .2. A u th o r/W o rk
23 .3 . Cu sto m er/O rder/P ro du c t
23 .4 . M i sc el l an eo u s ex am p l e m ap p i n gs
23 .4 .1 . " T yp ed" o n e- to - o n e asso c i ati o n
23 .4 .2. Co m p o si te k ey ex am p l e
23 .4 .3 . M an y- to - m an y w i th sh ared c o m p o si te k ey attri bu te
23 .4 .4 . Co n ten t based di sc ri m i n ati o n
23 .4 .5 . A sso c i ati o n s o n al tern ate k eys
T h i s c h ap ters ex p l o res so m e m o re c o m p l ex asso c i ati o n m ap p i n gs.
2 3 . 1 . E mp l oy er/ E mp l oy ee
T h e fo l l o w i n g m o del o f th e rel ati o n sh i p betw een E mpl o yer an d E mpl o yee u ses an en ti ty c l ass (E mpl o yment ) to
rep resen t th e asso c i ati o n . Y o u c an do th i s w h en th ere m i gh t be m o re th an o n e p eri o d o f em p l o ym en t fo r th e
sam e tw o p arti es. Co m p o n en ts are u sed to m o del m o n etary v al u es an d em p l o yee n am es.
H ere i s a p o ssi bl e m ap p i n g do c u m en t:
2 1 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" E mpl o yer" tab l e=" empl o yers " >
< id name=" id" >
< param name=" s eq u ence" >empl o yer_ id_ s eq < / param>
< / generato r>
< / id>
< / cl as s >
< cl as s name=" E mpl o yment" tab l e=" empl o yment_ perio ds " >
< id name=" id" >

< param name=" s eq u ence" >empl o yment_ id_ s eq < / param>
< / generato r>
< / id>
< pro perty name=" s tartD ate" co l u mn=" s tart_ date" / >
< pro perty name=" endD ate" co l u mn=" end_ date" / >
< co mpo nent name=" h o u rl yR ate" cl as s =" M o netaryA mo u nt" >

< pro perty name=" amo u nt" >
< co l u mn name=" h o u rl y_ rate" s q l - type=" NU M E R I C ( 12 , 2 )" / >
< / pro perty>
< pro perty name=" cu rrency" l ength =" 12 " / >
< / co mpo nent>
< many- to - o ne name=" empl o yer" co l u mn=" empl o yer_ id" no t- nu l l =" tru e" / >
< many- to - o ne name=" empl o yee" co l u mn=" empl o yee_ id" no t- nu l l =" tru e" / >
< / cl as s >
< cl as s name=" E mpl o yee" tab l e=" empl o yees " >
< id name=" id" >
< param name=" s eq u ence" >empl o yee_ id_ s eq < / param>
< / generato r>
< / id>
< pro perty name=" tax f il eNu mb er" / >
< co mpo nent name=" name" cl as s =" Name" >
< pro perty name=" f irs tName" / >
< pro perty name=" l as tName" / >
< / co mpo nent>
< / cl as s >
H ere i s th e tabl e sc h em a gen erated by Sch emaE x po rt .
2 1 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
create tab l e empl o yers (

id B I G I NT no t nu l l ,
name V A R C H A R ( 2 55),
primary k ey ( id)
)
create tab l e empl o yment_ perio ds (

h o u rl y_ rate NU M E R I C ( 12 , 2 ),
cu rrency V A R C H A R ( 12 ),
empl o yee_ id B I G I NT no t nu l l ,
empl o yer_ id B I G I NT no t nu l l ,
end_ date T I M E ST A M P ,
s tart_ date T I M E ST A M P ,
primary k ey ( id)
)
create tab l e empl o yees (

f irs tName V A R C H A R ( 2 55),
initial C H A R ( 1),
l as tName V A R C H A R ( 2 55),
tax f il eNu mb er V A R C H A R ( 2 55),
primary k ey ( id)
)
al ter tab l e empl o yment_ perio ds

add co ns traint empl o yment_ perio ds F K 0 f o reign k ey ( empl o yer_ id) ref erences empl o yers
al ter tab l e empl o yment_ perio ds
add co ns traint empl o yment_ perio ds F K 1 f o reign k ey ( empl o yee_ id) ref erences empl o yees
create s eq u ence empl o yee_ id_ s eq
create s eq u ence empl o yment_ id_ s eq
create s eq u ence empl o yer_ id_ s eq
2 3 . 2 . A uth or/ W ork

Co n si der th e fo l l o w i n g m o del o f th e rel ati o n sh i p s betw een W o rk , A u th o r an d P ers o n. I n th e ex am p l e, th e
rel ati o n sh i p betw een W o rk an d A u th o r i s rep resen ted as a m an y- to - m an y asso c i ati o n an d th e rel ati o n sh i p
betw een A u th o r an d P ers o n i s rep resen ted as o n e- to - o n e asso c i ati o n . A n o th er p o ssi bi l i ty w o u l d be to h av e
A u th o r ex ten d P ers o n.
T h e fo l l o w i n g m ap p i n g do c u m en t c o rrec tl y rep resen ts th ese rel ati o n sh i p s:
2 1 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" W o rk " tab l e=" w o rk s " dis criminato r- v al u e=" W " >
< id name=" id" co l u mn=" id" >

< / id>
< dis criminato r co l u mn=" type" type=" ch aracter" / >
< pro perty name=" titl e" / >

< s et name=" au th o rs " tab l e=" au th o r_ w o rk " >
< k ey co l u mn name=" w o rk _ id" / >
< many- to - many cl as s =" A u th o r" co l u mn name=" au th o r_ id" / >
< / s et>
< s u b cl as s name=" B o o k " dis criminato r- v al u e=" B " >

< pro perty name=" tex t" / >
< / s u b cl as s >
< s u b cl as s name=" So ng" dis criminato r- v al u e=" S" >

< pro perty name=" tempo " / >
< pro perty name=" genre" / >
< / s u b cl as s >
< / cl as s >
< cl as s name=" A u th o r" tab l e=" au th o rs " >

< ! - - T h e A u th o r mu s t h av e th e s ame identif ier as th e P ers o n - - >
< generato r cl as s =" as s igned" / >
< / id>
< pro perty name=" al ias " / >

< o ne- to - o ne name=" pers o n" co ns trained=" tru e" / >
< s et name=" w o rk s " tab l e=" au th o r_ w o rk " inv ers e=" tru e" >
< k ey co l u mn=" au th o r_ id" / >
< many- to - many cl as s =" W o rk " co l u mn=" w o rk _ id" / >
< / s et>
< / cl as s >
< cl as s name=" P ers o n" tab l e=" pers o ns " >

< / id>
< / cl as s >
T h ere are fo u r tabl es i n th i s m ap p i n g: w o rk s , au th o rs an d pers o ns h o l d w o rk , au th o r an d p erso n data

resp ec ti v el y. au th o r_ w o rk i s an asso c i ati o n tabl e l i n k i n g au th o rs to w o rk s. H ere i s th e tabl e sc h em a, as
gen erated by Sch emaE x po rt :
2 1 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
create tab l e w o rk s (
id B I G I NT no t nu l l generated b y def au l t as identity,
tempo F L O A T ,
genre V A R C H A R ( 2 55),
tex t I NT E G E R ,
titl e V A R C H A R ( 2 55),
type C H A R ( 1) no t nu l l ,
primary k ey ( id)
)
create tab l e au th o r_ w o rk (
au th o r_ id B I G I NT no t nu l l ,
w o rk _ id B I G I NT no t nu l l ,
primary k ey ( w o rk _ id, au th o r_ id)
)
create tab l e au th o rs (
al ias V A R C H A R ( 2 55),
primary k ey ( id)
)
create tab l e pers o ns (

primary k ey ( id)
)
al ter tab l e au th o rs
add co ns traint au th o rs F K 0 f o reign k ey ( id) ref erences pers o ns
al ter tab l e au th o r_ w o rk
add co ns traint au th o r_ w o rk F K 0 f o reign k ey ( au th o r_ id) ref erences au th o rs
al ter tab l e au th o r_ w o rk
add co ns traint au th o r_ w o rk F K 1 f o reign k ey ( w o rk _ id) ref erences w o rk s
2 3 . 3 . C us tomer/ O rd er/ P rod uct

I n th i s sec ti o n w e c o n si der a m o del o f th e rel ati o n sh i p s betw een C u s to mer, O rder, L ine I tem an d P ro du ct . T h ere
i s a o n e- to - m an y asso c i ati o n betw een C u s to mer an d O rder, bu t h o w c an yo u rep resen t O rder / L ineI tem /
P ro du ct ? I n th e ex am p l e, L ineI tem i s m ap p ed as an asso c i ati o n c l ass rep resen ti n g th e m an y- to - m an y
asso c i ati o n betw een O rder an d P ro du ct . I n H i bern ate th i s i s c al l ed a c o m p o si te el em en t.
T h e m ap p i n g do c u m en t w i l l l o o k l i k e th i s:
2 1 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" C u s to mer" tab l e=" cu s to mers " >

< id name=" id" >
< / id>
< s et name=" o rders " inv ers e=" tru e" >
< k ey co l u mn=" cu s to mer_ id" / >
< / s et>
< / cl as s >
< cl as s name=" O rder" tab l e=" o rders " >

< id name=" id" >
< / id>
< pro perty name=" date" / >
< many- to - o ne name=" cu s to mer" co l u mn=" cu s to mer_ id" / >
< l is t name=" l ineI tems " tab l e=" l ine_ items " >
< k ey co l u mn=" o rder_ id" / >
< l is t- index co l u mn=" l ine_ nu mb er" / >
< co mpo s ite- el ement cl as s =" L ineI tem" >
< pro perty name=" q u antity" / >
< many- to - o ne name=" pro du ct" co l u mn=" pro du ct_ id" / >
< / l is t>
< / cl as s >
< cl as s name=" P ro du ct" tab l e=" pro du cts " >

< id name=" id" >
< / id>
< pro perty name=" s erial Nu mb er" / >
< / cl as s >
cu s to mers , o rders , l ine_ items an d pro du cts h o l d c u sto m er, o rder, o rder l i n e i tem an d p ro du c t data resp ec ti v el y.
l ine_ items al so ac ts as an asso c i ati o n tabl e l i n k i n g o rders w i th p ro du c ts.
2 2 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
create tab l e cu s to mers (

primary k ey ( id)
)
create tab l e o rders (

cu s to mer_ id B I G I NT ,
date T I M E ST A M P ,
primary k ey ( id)
)
create tab l e l ine_ items (

l ine_ nu mb er I NT E G E R no t nu l l ,
o rder_ id B I G I NT no t nu l l ,
pro du ct_ id B I G I NT ,
q u antity I NT E G E R ,
primary k ey ( o rder_ id, l ine_ nu mb er)
)
create tab l e pro du cts (

s erial Nu mb er V A R C H A R ( 2 55),
primary k ey ( id)
)
al ter tab l e o rders

add co ns traint o rders F K 0 f o reign k ey ( cu s to mer_ id) ref erences cu s to mers
al ter tab l e l ine_ items
add co ns traint l ine_ items F K 0 f o reign k ey ( pro du ct_ id) ref erences pro du cts
al ter tab l e l ine_ items
add co ns traint l ine_ items F K 1 f o reign k ey ( o rder_ id) ref erences o rders
2 3 . 4 . M is cel l aneous ex amp l e map p ing s

T h ese ex am p l es are av ai l abl e fro m th e H i bern ate test su i te. Y o u w i l l fi n d m an y o th er u sefu l ex am p l e
m ap p i n gs th ere by searc h i n g i n th e tes t fo l der o f th e H i bern ate di stri bu ti o n .
2 3 . 4 . 1 . " T y pe d " one - to- one as s oc i ati on
2 2 1 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

< id name=" name" / >
< o ne- to - o ne name=" addres s "
cas cade=" al l " >
< f o rmu l a>name< / f o rmu l a>
< f o rmu l a>' H O M E ' < / f o rmu l a>
< / o ne- to - o ne>
< o ne- to - o ne name=" mail ingA ddres s "
cas cade=" al l " >
< f o rmu l a>name< / f o rmu l a>
< f o rmu l a>' M A I L I NG ' < / f o rmu l a>
< / o ne- to - o ne>
< / cl as s >
< cl as s name=" A ddres s " b atch - s iz e=" 2 "

ch eck =" addres s T ype in ( ' M A I L I NG ' , ' H O M E ' , ' B U SI NE SS' )" >
< co mpo s ite- id>
< k ey- many- to - o ne name=" pers o n"
co l u mn=" pers o nName" / >
< k ey- pro perty name=" type"
co l u mn=" addres s T ype" / >
< pro perty name=" s treet" type=" tex t" / >
< pro perty name=" s tate" / >
< / cl as s >
2 3 . 4 . 2 . C ompos i te k e y e x ampl e
2 2 2 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" C u s to mer" >
< id name=" cu s to merI d"

l ength =" 10" >
< generato r cl as s =" as s igned" / >
< / id>
< pro perty name=" name" no t- nu l l =" tru e" l ength =" 100" / >
< pro perty name=" addres s " no t- nu l l =" tru e" l ength =" 2 00" / >
< l is t name=" o rders "

inv ers e=" tru e"
cas cade=" s av e- u pdate" >
< k ey co l u mn=" cu s to merI d" / >
< index co l u mn=" o rderNu mb er" / >
< / l is t>
< / cl as s >
< cl as s name=" O rder" tab l e=" C u s to merO rder" l az y=" tru e" >
< s ynch ro niz e tab l e=" L ineI tem" / >
< s ynch ro niz e tab l e=" P ro du ct" / >
< co mpo s ite- id name=" id"

cl as s =" O rder$ I d" >
< k ey- pro perty name=" cu s to merI d" l ength =" 10" / >
< k ey- pro perty name=" o rderNu mb er" / >
< pro perty name=" o rderD ate"

type=" cal endar_ date"
< pro perty name=" to tal " >

< f o rmu l a>
( s el ect s u m( l i. q u antity*p. price)
f ro m L ineI tem l i, P ro du ct p
w h ere l i. pro du ctI d = p. pro du ctI d
and l i. cu s to merI d = cu s to merI d
and l i. o rderNu mb er = o rderNu mb er )
< / f o rmu l a>
< / pro perty>
< many- to - o ne name=" cu s to mer"

co l u mn=" cu s to merI d"
ins ert=" f al s e"
u pdate=" f al s e"

< k ey>
< co l u mn name=" o rderNu mb er" / >
< / k ey>
< o ne- to - many cl as s =" L ineI tem" / >

2 2 3 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
2 3 . 4 . 3 . M any - to- many w i th s h are d c ompos i te k e y attri b u te
< cl as s name=" U s er" tab l e=" ` U s er` " >

< co mpo s ite- id>
< k ey- pro perty name=" name" / >
< k ey- pro perty name=" o rg" / >
< s et name=" gro u ps " tab l e=" U s erG ro u p" >
< k ey>
< co l u mn name=" u s erName" / >
< co l u mn name=" o rg" / >
< / k ey>
< many- to - many cl as s =" G ro u p" >
< co l u mn name=" gro u pName" / >
< f o rmu l a>o rg< / f o rmu l a>
< / s et>
< / cl as s >
< cl as s name=" G ro u p" tab l e=" ` G ro u p` " >

< co mpo s ite- id>
< k ey- pro perty name=" name" / >
< k ey- pro perty name=" o rg" / >
< pro perty name=" des criptio n" / >
< s et name=" u s ers " tab l e=" U s erG ro u p" inv ers e=" tru e" >
< k ey>
< co l u mn name=" gro u pName" / >
< co l u mn name=" o rg" / >
< / k ey>
< many- to - many cl as s =" U s er" >
< co l u mn name=" u s erName" / >
< f o rmu l a>o rg< / f o rmu l a>
< / s et>
< / cl as s >
2 3 . 4 . 4 . C onte nt b as e d d i s c ri mi nati on
2 2 4 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< cl as s name=" P ers o n"

dis criminato r- v al u e=" P " >
< id name=" id"

co l u mn=" pers o n_ id"
u ns av ed- v al u e=" 0" >
< / id>
< dis criminato r

type=" ch aracter" >
< f o rmu l a>
cas e
w h en titl e is no t nu l l th en ' E '
w h en s al es pers o n is no t nu l l th en ' C '
el s e ' P '
end
< / f o rmu l a>
< / dis criminato r>

l ength =" 80" / >
< pro perty name=" s ex "

< co mpo nent name=" addres s " >

< pro perty name=" addres s " / >
< pro perty name=" co u ntry" / >
< / co mpo nent>
< s u b cl as s name=" E mpl o yee"

dis criminato r- v al u e=" E " >
< pro perty name=" titl e"
l ength =" 2 0" / >
< pro perty name=" s al ary" / >
< many- to - o ne name=" manager" / >
< / s u b cl as s >
< s u b cl as s name=" C u s to mer"

dis criminato r- v al u e=" C " >
< pro perty name=" co mments " / >
< many- to - o ne name=" s al es pers o n" / >
< / s u b cl as s >
< / cl as s >
2 3 . 4 . 5 . A s s oc i ati ons on al te rnate k e y s
2 2 5 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
< id name=" id" >

< / id>
< pro perty name=" name" l ength =" 100" / >
< o ne- to - o ne name=" addres s "

pro perty- ref =" pers o n"
cas cade=" al l "
f etch =" j o in" / >
< s et name=" acco u nts "

inv ers e=" tru e" >
< k ey co l u mn=" u s erI d"
pro perty- ref =" u s erI d" / >
< o ne- to - many cl as s =" A cco u nt" / >
< / s et>
< pro perty name=" u s erI d" l ength =" 8" / >
< / cl as s >
< id name=" id" >

< / id>
< pro perty name=" addres s " l ength =" 300" / >
< pro perty name=" z ip" l ength =" 5" / >
< pro perty name=" co u ntry" l ength =" 2 5" / >
< many- to - o ne name=" pers o n" u niq u e=" tru e" no t- nu l l =" tru e" / >
< / cl as s >
< cl as s name=" A cco u nt" >

< id name=" acco u ntI d" l ength =" 32 " >
< / id>
< many- to - o ne name=" u s er"

co l u mn=" u s erI d"
pro perty- ref =" u s erI d" / >
< pro perty name=" type" no t- nu l l =" tru e" / >
< / cl as s >
C h ap ter 2 4 . B es t P ractices
W ri te fi n e- grai n ed c l asses an d m ap th em u si n g < co mpo nent>:
U se an A ddres s c l ass to en c ap su l ate s treet , s u b u rb , s tate, po s tco de. T h i s en c o u rages c o de reu se an d
si m p l i fi es refac to ri n g.
D ec l are i den ti fi er p ro p erti es o n p ersi sten t c l asses:
2 2 6 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
H i bern ate m ak es i den ti fi er p ro p erti es o p ti o n al . T h ere are a ran ge o f reaso n s w h y yo u sh o u l d u se th em .

W e rec o m m en d th at i den ti fi ers be ' syn th eti c ' , th at i s, gen erated w i th n o bu si n ess m ean i n g.
I den ti fy n atu ral k eys:

I den ti fy n atu ral k eys fo r al l en ti ti es, an d m ap th em u si n g < natu ral - id>. I m p l em en t eq u al s ( ) an d h as h C o de( )
to c o m p are th e p ro p erti es th at m ak e u p th e n atu ral k ey.
P l ac e eac h c l ass m ap p i n g i n i ts o w n fi l e:
D o n o t u se a si n gl e m o n o l i th i c m ap p i n g do c u m en t. M ap co m. eg. F o o in th e fi l e co m/ eg/ F o o . h b m. x ml . T h i s
m ak es sen se, p arti c u l arl y i n a team en v i ro n m en t.
L o ad m ap p i n gs as reso u rc es:
D ep l o y th e m ap p i n gs al o n g w i th th e c l asses th ey m ap .
Co n si der ex tern al i z i n g q u ery stri n gs:

T h i s i s rec o m m en ded i f yo u r q u eri es c al l n o n - A N S I - stan dard S Q L fu n c ti o n s. E x tern al i z i n g th e q u ery
stri n gs to m ap p i n g fi l es w i l l m ak e th e ap p l i c ati o n m o re p o rtabl e.
U se bi n d v ari abl es.

A s i n J D B C, al w ays rep l ac e n o n - c o n stan t v al u es by " ?" . D o n o t u se stri n g m an i p u l ati o n to bi n d a
n o n - c o n stan t v al u e i n a q u ery. Y o u sh o u l d al so c o n si der u si n g n am ed p aram eters i n q u eri es.
D o n o t m an age yo u r o w n J D B C c o n n ec ti o n s:
H i bern ate al l o w s th e ap p l i c ati o n to m an age J D B C c o n n ec ti o n s, bu t h i s ap p ro ac h sh o u l d be c o n si dered a
l ast- reso rt. I f yo u c an n o t u se th e bu i l t- i n c o n n ec ti o n p ro v i ders, c o n si der p ro v i di n g yo u r o w n
i m p l em en tati o n o f o rg. h ib ernate. co nnectio n. C o nnectio nP ro v ider.
Co n si der u si n g a c u sto m typ e:

S u p p o se yo u h av e a J av a typ e fro m a l i brary th at n eeds to be p ersi sted bu t do es n o t p ro v i de th e
ac c esso rs n eeded to m ap i t as a c o m p o n en t. Y o u sh o u l d c o n si der i m p l em en ti n g o rg. h ib ernate. U s erT ype.
T h i s ap p ro ac h frees th e ap p l i c ati o n c o de fro m i m p l em en ti n g tran sfo rm ati o n s to /fro m a H i bern ate typ e.
U se h an d- c o ded J D B C i n bo ttl en ec k s:
I n p erfo rm an c e- c ri ti c al areas o f th e system , so m e k i n ds o f o p erati o n s m i gh t ben efi t fro m di rec t J D B C. D o
n o t assu m e, h o w ev er, th at J D B C i s n ec essari l y faster. P l ease w ai t u n ti l yo u k now so m eth i n g i s a
bo ttl en ec k . I f yo u n eed to u se di rec t J D B C, yo u c an o p en a H i bern ate Ses s io n an d u si n gfi l e:///u sr/sh are
/do c /H T M L /en - U S /i n dex .h tm l th at J D B C c o n n ec ti o n . T h i s w ay yo u c an sti l l u se th e sam e tran sac ti o n
strategy an d u n derl yi n g c o n n ec ti o n p ro v i der.
U n derstan d Ses s io n fl u sh i n g:
S o m eti m es th e S essi o n syn c h ro n i z es i ts p ersi sten t state w i th th e database. P erfo rm an c e w i l l be affec ted
i f th i s p ro c ess o c c u rs to o o ften . Y o u c an so m eti m es m i n i m i z e u n n ec essary fl u sh i n g by di sabl i n g au to m ati c
fl u sh i n g, o r ev en by c h an gi n g th e o rder o f q u eri es an d o th er o p erati o n s w i th i n a p arti c u l ar tran sac ti o n .
I n a th ree ti ered arc h i tec tu re, c o n si der u si n g detac h ed o bj ec ts:

W h en u si n g a serv l et/sessi o n bean arc h i tec tu re, yo u c an p ass p ersi sten t o bj ec ts l o aded i n th e sessi o n
bean to an d fro m th e serv l et/J S P l ayer. U se a n ew sessi o n to serv i c e eac h req u est. U se Ses s io n. merge( ) o r
Ses s io n. s av eO rU pdate( ) to syn c h ro n i z e o bj ec ts w i th th e database.
I n a tw o ti ered arc h i tec tu re, c o n si der u si n g l o n g p ersi sten c e c o n tex ts:

D atabase T ran sac ti o n s h av e to be as sh o rt as p o ssi bl e fo r best sc al abi l i ty. H o w ev er, i t i s o ften n ec essary
to i m p l em en t l o n g ru n n i n g ap p lic ation trans ac tions , a si n gl e u n i t- o f- w o rk fro m th e p o i n t o f v i ew o f a
u ser. A n ap p l i c ati o n tran sac ti o n m i gh t sp an sev eral c l i en t req u est/resp o n se c yc l es. I t i s c o m m o n to u se
detac h ed o bj ec ts to i m p l em en t ap p l i c ati o n tran sac ti o n s. A n ap p ro p ri ate al tern ati v e i n a tw o ti ered
arc h i tec tu re, i s to m ai n tai n a si n gl e o p en p ersi sten c e c o n tac t sessi o n fo r th e w h o l e l i fe c yc l e o f th e
ap p l i c ati o n tran sac ti o n . T h en si m p l y di sc o n n ec t fro m th e J D B C c o n n ec ti o n at th e en d o f eac h req u est an d
rec o n n ec t at th e begi n n i n g o f th e su bseq u en t req u est. N ev er sh are a si n gl e sessi o n ac ro ss m o re th an o n e
ap p l i c ati o n tran sac ti o n o r yo u w i l l be w o rk i n g w i th stal e data.
D o n o t treat ex c ep ti o n s as rec o v erabl e:

T h is is m o re o f a n ec essary p rac ti c e th an a " best" p rac ti c e. W h en an ex c ep ti o n o c c u rs, ro l l bac k th e
T rans actio n an d c l o se th e Ses s io n. I f yo u
do n o t do th i s, H i bern ate c an n o t gu aran tee th at i n - m em o ry state
2 2 7 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
ac c u ratel y rep resen ts th e p ersi sten t state. F o r ex am p l e, do n o t u se Ses s io n. l o ad( ) to determ i n e i f an

i n stan c e w i th th e gi v en i den ti fi er ex i sts o n th e database; u se Ses s io n. get( ) o r a q u ery i n stead.
P refer l az y fetc h i n g fo r asso c i ati o n s:

U se eager fetc h i n g sp ari n gl y. U se p ro x i es an d l az y c o l l ec ti o n s fo r m o st asso c i ati o n s to c l asses th at are
n o t l i k el y to be c o m p l etel y h el d i n th e sec o n d- l ev el c ac h e. F o r asso c i ati o n s to c ac h ed c l asses, w h ere
th ere i s an a ex trem el y h i gh p ro babi l i ty o f a c ac h e h i t, ex p l i c i tl y di sabl e eager fetc h i n g u si n g l az y=" f al s e" .
W h en j o i n fetc h i n g i s ap p ro p ri ate to a p arti c u l ar u se c ase, u se a q u ery w i th a l ef t j o in f etch .
U se th e op e n s e s s ion in v ie w p attern , o r a di sc i p l i n ed as s e m b ly p h as e to av o i d p ro bl em s w i th u n fetc h ed data:

H i bern ate frees th e dev el o p er fro m w ri ti n g tedi o u s D ata Trans f e r O b j e c ts (D T O ). I n a tradi ti o n al E J B
arc h i tec tu re, D T O s serv e du al p u rp o ses: fi rst, th ey w o rk aro u n d th e p ro bl em th at en ti ty bean s are n o t
seri al i z abl e; sec o n d, th ey i m p l i c i tl y defi n e an assem bl y p h ase w h ere al l data to be u sed by th e v i ew i s
fetc h ed an d m arsh al l ed i n to th e D T O s befo re retu rn i n g c o n tro l to th e p resen tati o n ti er. H i bern ate
el i m i n ates th e fi rst p u rp o se. U n l ess yo u are p rep ared to h o l d th e p ersi sten c e c o n tex t (th e sessi o n ) o p en
ac ro ss th e v i ew ren deri n g p ro c ess, yo u w i l l sti l l n eed an assem bl y p h ase. T h i n k o f yo u r bu si n ess m eth o ds
as h av i n g a stri c t c o n trac t w i th th e p resen tati o n ti er abo u t w h at data i s av ai l abl e i n th e detac h ed o bj ec ts.
T h i s i s n o t a l i m i tati o n o f H i bern ate. I t i s a fu n dam en tal req u i rem en t o f safe tran sac ti o n al data ac c ess.
Co n si der abstrac ti n g yo u r bu si n ess l o gi c fro m H i bern ate:

H i de H i bern ate data- ac c ess c o de beh i n d an i n terfac e. Co m bi n e th e D A O an d Th re ad L oc al S e s s ion
p attern s. Y o u c an ev en h av e so m e c l asses p ersi sted by h an dc o ded J D B C asso c i ated to H i bern ate v i a a
U s erT ype . T h i s adv i c e i s, h o w ev er, i n ten ded fo r " su ffi c i en tl y l arge" ap p l i c ati o n s. I t i s n o t ap p ro p ri ate fo r
an ap p l i c ati o n w i th fi v e tabl es.
D o n o t u se ex o ti c asso c i ati o n m ap p i n gs:

P rac ti c al test c ases fo r real m an y- to - m an y asso c i ati o n s are rare. M o st o f th e ti m e yo u n eed addi ti o n al
i n fo rm ati o n sto red i n th e " l i n k tabl e" . I n th i s c ase, i t i s m u c h better to u se tw o o n e- to - m an y asso c i ati o n s
to an i n term edi ate l i n k c l ass. I n fac t, m o st asso c i ati o n s are o n e- to - m an y an d m an y- to - o n e. F o r th i s
reaso n , yo u sh o u l d p ro c eed c au ti o u sl y w h en u si n g an y o th er asso c i ati o n styl e.
P refer bi di rec ti o n al asso c i ati o n s:

U n i di rec ti o n al asso c i ati o n s are m o re di ffi c u l t to q u ery. I n a l arge ap p l i c ati o n , al m o st al l asso c i ati o n s m u st
be n av i gabl e i n bo th di rec ti o n s i n q u eri es.
C h ap ter 2 5 . Databas e P ortabil ity C ons id erations

25 .1 . P o rtabi l i ty B asi c s
25 .2. D i al ec t
25 .3 . D i al ec t reso l u ti o n
25 .4 . I den ti fi er gen erati o n
25 .5 . D atabase fu n c ti o n s
25 .6 . T yp e m ap p i n gs
2 5 . 1 . P ortabil ity B as ics

O n e o f th e sel l i n g p o i n ts o f H i bern ate (an d real l y O bj ec t/R el ati o n al M ap p i n g as a w h o l e) i s th e n o ti o n o f
database p o rtabi l i ty. T h i s c o u l d m ean an i n tern al I T u ser m i grati n g fro m o n e database v en do r to an o th er, o r
i t c o u l d m ean a fram ew o rk o r dep l o yabl e ap p l i c ati o n c o n su m i n g H i bern ate to si m u l tan eo u sl y target m u l ti p l e
database p ro du c ts by th ei r u sers. R egardl ess o f th e ex ac t sc en ari o , th e basi c i dea i s th at yo u w an t H i bern ate
to h el p yo u ru n agai n st an y n u m ber o f databases w i th o u t c h an ges to yo u r c o de, an d i deal l y w i th o u t an y
c h an ges to th e m ap p i n g m etadata.
2 5 . 2 . Dial ect
T h e fi rst lin e o f p o rtabi l i ty fo r H i bern ate is th e di al ec t, w h ic h is a sp ec i al i z ati o n o f th e
2 2 8 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
o rg. h ib ernate. dial ect. D ial ect c o n trac t. A di al ec t en c ap su l ates al l th e di fferen c es i n h o w H i bern ate m u st
c o m m u n i c ate w i th a p arti c u l ar database to ac c o m p l i sh so m e task l i k e getti n g a seq u en c e v al u e o r stru c tu ri n g
a S E L E CT q u ery. H i bern ate bu n dl es a w i de ran ge o f di al ec ts fo r m an y o f th e m o st p o p u l ar databases. I f yo u
fi n d th at yo u r p arti c u l ar database i s n o t am o n g th em , i t i s n o t terri bl y di ffi c u l t to w ri te yo u r o w n .
2 5 . 3 . Dial ect res ol ution

O ri gi n al l y, H i bern ate w o u l d al w ays req u i re th at u sers sp ec i fy w h i c h di al ec t to u se. I n th e c ase o f u sers
l o o k i n g to si m u l tan eo u sl y target m u l ti p l e databases w i th th ei r bu i l d th at w as p ro bl em ati c . G en eral l y th i s
req u i red th ei r u sers to c o n fi gu re th e H i bern ate di al ec t o r defi n i n g th ei r o w n m eth o d o f setti n g th at v al u e.
S tarti n g w i th v ersi o n 3 .2, H i bern ate i n tro du c ed th e n o ti o n o f au to m ati c al l y detec ti n g th e di al ec t to u se based

o n th e j av a. s q l . D atab as eM etaD ata o btai n ed fro m a j av a. s q l . C o nnectio n to th at database. T h i s w as m u c h better,
ex p ec t th at th i s reso l u ti o n w as l i m i ted to databases H i bern ate k n o w abo u t ah ead o f ti m e an d w as i n n o w ay
c o n fi gu rabl e o r o v erri deabl e.
S tarti n g w i th v ersi o n 3 .3 , H i bern ate h as a fare m o re p o w erfu l w ay to au to m ati c al l y determ i n e w h i c h di al ec t

to sh o u l d be u sed by rel yi n g o n a seri es o f del egates w h ic h i m p l em en t th e
o rg. h ib ernate. dial ect. res o l v er. D ial ectR es o l v er w h i c h defi n es o n l y a si n gl e m eth o d:
pu b l ic D ial ect res o l v eD ial ect( D atab as eM etaD ata metaD ata) th ro w s J D B C C o nnectio nE x ceptio n
. T h e basi c c o n trac t h ere i s th at i f th e reso l v er ' u n derstan ds' th e gi v en database m etadata th en i t retu rn s th e
c o rresp o n di n g D i al ec t; i f n o t i t retu rn s n u l l an d th e p ro c ess c o n ti n u es to th e n ex t reso l v er. T h e si gn atu re al so
i den ti fi es o rg. h ib ernate. ex ceptio n. J D B C C o nnectio nE x ceptio n as p o ssi bl y bei n g th ro w n . A
J D B CCo n n ec ti o n E x c ep ti o n h ere i s i n terp reted to i m p l y a " n o n tran si en t" (ak a n o n - rec o v erabl e) c o n n ec ti o n
p ro bl em an d i s u sed to i n di c ate an i m m edi ate sto p to reso l u ti o n attem p ts. A l l o th er ex c ep ti o n s resu l t i n a
w arn i n g an d c o n ti n u i n g o n to th e n ex t reso l v er.
T h e c o o l p art abo u t th ese reso l v ers i s th at u sers c an al so regi ster th ei r o w n c u sto m reso l v ers w h i c h w i l l be
p ro c essed ah ead o f th e bu i l t- i n H i bern ate o n es. T h i s m i gh t be u sefu l i n a n u m ber o f di fferen t si tu ati o n s: i t
al l o w s easy i n tegrati o n fo r au to - detec ti o n o f di al ec ts beyo n d th o se sh i p p ed w i th H I bern ate i tsel f; i t al l o w s
yo u to sp ec i fy to u se a c u sto m di al ec t w h en a p arti c u l ar database i s rec o gn i z ed; etc . T o regi ster o n e o r m o re
reso l v ers, si m p l y sp ec i fy th em (sep erated by c o m m as, tabs o r sp ac es) u si n g th e ' h i bern ate.di al ec t_ reso l v ers'
c o n fi gu rati o n setti n g (see th e D I A L E C T _ R E SO L V E R S c o n stan t o n o rg. h ib ernate. cf g. E nv iro nment ).
2 5 . 4 . I d entifier g eneration
W h en c o n si deri n g p o rtabi l i ty betw een databases, an o th er i m p o rtan t dec i si o n i s sel ec ti n g th e i den ti fi er
gen erati o n stratagy yo u w an t to u se. O ri gi n al l y H i bern ate p ro v i ded th e nativ e gen erato r fo r th i s p u rp o se,
w h i c h w as i n ten ded to sel ec t betw een a s e q ue nc e , id e ntity , o r tab le strategy dep en di n g o n th e c ap abi l i ty o f
th e u n derl yi n g database. H o w ev er, an i n si di o u s i m p l i c ati o n o f th i s ap p ro ac h c o m es abo u t w h en targtetti n g
so m e databases w h i c h su p p o rt id e ntity gen erati o n an d so m e w h i c h do n o t. id e ntity gen erati o n rel i es o n th e
S Q L defi n i ti o n o f an I D E N T I T Y (o r au to - i n c rem en t) c o l u m n to m an age th e i den ti fi er v al u e; i t i s w h at i s k n o w n
as a p o st- i n sert gen erati o n strategy bec au ase th e i n sert m u st ac tu al l y h ap p en befo re w e c an k n o w th e
i den ti fi er v al u e. B ec au se H i bern ate rel i es o n th i s i den ti fi er v al u e to u n i q u el y referen c e en ti ti es w i th i n a
p ersi sten c e c o n tex t i t m u st th en i ssu e th e i n sert i m m edi atel y w h en th e u sers req u ests th e en ti ti y be
asso c i ated w i th th e sessi o n (l i k e v i a sav e() e.g.) regardl ess o f c u rren t tran sac ti o n al sem an ti c s.
N ote
H i bern ate w as c h an ged sl i gh tl y o n c e th e i m p l i c ati o n o f th i s w as better u n dersto o d so th at th e
i n sert i s del ayed i n c ases w h ere th at i s feasi bl e.
T h e u n derl yi n g i ssu e i s th at th e ac tu al sem an c ti c s o f th e ap p l i c ati o n i tsel f c h an ges i n th ese c ases.
S tarti n g w i th v ersi o n 3 .2.3 , H i bern ate c o m es w i th a set o f en h an c ed i den ti fi er gen erato rs targetti n g
p o rtabi l i ty i n a m u c h di fferen t w ay.
2 2 9 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM
N ote
T h ere are sp ec i fi c al l y 2 bu n dl ed e nh anc e d gen erato rs:
o rg. h ib ernate. id. enh anced. Seq u enceStyl eG enerato r
o rg. h ib ernate. id. enh anced. T ab l eG enerato r
T h e i dea beh i n d th ese gen erato rs i s to p o rt th e ac tu al sem an ti c s o f th e i den ti fer v al u e gen erati o n to th e
di fferen t databases. F o r ex am p l e, th e o rg. h ib ernate. id. enh anced. Seq u enceStyl eG enerato r m i m i c s th e beh av i o r o f
a seq u en c e o n databases w h i c h do n o t su p p o rt seq u en c es by u si n g a tabl e.
2 5 . 5 . Databas e functions
W arni ng
T h i s i s an area i n H i bern ate i n n eed o f i m p ro v em en t. I n term s o f p o rtabi l i ty c o n c ern s, th i s
fu n c ti o n h an dl i n g c u rren tl y w o rk s p retty w el l fro m H Q L ; h o w ev er, i t i s q u i te l ac k i n g i n al l o th er
asp ec ts.
S Q L fu n c ti o n s c an be referen c ed i n m an y w ays by u sers. H o w ev er, n o t al l databases su p p o rt th e sam e set o f

fu n c ti o n s. H i bern ate, p ro v i des a m ean s o f m ap p i n g a log ic al fu n c ti o n n am e to a a del egate w h i c h k n o w s h o w
to ren der th at p arti c u l ar fu n c ti o n , p erh ap s ev en u si n g a to tal l y di fferen t p h ysi c al fu n c ti o n c al l .
Important
T ec h n i c al l y th i s fu n c ti o n regi strati o n is h an dl ed th ro u gh th e
o rg. h ib ernate. dial ect. f u nctio n. SQ L F u nctio nR egis try c l ass w h i c h i s i n ten ded to al l o w u sers to p ro v i de
c u sto m fu n c ti o n defi n i ti o n s w i th o u t h av i n g to p ro v i de a c u sto m di al ec t. T h i s sp ec i fi c beh av i o r i s
n o t fu l l y c o m p l eted as o f yet.
I t i s so rt o f i m p l em en ted su c h th at u sers c an p ro gram ati c al l y regi ster fu n c ti o n s w i th th e
o rg. h ib ernate. cf g. C o nf igu ratio n an d th o se fu n c ti o n s w i l l be rec o gn i z ed fo r H Q L .
2 5 . 6 . T y p e map p ing s
T h i s sec ti o n sc h edu l ed fo r c o m p l eti o n at a l ater date...
References
[P o E A A ] P atte rns of E nte rp ris e A p p lic ation A rc h ite c ture . 0 - 3 21 - 1 27 4 2- 0 . by M arti n F o w l er. Co p yri gh t © 20 0 3
P earso n E du c ati o n , I n c .. A ddi so n - W esl ey P u bl i sh i n g Co m p an y.
[J P w H ] J av a P e rs is te nc e w ith H ib e rnate . S ec o n d E di ti o n o f H i bern ate i n A c ti o n . 1 - 9 3 23 9 4 - 8 8 - 5 .

h ttp ://w w w .m an n i n g.c o m /bau er2 . by Ch ri sti an B au er an d G av i n K i n g. Co p yri gh t © 20 0 7 M an n i n g
P u bl i c ati o n s Co .. M an n i n g P u bl i c ati o n s Co ..
Co p yri gh t © 20 0 4 R ed H at M i ddl ew are, L L C.
2 3 0 of 2 3 0 1 1 / 1 6 / 2 0 0 9 5 : 1 0 PM

Hibernate Complete

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Hibernate Complete

Enviado por

Direitos autorais:

Formatos disponíveis

HIBERNATE - Relational Persistence for Idiomatic Java h ttp : / / docs. j b oss. org / h ib ernate/ core/ 3 .

HIBERNATE - Relational Persistence for

Hibernate Reference Documentation

an d th an k s to J am es Co bb (G rap h i c D esi gn ) an d Ch eyen n e W eav er (G rap h i c D esi gn )

3 .1 . P ro gram m ati c c o n fi gu rati o n

5 .4 . S Q L q u o ted i den ti fi ers

1 4 .1 8 . R o w v al u e c o n stru c to r syn tax

I f yo u are n ew to H i bern ate an d O bj ec t/R el ati o n al M ap p i n g o r ev en J av a, p l ease fo l l o w th ese step s:

1 . R ead Ch ap ter 1 , Tutorial fo r a tu to ri al w i th step - by- step i n stru c ti o n s. T h e so u rc e c o de fo r th e tu to ri al

2. R ead Ch ap ter 2, A rc h ite c ture to u n derstan d th e en v i ro n m en ts w h ere H i bern ate c an be u sed.

4 . U se th i s referen c e do c u m en tati o n as yo u r p ri m ary so u rc e o f i n fo rm ati o n . Co n si der readi n g [J P w H ] i f

I f yo u h av e q u esti o n s, u se th e u ser fo ru m l i n k ed o n th e H i bern ate w ebsi te. W e al so p ro v i de a J I R A i ssu e

Co m m erc i al dev el o p m en t su p p o rt, p ro du c ti o n su p p o rt, an d trai n i n g fo r H i bern ate i s av ai l abl e th ro u gh J B o ss

M i c h ael G l o egl . A l l c o de i s c o n tai n ed i n th e tutorials/web di rec to ry o f th e p ro j ec t so u rc e.

1 . 1 . P art 1 - T h e firs t Hibernate A p p l ication

T h e fi rst th i n g w e n eed to do i s to set u p th e dev el o p m en t en v i ro n m en t. W e w i l l be u si n g th e " stan dard

W e w i l l be u si n g M av en i n th i s tu to ri al , tak i n g adv an tage o f i ts tran si ti v e dep en den c y m an agem en t

< mo del V ers io n>4. 0. 0< / mo del V ers io n>

< gro u pI d>o rg. h ib ernate. tu to rial s < / gro u pI d>

< dependencies >

< ! - - B ecau s e th is is a w eb app, w e al s o h av e a dependency o n th e s erv l et api. - - >

< ! - - H ib ernate u s es s l f 4j f o r l o gging, f o r o u r pu rpo s es h ere u s e th e s impl e b ack end - - >

< / pro j ect>

N ex t, w e c reate a c l ass th at rep resen ts th e ev en t w e w an t to sto re i n th e database; i t i s a si m p l e J av aB ean

pack age o rg. h ib ernate. tu to rial . do main;

impo rt j av a. u til . D ate;

priv ate String titl e;

priv ate v o id s etI d( L o ng id) {

pu b l ic D ate getD ate( ) {

pu b l ic v o id s etD ate( D ate date) {

pu b l ic String getT itl e( ) {

pu b l ic v o id s etT itl e( String titl e) {

T h e id p ro p erty h o l ds a u n i q u e i den ti fi er v al u e fo r a p arti c u l ar ev en t. A l l p ersi sten t en ti ty c l asses (th ere are

S av e th i s fi l e to th e src /m ain /j av a/org /h ibern ate/tutorial/d om ain di rec to ry.

< ?x ml v ers io n=" 1. 0" ?>

H i bern ate D T D i s so p h i sti c ated. Y o u c an u se i t fo r au to - c o m p l eti o n o f X M L m ap p i n g el em en ts an d attri bu tes

< cl as s name=" E v ent" tab l e=" E V E NT S" >

< / h ib ernate- mapping>

S o far w e h av e to l d H i bern ate h o w to p ersi st an d l o ad o bj ec t o f c l ass E v ent to th e tabl e E V E NT S. E ac h i n stan c e

< cl as s name=" E v ent" tab l e=" E V E NT S" >

< / h ib ernate- mapping>

T h e id el em en t i s th e dec l arati o n o f th e i den ti fi er p ro p erty. T h e name=" id" m ap p i n g attri bu te dec l ares th e

T h e n ested generato r el em en t sp ec i fi es th e i den ti fi er gen erati o n strategy (ak a h o w are i den ti fi er v al u es

i den ti fi ers. I den ti fi er v al u e gen erati o n i s al so o n e o f H i bern ate' s m an y ex ten si o n p o i n ts an d yo u c an p l u gi n i n

< cl as s name=" E v ent" tab l e=" E V E NT S" >

< / h ib ernate- mapping>

S im i l ar to th e id el em en t, th e name attri bu te o f th e pro perty el em en t tel l s H i bern ate w h i c h getter an d setter

T h e titl e m ap p i n g al so l ac k s a type attri bu te. T h e typ es dec l ared an d u sed i n th e m ap p i n g fi l es are n o t J av a

S av e th i s m ap p i n g fi l e as src /m ain /resourc es/org /h ibern ate/tutorial/d om ain /E v en t. h bm . x m l.

1 . 1 . 4 . H i b e rnate c onf i g u rati on

A t th i s p o i n t, yo u sh o u l d h av e th e p ersi sten t c l ass an d i ts m ap p i n g fi l e i n p l ac e. I t i s n o w ti m e to c o n fi gu re

H i bern ate w i l l be c o n n ec ti n g to th e database o n beh al f o f yo u r ap p l i c ati o n , so i t n eeds to k n o w h o w to o btai n

F o r H i bern ate' s c o n fi gu rati o n , w e c an u se a si m p l e h ib ernate. pro perties fi l e, a m o re so p h i sti c ated

< ?x ml v ers io n=' 1. 0' enco ding=' u tf - 8' ?>

< h ib ernate- co nf igu ratio n>

< s es s io n- f acto ry>

< ! - - D atab as e co nnectio n s ettings - - >

< !- - J D B C co nnectio n po o l ( u s e th e b u il t- in) - - >

< ! - - SQ L dial ect - - >

< ! - - E nab l e H ib ernate' s au to matic s es s io n co ntex t management - - >

< ! - - D is ab l e th e s eco nd- l ev el cach e - - >

< ! - - E ch o al l ex ecu ted SQ L to s tdo u t - - >

< ! - - D ro p and re- create th e datab as e s ch ema o n s tartu p - - >

< / s es s io n- f acto ry>