Using MySQL and Memcached on the GlassFish Application Server

 
 
By Pramod Gopinath and Rick Palkovic, April 2008  

Articles Index

Many developers use memcached and MySQL to cache content as part of their web application. This article presents a simple example application that uses MySQL and accesses a memcached server. The application is deployed on the GlassFish application server.

The example application was developed and deployed on a Sun Ultra 40 Workstation running the Solaris 10 Operating System. The format for commands and path names shown in the article are specific to the Solaris 10 OS, but you can easily adapt them to other platforms.

 
Contents

Installing the Tools
Running the Example Application
Application Overview
Summary
For More Information

Installing the Tools

You must install the following software to successfully run the example application:

MySQL Database. MySQL is the world's most popular open-source database software.

GlassFish v2 Update 1. GlassFish is a free, open-source application server that implements the latest features of the Java EE 5 platform.

Memcached Caching System. As defined on the memcached web site, memcached is a distributed-memory object-caching system, generic in nature but intended for use in speeding up dynamic web applications by alleviating database load. Portions of your web application in which the content changes infrequently are great candidates to be cached into a memcached server. By caching these portions, you increase the responsiveness of your application.

A classic use-case scenario for memcached is a tag cloud. A tag cloud is a set of weighted tags, typically shown as words. The tags can appear in alphabetical order, in a random order, sorted by weight, and so on, and they are updated infrequently.

The example application described in this article reuses components from the well-known example Java Pet Store application to create a cloud of tags associated with pets.

Installing the GlassFish-MySQL Bundle

The GlassFish application server and MySQL have been released as a convenient single bundle. You can download and install the bundle at no cost. Just follow these instructions:

  1. Download the GlassFish V2 + MySQL binary.
  2. Install the bundle by following instructions from the installation guide, specifically the section titled Installing Application Server 9.1 Update 1 With MySQL Community Server.

After you have installed the bundle, be sure to follow the installation guide instructions in the section To Start MySQL. These instructions describe how to create the necessary MySQL database and users. You will find scripts to install the database and tables required for the application later in this article.

Starting the GlassFish Application Server

Start the GlassFish application server with the following command:

    $GLASSFISH_HOME/bin/asadmin start-domain domain1
 

where the environment variable $GLASSFISH_HOME refers to the location where you have installed GlassFish v2 — for example, /export/home/glassfish_install/v2ur1/glassfish.

GlassFish Log Files

You can access a log file containing information about the server at the following location on your system:

    $GLASSFISH_HOME/domains/domain1/logs/server.log
 

Installing Memcached

If you are using the Solaris OS, you can install memcached with Cool Stack, an open-source software stack optimized for the Sun Solaris platform. Binaries for other platforms are available from the memcached web site.

After a successful Cool Stack installation in the Solaris 10 environment, the memcached executable is available at the following location:

    /opt/coolstack/bin/memcached
 

You can now launch the memcached server from the command line. For example, to launch the memcached server on a Solaris 10 machine with IP address 123.456.789.123 and accepting connections on port 11211, use the following command: 

    /opt/coolstack/bin/memcached -d -m 2048 -l 123.456.789.123 -p 11211
 

Downloading the Example Application

Download the example application, which is provided in the form of a jar file, and expand it into a directory. For example, the following commands expand the jar file into the /export/home/samples/memcachedSample directory: 

   mkdir /export/home/samples
   cd /export/home/samples
   jar xvf /export/home/downloads/memcachedSample.jar
   cd memcachedSample
 

For the remainder of this article, assume that the application directory is /export/home/samples/memcachedSample, identified as <application_dir> .

The application uses the Whalin memcached Java client, maintained by Greg Whalin, to access the memcached servers. Many other memcached Java clients are available. The authors of this article chose Whalin's client because of the strength of its documentation and active support.

If you want to adapt the example application and scale it up to solve your own business problem, research the suitability of the Whalin client and, if necessary, choose another.

Configuring the Application for the Memcached Server

