As web applications are architected/re-architected caching is often added to reduce data access bottlenecks that often hinder scalability and performance. Weblogic Server (WLS) now has a range of features, collectively called "ActiveCache", that provides Coherence cache integration in a Java Servlet context, a JPA context (Toplink Grid) and an HTTP session context (Coherence*Web).Ê This post will concentrate on the first of these integration points and show how a J2EE web application cab be packaged, deployed and managed in WLS to seamlessly take advantage of a data caching tier.
So how do all the parts work together? With WLS 10.3.4+ you can now use its NodeManager (a process monitoring and management service) to manage components other than WLS, like Coherence. There are also additional administration pages in the WLS Administration Console (http://localhost:7001/console) to configure Coherence clusters (via the Environment > Coherence Clusters menu):
And Coherence cluster nodes (via the Environment > Coherence Servers menu):
These allow a cluster to be defined and all the cluster nodes to be started and stopped from the WLS Admin console.
In this example the Servlet and all the Coherence cache nodes are all part of the same Coherence cluster, but the Servlet does not hold any data, i.e. its storage attribute is disabled. This means that when it is deployed or un-deployed no cache data needs to be moved between the cluster nodes - because it will not hold any data. This topology is shown below:
Note: the diagram above shows how HTTP session data can be cached in Coherence but the topology is identical for this use case, where web application data is being cached.
These instructions make a few assumptions, namely that:
To setup the environment to deploy the sample application the following steps are required:
- Configure and startup WLS NodeManager that will start and stop the Coherence cluster nodes.
This step may be obvious for readers who are familiar with WLS, but just for completeness these are the steps I needed to do on a Mac.
FirstÊ I set the environment parameters used to start-up WLS:
# Dir where WLS installed to
export USER_MEM_ARGS="-Xmx1024m -XX:PermSize=1024m"
Then I set the NodeManager parameters in the nodemanager.properties file ($MW_HOME/wlserver/common/nodemanager/nodemanager.properties) so that it did not try to use the native libraries (this step is platform specific) and that SSL was not used - to make the setup simpler;
I also added the WLS domain that my application will be deployed to the nodemamanger.domain ($MW_HOME/wlserver/common/nodemanager/nodemanager.domain) properties file;
Finally I started the NodeManager for my laptop (note a NodeManager is associated with a machine and not a domain);
- Configure a new Machine definition using the WLS Admin console
Next you need to define a Machine definition that will enable a NodeManager to be used to start the Coherence cluster. As was mentioned above, a NodeManager is associated with a server not a domain and "A machine is the logical representation of the computer that hosts one or more Weblogic Server instances (servers)."
To configure a Machine navigate to Machines screen in the WLS Admin console via the Environment > Machines menu and click on the New button and specify:
Name: MyMachine - the name of your machine
Machine OS: Other - I did not specify one here as there are no native libraries for Mac OSX
Type: Plain - so as to avoid additional security configuration
Note: I left all other parameters to the defaults.
As the NodeManager has been started up using the default parameters it should be found without specifying any additional setup. The monitoring page for the machine should then show that the NodeManager is reachable.
If the status is not reachable the take a look at the output for the NodeManager if you have started it from a console or at the NodeManager log file ($MW_HOME/wlserver/common/nodemanager/nodemanager.log).
- Configure and startup the Coherence cluster
To startup the Coherence cluster that will be used to cache the web application data you need to create a Coherence cluster configuration and then define the and startup the Coherence servers. To configure the Coherence cluster navigate to the Coherence cluster definition screen via the Environment > Coherence Clusters menu. The configuration parameters I used were:
Name: MyCluster - this is the name of the cluster and will help prevent accidental clustering between different environments
Use a Custom Cluster Configuration File: /Users/Dave/Documents/workspace/WLSCohWebAppEAR/EarContent/APP-INF/classes/tangosol-coherence-override.xml - this is the Coherence operational override file for the cluster, NOT the cache configuration file
To configure the Coherence cluster servers navigate to the Coherence cluster definition screen via the Environment > Coherence Servers menu. The General configuration parameters I used were:
Name: CacheServer1 - this can be any name
Machine: MyMachine - select the name of the Machine definition you have just created
Cluster: MyCluster - select the name of the cluster you have just created
Unicast Listen Port: 9999 - the default is 8888 but its worth selecting something different and from that other clusters to prevent your servers accidentally joining another cluster
All other default general configuration parameters were accepted.
The Server Start configuration parameters entered were:
Java Home: /Library/Java/Home - the base dir of your Java installation
Java Vendor: Apple
BEA Home: /Users/Dave/apps/wls1035_dev/wlserver - the installation dir for WLS
Root Directory: /Users/Dave/apps/mywls/user_projects/domains/base_domain - the domain base dir
Class Path: /Users/Dave/apps/wls1035_dev/modules/features/weblogic.server.modules.coherence.server_10.3.4.1.jar:/Users/Dave/coherence/3.7/coherence-java/coherence/lib/coherence.jar - note the order of these Jar files seems to be important and you should specify the correct path separator, in this case a ':' char
Arguments: -Xms1024m -Xmx1024m -Dtangosol.coherence.cacheconfig=/Users/Dave/Documents/workspace/WLSCohWebAppEAR/EarContent/APP-INF/classes/coherence-cache-config.xml -Dtangosol.coherence.distributed.localstorage=true -Dtangosol.coherence.role=CacheServer - the arguments to the JVM that will run the Coherence cache server. Note: the last parameter as in the Coherence override file the default storage setting has been set to false, so for storage enabled nodes it has to be explicitly enable. This is because its not possible to override the storage enabled default setting by using system properties just for the TestServlet other than setting this property in the WLS startup script.
Obviously you will need to modify these paths to reflect thoseÊ in your environment.
To create additional Coherence Servers you can just clone this one on the Coherence Servers admin page and change the name of the new Coherence Server.
The Coherence Cluster is started from the Coherence Servers page which you can navigate to by selecting the Environment > Coherence Servers menu. On this page select the Control tab, select all the Coherence Servers that you have just defined and click on the StartÊ button.
- Deploy the Coherence and ActiveCache shared libraries
The Coherence and ActiveCache Jar files can be deployed in a number of ways, added to the CLASSPATH of WLS, deployed as a shared library or as part of the web application. In this case the Jar files have been deployed as a shared library, which provides both usage isolation (as only applications that import the libraries will have them in scope) and a minimal resource overhead (as only 1 copy of the classes will be loaded). Shared libraries can be deployed through the WLS Admin Console via the Environment > Deployments menu, as shown below (accepting the default settings should be fine to get started):
- Package and deploy the web application that will utilize a Coherence cache
This can be done as either a WAR or EAR file. I choose an EAR file here. You can do this either by dropping the archive into the autodeploy directory of WLS, through the Admin console, using the Weblogic Scripting Tool (WLST) or through and IDE like Eclipse (that uses WLST). I choose the later for convenience. An easy way to do so is through the wizards provided by the Oracle Enterprise Pack for Eclipse (OEPE) plugin - as shown below:
To do this you can just import the example EAR web application projects (and its dependent projects),Ê update the library paths for Coherence etc and deploy to the target WLS.
Testing of the sample web application
To access the TestServlet sample web application go to the URL http://<your hostname>:7001//WLSCohWebApp/TestServlet , for instance http://192.168.56.1:7001/WLSCohWebApp/TestServlet.. It outputs the Coherence cluster members and also puts an entry in a cache called "MyCache" whose key is the HTTP session Id and the value is the last modified value of the HTTP session. Its output is shown below:
This output tells you how many clients have an active session and how many cluster members are in the cluster. All this cache data is visible across all invocations of this Servlet, so application data like reference data or values in drop-down-lists etc, that doesn't change frequently are ideal candidates.
Description of the sample web application
The ActiveCache functionality allows cache references to be configured as resources. In the TestServlet the Resournce annotation is used to dynamically inject a reference to the NamedCache "MyCache", as shown below:
A Coherence cache reference (NamedCache) resource and also be looked up using a JNDI lookup.
The shared libraries that the Servlet references are specified in the weblogic-application.xml file:
The Coherence cluster can be monitored through JMX. To see the metrics for the cluster open JConsole on the machine you are testing on and select one of the weblogic.server.nodemanager... process (a Coherence management server could also be started to provide remote access). If you expand the node tree you will see the following metrics:
For explicit startup and shutdown operations a Servlet listener class has been registered that will shutdown the web application as a cluster node if the application is un-deployed.
I hope this post has been useful and gives you an overview of how the WLS ActiveCache functionality can be used in a web application to provide fast access to frequently used data. Although the cache is used as a "side cache" here - where the data is added to the cache explicitly - it could easily be configured to load the required data into the cache on-demand from a database or some other data source. Other options not explored here, but worth considering, are scripting the cluster setup and startup using WLST.
The sample application can be downloaded from here.
Other useful resources