4 Building Your First Coherence Application

This chapter provides step-by-step instructions for building and running a basic Coherence example and demonstrates many fundamental Coherence concepts. The sample application is a simple Hello World application and is implemented both as a standalone Java application and a JSP application. Lastly, a JDeveloper section has been included that provides some basic instructions for setting up JDeveloper when developing with Coherence.

Note:

The example in this chapter is basic and is only intended to teach general concepts. For more advanced examples, download the Coherence Examples included with the documentation library.

4.1 Task 1: Define the Example Cache

Caches are defined in a cache configuration deployment descriptor and are referred to by name within an application. This allows configuration changes to be made to a cache without having to change an application's code. The following cache configuration defines a basic distributed cache which is mapped to the cache name hello-example.

4.2 Task 2: Configure and Start the Example Cluster

Caches are hosted on a Coherence cluster. At run time, any JVM process that is running Coherence automatically joins the cluster and can access the caches and other services provided by the cluster. When a JVM joins the cluster, it is called a cluster node, or alternatively, a cluster member. For the sample applications in this chapter, two separate Java processes form the cluster: a cache server process and the Hello World application process. For simplicity, the two processes are collocated on a single computer. The cache server, by default, is configured to store cache data.

The example cluster uses an operational override file to modify the out-of-box default cluster configuration. In particular, the default configuration is modified to create a private cluster which ensures that the two processes do not attempt to join an existing Coherence cluster that may be running on the network. The default configuration is also modified to load the example-config.xml cache configuration file instead of the default cache configuration file.

To configure and start the example cluster:

Create a file named tangosol-coherence-override.xml.

Add the following override configuration and replace cluster_name and port with values that are unique for this cluster. For example, use your name for the cluster name and the last four digits of your phone number for the port.

Save the file to the same directory where the example-config.xml file was saved.

From a command prompt, start a cache server instance using the DefaultCacheServer class and include the location of the coherence.jar library and the configuration files as a Java -cp option. For example:

4.3 Task 3: Create and Run a Basic Coherence Standalone Application

Step 3 is a multi-part step that includes a sample Hello World application and instructions for running and verifying the example. The application is run from the command line and starts a cache node that joins with a cache server. The application puts a key named k1 with the value Hello World! into the hello-example cache and then gets and prints out the value of the key before exiting. Lastly, an additional cluster node is started to verify that the key is in the cache.

4.3.1 Create the Sample Standalone Application

Applications use the Coherence API to access and interact with a cache. The CacheFactory class is used to get an instance of a cache and the NamedCache interface is used to retrieve and store objects in the cache. The Hello World application is very basic, but it does demonstrate using the CacheFactory class and the NamedCache interface.

4.3.2 Run the Sample Standalone Application

Run the Hello World application and include the location of the coherence.jar library and the configuration files as a Java -cp option. In addition, restrict the client from locally storing partitioned data. For example:

The Hello World application starts. The cache factory instance is created and becomes a member of the cluster. The k1 key with the Hello World! value is loaded into the hello-example cache. The key is then retrieved from the cache and the value is emitted as part of the output. Lastly, the cache factory is shutdown and leaves the cluster before the Hello World application exits.

4.3.3 Verify the Example Cache

The cache server in this example is configured, by default, to store the cache's data. The data is available to all members of the cluster and persists even after members leave the cluster. For example, the Hello World application exits after it loads and displays a key in the cache. However, the cache and key are still available for all cluster members.

This step uses the cache factory command-line tool to connect to the hello-example cache and list all items in the cache. It demonstrates both the persistent and distributed nature of Coherence caches.

To verify the cache:

From a command prompt, start a standalone cache factory instance using the CacheFactory class and include the location of the coherence.jar library and the configuration files as a Java -cp option. For example:

The cache factory instance starts and becomes a member of the cluster and returns a command prompt for the command-line tool.

At the command-line tool command prompt, get the hello-example cache using the cache command:

cache hello-example

At the command-line tool command prompt, retrieve the contents of the cache using the list command.

list

The command returns and displays:

k1 = Hello World!

4.4 Task 4: Create and Run a Basic Coherence JavaEE Web Application

Step 4 is a multi-part step that includes the Hello World application re-implemented as a JSP page. Instructions are included for packaging the sample as a Web application to be deployed to a JavaEE server. The application runs on the application server and starts a cache node that joins with a cache server. The application puts a key named k2 with the value Hello World! into the hello-example cache and then gets and prints out the value of the key before exiting. Lastly, an additional cluster node is started to verify that the key is in the cache.

4.4.1 Create the Sample Web Application

To create the sample Web application:

Create a basic Web application directory structure as follows:

/
/WEB-INF
/WEB-INF/classes
/WEB-INF/lib

Copy the below JSP to a text file and save the file as hello.jsp in the root of the Web application directory.

4.4.2 Deploy and Run the Sample Web Application

From a browser, run the Hello World application by accessing the hello.jsp file using the following URL. Substitute host and port with values specific to the deployment.

http://host:port/hello/hello.jsp

The Hello World application starts. The cache factory instance is created and becomes a member of the cluster. The k2 key with the Hello World! value is loaded into the hello-example cache. The key is then retrieved from the cache and the value is displayed in the browser. Lastly, the cache factory shuts down and leaves the cluster.

