Managed Coherence Servers

Files Prepare Deploy Troubleshooting Related Topics

About the Example

Managed Coherence Servers provide a tight integration between Weblogic Server and Coherence, allowing for a simplified and streamlined development and management environment for distributed applications. This functionality allows you to build a new archive type called a Grid Archive, or GAR, which can be deployed and managed using standard Weblogic Server best practices. Developers can now streamline their build artifacts to generate GARs, and operations departments can have a standardized way of deploying Coherence in test and production environments.

This example builds a domain consisting of an Administration Server and two WebLogic clusters, each having two Managed Servers. Coherence is configured and associated with the clusters.

The cluster StorageTier includes two Managed Servers: storage1 and storage2. This cluster is set to storage-enabled and holds data for the application.
The cluster ClientTier has two Managed Servers, client1 and client2. This cluster is set to storage-disabled.

The configuration of the domain created in this example is shown in the following figure.

Architecture for multi server example

The following artifacts are deployed in this example:

ExampleGAR.gar - A GAR containing the classes and configuration required to access Coherence. This file is deployed to StorageTier.
ExampleEAR.ear - An EAR containing the preceding GAR and a WAR file with a simple application that exercises Coherence. This file is deployed to ClientTier.
ExampleListenerEAR.ear - An EAR containing the preceding GAR and an EJB with a MapListener configured to listen on events in Coherence. This file is deployed to the Managed Server client1.

Note: This example starts four Managed Servers and an Administration Server. A minimum of 4GB of RAM is required, and 6GB is highly recommended.

Files Used in the Example

Directory Location: D:\Oracle\Middleware\Oracle_Home\wlserver/samples/server/examples/src/examples/coherence/managed-coherence-servers/multi-server

Grid Archive (GAR) Components
DataGenerator.java	Class that generates random contacts.
Contact.java	Class that defines a contact.
ContactId.java	Class that defines the key for a contact.
Address.java	Class that defines an address for a contact.
PhoneNumber.java	Class that defines a contact.
LifecycleReactor.java	Class that defines actions that can be invoked pre/post startup and shutdown of the Managed Coherence Server.
coherence-application.xml	GAR-specific deployment descriptor that contains a pointer to the cache configuration and a number of optional components.
example-cache-config.xml	Oracle Coherence cache configuration file used in this example.
Web Archive (WAR) Components
ContactComparator.java	Comparator that orders the list of contacts.
ContactBean.java	Bean that holds the state of the current contacts.
CacheControlBean.java	Bean that holds the logic for controlling page navigation and validation.
ReferenceDataBean.java	Bean that holds the reference data for the application.
ContactList.jsp	JSF page that displays the contact list.
ContactDetail.jsp	JSF page that inserts or updates a contact.
Example.css	Stylesheet.
Oracle_3d_v3.jpg	Oracle Logo.
web.xml	`web.xml` file that defines the JSF mappings.
EJB Components
SingletonFileWriterStartupBean.java	EJB 3.1 singleton to be initiated on Managed Coherence Server startup to add the `MapListener` to the contacts cache.
ContactFileWriterListener.java	The `MapListener` called by the singleton EJB to log, insert, update, or delete events on the contacts cache in a file.

Prepare the Example

Prerequisites

Before working with this example, install Oracle WebLogic Server, including the examples, if you have not already done so.

Configure Oracle WebLogic Server

No special configuration is required for this example.

Build the Example

To build the example, complete the following steps:

Open a command shell or window and navigate to the ORACLE_HOME/wlserver/server/bin directory (where ORACLE_HOME represents the central support directory for all WebLogic products installed on your machine; for example, C:\Oracle\Middleware\Oracle_Home).
Set your WebLogic Server environment by entering the following command:
- UNIX or Linux: . ./setWLSEnv.sh
- Windows: setWLSEnv.cmd
Navigate to the D:\Oracle\Middleware\Oracle_Home\wlserver/samples/server/examples/src/examples/coherence/managed-coherence-servers/multi-server directory.
Enter the following command to compile and package the sample and prepare it for deployment:

ant all

The preceding command creates the build directories, compiles the Java source files, and packages the required GAR and EAR files described above.

Deploy and Run the Example

Using the command shell from which you built the example, complete the following steps:

Enter the following command:

ant deploy
You are prompted to confirm the creation of the domain directory. Note that if you ran the example previously, the domain directory is re-created. This directory is created in the following location:

ORACLE_HOME/user_projects/domains/multi_domain
Enter a password for the user weblogic. (Note that the password you enter is echoed in the command shell.)
Enter the host name of the machine on which you are running the example. To accept the host name that is displayed, simply press Enter.
Enter the listen port for the Administration Server. To accept the default port 7001, simply press Enter.
Enter the starting port for the Managed Servers. To accept the default port of 7003, simply press Enter.
The ant task automatically does the following:

Uses WLST offline to creates a domain with only an Administration Server.
Starts the Administration Server.
Configures the Coherence cluster, creates the WebLogic clusters and the Managed Servers, and associates the Managed Servers with the WebLogic clusters and the Coherence cluster.
Registers the domain with Node Manager.
Starts Node Manager.
Restarts the Administration Server, which causes the configuration changes to take effect.
Starts all Managed Servers.
Deploys the ExampleGAR.gar file to the StorageTier cluster.
Deploys the ExampleEAR.ear file to the ClientTier cluster.
Deploys the ExampleListenerEAR.ear file to the client1 Managed Server.

