JPA Implementation Patterns: Lazy Loading

anybody that has been working with hibernate for a while has probably seen a lazyinitializationexception or two, usually followed by a message such as "failed to lazily initialize a collection of role: com.xebia.jpaip.order.order.orderlines, no session or session was closed" or "could not initialize proxy - no session" . even though these message may baffle new users of hibernate, they are a lot better than the nullpointerexceptions openjpa gives you in these cases (at least when using runtime bytecode enhancement ).

to use jpa to its full potential it is imperative to understand how lazy loading works, as it allows you to model your complete database with all its relations without loading that whole database as soon as you access just one entity.

because of this it is unfortunate that the jpa 1.0 specification doesn't cover this subject in more depth than a few sentences along the lines of:

the eager strategy is a requirement on the persistence provider runtime that data must be eagerly fetched. the lazy strategy is a hint to the persistence provider runtime that data should be fetched lazily when it is first accessed. the implementation is permitted to eagerly fetch data for which the lazy strategy hint has been specified.

as of this writing, the proposed final draft of the jpa 2.0 specification does not add anything in this department. the best we can do for now is read the documentation of our jpa provider and do some experiments.

when lazy loading can occur

all @basic , @onetomany , @manytoone , @onetoone , and @manytomany annotations have an optional parameter called fetch. if this parameter is set to fetchtype.lazy it is interpreted as a hint to the jpa provider that the loading of that field may be delayed until it is accessed for the first time:

• the property value in case of a @basic annotation,
• the reference in case of a @manytoone or a @onetoone annotation, or
• the collection in case of a onetomany or a @manytomany annotation.

the default is to load property values eagerly and to load collections lazily. contrary to what you might expect if you have used plain hibernate before, references are loaded eagerly by default.

before discussing how to use lazy loading, let's have a look into how lazy loading may be implemented by your jpa provider.

build-time bytecode instrumentation, run-time bytecode instrumentation and run-time proxies

to make lazy loading work, the jpa provider has to do some magic to make the objects that are not there yet appear as if they are there. there are a number of different ways jpa providers can accomplish this. the most popular methods are:

• build-time bytecode instrumentation - the entity classes are instrumented just after they have been compiled and before they are packaged to be run. the advantage of this approach is that bytecode instrumentation can provide the best performance and the least leaky abstraction. a disadvantage is that it requires you to change your build procedure and is (therefore) not always compatible with ide's. the instrumented classes may be binary incompatible with their uninstrumented versions which could cause java serialization problems and the like, but this is not something i have heard anybody mention as a problem yet.
• run-time bytecode instrumentation - instead of instrumenting the entity classes at build-time, they can also be instrumented at run-time. this requires installing a java agent using the -javaagent option from jdk 1.5 and upwards, using class retransformation when running under jdk 1.6 or a later version, or some proprietary method if you are using an older jdk. so while this method does not require you to modify your build procedure, it is very specific to the jdk you are using.
• run-time proxies - in this case the classes are not instrumented but the objects returned by the jpa provider are proxies to the actual entities. these proxies can be dynamic proxy classes , proxies that have been created by cglib , or proxy collections classes. while requiring the least setup, this method is the least transparent of the ones available to jpa implementors and therefore requires you to know most about them.

run-time proxy based lazy loading with hibernate

while hibernate supports build-time bytecode instrumentation to enable lazy loading of individual properties, most users of hibernate will be using run-time proxies; it is the default and works well for most cases. so let's explore hibernate's run-time proxies.

two kind of proxies are created by hibernate:

1. when lazily loading an entity through a lazy many-to-one or one-to-one association or by invoking entitymanager.getreference , hibernate uses cglib to create a subclass of the entity class that acts a proxy to the real entity. the first time any method on that proxy is invoked, the entity is loaded from the database and the method call is passed on to the loaded entity. my colleague maarten winkels has blogged about the pitfalls of these hibernate proxies last year.
2. when lazily loading a collection of entities though a one-to-many or a many-to-many association, hibernate returns an instance of a class that implements the persistentcollection interface such as persistentset or persistentmap. the first time that collection is accessed, its members are loaded. the member entities are loaded as regular classes, so the hibernate proxy pitfalls mentioned above don't apply here.

to get a feel for what happens here, you might want to step through some simple jpa code in the debugger and see the objects that hibernate creates. it will increase your understanding if the mechanism a lot.

run-time bytecode instrumentation with openjpa

openjpa offers a number of enhancement methods , as the documentation calls it, of which i found run-time bytecode instrumentation the easiest to set up.

stepping through the debugger you can see that openjpa does not create proxies. instead a few extra fields have appeared in each entity class, with names like pcstatemanager or pcdetachedstate. more importantly you can see that a lazily loaded entity has all its fields set to 0 or null and that its state is only loaded when a method is invoked on it. more precisely, a property that is configured to be loaded lazily is only loaded when its getter is invoked.

it is very important to know that direct access to the fields of a lazily loaded entity (or the field behind a lazily loaded property) does not trigger loading of that entity (or field). also, when the session is no longer available openjpa does not throw an exception as hibernate does but just leaves the values in their uninitialized state, later causing the nullpointerexceptions i mentioned above.

openjpa vs. hibernate

the first difference between these two approach you might notice is the objects that get proxied/instrumented:

• openjpa instruments all entities which means it can detect when you access a lazy reference or collection from the referring entity and it will then return an actual entity or a collection of actual entities. only when you lazily load an entity using entitymanager.getreference or when you have configured a property to be lazily loaded, will you get a (partially) empty entity.
• in the case of a lazy reference (or an entity that has been lazily loaded with entitymanager.getreference) hibernate proxies the lazy object itself using cglib, which causes the proxy pitfalls mentioned before. when using a lazy collection hibernate is just as transparent as openjpa. finally, hibernate does not support lazily loaded properties using proxies.

if you compare openjpa's instrumentation to the run-time proxies created by hibernate you can see that the approach taken by openjpa is more transparent. unfortunately it is let down somewhat by openjpa's less than robust error handling.

the pattern

so now that we know how to configure lazy loading and how it works, how can we use it properly?

step 1 would be to examine all your associations and see which should be lazily loaded and which should be eagerly loaded. as a rule of thumb i start out leaving all *-to-one associations eager (the default). they usually don't add up to a large number of queries anyway and if they do, i can change them. then i examine all *-to-many associations. if any of them are to entities that are always accessed and therefore always loaded, i configure them to be loaded eagerly. and sometimes i use the hibernate specific @collectionofelements annotation to map such "value type" entities.

step 2 is the most important. to prevent any lazyinitializationexceptions or nullpointerexceptions you need to make sure that all access to your domain objects occurs within one transaction . when domain objects are accessed after a transaction has finished, the persistence context can no longer be accessed to load the lazy objects, and that causes these problems. there are two ways to solve this:

1. the most pure way is to place a service facade (or remote facade if you will) in front of your services and only communicate with clients of your service facade through transfer objects (a.k.a. data transfer objects a.k.a. dto's). the facade's responsibility is to copy all appropriate values from your domain objects to the data transfer objects, including making deep copies of references and collections. the transaction scope of your application should include the service facade for this pattern to work, i.e. set your facade to be @transactional or give it a proper @transactionattribute .
2. if you are writing a model 2 web application with an mvc framework, a widely used alternative is to use the open entitymanager in view pattern. in spring you can configure a servlet filter or a web mvc interceptor that will open the entity manager when a request comes in and will keep it open until the request has been handled. the means the same transaction is active in your controller and in your view (jsp or otherwise). while purists may argue that this makes your presentation layer depends on your domain objects, it is a compelling approach for simple web applications.

step 3 is to enable sql logging of your jpa provider and exercise some of the use cases of your applications. it is enlightening to see what queries are performed when entities are accessed. the sql log can also provide you with input for performance optimizations so you can revisit the decisions you made in step 1 and tune your database. in the end lazy loading is all about performance , so don't forget this step!

i hope this blog has given you some insight into how lazy loading works and how you can use it in your application. in the next blog i will delve deeper into the topic of the dto and service facade patterns. but before i leave you i would like to thank everybody that came to my j-spring 2009 talk on this subject . i had a lot of fun! it really seems a lot of people are wondering how to effectively use jpa because i got a lot of questions. unfortunately the questions made me run out of time. next time i will pay more attention to the girl with the time card. and bring my own water. thanks again for being there!

from http://blog.xebia.com