To make the example application work, you must edit one source file that specifies server information. In that file, named WhalinMemcachedClient.java, you identify the server by the IP address and port number you used to start the memcached server.

  1. To edit the file with the Vi text editor, use the following commands: 
        cd  
                        
<application_dir>
    cd src/java/com/sun/javaee/blueprints/petstore/cache
    vi WhalinMemcachedClient.java
     

    You can, of course, use another text editor of your choice.

  2. In the file, locate the following section: 
        String[] servers =
    {
       ...
    }
     

    Replace the IP address and port number listed between the curly braces with those of the memcached server(s) that you have configured. For example,

        String[] servers =
    {
       "123.456.789.123:11211"
    }
     
  3. You may also want to edit the next section: 
        Integer[] weights =
    {
       ...
    }
     

    The weights are integers representing the ability of each server to handle load, where larger integers represent greater capability. List the weights in the same order as the servers you listed in the previous step. For example, if you have a single server with weight 3, edit the weights statement as follows:

        Integer[] weights =
    {
       3
    }
     

    See SockIOPool in the memcached Javadoc for more information.

Editing the Build Properties File

Now, edit the build.properties file to ensure that the value of javaee.home is the same as that of the environment variable GLASSFISH_HOME, the location where you installed GlassFish v2.

  1. In a text editor, open the file 
                             
<application_dir>/bp-project/build.properties.
     
  2. In the build.properties file, search for the property javaee.home. If its value is different from the value of GLASSFISH_HOME, edit the value as necessary.

After you have made the changes, you can build the application.

Building the Application

Build the application with the following commands:

    cd  
                    
<application_dir>

    ant
 

Creating a MySQL User and Database

You must now create a MySQL user and database for use with the example application. You must also create database tables and load them with data.

  1. In a command shell, start MySQL as root:
  2.    >mysql -u root
     
  3. Use the following MySQL commands to create a user and database, and exit MySQL.
  4. mysql>CREATE DATABASE memcachedSample;
mysql>CREATE USER 'web20'@'localhost' IDENTIFIED BY 'web20';
mysql>GRANT ALL PRIVILEGES ON memcachedSample.* TO 'web20'@'localhost';
mysql>exit;
     
  5. Use the following commands to create the tables and load them with data:
  6.    >mysql -uweb20 -pweb20 -Dbpwebapp < \
      
                        
<application_dir>/setup/sql/create_mysql.sql
   >mysql -uweb20 -pweb20 -Dbpwebapp  < \
      
                        
<application_dir>/setup/sql/memcachedSampledata.sql
     

Creating the JDBC Connection Pool and JNDI Resources

You now must create the JDBC connection pool and JNDI resources that the example uses. The build.xml file in the memcachedSample directory contains ant targets that create these resources.

Use the following commands to create the required JDBC connection pool and JNDI resources:

    cd  
                    
<application_dir>/
    ant create-resource-local
 

Deploying the Application

You are now ready to deploy the application using the application war file memcachedSample.war, located in the memcachedSample/dist directory. Use the following command to deploy the application: 

    cd  
                    
<application_dir>/dist
    $GLASSFISH_HOME/bin/asadmin deploy memcachedSample.war
 

If the deployment is successful, your browser should be able to access the application home page at the following URL: 

    http://server:8080/memcachedSample
 

If you cannot access the application home page, refer to the server log to learn about any errors that may have occurred. The log file is available at the following location: 

    $GLASSFISH_HOME/domains/domain1/logs/server.log
 
Running the Example Application

To launch the application, enter the following URL at the address line of a web browser: 

    http://server:8080/memcachedSample
 

Your browser should open a page like the one shown in Figure 1.

Index page for MemcachedSample application
Figure 1. Example Application Index Page
 

When you click Run the Sample, the index.jsp page is composed on the server and loaded into your browser. This page, shown in Figure 2, displays the tag cloud. The complete HTML section that displays the tag cloud is cached into the memcached server. The first time the page is loaded, a query is executed to the backing MySQL database, then the HTML section describing the tag cloud is stored into the memcached server.

Example Application Tag Cloud
Figure 2. Example Application Tag Cloud
 

