Oracle Coherence Requirements and Configuration as a Scale-Out Repository

For a production environment, you must use Oracle Coherence version 14.1.1 or later.

Note: Micro Focus recommends that you use either Java 8 with Remote clients or Java 11 with Direct or Remote clients to avoid an issue with high CPU usage when used in a PAC environment.

For more information on Oracle Coherence click here.

You will require the Coherence file coherence.jar, and if you are configuring security you will also require the coherence-login.jar file.

Coherence clients and servers are configured using a combination of xml configuration files and Java system properties.

The Micro Focus Enterprise Server support file mfescache.jar is shipped with Enterprise Developer, and can be located at %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin. The Micro Focus configuration file mfescache.cfg is also supplied and can be located at %ProgramFiles(x86)%\Micro Focus\Enterprise Server\etc. These are suitable for production use, provided that system properties are configured for items such as the cluster name. If the cluster name is not configured one is automatically generated based on the OS username running the client or server, for example, "User's cluster". When using the default configuration files, the cluster name must always be configured via the coherence.cluster property. The default configuration filename is mfes-cache-config.xml and it is located along the CLASSPATH within the mfescache.jar file. The configuration file can be extracted and modified if required.

The Coherence clients and servers can discover each other by multicasting or unicasting using a list of well-known addresses and will attempt to join to form a single cluster using a specified cluster name. The cluster name can be configured using the Java property coherence.cluster. See Oracle Coherence documentation for more information on cluster formation and configuration.

Note: Cluster names are limited in length to 64 characters.

The mfescache.cfg configuration file and well-known addresses

The Micro Focus configuration file mfescache.cfg defines the Java Virtual Machine environment created by Enterprise Server to enable it to utilize Coherence clients. This file can be modified by a text editor to add additional properties such as CLASSPATH entries or well-known addresses. The default cache configuration file (mfes-cache-config.xml) uses well-known addresses. The well-known addresses are specified as a comma-separated list of endpoints enclosed within curly parentheses {} using a Java property named mfescache.wka.CLUSTERNAME, for example:

mfescache.wka.MYPAC_cluster={192.168.11.12:7574,192.168.11.14:7574}

A Coherence server at one of the specified endpoints must be contactable to enable members to join or access the cluster. If the endpoint is not specified, then the port is set to the value of the coherence.clusterport value, the default value is the IANA registered port 7574. In environments where the network DNS can be configured to return multiple addresses for a network name then that facility can be used to simplify the configuration. If you are specifying a single endpoint address then the enclosing curly parentheses {} can be omitted.

Starting a Coherence server

To start a Coherence server for use with Enterprise Server you will require the following:

Java 1.8 or later.
The coherence.jar file from Oracle Coherence version 14.1.1 or later.
The Enterprise Server mfescache.jar support file.
Access to a Coherence cache configuration file, and/or Coherence operational override configuration file.

Note: The Enterprise Server Coherence feature does not support using alternative Scale-Out Repository (SOR) models. So just a single SOR should be configured.

Both the Oracle Coherence coherence.jar file, and the Micro Focus mfescache.jar files must be on the Java CLASSPATH when running the server.

Unless the default cache configuration filename is being used, the location should be specified using the coherence.cacheconfig system property. This can be the name of a file on CLASSPATH, a path to a local file, or a URL providing the configuration content.

Each server cluster is started using a command similar to one of the following, assuming that the two jar files are in the current directory. Use a suitable cluster name in place of MYPAC_cluster; the class listed is a wrapper around the Coherence server, setting the following properties:

tangosol.pof.enabled=true, 
coherence.pof.config=es-pof-config.xml,
coherence.role=server,
coherence.cacheconfig=mfes-cache-config.xml

Note: If the properties are already set they will not be overridden, with the exception of tangosol.pof.enabled.

Micro Focus recommends that you use a minimum of 3 servers for a production environment, this will support data redundancy and recovery in case a server were to fail or require maintenance. For testing purposes, a single server is sufficient.

In Coherence, the minimum number of service members that are required in a cluster before a service action is allowed or disallowed is referred to as a quorum. You can configure a quorum policy to control when specific service actions are allowed in a cluster ensuring that a cluster is adequately provisioned. See Oracles Coherence documentation for more information. To assist you configuring of a quorum policy the supplied operational override file defaults the coherence.role to "es-client" and defaults the cluster-survivor-quorum timeout-survivor-quorum elements to require at least one "es-client" and one "server".

Other than log settings, the servers can typically be started using the same configuration, for example:

java -cp coherence.jar:mfescache.jar -Dcoherence.cluster=MYPAC_cluster -Dmfescache.wka.MYPAC_cluster={192.168.11.12:7574,192.168.11.14:7574} com.microfocus.es.cache.coherence.ESCacheServer

To send output to a file using the default port:

java -cp coherence.jar:mfescache.jar -Dcoherence.cluster=MYPAC_cluster -Dmfescache.wka.MYPAC_cluster={192.168.11.12,192.168.11.14} -Dcoherence.log=/tmp/coherence.log com.microfocus.es.cache.coherence.ESCacheServer

To specify an alternative cache configuration file:

java -cp coherence.jar:mfescache.jar -Dcoherence.cluster=MYPAC_cluster -Dmfescache.wka.MYPAC_cluster={192.168.11.12,192.168.11.14} -Dcoherence.cacheconfig=mycacheconfig.xml com.microfocus.es.cache.coherence.ESCacheServer

Logging

Coherence logging is specified using the properties coherence.log=<location> and coherence.log.level=n where n can be between 0 to 9. See Oracle Coherence for more information on the log level. In addition to the standard Coherence behaviour, if @PID@ is included within the <location> it will be replaced with a process specific identifier which is useful when logging Enterprise Server processes. For example:

coherence.log=/logs/coherence_@PID@.log

Would set the log to be /logs/coherence_1234@mymachine.log.

By default, for Enterprise Server clients the coherence.log.level property is set to 0 but this can be overridden by specifying it as part of the SOR configuration, for example:

ES_SCALE_OUT_REPOS_1=MYSOR=coherence,,coherence.cluster=MYPAC_cluster,,mfescache.wka.MYPAC_cluster=127.0.0.1,coherence.log.level=9,coherence.log=/tmp/coherence.log##TMP#

Security

If security is enabled for the Coherence server, the user-id to use for access must be specified with an at character (@) as a suffix followed with the rest of the connection string, for example:

ES_SCALE_OUT_REPOS_1=MYSOR=coherence,MYUSER@mfes-cache-config.xml,coherence.cluster=MYPAC_cluster,mfescache.wka.MYPAC_cluster=127.0.0.1##TMP#

Micro Focus recommends that you store the password in the Vault Facility. See Vault Facility for more information.

Coherence security is configured using an "operational override" configuration file, this can be called tangosol-coherence-override.xml and is found on CLASSPATH or specified using the coherence.override system property. You must specify a corresponding Java security policy. A tangosol.coherence.override.xml file is included in the mfescache.jar, which by default does not specify any security settings.