This chapter provides instructions for upgrading applications that use Coherence, Coherence*Web, ActiveCache, and TopLink Grid to 12c (12.1.2).
Upgrading Applications Using Coherence and Coherence*Web on WebLogic Server
Upgrading Applications Using TopLink Grid on WebLogic Server
Follow these instructions for upgrading applications running on WebLogic Server that use Coherence and Coherence*Web.
In an existing WebLogic Server domain:
Stop and undeploy the applications that use Coherence*Web.
Undeploy the coherence.jar and coherence-web-spi.war files if they are deployed.
Follow the steps to upgrade WebLogic Server and its domains to WebLogic Server 12c (12.1.2). For information on upgrading WebLogic Server, see Oracle Fusion Middleware Upgrading Oracle WebLogic Server.
Modify your applications to remove all references to the coherence.jar file:
In the weblogic.xml file, remove the <library-ref> element that refers to the coherence-web-spi file.
In the META-INF/MANIFEST.MF file, remove the following lines that identify Coherence as an extension:
Extension-List: coherence coherence-Extension-Name: coherence
Remove any explicit references to the coherence.jar file in the classpath.
Modify your applications to use the required settings for Coherence 12c (12.1.2):
If you used the default session-cache-config.xml file in your Coherence release 3.7.1.x application, note that the name has been changed to default-session-cache-config.xml in 12c (12.1.2).
For example, if you used this context parameter value in Coherence release 3.7.1.x application:
tangosol.coherence.cacheconfig=session-cache-config.xml
change it to default-session-cache-config.xml in 12c (12.1.2):
tangosol.coherence.cacheconfig=default-session-cache-config.xml
You should not have to change the session cache file name. If you created a custom session-cache-config.xml, you should be able to leave the file name as it is.
If your application is in an EAR file, then the packaging for the custom session-cache-config file has changed in 12c (12.1.2). For 12c (12.1.2) packaging instructions, see "Using a Custom Session Cache Configuration File" in Oracle Fusion Middleware Administering HTTP Session Management with Oracle Coherence*Web.
Redeploy your applications on WebLogic Server.
The following sections describe how to upgrade applications that run in application-scoped, EAR-scoped, and WAR-scoped clusters. Before you upgrade the applications, you must first upgrade the Coherence-side configuration.
Follow these steps to upgrade the Coherence-side configuration. The upgrades must be made to any pre-12c (12.1.2) Coherence cache server startup scripts that you are using that reference the pre-12c (12.1.2) Coherence JARs. The scripts that are shipped with Coherence do not need to be changed.
Shutdown the Coherence servers.
Modify the Coherence cache server startup script to change classpath (${ORACLE_HOME} in WebLogic Server 12c (12.1.2)):
—Replace coherence.jar with ${ORACLE_HOME}/coherence/lib/coherence.jar.
—Replace javax.persistence_1.*.jar with ${ORACLE_HOME}/oracle_common/modules/javax.persistence_2.0.0.0_2-0.jar.
—Replace com.oracle.toplinkgrid_1.1.0.0_11-1-1-6-0.jar with ${ORACLE_HOME}/oracle_common/modules/oracle.toplink_12.1.2/toplink-grid.jar.
—Replace org.eclipse.persistence_1.2.0.0_2-3.jar with ${ORACLE_HOME}/oracle_common/modules/oracle.toplink_12.1.2/eclipselink.jar.
Restart the Coherence servers.
If you have application server-scoped applications running in your Coherence clusters, follow these steps to upgrade to Coherence 12c (12.1.2).
Follow the steps to upgrade WebLogic Server and its domains to WebLogic Server 12c (12.1.2). For information on upgrading WebLogic Server and its domains, see Oracle Fusion Middleware Upgrading Oracle WebLogic Server.
Follow these steps to upgrade the WebLogic Server-side configuration before you start any managed servers:
Note:
In the WebLogic Server 12c (12.1.2), thetoplink-grid.jar and coherence.jar files (as well as the coherence-web.jar and eclipselink.jar files) are automatically included in WebLogic Server system classpath.Remove any explicit references to the toplink-grid.jar file from the WebLogic Server classpath. Examples of old references include the following:
com.oracle.toplinkgrid_1.1.0.0_11-1-1-6-0.jar javax.persistence_1.*.jar org.eclipse.persistence_1.2.0.0_2-3.jar
Remove any explicit references to the coherence.jar file from the WebLogic Server classpath. Examples of old references include the following:
coherence.jar coherence-web.jar coherence-web-spi.war
Restart the WebLogic Servers.
Redeploy your applications.
If you have EAR-scoped TopLink applications running in your Coherence clusters, then you can upgrade your applications to use Coherence 12c (12.1.2) in any of the following ways:
Upgrade your applications to use GAR file format. See "Using GAR File Format".
Update the shared libraries. See "Updating Shared Libraries".
Update the toplink-grid.jar and coherence.jar files packaged in the EAR file. See "Packaging the toplink-grid.jar and coherence.jar Files in the EAR File".
Note:
The following procedures assume that you have upgraded WebLogic Server and its domains to WebLogic Server 12c (12.1.2). For information on upgrading WebLogic Server, see Oracle Fusion Middleware Upgrading Oracle WebLogic Server.The following steps assume that you are upgrading your application to use GAR file format. This is the approach recommended by Oracle. For more information on packaging applications in GAR file format, see "Creating Coherence Applications for WebLogic Server" in Developing Oracle Coherence Applications for Oracle WebLogic Server.
Remove any references to Coherence and TopLink Grid shared libraries from the application and WebLogic Server classpaths.
Note:
You can remove these references because in the WebLogic Server 12c (12.1.2), thetoplink-grid.jar and coherence.jar files (as well as the coherence-web.jar and eclipselink.jar files) are automatically included in WebLogic Server system classpath.Examples of references to Coherence include:
coherence.jar coherence-web.jar coherence-web-spi.war
Examples of references to TopLink Grid include:
com.oracle.toplinkgrid_1.1.0.0_11-1-1-6-0.jar javax.persistence_1.*.jar org.eclipse.persistence_1.2.0.0_2-3.jar
Remove references to the coherence.jar and toplink-grid.jar from the weblogic-application.xml file.
Remove the <coherence-cluster-ref> element, which configures Coherence cluster properties, from the weblogic-application.xml file.
If you have configured a filtering classloader, then remove it. This feature is defined in the <prefer-application-packages> element in the weblogic-application.xml file. Remove any <prefer-application-packages> elements that reference the coherence.jar and toplink-grid.jar files.
If you have packaged the toplink-grid.jar and coherence.jar files within the EAR file, then remove them from the EAR file.
Restart the WebLogic Server and the Coherence servers.
Redeploy your applications.
This approach assumes that you are referencing the toplink-grid.jar and coherence.jar files as shared libraries and do not want to change the packaging of your applications. In this case, you must redeploy the 12c (12.1.2) versions of the toplink-grid.jar and coherence.jar files as shared libraries.
Packaging the toplink-grid.jar and coherence.jar Files in the EAR File
This approach assumes that you have packaged your toplink-grid.jar and coherence.jar files in the EAR file. In this case, replace the toplink-grid.jar and coherence.jar files with the12c (12.1.2) version of these files.
If you have WAR-scoped TopLink applications running in your Coherence clusters, then you can upgrade your applications to use Coherence 12c (12.1.2) in any of the following ways:
Update the shared libraries. See "Updating Shared Libraries".
Update the toplink-grid.jar and coherence.jar files packaged in the WAR file.
Note:
The following procedures assume that you have upgraded WebLogic Server and its domains to WebLogic Server 12c (12.1.2). For information on upgrading WebLogic Server, see Oracle Fusion Middleware Upgrading Oracle WebLogic Server.This approach assumes that you are referencing the toplink-grid.jar and coherence.jar files as shared libraries and do not want to change the packaging of your applications. In this case, all you need to do is to update the shared library references to use the 12c (12.1.2) version of the toplink-grid.jar and coherence.jar files.
Packaging the toplink-grid.jar and coherence.jar Files in the WAR File
This approach assumes that you have packaged your toplink-grid.jar and coherence.jar files in the EAR file. In this case, replace the toplink-grid.jar and coherence.jar files with the12c (12.1.2) version of these files.
For all Extend client customers (Java, C++, and .NET), you must upgrade the cluster side before upgrading the Coherence*Extend clients. This is in compliance with the Coherence client and proxy upgrade policy. For more information on compatibility between the current release of Coherence*Extend and earlier versions, see "Compatibility Between Coherence*Extend Versions" in Oracle Fusion Middleware Developing Remote Clients for Oracle Coherence.
The following sections describe upgrade considerations for Coherence*Web.
The coherence-web-spi.war file, which was included in previous releases of Coherence*Web, is deprecated in 12c (12.1.2). The Coherence 12c (12.1.2) distribution includes a coherence-web-spi.war file in the coherence\lib directory, but this file is provided only for backward compatibility with older versions of WebLogic Server. If you are using WebLogic Server 12c (12.1.2) or later, you should not have to work with or reference this file. If you attempt to deploy the coherence-web-spi.war file to WebLogic Server 12c (12.1.2) or later, it will be ignored.
ActiveCache (active-cache.jar), the collection of WebLogic Server features which allow deployed applications to easily use Coherence data caches and seamlessly incorporate Coherence*Web for session management, has been deprecated in the 12c (12.1.2) release. ActiveCache is still supported in the 12c (12.1.2), primarily to support upgrades of applications developed on older releases. For more information on ActiveCache, see Oracle Fusion Middleware Using ActiveCache.
Users must migrate to Managed Coherence Servers when developing new WebLogic Server/Coherence applications for the current release. For more information on Managed Coherence Servers, see Oracle Fusion Middleware Developing Oracle Coherence Applications for Oracle WebLogic Server.
In previous releases, Coherence cache configurations and services used by Coherence*Web SPI were defined in the session-cache-config.xml file, As of the 12c (12.1.2), Coherence cache configurations and services used by Coherence*Web are defined in the default-session-cache-config.xml file, which can be found in the coherence-web.jar file. The default cache and services configuration defined in the default-session-cache-config.xml file should satisfy most Web applications.
You can create your own custom session cache configuration by packaging a file named session-cache-config.xml in your Web application. For more information see, "Using a Custom Session Cache Configuration File" in Oracle Fusion Middleware Administering HTTP Session Management with Oracle Coherence*Web.
The 11g Release 1 (10.3.6) version of ActiveCache is documented in Oracle Fusion Middleware Using ActiveCache. This version of ActiveCache will work with WebLogic Server and Coherence 12c (12.1.2) but some of the documented steps are no longer required.
Note:
ActiveCache is deprecated in the 12c (12.1.2) release. Users must migrate to Managed Coherence Servers. For more information on Managed Coherence Servers, see Oracle Fusion Middleware Developing Oracle Coherence Applications for Oracle WebLogic Server."Choose the ActiveCache Deployment Topology" describes the several different combinations of application and data tiers, or cluster topologies, in which ActiveCache can be deployed. In upgrading applications using ActiveCache, you should not use the Out-of-Process topology except for backward compatibility. In the current release, WebLogic Out-of-Process topology is the preferred approach. Using managed Coherence servers makes the WebLogic Out-of-Process topology easier to configure.
"Locate the Cache Configuration File" describes the location where you place the cache configuration file. The location where you store the cache configuration file determines the cache scope; that is, the visibility of the caches to deployed applications. The approaches described in this section will work, but putting the cache configuration in the system classpath is a bad practice unless there is only one and will only ever be one application using Coherence in the server.
Oracle recommends that you use a GAR file when you package your application. The cache configuration file is packaged in the GAR file. For more information on the GAR file and its packaging structure, see Oracle Fusion Middleware Developing Oracle Coherence Applications for Oracle WebLogic Server.
"Configuring Application-Server Scoped Coherence Clusters" describes a configuration such that all deployed applications on WebLogic Server instances that are directly accessing Coherence caches become part of one Coherence cluster. In the procedure, do not perform Step 1: do not put the coherence.jar and active-cache.jar files in the system classpath. The active-cache.jar file uses the classpath in the MANIFEST file to add the Coherence integration module to the classpath. In release 12c (12.1.2), the Coherence integration module will always be in the server classpath, in addition to the coherence.jar file.
"Configuring EAR-Scoped Coherence Clusters" describes a configuration such that all deployed applications within each EAR become part of one Coherence cluster. Caches will be visible to all modules in the EAR. The procedure described in this section will not work as described. Because coherence.jar is already in the system classpath, you must follow the steps documented in the section "To Define a Filtering Classloader for Application-Scoped Coherence Clusters".
The only reason to use the EAR-scoped approach is to isolate your application from other Coherence applications. That use case is better handled by the application isolation provided by a GAR file, or by using the scope element in the cache configuration file. Another use case is to use a different version of coherence.jar than is in the system classpath but using a different version should be discouraged.
"Configuring WAR-Scoped Clusters" describes a configuration such that each deployed Web application becomes its own Coherence cluster. Caches will be visible to the individual modules only. In the procedure, do not perform Steps 1 and 2. The coherence.jar and active-cache.jar should not be deployed as shared libraries nor should they appear in the MANIFEST file. You can perform Step 3 to reference the Coherence cluster system resource, but making the managed server a member of the Coherence cluster is the preferred approach.
"Example 3-10 tangosol-coherence-override.xml" displays a custom cache configuration file that contains a logging configuration. The logging configuration is not needed because of log integration in release 12c (12.1.2).
"Start a Cache Server" section describes several different ways of starting the cache server. The Out-of-Process topology should be replaced with managed Coherence servers. The procedure described in "Starting a Cache Server Using Node Manager" should be performed by using managed Coherence servers, instead of using the external cache server managed by WebLogic Server.
The following sections describe replacements for features that have been deprecated in Coherence 12c (12.1.2).
The packet-pool and message-pool elements are deprecated. In Coherence 12c (12.1.2), the API will now take care of sizing. To upgrade, remove the elements from any configuration files.
The LH store manager is deprecated as of Coherence 12c (12.1.2) release. Use Berkeley DB for similar functionality.
The NamedCache lock APIs are deprecated. Use the locking support that is provided by the entry processor API instead (EntryProcessor for Java and C++, IEntryProcessor for .NET).
The com.tangosol.run.xml.XmlConfigurable interface has been deprecated in the Coherence 12c (12.1.2) release. Coherence used this interface to inject XML parameters into instances of custom classes.
Note:
For information on the interfaces, classes, and methods affected by the deprecation of theXmlConfigurable interface, see "XmlConfigurable Interface".In the Coherence 12c (12.1.2) release, you can initialize parameters by writing XML which nests <instance> and <class-scheme> (or any other custom namespace) inside of <param-value> elements.
For example, given the following Java code:
public class MyClass
{
public MyClass(String s, OtherClass o, int i) { ... }
}
public class OtherClass
{
public OtherClass(String s) { ... }
}
You can initialize the MyClass and OtherClass classes by writing the following XML. In the XML, the MyClass class is initialized with the string Hello World and the integer 42. The instance of the OtherClass class which appears in the MyClass class, is initialized with the string Goodbye World.
<instance>
<class-name>MyClass</class-name>
<init-params>
<init-param>
<param-value>Hello World</param-value>
</init-param>
<init-param>
<param-value>
<instance>
<class-name>OtherClass</class-name>
<init-params>
<init-param>
<param-value>Goodbye World</param-value>
</init-param>
</init-params>
</instance>
</param-value>
</init-param>
<init-param>
<param-value>42</param-value>
</init-param>
</init-params>
</instance>
The following sections describe issues that you might need to consider when upgrading to Coherence 12c (12.1.2).
DistributedCache now defaults to the Exabus optimized transport in Exalogic environments. For more information, see the description of the <reliable-transport> element in "DistributedCache Service Parameters" in Oracle Fusion Middleware Developing Applications with Oracle Coherence.
When connecting from a remote RMI client (different physical computer), add the java.rmi.server.hostname RMI system property to the script with the value set to the cluster member's IP address. The address ensures that the RMI stubs that are sent to the client contain the correct server address. For more information, see "Allowing Remote Access to Oracle Coherence MBeans" in Oracle Fusion Middleware Managing Oracle Coherence.
Key association is now processed on the extend client by default. Existing client implementations (including Java clients) that rely on key association on the cluster must set the defer-key-association-check parameter in order to force the processing of key classes on the cluster.
To force key association processing to be done on the cluster side instead of by the extend client, set the <defer-key-association-check> element, within a <remote-cache-scheme> element, in the client-side cache configuration to true. For example:
<remote-cache-scheme> ... <defer-key-association-check>true</defer-key-association-check> </remote-cache-scheme>
For more information, see "Deferring the Key Association Check" in Oracle Fusion Middleware Developing Remote Clients for Oracle Coherence.
The default near cache invalidation strategy auto has changed to ensure that reduced network traffic is prioritized over performance. Set the invalidation strategy to all for pre-12c (12.1.2) default behavior. For more information, see "Near Cache Invalidation Strategies" in Oracle Fusion Middleware Developing Applications with Oracle Coherence.
Use the BACKUP CACHE statement to write a serialized representation of the given cache to a file represented by the given filename. The backup is not forward or backward compatible between 3.x and 12.1.x. See "Writing a Serialized Representation of a Cache to a File" in Oracle Fusion Middleware Developing Applications with Oracle Coherence.
The resource-config element contains the configuration information for a class that extends the com.sun.jersey.api.core.ResourceConfig class. The instance is used by the HTTP acceptor to load resource and provider classes for the Coherence REST application that is mapped to the specified context path. Multiple resource configuration classes can be configured and mapped to different context paths. For more information, see "Deploying with the Embedded HTTP Server" in Oracle Fusion Middleware Developing Remote Clients for Oracle Coherence.
Coherence 12c (12.1.2) is supported on Oracle HotSpot JVM 1.7 and other 1.7-level JVMs. There is no JRockit 1.7, so JRockit is not longer relevant. Extend clients are supported on JVM 1.6+, including JRockit. For more information, see "JVM Recommendations" in Oracle Fusion Middleware Administering Oracle Coherence.
Applications that use the Invocable API may receive an error when upgrading from Coherence 3.7.1 to Coherence 12.x due to a change in serialization requirements. In Coherence 3.7.1, if an Invocable is sent to a number of nodes including itself, then there is a chance that it will begin local execution before having been serialized for transmission to the remote members. If the Invocable updates non-transient state, this state will be leaked to the other nodes as part of the delayed serialization.
In Coherence 12.x, applications that use the Invocable API on local members must make sure that their classes (such as entry processors and aggregators) are serializable.