You can view statistics about the memcached servers that are known to this application by clicking on Memcached Stats in the upper right section of the display. In Figure 3, note that the application recognizes two memcached instances running on the same machine on different ports: 11211 and 11212.

Memcached Server Statistics
Figure 3. Memcached Server Statistics
 

At the bottom of the statistics page, note the link Remove TagCloud. When you click the link, the entry stored in the memcached servers for this tag cloud is removed, and a subsequent call to index.jsp reloads the contents.

Note also the Tag link in the upper right corner of the page. Clicking this link enables you to create a new tag for the tag cloud. The application contains code that removes the cached tag cloud from the memcached servers when you create a new tag.

Figure 4 shows the page where you can add a new tag.

Add a new tag and clear the tag cloud from memcached
Figure 4. Add New Tag
 

The list of current tags displayed at the bottom of the page is obtained by querying the database using a Java Persistence API (JPA) call. This information is also a good candidate to be stored on the memcached server.

Application Overview

As mentioned earlier, this example reuses components from the Java Pet Store application to create a tag cloud that displays tags associated with pets. To keep the example as simple as possible, calls to the memcached servers have been incorporated into the JavaServer Pages (JSP) technology pages themselves. These are the three JSP files of interest: 

    web/index.jsp
    web/createTag.sjp
    web/memcachedStats.jsp
 

You can examine each file to see how it interacts with the memcached server.

The index.jsp File

Open the web/index.jsp file, and locate the following block of code near the end: 

    String tagCloudStr = (String) mcc.get("tagCloud");
    if (tagCloudStr == null) {
        tagCloudStr = cf.getTagsCloudInfo(3);
        mcc.set(tagCloudKey, tagCloudStr);
    }
 

The first statement checks to see whether the memcached server has the tag cloud information, using the key tagCloud. The if test determines whether the information is present. If it is not, it is obtained by calling into the method cf.getTagsCloudInfo(), where cf is an instance of the CatalogFacade class. This method takes as an argument the number of tags to display on each row — in this case, 3. The logic of the method can be summarized as follows:

  • Use Java Persistence API calls to fetch the data from the backing MySQL database.
  • Using the results returned, create the HTML table cell component associated with the tag cloud.
  • Use some logic to associate each tag with the font size that will be used to display the tags in the tag cloud.

After the HTML string has been created, it is stored into the memcached server by the call to mcc.set(tagCloudKey, tagCloudStr), where tagCloudKey has the value tagCloud.

The createTag.jsp File

Open the web/createTag.jsp file and locate the following lines of code: 

    String tagName = request.getParameter("tagName");

    if (tagName != null && !"".equals(tagName)) {
        // Insert the tag into the database.
        cf.addTag(tagName);
        mcc.delete(tagCloudKey);        // where tagCloudKey = "tagCloud"
    }
 

This code inserts a new tag into the database. After doing so, the mcc.delete() method deletes the information associated with the tagCloudKey from the memcached server.

The memcachedStats.jsp File

Open the web/memcachedStats.jsp file and note the following statement: 

        Map allServersInfo = mcc.stats();
 

The mcc.stats() method is part of the API provided by the Whalin memcached Java client. It is used to display the statistics of the memcached server. The map it returns is keyed on the server name. Its value is another map that contains stats, with stat name as key and value as value.

Refer to the Javadocs of the Whalin memcached client for more information.

Summary

In this article, you deployed a simple application that uses MySQL as its database and accesses a memcached server. You deployed the application on the GlassFish application server. With the techniques illustrated in the example, you can use the memcached distributed memory caching system to increase the performance of your own database-backed web applications.

For More Information

Acknowledgments

The authors wish to thank the following individuals for their help:

  • Sridatta Vishwanath for proposing this project
  • Binu John for his help and insight when coming up with the best use-case scenario
  • Kim LiChong for helping the author get started with memcached and GlassFish v2
  • Sathyan Catari for providing the section on GlassFish and MySQL bundle
Rate and Review
Tell us what you think of the content of this page.
Excellent   Good   Fair   Poor  
Comments: