Seam and EhCache – A Short Primer

There has been excellent coverage on how to attain the most performance out of your Seam-based Web applications. One aspect of improving Seam performance that, in my opinion, has received less attention, is the framework’s excellent built-in support for caching of entity java beans and query results.

In this article, I will briefly describe the steps I took in order to configure some basic to intermediate-level caching throughout our system. Although I did not go as far as to gather metrics on the performance gain, I will say that our entire team noticed a 30-50% improvement across the board – and all from some fairly easy work.

Because of our non-JBoss native application stack – we’re using WebLogic 11g – I chose to select EhCache as my cache provider of choice.

Package EhCache

For this primer we will be using EhCache 1.5. Download ehcache-1.5.0.jar (link) and place it in your /lib directory. Using your chosen build script (Ant, Maven, etc.), ensure that ehcache-1.5.0.jar is built to your EAR so that the classpath loader will find the library at startup.

Configure the Provider

Next, we need to make sure that EhCache (or your chosen cache provider) is properly configured. Modify components.xml and tell Seam to load the EhCache provider.

components.xml

<cache:eh-cache-provider name="cacheProvider"/>

The last step is to configure your persistence provider. Normally with Seam this configuration is broken up into several profiles (local, dev, test, and prod). In this example, I will be showing how I configured my persistence provider for our “local” profile.

Note that there are several options for hibernate.cache.provider_class; I have chosen to use the Singleton provider in this example.

persistence-local.xml

<!-- ... other properties .... ->
<property name="hibernate.cache.use_query_cache" value="true"/>
        <property name="hibernate.use_second_level_cache" value="true"/>
        <property name="hibernate.default_batch_fetch_size" value="16"/>
        <property name="hibernate.generate_statistics" value="true"/>
<property name="hibernate.cache.provider_class" value="net.sf.ehcache.hibernate.SingletonEhCacheProvider"/>
<property name="net.sf.ehcache.configurationResourceName" value="/ehcache2.xml"/>

Note in the example above that we have set hibernate.generate_statistics equal to true; this will initially help you tune your caching provider by enabling you to compare the query statistics (once properly setup via your log4j configuration).

Annotate Your Entities

Be aware that Seam comes with built-in caching; you can always annotate your entity java beans with the @Cache annotation. However, in this primer, we are building a path towards a more robust and advanced cache configuration. Even though the annotations remain the same, how they will be interpreted and used by EhCache will be up to us.

Annotating your entities are a simple and effective means to provide high-level caching of your application’s data. The three main cache strategies that we will concern ourselves with are:

READ_WRITE – should be used for objects that will be read and written to; these objects will change

READ_ONLY – should be used in cases where the object does not change; this tells Hibernate and EhCache to strongly cache this object

NONSTRICT_READ_WRITE – should be used in cases where an object is rarely written to; it will be cached to a degree less than READ but more than READ_WRITE

TRANSACTIONAL – this strategy is not available with EhCache but can be used with other cache providers

In my first entity, I have an object (User.java) that is both read and written; I want it to be cached, but it will need to be designated as READ_WRITE. User objects are heavily queried throughout our system but often modified. Later, I will show how you can provide more control over the caching of a specific object or region.

@Entity @Audited
@Table(name="USERS")
@Cache(usage=CacheConcurrencyStrategy.READ_WRITE
@Name("user")
@Scope(ScopeType.EVENT)
@BypassInterceptors
public class User implements Serializable
{
    /** the users internal id **/
	@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	private Long id;

    /** the userid/logon **/
	@UserPrincipal
	@Length(min=5, max=32)
	private String userId;

 // Rest of class below...

In my second entity I have an object called AdminValue.java; this object is used as metadata throughout the system. This object populates dropdowns and for the most part will not change.

@Entity @Audited
@Table(name = "APP_ADMIN_VALUES")
@Cache(usage=CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
@Name("adminValue")
@Scope(ScopeType.EVENT)
public class AdminValue implements Serializable
{

    /** the id **/
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Column(name="ID")
    private Long id;

    /**
     * name of the value
     */
    @NotNull
    @Length(max=50)
    @Index(name="IDX_ADMIN_VALUE_NAME")
    private String name;

    // Rest of class below...

Next, we have an object (MenuItem.java) that truly does not change. It is populated when the application deploys and will rarely, if ever, change. Because it is used throughout interface, though, I want it to be cached heavily to speed up page rendering.

@Entity
@Cache(usage=CacheConcurrencyStrategy.READ_ONLY, region = "com.bah.englink.MenuItem")
@Name("menuItem")
@Scope(ScopeType.EVENT)
@Table(name="APP_MENU_ITEMS")
public class MenuItem implements Serializable
{
	@Id
	@GeneratedValue(strategy = GenerationType.AUTO)
	private int id; //Uniquie id for the menu item

	@ManyToOne(optional=true)
	@Index(name="IDX_MENU_ITEM_FK01")
	private MenuItem parent; //Defines the parent associated with item, can be null for the top level

	@NotNull
	@Length(max=64)
	@Index(name="IDX_MENU_ITEM_NAME")
	private String name; //Name that displays on the screen

        // Rest of class below...

Using Query Hints with Named Queries

Named queries are particularly useful; they are strongly typed, and are therefore checked at compile-time, and cached via Seam/Hibernate JPA. You can provide further caching of named queries like so:

@NamedQueries({
@NamedQuery(
    name="lookupCategoryByName",
    query="from AdminCategory ac where ac.name=:name order by ac.name asc",
    hints={@QueryHint(name="org.hibernate.cacheable", value="true")}),
@NamedQuery(
    name="lookupCategoryByNameByModule",
    query="from AdminCategory ac where ac.name=:categoryName and ac.adminModule.name=:moduleName",
    hints={@QueryHint(name="org.hibernate.cacheable", value="true")})
})
public class AdminCategory implements Serializable
{

Advanced Configuration Via Regions

Here is where the fun begins; using the ehcache2.xml that we specified in our persistence provider, we can define minute details regarding how a particular object (or region of objects) are cached. This feature provides a high-level of control. There are many aspects of these configuration options that are a bit above my head, so I’ve outlined some examples that I used to show what is possible.

Whenever specifying a region with your @Cache annotation, you should try to have a corresponding region defined in your ehcache2.xml. Here are some examples.

//@Cache(usage=CacheConcurrencyStrategy.READ_WRITE, region = "com.bah.englink.ejb.User")

<cache name="com.bah.englink.ejb.User"
           maxElementsInMemory="10000"
           maxElementsOnDisk="20000"
           eternal="false"
           overflowToDisk="true"
           diskSpoolBufferSizeMB="100"
           timeToIdleSeconds="4000"
           timeToLiveSeconds="8000"
           memoryStoreEvictionPolicy="LRU"
            />
@Cache(usage=CacheConcurrencyStrategy.READ_ONLY, region = "com.bah.englink.MenuItem")

<cache name="com.bah.englink.MenuItem"
           maxElementsInMemory="10000"
           maxElementsOnDisk="5000"
           eternal="false"
           overflowToDisk="true"
           diskSpoolBufferSizeMB="40"
           timeToIdleSeconds="9000"
           timeToLiveSeconds="18000"
           memoryStoreEvictionPolicy="LFU"
            />

Note, the bundled ehcache2.xml that comes with ehcache-1.5.0.jar has many more examples for you to review and understand.

Logging

If you would like to see exactly which objects EhCache is storing, and when/if cache objects are being hit, you can turn on debug output from EhCache via your log4j.xml settings.

 <category name="org.hibernate.cache">
	<priority value="DEBUG"/>
   </category>
[/sourecode]

After doing so, you should see cache output, such as in the example below.
[sourcecode language='text']
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-90
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-66
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-65
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-51
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-89
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-82
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-88
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-1004
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-1005
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-14
15:42:44,107 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-83
15:42:44,123 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-26
15:42:44,123 DEBUG [ReadOnlyCache] Caching: com.bah.englink.MenuItem#-64

Conclusion

I hope this has been a useful, if intermediate, review of caching in your Seam-based application using Hibernate and EhCache. Please feel free to let me know what I have missed or if you find any mistakes.

More Resources

Hibernate: Truly Understanding Second-Level Cache

Second-Level Cache with EhCache

The Skinny on Apple’s iPhone App Store Rejections

I found this excellent resource on what Apple won’t let you get away with – based on actual submission experiences – but won’t necessarily tell you upfront.

Here are some examples:

• Cannot simulate failures or errors
• Must notify the user on internet connection failures
• Free/Lite version can’t up-sell (tricky)

Click here to visit the Application Submission Feedback page.

Top 5 IntelliJ IDEA Performance Tips

We use JetBrains IntelliJ IDEA Java IDE and love its features, functionality, and price point. Dealing with its performance is another matter, however. When developing Seam 2.x applications, IDEA can just crawl – and this is when sticking to just one project or SVN branch at a time. … Continue Reading

Porting a Seam 2.1.2 application to WebLogic 11g

I’m working on a lengthy re-configuration of a large Seam 2.x project from JBoss-native to WebLogic. It all sounds well and good, but if you’re familiar with the headaches of Java EE interopability, then you’ll realize this is no easy task.

I thought I would share one particular nagging exception that had me going for a while.

When you see something like the following but you know that the object is not null…

Caused by: org.jboss.seam.RequiredException: @In attribute requires non-null value: mySessionBean.myAttribute

You’ll likely need to annotate the mySessionBean class with the following:
@TransactionAttribute(REQUIRED_NEW)

This forces the managed persistence context to create a new transaction for the given bean. Without doing so, the context may be looking within the current transaction, wherein the expected object does not exist.

Perhaps Seam does this for you, and this is the problem with a framework that tries to hide much of the complexity of Java EE from the developer/integrator. As you can see, WebLogic expects this.

I’ll hopefully be putting together a guide on how I converted a 50+ SFSB Seam application to WebLogic once I find some time.

Seam Recipes [Part 1]: s:decorate

Introduction

As a developer, forms are one of my biggest grievances whenever I am building a Web application. Why? Well, for one, there is nothing pretty about creating a form. Even the best Web designers, with all of their fancy CSS wizardy, struggle to build clean, consistent, and reusable form layers that can be used anywhere within an application. To complicate matters, nothing in the HTML 4 spec (though, this will change with HTML 5) provide any sort of functionality around form elements.

Enter Seam, or, more specifically, Seam’s extended decorate component. As I will show you in this first Seam recipe, Java Server Faces (JSF) and Seam Decorate can be used to provide a small, reusable, and extremely versatile component that makes building complicated Web forms a snap. Now, I won’t go into details about how to build a new Seam project. But I will show you how I have leveraged Seam’s functionality to suit my needs. Let’s begin.

Part 1 – Creating a Simple s:decorate Facelet

Out of the box, s:decorate provides JSF form validation and formatting for messages. It also creates a targetable area for reRenders, which are especially helpful when creating AJAX applications using RichFaces. Through EL, Seam Decorate also understands the “required” attribute on your input components and can render both a visual element to your form in addition to automatic binding to your “messages” component.

Here is an example of a simple s:decorate, as often used within Seam’s own documentation.
exit.xhtml

	
		*

myEditForm.xhtml

	Last Name:
	

Easy, right?

Part 2 – Extending the Facelet with Additional Layouts

As forms go, there is not just one mode to handle all situations. Some forms are mixtures of editable fields, disabled fields, and even just outputted text. To handle this problem, I created four distinct layouts (facelets) to handle different situations:

• edit.xhtml, as previously seen
• view.xhtml
• simpleEdit.xhtml
• simpleView.xhtml

Now, I can create a form quickly and easily for both modes. When I want to output text in the familiar form layout, I just use the “vew” layout versus the “edit” layout. The “view” layout removes the s:label component and remove messages for error validation.

“simpleView” differs from “view.xhtml” only in the layout of the form element; it suits my needs particularly well for textareas or other large components, where I want the label to appear above the input area.

view.xhtml

myViewForm.xhtml

	Last Name:
	

Part 3 – Adding Custom Functionality

Something a lot of users like to have, and clients like talk about, are tool tips. Let’s add tool tip support our s:decorate components using the wz_tooltip Javascript library. You can choose any tool tip library that you would like; the s:decorate example below will support just about anything you throw at it. Because not all form elements will need a tool tip, we will control its presentation based on UI parameters. For the tool tip, we will simply print a [?] next to the input label. But I’ve also used this layout to print images and use more advanced tool tip engines, like Prototip2.

edit.xhtml

	
		*



[?]

We’ll apply the tool tip, when needed, by specifying the “id” of the tool tip, the title, and body of the text, as below. Here I also use our application’s resource bundle to grab the title and body of the tool tip.

myForm.xhtml

SSN:
	
	
	
	

Step 4 – Further Enhancements

At this point, I hope you have gotten some good ideas for how you can use the Seam Decorate component to easily reuse a flexible form component. It is easy to see how one would extend the component by adding such parameters as “reRender”, or “disabled”, to further control the appearance and functionality of the elements on your form.

Seam Framework – Top Resources for Developers

At my company, we have been using the Seam Framework for over two years to develop large-scale Java EE applications for our customers. It has been a rough ride at times but I firmly believe Seam requires every Java developer’s close look; even if you must ultimately choose one of the other numerous Java frameworks (Spring, Struts, Stripes, et. Al.), I think you will have gained a greater appreciation for Seam and Java enterprise development in general by evaluating Seam’s contributions to the JEE space. And no, I do not work for JBoss. I will be following this post with a series of Seam recipes showcasing how I have used Seam to solve common Web development challenges.

Here are some of the top Seam resources which I have found to be indispensable. Please feel free to recommend your favorites.

Seam Framework: Experience the Evolution of Java EE (2nd Edition)

This very recent release contains information and recipes on a number of the changes and improvements to the Seam Framework since the 2.0 release. It is authored by a Michael Yuan who is regarded as a Seam expert and a contributor to the project.

Seam in Action

While not quite as recent, Dan Allen – also an expert in the Seam space – gives the reader an opportunity to read more about how to apply Seam rather than a regurgitation of Seam documentation.

Java Persistence with Hibernate

A must have for working with Hibernate/JPA; although it doesn’t directly apply to Seam, you’ll find ways to apply your new knowledge of this powerful ORM framework within your Seam applications. Some of the topics covered include performance tuning your HQL/EJB-QL, indexing, Hibernate criteria, and composite keys.

Pro EJB 3: Java Persistence API

Great for beginning to learn building, testing, and persisting EJBs.

Practical RichFaces

One of the advantages of Seam is its nature of working directly “out of the box” with JSF, and in particular, the RichFaces JSF component suite. I’ve been using RichFaces for over two years and have been seen it mature immensely. The members of the RichFaces team are truly driven in their efforts to provide a world-class (and free) JSF library for developers.

Notable Web resources