Oracle Coherence and Oracle WebLogic Server: Setting Up an Eclipse Development Environment
This tutorial shows you how to configure an Eclipse-based development environment to develop Web and enterprise applications for Oracle WebLogic Server that use the Oracle Coherence
data caching system.
Approximately 1 hour
This tutorial covers the following topics:
Place the cursor over this
icon to load and view all the screenshots for this tutorial.
(Caution: This action loads all screenshots simultaneously, so the response
time may be slow depending on your Internet connection.)
Note: Alternatively, you can place the cursor
over each individual icon in the following steps to load and view only the screenshot
associated with that step.
This tutorial
walks you through the setup required to create Java enterprise (Web) applications that run on Oracle WebLogic Server, use Oracle Coherence, and are developed by using Eclipse.
Oracle Coherence is a component of Oracle Fusion Middleware that enables organizations to predictably scale mission-critical applications by providing fast and reliable access to frequently used data. By automatically and dynamically partitioning data in memory across multiple servers, Oracle Coherence enables continuous data availability and transactional integrity, even in the event of a server failure. As a shared infrastructure, Oracle Coherence combines keeping data local with the local processing power to perform real-time data analysis, in-memory grid computations, and parallel transaction and event processing. Oracle Coherence comes in three editions: Java Edition, C++ Edition, and .NET Edition. This tutorial covers the Java Edition.
Oracle WebLogic Server 10g
is the world's best application server for building and running enterprise applications and services. It fully implements the latest Java EE standards and offers choice in development frameworks and integral tooling. Comprehensive and accessible management capabilities enable administration of sophisticated systems via a well-designed graphical console and/or automation. All users benefit from Oracle WebLogic Server's reliability and performance, which has been tested over years of enterprise-grade production use in demanding customer environments the world over.
The steps in this tutorial will take you from the product prerequisites to the basic setup that is required to code, deploy, and test a Web application that uses Oracle Coherence.
You can use Oracle Coherence with applications that run on Oracle WebLogic Server in the following ways:
Direct application interaction with Coherence
Application server&level (Session) access to Coherence
covers the basic setup and a very high-level example of the first way. By simply adding a .jar file (Java library) to your application or application server classpath, and with a few lines of code, your application can cache information that can be accessed by other applications in such a way that is fault tolerant and scalable, all without needing the extra overhead and infrastructure of relational databases,
persistence (such as JPA, EJB, Hibernate, and so on), or Object Relationship Management (ORM) facilities. Instead, you can use simple Plain Old Java Objects (POJOs), which can be handled by servlets or JSPs on WebLogic Server.
the software for this tutorial can be freely downloaded. This tutorial was developed using Microsoft Windows XP SP2, but these instructions can be modified to work on Linux as well if you have the requisite knowledge of the differences between the two operating systems.
Before starting this tutorial, you should:
Have access to or have installed the following software:
Oracle Coherence for Java Version 3.4.2 (or later) ()
Oracle WebLogic Server 10gR3 for Windows ()
Eclipse 3.4 (Ganymede) for Windows ()
Additionally, you
need the Oracle Enterprise Pack for Eclipse (OEPE), which is a free set of plug-ins and extensions that will make developing for and deploying to Oracle WebLogic Server easier and smoother. The OEPE can be installed using Eclipse&s Software Update function and is detailed in the section of this tutorial titled &.&
Oracle WebLogic Server
installs a Java 1.6 JDK, which is required for running the server and other products. After the products are installed, ensure that it is the WebLogic-supplied JDK that you are using by setting your system's path environment settings appropriately.
Although you can install the products in locations of your choice, the following generic labels
refer to these locations in the tutorial instructions.
$MIDDLEWARE_HOME: The product installation location for Oracle WebLogic Server (The current installation documentation refers to this as BEA_HOME.)
$COHERENCE_HOME: The location of your Oracle Coherence installation
$WORKSPACE: The location of the Eclipse workspace that you will create
$DOMAIN_HOME: The location of the WebLogic Server Domain that you will create
Refer to the following documentation:
Download the
for reference.
This section assumes that you have:
Installed all the required products (Oracle Coherence, Oracle WebLogic Server, and Eclipse 3.4)
Verified that Oracle Coherence works according to the Coherence installation or verified the instructions that were linked in the previous section
In this topic, you create a WebLogic Server domain, choose the basic Eclipse workspace, and install the Oracle Enterprise Pack for Eclipse.
To create the WebLogic Server domain, perform the following steps:
Read the following documentation on creating an Oracle WebLogic Server domain with the Domain Configuration Wizard:
Open the WebLogic Domain Configuration Wizard by selecting
Start & All Programs & Oracle WebLogic & WebLogic Server 10gR3 & Tools & Configuration Wizard.
Select the Create a new WebLogic Server domain option and click Next.
Create a domain based on WebLogic Server.
(Accept the default that is presented.) Click Next.
Enter the login credentials to be used. Enter weblogic as the username and password.
Accept the defaults for Development Mode and the JDK (Sun SDK 1.6), and click Next.
Select No for any further changes. Click Next.
Name the domain WLS_A. Choose the location, and then click Create to generate the domain.
When finished, make sure that Start Admin Server is deselected and click Done.
To choose the Eclipse workspace location, perform
the following steps:
Launch Eclipse.
You will be presented with the Eclipse Workspace Launcher. Choose a location for your workspace. (For example, use D:\oracle\tutorial. This location will be referred to as $WORKSPACE from this point forward.)
To install the Oracle Enterprise Pack for Eclipse, perform the following steps:
With your Eclipse workspace open, close the Welcome screen that is displayed.
Access the Eclipse Software Update function. From the Help menu, select Software Updates.
Available Software tab, and then click Add Site.
Enter the following URL: /otn_software/oepe/ganymede. Click OK.
Note: You can find more information about the Oracle Enterprise Pack for Eclipse .
Expand the new site that you just added and select the check box for Oracle Enterprise Pack for Eclipse. Confirm that all the subcomponents are selected and click Install.
Click Next on the Install screen.
Accept the license terms and click Finish on the Review Licenses screen.
After the installation, you
see a dialog box to finalize the process. Click Yes to restart Eclipse. When prompted, open your tutorial workspace again.
In this topic, you create the Coherence-enabled Web project in Eclipse.
To create a new Coherence-enabled Web application project, perform the following steps:
Select File & New & Dynamic Web Project.
Name the project SimpleCacheApp and click the New button for Target Runtime.
Select Oracle & Oracle WebLogic Server 10gR3 as the type and click Next.
Browse to the WebLogic Server home ($MIDDLEWARE_HOME\wlserver_10.3) and click Finish.
The Dynamic Runtime Module version
automatically updates to 2.5 and the Configuration is set to Default Configuration for Oracle WebLogic Server 10gR3.
No further configuration is needed. Click Finish.
To add the libraries that are necessary for your application to use Coherence, perform the following steps:
Right-click SimpleCacheApp in the Project Explorer and select Properties.
Go to the Java Build Path category and click the Libraries tab. Click Add Library.
Select User Library and click Next.
Click the User Libraries button.
Next click the New button in
User Libraries.
Name the library Coherence, and then click OK.
Click the Add JARs button.
Browse to the $COHERENCE_HOME/lib folder. Select the coherence.jar file and click Open.
Click OK, Finish, and then OK again. The Coherence library is added to the project.
You can add Coherence libraries in the following ways:
As a system classpath library on the application server (the method detailed in this tutorial). This is done by adding coherence.jar to the domain&s lib folder. This automatically makes all Coherence classes available to all deployed applications.
As an application-bundled library by adding coherence.jar to the project&s WEB-INF/lib folder, in which case each application that uses Coherence must have its own copy of coherence.jar.
As a shared library by deploying the coherence.jar file to WebLogic Server as a shared library, and then referencing it from within your application's weblogic-application.xml or weblogic.xml file. This would require referencing the library in each and every deployment that uses Coherence.
Copy the coherence.jar file from the $COHERENCE_HOME/lib folder to the $DOMAIN_HOME/WLS_A/lib folder.
Note: Any JAR files added to the domain's lib folder are automatically added to that domain's classpath and should be accessible to any applications deployed in that domain.
To add the server configuration to Eclipse so that you can deploy the application directly, perform the following steps:
Select the Servers view in the bottom pane of the Eclipse window. Right-click inside the view and select New & Server.
Accept the defaults for the server host name (localhost), the server type (Oracle WebLogic Server 10gR3), and Server Runtime. Change Server Name to Oracle WebLogic Server A. Click Next.
Change the name again to Oracle WebLogic Server A, and browse to the domain directory that you created ($DOMAIN_HOME/WLS_A). Click Finish.
Start your domain by using the startWebLogic.cmd script found in the $DOMAIN_HOME/WLS_A directory. Verify that after the server is up and running. Eclipse reports the server state as Started.
Eclipse is now configured to be able to deploy projects to the Oracle WebLogic Server. In a subsequent step, you add the project to the server configuration and the Oracle Enterprise Pack for Eclipse deploys it for you.
In this topic, you create a simple HttpServlet that
connects to and exchanges data with the Coherence cache server. This code provides an example of application-level interaction with Oracle Coherence.
To create a simple HttpServlet that uses Coherence, perform the following steps:
Expand SimpleCacheApp in the Project Explorer. Right-click the Java Resources node and select New & Servlet.
Set the package to obe.coherence and name the class SimpleCacheTest1. Click Next.
Accept the default values for Initialization Parameters and URL Mappings and click Next.
Deselect doPost, but keep all other defaults selected. Click Finish.
Code the doGet() method to do the following:
Connect to the Coherence cluster.
Access a named cache called &mycache.&
Retrieve a value from the cache with the key of &greeting.&
Output that value to the Server console and the Web browser.
Connect to the Coherence cache by using the following code:
CacheFactory.ensureCluster();
When you add this code, CacheFactory
initially has a red underline because the CacheFactory class must be imported. Because there is only one CacheFactory in the classpath (com.tangosol.net.CacheFactory, which comes from coherence.jar), it is automatically imported.
Additionally, when you enter
&.& after the CacheFactory declaration, Eclipse opens a code completion box that shows you all the methods that are available for the class.
Now connect to the cache called mycache using CacheFactory.
NamedCache cache = CacheFactory.getCache(&mycache&);
This time, because there are several possibilities for NamedCache, it is not automatically imported. Click the Red X symbol in
the left margin and select Import &NamedCache& (com.tangosol.net). This import is now added at the top of the source code.
Now retrieve a value from the cache that can be found with a key of &greeting& and store it as a String.
String cachedValue = (String) cache.get(&greeting&);
Note: For objects to be cached, they must be serializable, and String automatically implements Serializable.
Output this value to the server console and the browser by using the following code.
// Output this value to the server console
System.out.println(&Value retrieved from cache: & + cachedValue);
// Output this value to the browser that called this servlet.
response.setContentType(&text/ charset=ISO-8859-1&);
PrintWriter out = response.getWriter();
out.println(&&html&&);
out.println(&&head&&title&SimpleCacheTest&/title&&/head&&);
out.println(&&body&&);
out.println(&&p&&br&The value from the Coherence Cache is : & + cachedValue + &&/p&&);
out.println(&&/body&&/html&&);
out.close();
Import any
classes that are required by using the same procedure from step 7.
Save your code.
Now that the code is complete, you can test it by deploying it to your WebLogic Server domain.
To test your servlet or Coherence code,
perform the following steps:
Ensure that there are no errors in your code. (Look for any red marks in the source view margins.)
If they are not already running, start an instance of the Coherence cache server, an instance of the Coherence shell client, and your WebLogic Server Domain. Ensure that they start without any issues.
To start the Coherence cache server, run: $COHERENCE_HOME/bin/cache-server.cmd.
To start the Coherence shell client, run: $COHERENCE_HOME/bin/coherence.cmd.
To start the WebLogic Server Domain, run: $DOMAIN_HOME/WLS_A/startWebLogic.cmd.
From the Coherence shell client, connect to the &mycache& cache.
Map (?): cache mycache
You should see the XML schema for this cache displayed in the client. You should also see a brief burst of activity in the Coherence Shell window.
Enter a value in the cache. Using the Coherence shell client, create a value with a key of greeting and a value of hello.
Map (mycache): put greeting hello
The client should return a response of null.
Deploy your project to the WebLogic Server. Right-click the Oracle WebLogic Server entry in the Servers view in Eclipse and select Add and Remove Projects.
Add SimpleCacheApp to Configured projects and click Finish.
deploys the application to the WebLogic Server. Ensure that the status for the Server entry shows &Synchronized&
and that there are no errors reported in the WebLogic Server console window.
Right-click SimpleCacheTest1
in the Project Explorer (under SimpleCacheApp\Java Resources\src\obe.coherence) and select Run As & Run on Server.
In the Run On Server dialog box, click Finish.
While the servlet is loaded and the Eclipse test browser is invoked to access it, the doGet() method is called and the servlet connects to the Coherence cache (because you
see Coherence-related information in the WebLogic Server window as well as activity in the Coherence cache server window). Both the WLS window and the Eclipse test browser should show the value that you entered via the Coherence shell client.
Change the value using the Coherence client shell.
put greeting howdy
Rerun the servlet by clicking the Refresh icon
in the Eclipse test browser. The updated value should be immediately shown in the test browser.
Bonus Challenge: Update the servlet to update the value for the greeting after the original value has been retrieved and displayed.
How would you accomplish this? (Hint: What command do you use in the Coherence client? Is there a similar method available to the NamedCache object?)
After you make a change, note that the Status for the Server entry in Eclipse has changed to Republish. This means that your code and the deployed application are out of sync and the server is not running the latest version of the application.
Right-click
the server entry and select Publish again.
After the status says Synchronized, make sure that there is a value in the cache using the Coherence client (set the greeting value to hello again), and then test the servlet again using the Eclipse test browser.
Note that the value you set with the client is shown in the browser and the WebLogic Server window as before. Use the client to
check what value is currently in the cache.
Map (mycache): list
The value returned should be the same as the cache.put() value that you added to the servlet code.
Try refreshing the Eclipse test browser right now. What value does it show?
to see the solution code for this if you need help.
Oracle Coherence uses a peer-to-peer architecture with no masters or slaves. By default, when a node connects to the Coherence grid, it becomes part of the grid as one of the cache servers, not just a client or consumer. There are advantages and disadvantages to this scenario. The advantages are that data in the cache (particularly in replicated models) is now &local& to the application server and no network traffic is needed for the application to retrieve the data after it is replicated. The disadvantage is that this is an additional process and a memory overhead for the application server JVM and hardware, which may be undesirable.
By setting the &local-storage& of a node to &false,& that node becomes a consumer only (just a client). This is done by passing a command-line argument to the Coherence node. But if it is an application running on a Java application server that is the node, you add the needed argument, -Dtangosol.coherence.distributed.localstorage=false
to the Java parameters that are being passed during the WebLogic Server startup.
Background on the scripts that start a WebLogic Server domain:
If you look at your domain directory ($DOMAIN_HOME/WLS_A) closely you may notice that there are two startWebLogic.cmd scripts: One in the domain's root folder, and one in the bin folder. Here is an explanation of how they work:
WebLogic Server Startup Scripts
Description
DOMAIN_HOME/startWebLogic.cmd
Convenience script that calls the startWebLogic.cmd script in the bin folder
DOMAIN_HOME/bin/startWebLogic.cmd
Script that calls setDomainEnv.cmd to set the WebLogic Server environment, and performs the actual startup of the server
DOMAIN_HOME/bin/setDomainEnv.cmd
Script that sets the environment for starting the WebLogic Servers for this domain. This is called by DOMAIN_HOME/bin/startWebLogic.cmd. You can set Coherence configuration arguments through Java properties in this file.
To configure the Coherence node spawned by the WebLogic Server,
perform the following steps:
Open $DOMAIN_HOME/WLS_A/bin/setDomainEnv.cmd in a text editor.
a line in the setDomainEnv.cmd file
similar to the following line (approximately line 258):
set JAVA_PROPERTIES=%JAVA_PROPERTIES% %WLP_JAVA_PROPERTIES%
Above it, add the following lines:
ADDING COHERENCE SETTINGS
set COHERENCE_PROPERTIES=-Dtangosol.coherence.distributed.localstorage=false
Modify the JAVA_PROPERTIES line that you identified in step 1 to include the new environment variable that you created.
set JAVA_PROPERTIES=%COHERENCE_PROPERTIES% %JAVA_PROPERTIES% %WLP_JAVA_PROPERTIES%
Start (or restart) your WebLogic Server domain and shut down any running Coherence cache server and Coherence shell client instances.
Redeploy the test application and test the servlet again as you did in the previous section. What result do you get this time?
If the Coherence cache server is shut down, the test should fail with a &storage not configured& exception. This is because you have configured the WebLogic Server domain to act only as a client node and it cannot provide caching services to the application.
Start up the Coherence cache server again as well as the Coherence client shell, and retest the application as you did in the previous section. (Remember to add a value with the Coherence shell client first). Does it work now?
There are additional Coherence configuration settings that can be made via command-line arguments, such as overriding the cache configuration settings.
In this lesson, you learned how to:
Create and configure a domain that can host applications that use Oracle Coherence
Set up an Eclipse development environment to deploy to the Oracle WebLogic Server and create applications that use Oracle Coherence
Create a Web application project and code a servlet that connects to and shares data with an Oracle Coherence Data Cache
Deploy and test a Coherence application from Eclipse to the Oracle WebLogic Server
Configure the Coherence Node Settings from the Application Server Node
To learn more about Oracle Coherence, you can refer to:
This tutorial has given you the basic environment settings needed to use Coherence in an application-level context for a Web or an enterprise application running on a Java application server. Refer to the Coherence tutorials listed in the
and try to apply them to a Web application through what you have learned in this tutorial.
Place the cursor over this icon to hide all screenshots.