2 Using JDeveloper with Coherence

This chapter describes how to set up JDeveloper to build and run Coherence-based Java applications.

Configuring Oracle JDeveloper for Coherence
JDeveloper Basics
Accessing the Data Grid from Java
Creating Your First Coherence-Based Java Application

2.1 Configuring Oracle JDeveloper for Coherence

To start and configure JDeveloper for use with Coherence:

Open a terminal window and verify that the PATH environment variable is set to include \oracle\product\jdk160_05\bin. If the PATH environment variable does not include jdk160_05\bin directory, then set the variable as follows:
1. Set the JAVA_HOME environment variable to the base of the JDK installation.
```
set JAVA_HOME=\oracle\product\jdk160_05
```
2. Include %JAVA_HOME%\bin in the PATH environment variable.
```
set PATH=%JAVA_HOME%\bin;%PATH%
```
3. Start JDeveloper. If you get a message asking you to select a role, select Default Role. If you get a message asking whether you want to migrate from previous versions of JDeveloper, select No. Close any window that displays the Tip of the Day."
  
  Figure 2-1 Select Role Dialog Box
After JDeveloper starts, click New Application to create an application.

An application is a way of grouping projects or source code. This new application will hold the Coherence projects.
In the dialog box, change the application name to Coherence, the directory to \home\oracle\labs, and the application package prefix to com.oracle.coherence.handson. Click OK, and then click Cancel when prompted to create a new project.

Figure 2-2 Creating an Application in JDeveloper
Add the Coherence JAR files to the default project properties. From the Tools menu, select Default Project Properties. The Default Properties dialog box opens.

Figure 2-3 Default Properties Dialog Box
Click Libraries and Classpath, and click the Add Library button. The Add Library dialog box opens.

Figure 2-4 Add Library Dialog Box
In the Add Library dialog box, click New.

The Create Library dialog box opens.

Figure 2-5 Create Library Dialog Box
Click Add Entry to open the Select Path Entry dialog box.

Find and expand the coherence\lib directory, which is under the \oracle\product directory.
Highlight and select the coherence.jar file add it to the Classpath. Then, click OK to return to the Create Library dialog box.

Figure 2-6 Select Path Entry Dialog Box
In the Create Library dialog box, change the name in the Library Name field to Coherence. The contents of the dialog box should look like this:

Figure 2-7 Create Library Dialog Box with the Coherence Jar on the Classpath
Click OK in the Create Library, Add Library, and Default Project Properties dialog boxes to return to the JDeveloper IDE. Oracle JDeveloper is now set up with the correct Coherence libraries.

2.2 JDeveloper Basics

This section describes some of the common tasks that are a part of building projects in JDeveloper.

Creating a New Application and Project
Creating a Java Class
Changing Project Properties, Setting Runtime Configuration, and

2.2.1 Creating a New Application and Project

To create a new application in JDeveloper:

Choose File > New... in the JDeveloper IDE. This opens the New Gallery.
Choose General > Projects in the Categories section of the New Gallery dialog box and Generic Project in the Items section. Click OK.

Figure 2-8 Creating a New Application in the New Gallery
In the Create Generic Application dialog box, enter the name the project.
- Replace Application1 with the name of your application.
- Ensure that directory path to the project is correct.
- Click Next.
Figure 2-9 Providing an Application Name
JDeveloper asks you to create a new project within the application. Enter a name for the project. If necessary, select a project technology from the Available list. Click Finish to create the new project.

Figure 2-10 Providing a Project Name

2.2.2 Creating a New Project in an Existing Application

To create a project in an existing application:

Right-click the Coherence application and choose New... In the New Gallery choose Projects under Categories and Generic Project under Items. Click OK.

Figure 2-11 Creating a New Project in an Existing Application
Enter a Project Name, ensure that the Default Package is set correctly, and select a Project Technology if necessary. Click Finish.

Figure 2-12 Providing Details for the New Project

2.2.3 Creating a Java Class

To create a new Java class in JDeveloper:

Right-click the project entry in the Navigator pane and select New.
Select Java under the General category and select Java Class. Click OK.

Figure 2-13 Creating a Java Class in the New Gallery
Replace Class1 with the name of your class. Select the Generate Main Method check box if the file must be runnable. Click OK to create the Java class.

Figure 2-14 Providing Details for the Java Class

2.2.4 Changing Project Properties, Setting Runtime Configuration, and

To change the project's runtime properties in JDeveloper:

Right click the project and select Project Properties.
In the Project Properties dialog box select Run/Debug/Profile and click Edit.

Figure 2-15 Project Properties Dialog Box
You can set a number of values in the Edit Run Configuration dialog box:
- Set Virtual Machine to either Client or Server.
- Set values for local storage and log level in the Java Options field. For example:
```
-Dtangosol.coherence.distributed.localstorage=false -Dtangosol.coherence.log.level=3
```
Figure 2-16 Setting the Runtime Configuration
Click OK in the Edit Run Configuration dialog box and OK in the Project Properties dialog box to return to the JDeveloper IDE.

2.2.5 Adding JARS and Libraries to the Project Classpath

To add JAR files or libraries to the project classpath:

Right click the project and select Project Properties.
In the Project Properties dialog box select Libraries and Classpaths and click Add JAR/Directory.
Navigate to the JAR file or directory that you want to include in the classpath.

Figure 2-17 Adding JARS or Libraries to the Classpath
Click Select in the Add Archive or Directory dialog box. Click OK in the Project Properties dialog box.

Figure 2-18 Adding a JAR or Library to the Project Classpath

2.3 Accessing the Data Grid from Java

In this exercise, you will develop a simple, Java console-based application to access, update, and remove simple types of information from a Coherence clustered cache. You also get familiar with using the Coherence Java APIs. In this exercise, using JDeveloper, you perform the following:

Create a new project
Create a new NamedCache
Put information into the cache and then retrieve it
Retrieve information about the cache

All Coherence caches are named, have a lifetime scoped by the cluster instance in which they exist, and implement the com.tangosol.net.NamedCache interface. The NamedCache interface is an extension of java.util.Map and holds data and resources that are shared among the cluster members. Each NamedCache holds data as key/value pairs. Keys and values can be both simple and complex object types. The NamedCache interface provides extensions to the Map interface, such as locking and synchronization, storage integration, queries, event aggregations, and transactions. The cache topology (or implementation) can be swapped or changed without code changes. Table 2-1 describes some of the more commonly used methods within the NamedCache interface:

Table 2-1 Methods in the NamedCache Interface

Method Name	Description
`voidclear()`	Removes all entries from the `NamedCache`.
`boolean containsKey(Object key)`	Returns `true` if `NamedCache` contains an entry for the key.
`boolean containsValue(Objectvalue)`	Returns `true` if there is at least one entry with this value in `NamedCache`.
`Object get(Object key)`	Gets the entry from `NamedCache` for that key.
`Object put(Object key,Objectvalue)`	Puts an object in the cache and returns the previous value (if any).
`Object remove(Object key)`	Removes the mapping for this `key` from this map if present. Inherited from `ConcurrentMap`.
`Set entrySet()`	Returns a set of key/value pairs.
`Collection values()`	Gets all values back as a collection.
`CacheService getCacheService()`	Returns the `CacheService` that this `NamedCache` is a part of.

The com.tangosol.net.CacheFactory class is typically used to obtain an instance of a NamedCache. Table 2-2 describes some of the more commonly used methods in the CacheFactory class.

Table 2-2 Methods in the CacheFactory Class

Method Name	Description
`static Cluster ensureCluster(`)	Obtains a cluster object running Coherence services.
`static void shutdown()`	Shuts down all clustered services.
`static NamedCache getCache(String cache)`	Returns an instance of a cache. Either joins an existing cache in the cluster or creates the cache if this is the first member.

For a full list of methods, in the NamedCache interface and the CacheFactory class, see the Javadoc in \oracle\product\coherence\doc.

To create an application to access, update, and remove simple types of information from a Coherence clustered cache:

Create a new project in JDeveloper.

See "Creating a New Project in an Existing Application" if you need detailed instructions. Name the project InsertValue. Ensure that directory is C:\home\oracle\labs\InsertValue.

Check the Project Properties>Libraries and Classpath value for the Coherence entry. Ensure that the full path is provided for the coherence.jar: C:\oracle\product\coherence\lib\coherence.jar
Create your first Coherence Java program.

See "Creating a Java Class" if you need detailed information. Name the class MyFirstSample and select the Generate Main Method check box.
1. In the JDeveloper editor, write the code to create a NamedCache, put in a value, and then verify the value that you put in. Save the file after you finish coding. Example 2-1 illustrates a sample program.
  Example 2-1 Creating a NamedCache; Inserting and Verifying Values
```
package com.oracle.coherence.handson;

import com.tangosol.net.CacheFactory;
import com.tangosol.net.NamedCache;

public class MyFirstSample {
    public MyFirstSample() {
    }

    public static void main(String[] args) {
        
       // create or get a named cache called mycache 
       NamedCache myCache = CacheFactory.getCache("mycache");
       
       // put key, value pair into the cache. 
       myCache.put("Name","Tim Middleton");
        
       System.out.println("Value in cache is " + myCache.get("Name"));
        
    }
}
```
2. Run the program in JDeveloper: right-click the MyFirstSample.java class in the editor and choose Run.
3. You should see messages similar to the following:
  
  Figure 2-19 Output for Creating a NamedCache and Storing and Retrieving Values
Now create another Java class which gets the value from your cache, instead of doing a put and then a get. Name this Java class MyFirstSampleReader. See "Creating a Java Class" if you need detailed information. Example 2-2 illustrates a sample program.
Example 2-2 Getting a Value from the Cache
```
package com.oracle.coherence.handson;

import com.tangosol.net.CacheFactory;
import com.tangosol.net.NamedCache;

public class MyFirstSampleReader {
    
    public MyFirstSampleReader() {
    }

    public static void main(String[] args) {
        // ensure we are in a cluser
        CacheFactory.ensureCluster();
         
        // create or get a named cache called mycache 
        NamedCache myCache = CacheFactory.getCache("mycache");
                
        System.out.println("Value in cache is " + myCache.get("Name"));
    }
}
```
Run the MyFirstSampleReader class. Figure 2-20 illustrates the output from the program. Note that a null value is returned. Although MyFirstSample successfully created and populated the NamedCache, the cache only existed within the MyFirstSample process memory. When MyFirstSample terminated so did the cache.

Note that a null value returned. When the MyFirstSample class runs, it is storage-enabled by default unless otherwise specified. So, it creates a NamedCache when it starts, puts the value in, and when the class completes, the NamedCache disappears.

Figure 2-20 Output from the Sample Reader Program
Start the cache-server.cmd that you used in "Testing a Coherence Installation", run MyFirstSample to put the value in the NamedCache, and then run MyFirstSampleReader to read the value from the cache. Note the output illustrated in Figure 2-21: the "Gene Smith" value stored by MyFirstSample is returned by MyFirstSampleReader. By default, unless specified otherwise, all processes start as storage-enabled. This means that the process can store data as part of the cluster.

Figure 2-21 Output from the Sample Reader Program with a Running Cache Server

This should not be the case for a process that joins the cluster only to perform an operation, such as putting in a value and then leaving, like MyFirstSample. You must modify the process so that it is not storage-enabled.

This is done using the following Java command-line parameter.
```
-Dtangosol.coherence.distributed.localstorage
```
The value -Dtangosol.coherence.distributed.localstorage=true specifies that the process is storage-enabled. Setting the parameter to false specifies that the process is not storage-enabled.
1. Change the project properties to disable local storage. See "Changing Project Properties, Setting Runtime Configuration, and" for detailed information.
2. Ensure the Virtual Machine field is set to server. Enter the following value in the Java Options field:
```
-Dtangosol.coherence.distributed.localstorage=false -Dtangosol.coherence.log.level=3
```
  The Java option tangosol.coherence.log.level=level changes the level of logging produced by Coherence. The level can be set to a number between 0 and 9. The default is 5. A value of 0 means no logging. A value of 9 means extremely verbose. A value of 3 is often useful enough for most application development.
Shut down any running cache servers and rerun your MyFirstSample class.

You receive a message similar to the one in Figure 2-22 indicating that storage is not enabled on the cluster, because you have set this member to be storage-disabled.

Figure 2-22 Output from JDeveloper if Storage is Disabled
Start the cache server again and retest. You should now see that the data is persisted between running the two Java examples.

2.4 Creating Your First Coherence-Based Java Application

In this exercise, you develop a simple Java console-based application to access, update, and remove simple types of information from a Coherence clustered cache.

This exercise assumes you have completed "Testing a Coherence Installation". Make sure you have a cache server and a Coherence console up and running.

Unlike client/server applications, in which client applications typically "connect" and "disconnect" from a server application, Coherence-based clustered applications simply "ensure" they are in a cluster, after which they may use the services of the cluster. Coherence-based applications typically do not "connect" to a cluster of applications; they become part of the cluster.

To create a Java console-based application to access, update, and remove simple types of information from a Coherence clustered cache:

Examine the methods in the CacheFactory class using the Coherence Java documentation (Javadoc) that is shipped in the \oracle\product\coherence\doc directory.
Develop a simple Java console application (Java class) called YourFirstCoherenceApplication that uses the CacheFactory class to join a cluster (using the ensureCluster method), and then leave the cluster (using the shutdown method). See "Creating a Java Class" if you need detailed informaiton on creating a Java class.
Examine the methods that are available in the NamedCache interface using the Javadoc.
Extend your application to use the CacheFactory method getCache to acquire a NamedCache for the cache called mycache (the same cache name used in the exercise: "Testing a Coherence Installation").
With the NamedCache instance, use the "get" method to retrieve the value for the key "message" (the same key used in the exercise: "Testing a Coherence Installation").

Output the value to the standard out using the System.out.println(….) method.

Example 2-3 illustrates a sample Coherence-based Java application:

Example 2-3 Sample Coherence-Based Java Application

package com.oracle.coherence.handson;

import com.tangosol.net.CacheFactory;
import com.tangosol.net.NamedCache;

public class YourFirstCoherenceApplication {
public YourFirstCoherenceApplication() {
}

   public static void main(String[] args) {

      CacheFactory.ensureCluster();

      NamedCache myCache = CacheFactory.getCache("mycache");

      String message = (String)myCache.get("message");

      System.out.println(message);

      CacheFactory.shutdown();
YourFirstCoherenceApplication yourfirstcoherenceapplication = new YourFirstCoherenceApplication(); 
   }

}

Ensure that you have the Coherence cache server and console up and running. In the console, connect to the mycache cache. For example:
```
Map(?): cache mycache
```
Execute YourFirstCoherenceApplication from the JDeveloper IDE and view the result.

Figure 2-23 illustrates the output from YourFirstCoherenceApplication. The output indicates that there is no data in the cache for the message key.

Figure 2-23 Output from Coherence-Based Java Application—No Value for the Key
Using the running Coherence shell, change the key "message." For example, enter
```
Map <mycache>: put message "hello"
```
Rerun YourFirstCoherenceApplication from the JDeveloper IDE to see the changed values. Figure 2-24 illustrates that cache now holds the value hello for the key message.

Figure 2-24 Output from Coherence-Based Java Application—A Data Value for the Key
Rerun YourFirstCoherenceApplication with the following JVM parameter. Notice that the output is the same as the previous run.
```
-Dtangosol.coherence.distributed.localstorage=false
```
Shut down your cache server and Coherence shell instances. Restart the cache server and then rerun YourFirstCoherenceApplication (with the preceding JVM parameter set). Note the output is now null.
If you change the value of the message key in your application (using the put method), is the new value available through the Coherence shell?
1. For example, comment out the get method and add the put method.
```
//String message = (String)myCache.get("message");
  String message = (String)myCache.put("message", "bye");
```
2. Run YourFirstCoherenceApplication.
3. Run the get command in the Coherence console.
```
Map (mycache): get message
```
  You should see bye as the output.
Try setting the following JVM parameter and rerunning YourFirstCoherenceApplication. Note that it causes the application to return a null value since local storage is not enabled.
```
-Dtangosol.coherence.distributed.localstorage=false 
```