4.4.3 Verify the Example Cache

The cache server in this example is configured, by default, to store the cache's data. The data is available to all members of the cluster and persists even after members leave the cluster. For example, the Hello World application exits after it loads and displays a key in the cache. However, the cache and key are still available for all cluster members.

This step uses the cache factory command-line tool to connect to the hello-example cache and list all items in the cache. It demonstrates both the persistent and distributed nature of Coherence caches.

To verify the cache:

From a command prompt, start a standalone cache factory instance using the CacheFactory class and include the location of the coherence.jar library and the configuration files as a Java -cp option. For example:

The cache factory instance starts and becomes a member of the cluster and returns a command prompt for the command-line tool.

At the command-line tool command prompt, get the hello-example cache using the cache command:

cache hello-example

At the command-line tool command prompt, retrieve the contents of the cache using the list command.

list

The command returns and displays:

k2 = Hello World!

4.5 Using JDeveloper for Coherence Development

This section provides basic instructions on how to setup JDeveloper for Coherence development. The instructions are for running Coherence within the IDE which is a common approach during development. While the instructions are specific to JDeveloper, the same approach should be possible with any IDE. See your IDE's documentation for specific instructions.

4.5.1 Running Coherence in JDeveloper

JDeveloper can run cache server (DefaultCacheServer) and cache (CacheFactory) instances. Each instance is started as a separate Java process and emits standard output to the process' log. Input (such as cache commands) can be entered directly in the process as if it were started from the command line. This configuration facilitates development and testing Coherence solutions.

To run Coherence in JDeveloper:

In JDeveloper, create a new Generic Application, which includes a single project. If you are new to JDeveloper, consult the Online Help for detailed instructions.

In the Application Navigator, double-click the new project. The Project Properties dialog box displays.

Select the Libraries and Classpath node. The Libraries and Classpath page displays

From the Run/Debug/Profile page, click New. The Create Run Configuration dialog box displays.In the Name text box, enter a name for the new run configuration. In the Copy Settings From drop-down box, choose default. Click OK. The new run configuration displays in the Run Configuration list.

From the Run Configuration list, select the new Run Configuration and click Edit. The Edit Run Configuration dialog box displays and the Launch Settings node is selected.

From the Launch Settings page, click Browse to select a Default Run Target. The Choose Default Run Target dialog box displays.

From the directory tree, select COHERENCE_HOME\lib\coherence.jar\com\
tangosol\net\DefaultCacheServer.class and click Open. The DefaultCacheServer class is entered as the default run target as shown below:

Tip:

Use the Java Options text box to set Coherence system properties.

Select the Tool Settings Node. The Tool Settings page displays.

From the Additional Runner Options section, click the Allow Program Input check box. A check mark in the box indicates that the option is selected.

Click OK.

Repeat Steps 6 through 14 and select COHERENCE_HOME\lib\coherence.jar\
com\tangosol\net\CacheFactory.class as the default run target as shown below:

Click OK to close the Project Properties dialog box.

Use the Run button drop-down list to select and start the run configuration for the cache server. A cache server instance is started and output is shown in the process's log tab as shown below:

Use the Run button drop-down list to select and start the run configuration for the cache. A cache instance is started and output is shown in the process's log tab as shown below.

From the Cache Factory's Running Log tab, use the Input text box located at the bottom of the tab to interact with the cache instance. For example, type help and press Enter to see a list of valid commands.

4.5.2 Viewing Thread Dumps in JDeveloper

Java can dump a list of threads and all their held locks to standard out. This is achieved in Linux environments using the kill command and in Windows environments using ctrl+break. Thread dumps are very useful for troubleshooting during development (for example, finding deadlocks).

When developing Coherence solutions in JDeveloper, you can view thread dumps directly in a process's log tab. This is achieved, by sending the above signals to the Java process running in JDeveloper.

To view thread dumps in JDeveloper:

From a shell or command prompt, use JDK_HOME/bin/jps to get the Process ID (PID) of the Java process for which you want to view a thread dump.

On Linux, use kill -3PID to send a QUIT signal to the process. On Windows, you must use a third-party tool (such as SendSignal) to send a ctrl+break signal to a remote Java process.

The thread dump is viewable in the process's log in JDeveloper.

4.5.3 Creating Configuration Files in JDeveloper

JDeveloper can create Coherence configuration files. JDeveloper loads the appropriate XSD files and lists all the elements in the Component Palette. In addition, JDeveloper validates configuration files against the XSD and provides XML code completion. The following procedure creates both a cache configuration file and an operational override file. The same procedure can be used for any of the Coherence configuration files.

To create a cache configuration and operation override file in JDeveloper:

Extract coherence-cache-config.xsd, coherence-cache-config-base.xsd, coherence-operational-config.xsd, coherence-operational-config-base.xsd, and coherence-config-base.xsd from the COHERENCE_HOME\lib\coherence.jar library to a directory on your computer.

Enter coherence-cache-config.xml as the file name and save it to the same directory where the XSD is located. At run time, this file must be found on the classpath and must be loaded before the coherence.jar file.

Click OK. The cache configuration file is created, opened for editing, and listed in the Application Navigator under the resources folder for your project.