When the ant task finishes running, text similar to the following should be displayed in the command shell:


     [echo] Application is now deployed. If you used the default ports, go to the following url to access the application:
     [echo] http://hostname:7007/example-web-app
     [echo] 
     [echo] If you changed the default port, the port will be the starting port you entered (7003)+4
     [echo] 
     [echo] To access the AdminServer console, go to the following URL:
     [echo] http://hostname:7001/console
     [echo] 
     [echo] To shutdown the servers, run "ant shutdownMultiServer" or shutdown from the Admin console.
     [echo] You will then need to stop nodeManager.

To run the example and view the GAR deployment artifacts, complete the following steps:

Launch a browser and enter the following URL in the address bar:

hostname:port/example-web-app

The string hostname:port corresponds to the machine host name and listen port which is displayed above in the ant output.

The Web application UI is displayed in the browser. This is a simple Contacts application which stores its data within a Coherence cache.
When you first access the link you will notice that data is already loaded. This is because the postStart event has fired and has loaded the initial data. (See the LifecycleReactor.java class above)
You can click Insert 20 Random Contacts to insert additional contacts. The following table is then displayed in the browser.
Log in to the Administration Console as user weblogic, using the password you specified earlier.
In the left pane of the Administration Console, select Deployments. The deployments are displayed, as shown in the following figure. You can see that ExampleEAR contains two modules: the Coherence Archive (GAR File), and the Web application.
To view the output from the EJB module, use the command shell in which you deployed the example and navigate to the ORACLE_HOME/user_projects/domains/multi_server directory. When a change to the data occurs, information about the change is appended to the file ContactFileWriterListener.log.

Connecting to the Coherence MBean Server

In WebLogic Server 12.2.1 and above, the dynamic proxy feature is set by default and this feature will automatically choose a Managed Server to host the MBean server. This means that a Managed Server will be chosen automatically to act as the management proxy and will collect and display all of the Coherence MBeans from all the members. If the current management proxy goes down, another Managed Server is chosen as the management proxy.
To connect to the management proxy, using the command shell from which you built the example, you can connect to the the Domain Runtime MBean server. The instructions below explain how to connect using JConsole and JVisualVM.

JConsole

The jconsole tool is a JMX-compliant graphical tool for monitoring a Java virtual machine. It can monitor both local and remote JVMs. It can also monitor and manage an application.If want to start jconsole manually, enter the JDK installation directory and then execute /bin/jconsole.exe.

Set your WebLogic Server environment by using setDomainEnv.sh/cmd or setWLSEnv.sh/cmd.
Using the supplied jconsole.sh/jconsole.cmd script, start JConsole.
Enter the following in the 'Remote Process' field (changing host/port as appropriate) along with the WebLogic username and password.
```
service:jmx:iiop://127.0.0.1:7001/jndi/weblogic.management.mbeanservers.domainruntime
```
Once you have connected you will see the MBean tree.

JVisualVM

JVisualVM is short for Java VisualVM. Java VisualVM is a tool that provides a visual interface for viewing detailed information about Java applications while they are running on a Java Virtual Machine (JVM), and for troubleshooting and profiling these applications. Various optional tools, including Java VisualVM, are provided with Sun's distribution of the Java Development Kit (JDK) for retrieving different types of data about running JVM software instances.If want to start manually, enter the JDK installation directory and then execute /bin/jvisualvm.exe.

Set your WebLogic Server environment by using setDomainEnv.sh/cmd or setWLSEnv.sh/cmd.
Using the supplied jvisualvm.sh/jvisualvm.cmd script, start JVisualVM.
In the 'Applications' tab right-click and choose 'Add JMX Connection'. Enter the following in the 'Connection' field (changing host/port as appropriate) along with the WebLogic username and password.
```
service:jmx:iiop://127.0.0.1:7001/jndi/weblogic.management.mbeanservers.domainruntime
```
Once you have connected you can choose the MBeans tab. If you don't see the 'MBeans' tab then choose 'Tools'->'Plugins' and download and install the 'JVisualVM-MBeans' plugin.

To shut down the WebLogic Server instances in which the multi-server example is running, do one of the following:

In the command shell from which you deployed the example, navigate to the D:\Oracle\Middleware\Oracle_Home\wlserver/samples/server/examples/src/examples/coherence/managed-coherence-servers/multi-server directory and enter the following command:

ant shutdownMultiServer
In the Administration Console, complete the following steps for each server instance:
1. In the left pane of the console, expand Environment and select Servers.
2. In the Servers table, select the name of the server that you want to shut down, and select Control > Start/Stop.
3. In the Server Status table, select the server that you want to shut down.
4. In the Shutdown drop-down menu, select Force shutdown now.
5. You must manually stop Node Manager, by killing the process, once all Managed Servers are shut down.

Troubleshooting

If the ant command cannot be found, ensure you have run the WL_HOME/server/bin/setWLSEnv script.
If on UNIX or Linux systems, Node Manager fails to start and displays the message weblogic.nodemanager.common.ConfigException: Native version is enabled but node manager native library could not be loaded, enter the following command prior to running the ant deploy task:

export LD_LIBRARY_PATH=ORACLE_HOME/wlserver/server/native/linux/i686:$LD_LIBRARY_PATH

You may need to substitue linux/i686 for the appropriate value for your version of UNIX, or Linux, and chipset.
General Troubleshooting Tips for Examples

document.write(document.title);

About the Example

Files Used in the Example

Grid Archive (GAR) Components

Web Archive (WAR) Components

EJB Components