3 Understanding Configuration

The Coherence distribution includes default configuration files that applications and solutions override when creating their own Coherence configurations.

This chapter includes the following sections:

About Coherence Configuration File Formatting

For proper configuration validation, all configuration files should reference a schema (xsd). The schema dictates the order of elements.

Ensure that you specify the configuration parameters by following the sequence defined in the schema (XSD). Else, schema validation fails and prevents Coherence from starting.

When creating a configuration file, do not use the default configuration file names to ensure that configuration file selection is not based on classpath ordering.

Overview of the Default Configuration Files

The Coherence distribution includes a set of default XML configuration files that are included within the COHERENCE_HOME\lib\coherence.jar library.The easiest way to inspect these files and their associated schemas is to extract the Coherence library to a directory.

The configuration files provide a default setup that allows Coherence to be used out-of-box with minimal changes. The files are for demonstration purposes only and can be reused or changed as required for a particular application or solution. However, the recommended approach is to provide configuration files that override the default configuration files.

The default configuration files include:

  • tangosol-coherence.xml – This files provides operational and run-time settings and is used to create and configure cluster, communication, and data management services. This file is typically referred to as the operational deployment descriptor. The schema for this file is the coherence-operational-config.xsd file. See Operational Configuration Elements.

  • tangosol-coherence-override-dev.xml – This file overrides operational settings in the tangosol-coherence.xml file when Coherence is started in developer mode. By default, Coherence is started in developer mode and the settings in this file are used. The settings in this file are suitable for development environments. The schema file for this override file and the schema for the operational deployment descriptor are the same.

  • tangosol-coherence-override-eval.xml – This file overrides operational settings in the tangosol-coherence.xml file when Coherence is started in evaluation mode. The settings in this file are suitable for evaluating Coherence. The schema file for this override file and the schema for the operational deployment descriptor are the same.

  • tangosol-coherence-override-prod.xml – This file overrides operational settings in the tangosol-coherence.xml file when Coherence is started in production mode. The settings in this file are suitable for production environments. The schema file for this override file and the schema for the operational deployment descriptor are the same.

  • coherence-cache-config.xml – This file is used to specify the various types of caches which can be used within a cluster. This file is typically referred to as the cache configuration deployment descriptor. The schema for this file is the coherence-cache-config.xsd file. See Cache Configuration Elements.

  • coherence-pof-config.xml – This file is used to specify custom data types when using Portable Object Format (POF) to serialize objects. This file is typically referred to as the POF configuration deployment descriptor. The schema for this file is the coherence-pof-config.xsd file. See POF User Type Configuration Elements.

  • Management configuration files – A set of files that are used to configure Coherence management reports. The files are located in the /reports directory within coherence.jar. The files include a report group configuration files (report-group.xml, the default), which refer to any number of report definition files. Each report definition file results in the creation of a report file that displays management information based on a particular set of metrics. The schema for these files are the coherence-report-config.xsd file and the coherence-report-group-config.xsd file, respectively. See Report File Configuration Elements and Report Group Configuration Elements in Managing Oracle Coherence.

Specifying an Operational Configuration File

The tangosol-coherence.xml operational deployment descriptor provides operational and run-time settings and is used to create and configure cluster, communication, and data management services.At run time, Coherence uses the first instance of tangosol-coherence.xml that is found in the classpath.

The default operational deployment descriptor that is shipped with Coherence is located in the root of the coherence.jar library. This file can be changed as required; however, overriding this file is recommended when configuring the operational run time. See Understanding the XML Override Feature.

See also Using Coherence Clusters.

This section includes the following topics:

Using the Default Operational Override File

Elements in the default tangosol-coherence.xml file are overridden by placing an operational override file named tangosol-coherence-override.xml in the classpath at run time. The structure of the override file and the operational deployment descriptor are the same except that all elements are optional. The override file includes only the elements that are being changed. Any missing elements are loaded from the tangosol-coherence.xml file.

In general, using the operational override file provides the most comprehensive method of configuring the operational run time and is used in both development and production environments.

To use the default operational override file:

  1. Create a file named tangosol-coherence-override.xml.
  2. Edit the file and add any operational elements that are to be overridden.

    The following example configures a cluster name and overrides the default cluster name:

    <?xml version='1.0'?>
    
    <coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
       coherence-operational-config.xsd">
       <cluster-config>
          <member-identity>
             <cluster-name system-property="coherence.cluster">
                MyCluster</cluster-name>
          </member-identity>
       </cluster-config>
    </coherence>
    
  3. Save and close the file.
  4. Make sure the location of the operational override file is located in the classpath at run time.

    The following example demonstrates starting a cache server that uses an override file that is located in COHERENCE_HOME.

    java -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

    Tip:

    When using the cache-server and coherence scripts during development, add the location of the tangosol-coherence-override.xml file to the classpath using the Java -cp argument in each of the scripts.

Specifying an Operational Override File

The coherence.override system property specifies an operational override file to be used instead of the default tangosol-coherence-override.xml file. The structure of the specified file and the operational deployment descriptor are the same except that all elements are optional. Any missing elements are loaded from the tangosol-coherence.xml file.

The coherence.override system property provides an easy way to switch between different operational configurations and is convenient during development and testing.

To specify an operational override file:

  1. Create a text file.
  2. Edit the file and add any operational elements that are to be overridden.

    The following example configures the multicast join timeout:

    <?xml version='1.0'?>
    
    <coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
       coherence-operational-config.xsd">
       <cluster-config>
          <multicast-listener>
             <join-timeout-milliseconds>6000</join-timeout-milliseconds>
          </multicast-listener>
       </cluster-config>
    </coherence>
    
  3. Save the file as an XML file and close the file.
  4. Specify the name of the operational override file as a value of the coherence.override system property. If the file is not located in the classpath, enter the full (or relative) path to the file and the name. The system property also supports the use of a URL when specifying the location of an operational override file.

    The following example demonstrates starting a cache server and using an operational override file that is named cluster.xml which is located in COHERENCE_HOME.

    java -Dcoherence.override=cluster.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

Defining Override Files for Specific Operational Elements

Override files can be created to override the contents of specific operational elements. The override files follow the same structure as the operational deployment descriptor except that their root element must match the element that is to be overridden. See Defining Custom Override Files.

In general, override files for specific operational elements provides fine-grained control over which portions of the operational deployment descriptor may be modified and allows different configurations to be created for different deployment scenarios.

To define override files for specific operational elements:

  1. Create a tangosol-coherence-override.xml file. See Using the Default Operational Override File.
  2. Add an xml-override attribute to an element that is to be overridden. The value of the xml-override attribute is the name of an override file.

    The following example defines an override file named cluster-config.xml that is used to override the <cluster-config> element.

    <?xml version='1.0'?>
    
    <coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
       coherence-operational-config.xsd">
       <cluster-config xml-override="/cluster-config.xml">
       ...
       </cluster-config>
    </coherence>
    
  3. Save and close the file.
  4. Create a text file.
  5. Edit the file and add an XML node that corresponds to the element that is to be overridden. The XML root element must match the element that is to be overridden.

    Using the example from step 2, the following node is created to override the <cluster-config> element and specifies a multicast join timeout.

    <?xml version='1.0'?>
    
    <cluster-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
       coherence-operational-config.xsd">
       <multicast-listener>
          <join-timeout-milliseconds>4000</join-timeout-milliseconds>
       </multicast-listener>
    </cluster-config>
    
  6. Save the file as an XML file with the same name used in the xml-override attribute.
  7. Make sure the location of both override files are located in the classpath at run time.

    The following example demonstrates starting a cache server that uses override files that are located in COHERENCE_HOME.

    java -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

Viewing Which Operational Override Files are Loaded

The output for a Coherence node indicates the location and name of the operational configuration files that are loaded at startup. The operational configuration messages are the first messages to be emitted when starting a process. The output is especially helpful when using multiple override files and is often useful when developing and testing Coherence applications and solutions.

The following example output demonstrates typical messages that are emitted:

Loaded operational configuration from resource "jar:file:/D:/coherence/lib/
   coherence.jar!/tangosol-coherence.xml"
Loaded operational overrides from resource "jar:file:/D:/coherence/lib/
   coherence.jar!/tangosol-coherence-override-dev.xml"
Loaded operational overrides from resource "file:/D:/coherence/
   tangosol-coherence-override.xml"
Optional configuration override "/cluster-config.xml" is not specified
Optional configuration override "/custom-mbeans.xml" is not specified

The above output indicates that the operational deployment descriptor included in coherence.jar was loaded and that settings in this file are overridden by two loaded override files: tangosol-coherence-override-dev.xml and tangosol-coherence-override.xml. In addition, two override files were defined for specific operational elements but were not found or loaded at run time.

Specifying a Cache Configuration File

The coherence-cache-config.xml cache configuration deployment descriptor file is used to specify the various types of caches that can be used within a cluster.
At run time, Coherence uses the first coherence-cache-config.xml file that is found in the classpath. A sample coherence-cache-config.xml file is included with Coherence and is located in the root of the coherence.jar library. The sample file is provided only for demonstration purposes. It can be changed or reused as required; however, it is recommended that a custom cache configuration deployment descriptor be created instead of using the sample file.

Note:

  • It is recommended (although not required) that all cache server nodes within a cluster use identical cache configuration descriptors.

  • Coherence requires a cache configuration deployment descriptor to start. If the cache configuration deployment descriptor is not found at run time, an error message indicates that there was a failure loading the configuration resource and also provides the name and location for the file that was not found.

See also Using Caches.

This section includes the following topics:

Using a Default Cache Configuration File

Coherence is configured out-of-box to use the first coherence-cache-config.xml file that is found on the classpath. To use a coherence-cache-config.xml file, the file must be located on the classpath and must precede the coherence.jar library; otherwise, the sample coherence-cache-config.xml file that is located in the coherence.jar is used.

To use a default cache configuration file:

  1. Make a copy of the sample coherence-cache-config.xml file that is located in the coherence.jar and save it to a different location. The cache definitions that are included in the sample file are for demonstration purposes and are used as a starting point for creating solution-specific cache configurations.
  2. Ensure that the location where the coherence-cache-config.xml file is saved is in the classpath at run time and that the location precedes the coherence.jar file in the classpath.

    The following example demonstrates starting a cache server that uses a coherence-cache-config.xml cache configuration file that is located in COHERENCE_HOME.

    java -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

Overriding the Default Cache Configuration File

The default name and location of the cache configuration deployment descriptor is specified in the operational deployment descriptor within the <configurable-cache-factory-config> element. This element can be overridden to specify a different name an location to be used for the default cache configuration file.

To override the default cache configuration file:

  1. Make a copy of the default coherence-cache-config.xml cache configuration file that is located in the coherence.jar and save it to a location with a different name.
  2. Create a tangosol-coherence-override.xml file. See Using the Default Operational Override File.
  3. Edit the operational override file and enter a <configurable-cache-factory-config> node that specifies the name of the cache configuration file created in step 1. If the cache configuration file is not located in the classpath, enter the full (or relative) path to the file as well. The element also supports the use of a URL when specifying the location of a cache configuration file.

    The following example specifies a cache configuration deployment descriptor called MyConfig.xml.

    <?xml version='1.0'?>
    
    <coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
       coherence-operational-config.xsd">
       <configurable-cache-factory-config>
          <init-params>
             <init-param>
                <param-type>java.lang.String</param-type>
                <param-value system-property="coherence.cacheconfig">
                   MyConfig.xml</param-value>
             </init-param>
          </init-params>
       </configurable-cache-factory-config>
    </coherence>
    
  4. Save and close the file.
  5. Ensure that the location of the operational override file is located in the classpath at run time.

    The following example demonstrates starting a cache server using an operational override file and a custom cache configuration file that are located in COHERENCE_HOME.

    java -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

Using the Cache Configuration File System Property

The coherence.cacheconfig system property is used to specify a custom cache configuration deployment descriptor to be used instead of the configured default cache configuration deployment descriptor. The system property provides an easy way to switch between different configurations and is convenient during development and testing.

To specify a custom cache configuration file, enter the name of the file as a value of the coherence.cacheconfig system property. This is typically done as a -D Java option when starting a Coherence node. If the file is not located in the classpath, enter the full (or relative) path to the file and the name. The system property also supports the use of a URL when specifying the location of a cache configuration file.

The following example starts a cache server and specifies a cache configuration deployment descriptor called MyConfig.xml that is located in COHERENCE_HOME.

java -Dcoherence.cacheconfig=MyConfig.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

Viewing Which Cache Configuration File is Loaded

The output for a Coherence node indicates the location and name of the cache configuration deployment descriptor that is loaded at startup. The configuration message is the first message to display after the Coherence copyright text is emitted. The output is especially helpful when developing and testing Coherence applications and solutions.

The following example output demonstrates a cache configuration message which indicates that a cache configuration deployment descriptor named Myconfig.xml was loaded:

Loaded cache configuration from resource "file:/D:/coherence/Myconfig.xml"

Specifying a POF Configuration File

The pof-config.xml POF configuration deployment descriptor file is used to specify custom user types when using Portable Object Format (POF) for serialization.
At run time, Coherence uses the first pof-config.xml file that is found in the classpath.

Note:

  • It is recommended that all nodes within a cluster use identical POF configuration deployment descriptors.

  • A POF configuration deployment descriptor is only loaded if the POF serializer is either configured as part of a cache scheme or configured globally for all cache schemes.

See also Using Portable Object Format.

This section includes the following topics:

Overriding the Default POF Configuration File

The default pof-config.xml POF configuration file is located in the root of the coherence.jar library. Coherence is configured out-of-box to use the first pof-config.xml file that is found on the classpath. To use a different pof-config.xml file, the file must be located on the classpath and must precede the coherence.jar library; otherwise, the default pof-config.xml file that is located in the coherence.jar library is used.

The POF configuration file should be customized for a particular application. The default POF configuration file references the coherence-pof-config.xml file. This is where the Coherence specific user types are defined and should always be included when creating a POF configuration file.

To override the Default POF Configuration File:

  1. Create an XML file.
  2. Edit the file and create a <pof-config> node that includes the default Coherence POF user types:
    <?xml version="1.0"?>
    
    <pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config
       coherence-pof-config.xsd">
       <user-type-list>
          <include>coherence-pof-config.xml</include>
       </user-type-list>
    </pof-config>
    
  3. Save the file as pof-config.xml and close the file.
  4. Ensure that the location of the POF configuration file is located in the classpath at run time.

    The following example demonstrates starting a cache server and using a POF configuration file that is located in COHERENCE_HOME.

    java -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

Using the POF Configuration File System Property

The coherence.pof.config system property is used to specify a custom POF configuration deployment descriptor to be used instead of the default pof-config.xml file. The system property provides an easy way to switch between different configurations and is convenient during development and testing.

To specify a custom POF configuration file:

  1. Create an XML file.
  2. Edit the file and create a <pof-config> node that includes the default Coherence POF user types:
    <?xml version="1.0"?>
    
    <pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config
       coherence-pof-config.xsd">
       <user-type-list>
          <include>coherence-pof-config.xml</include>
       </user-type-list>
    </pof-config>
    
  3. Save and close the file.
  4. Enter the name of the file as a value of the coherence.pof.config system property. This is typically done as a -D Java option when starting a Coherence node. If the file is not located in the classpath, enter the full (or relative) path to the file and the name. The system property also supports the use of a URL when specifying the location of a POF configuration file.

    The following example starts a cache server and specifies a POF configuration deployment descriptor called MyPOF.xml that is located in COHERENCE_HOME.

    java -Dcoherence.pof.config=MyPOF.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

Combining Multiple POF Configuration Files

The <include> element is used within a POF configuration deployment descriptor to include user types that are defined in different POF configuration deployment descriptors. This allows user types to be organized in meaningful ways, such as by application or development group.

Note:

When combining multiple POF configuration files, each user type that is defined must have a unique <type-id>. If no type identifier is included, then the type identifiers are based on the order in which the user types appear in the composite configuration file.

To combine multiple POF configuration files:

  1. Open an existing POF configuration file that is being loaded at startup.
  2. Add an <include> element whose value is the name of a POF configuration file. If the file is not located in the classpath, enter the full (or relative) path to the file and the name. A URL can also be used to locate the file.

    The following example combines two POF configuration files in addition to the default Coherence POF configuration file:

    <?xml version='1.0'?>
    
    <pof-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-pof-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-pof-config
       coherence-pof-config.xsd">
       <user-type-list>
          <include>coherence-pof-config.xml</include>
          <include>hr-pof-config.xml</include>
          <include>crm-pof-config.xml</include>
       </user-type-list>
    </pof-config>
    
  3. Save and close the file.
  4. If required, ensure that the location of the POF configuration files are located in the classpath at run time.

    The following example demonstrates starting a cache server that uses POF configuration files that are located in COHERENCE_HOME.

    java -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

Viewing Which POF Configuration Files are Loaded

The output for a Coherence node indicates the location and name of the POF configuration deployment descriptors that are loaded at startup. The configuration messages are among the messages that display after the Coherence copyright text is emitted and are associated with the cache service that is configured to use POF. The output is especially helpful when developing and testing Coherence applications and solutions.

The following example output demonstrates POF configuration messages which indicate that four POF configuration deployment descriptors were loaded:

Loading POF configuration from resource "file:/D:/coherence/my-pof-config.xml"
Loading POF configuration from resource "file:/D:/coherence/coherence-pof-config.xml"
Loading POF configuration from resource "file:/D:/coherence/hr-pof-config.xml"
Loading POF configuration from resource "file:/D:/coherence/crm-pof-config.xml"

Specifying Management Configuration Files

There are several different configuration files that are used to configure management.

The management configuration files include:

  • report group configuration file – A report group configuration file is used to list the name and location of report definition files and the output directory where reports are written. The name and location of this file is defined in the operational deployment descriptor. By default, the report-group.xml file is used and is located in the /reports directory of the coherence.jar. Additional report group configuration file are provided and custom report group files can be created as required.

  • report configuration files – A report configuration file defines a report and results in the creation of a report file that displays management information for a particular set of metrics. Report configuration files must be referenced in a report group configuration file to be used at run time. The default report configuration files are located in the /reports directory of the coherence.jar and are referenced by the default report group configuration file. Custom report configuration files can be created as required.

  • custom-mbeans.xml – This file is the default MBean configuration override file and is used to define custom MBeans (that is, application-level MBeans) within the Coherence JMX management and monitoring framework. This allows any application-level MBean to be managed and monitored from any node within the cluster. Custom MBeans can be defined within the operational override file. However, the MBean configuration override file is typically used instead.

See also Introduction to Oracle Coherence Management.

This section includes the following topics:

Specifying a Custom Report Group Configuration File

The name and location of the default report group configuration file is specified in the operational configuration deployment descriptor within the <management-config> node. A custom report group configuration file can be specified by either using an operational override file or a system property.

Note:

The report group configuration file is only loaded if JMX management is enabled. The examples in this section demonstrate enabling JMX management on nodes that host an MBean server.

This section includes the following topics:

Overriding the Default Report Group Configuration File

The name and location of a custom report group configuration file can be specified using an operational override file. This mechanism overrides the default name and location of the report group configuration file.

To override the default report group configuration file:

  1. Create an XML file.
  2. Edit the file and create a <report-group> node as follows. This example configures a single report.
    <?xml version='1.0'?>
    
    <report-group xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-report-group-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-report-group-config
       coherence-report-group-config.xsd">
       <frequency>1m</frequency>
       <output-directory>./</output-directory>
       <report-list>
          <report-config>
             <location>reports/report-node.xml</location>
          </report-config>
       </report-list>
    </report-group>
    
  3. Save and close the file.
  4. Create a tangosol-coherence-override.xml file. See Using the Default Operational Override File.
  5. Edit the file and enter a <management-config> node that specifies the name of the report group configuration file. If the report group configuration file is not located in the classpath, enter the full (or relative) path to the file as well. The element also supports the use of a URL when specifying the location of a report group configuration file.

    The following example enables JMX management and specifies a report group configuration deployment descriptor called my-group.xml.

    <?xml version='1.0'?>
    
    <coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
       coherence-operational-config.xsd">
       <management-config>
          <managed-nodes system-property="coherence.management">
             all</managed-nodes>
          <reporter>
             <configuration system-property="coherence.management.report.
                configuration">my-group.xml</configuration>
          </reporter>
       </management-config>
    </coherence>
    
  6. Save and close the file.
  7. Ensure that the location of the operational override file is located in the classpath at run time.

    The following example demonstrates starting a cache server using an operational override file and a report group configuration file that are located in COHERENCE_HOME.

    java -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    
Using the Report Group Configuration File System Property

The coherence.management.report.configuration system property is used to specify a custom report group configuration file to be used instead of the default report-group.xml file. The system property provides an easy way to switch between different configurations and is convenient during development and testing.

To specify a custom report group configuration file, enter the name of the file as a value of the coherence.management.report.configuration system property. This is typically done as a -D Java option when starting a Coherence node. If the file is not located in the classpath, enter the full (or relative) path to the file and the name. The system property also supports the use of a URL when specifying the location of a report group configuration file.

The following example starts a cache server, enables JMX management, and specifies a report group configuration file that is named my-group.xml and is located in COHERENCE_HOME.

java -Dcoherence.management=all -Dcoherence.management.report.configuration=my-group.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

Specifying an MBean Configuration File

The tangosol-coherence.xml operational deployment descriptor defines an operational override file that is named custom-mbeans.xml and is specifically used to define custom MBeans. A name and location of the override file may also be specified using the MBean configuration file system property.

This section includes the following topics:

Using the Default MBean Configuration Override File

Custom MBeans are defined within an override file named custom-mbeans.xml. At run time, Coherence uses the first instance of custom-mbeans.xml that is found in the classpath.

To use the default MBean configuration override file:

  1. Create a file named custom-mbeans.xml.
  2. Edit the file and create an empty <mbeans> node as follows:
    <?xml version='1.0'?>
    
    <mbeans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
       xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
       coherence-operational-config.xsd">
    </mbeans>
    
  3. Save and close the file.
  4. Make sure the location of the custom MBean configuration override file is located in the classpath at run time.

    The following example demonstrates starting a cache server that uses a default MBean configuration override file that is located in COHERENCE_HOME.

    java -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    
Using the MBean Configuration File System Property

The coherence.mbeans system property specifies an MBean configuration override file to be used instead of the default custom-mbeans.xml override file. The system property provides an easy way to switch between different MBean configurations and is convenient during development and testing.

To specify an MBean configuration override file, enter the name of the file as a value of the coherence.mbeans system property. This is typically done as a -D Java option when starting a Coherence node. If the file is not located in the classpath, enter the full (or relative) path to the file and the name. The system property also supports the use of a URL when specifying the location of an MBean configuration override file.

The following example starts a cache server and specifies an MBean configuration override file that is named my-mbeans.xml and is located in COHERENCE_HOME.

java -Dcoherence.mbeans=my-mbeans.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

Viewing Which Management Configuration Files are Loaded

The output for a Coherence node indicates the location and name of the report group configuration file and the MBean configuration file that are loaded at startup. The output is especially helpful when developing and testing Coherence applications and solutions.

Report Group Configuration File

The report group configuration messages are among the messages that display after the Coherence copyright text is emitted.

The following example output demonstrates a report group configuration message that indicates the my-group.xml file is loaded:

Loaded Reporter configuration from "file:/D:/coherence/my-group.xml

MBean Configuration Override File

The MBean configuration message is emitted with the other operational override messages and is among the first messages to be emitted when starting a process. The output is especially helpful when using override files and is often useful when developing and testing Coherence applications and solutions.

The following example output demonstrates an operational override message that indicates the default MBean configuration override file is loaded:

Loaded operational overrides from resource "file:/D:/coherence/custom-mbeans.xml"

Disabling Schema Validation

Coherence uses schema validation to ensure that configuration files adhere to their respective schema definition.Configuration files that include a schema reference are automatically validated against the schema when the configuration file is loaded. A validation error causes an immediate failure and an error message is emitted that indicates which element caused the error. Schema validation should always be used as a best practice.

Schema validation can be disabled if required. To disable schema validation, remove the xsi:schemaLocation attribute from a configuration file. The following example creates a tangosol-coherence-override.xml file that does not contain a schema reference and is not validated when loaded:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config">
   ...
</coherence>

Note:

When schema validation is disabled, Coherence only fails if the XML is malformed. Syntactical errors are ignored and may not be immediately apparent.

Understanding the XML Override Feature

You can use the XML override feature to change operational settings without having to edit the default tangosol-coherence.xml operational deployment descriptor that is located in the coherence.jar.This mechanism is the preferred way of configuring the Coherence operational run time.

The XML override feature works by associating an XML document, commonly referred to as an override file, with a specific operational XML element. The XML element, and any of its subelements, are then modified as required in the override file. At run time, Coherence loads the override file and its elements replace (or are added to) the elements that are in the tangosol-coherence.xml file.

An override file does not have to exist at run time. However, if the override file does exist, then its root element must match the element it overrides. In addition, subelements are optional. If a subelement is not defined in the override file, it is loaded from the tangosol-coherence.xml file. Typically, only the subelements that are being changed or added are placed in the override file.

This section includes the following topics:

Using the Predefined Override Files

Multiple override files are predefined and can override elements in the operational deployment descriptor. These files must be manually created and saved to a location in the classpath.

  • tangosol-coherence-override.xml – This override file is defined for the <coherence> root element and is used to override any element in the operational deployment descriptor. The root element in this file must be the <coherence> element.

  • custom-mbeans.xml – This override file is defined for the <mbeans> element and is used to add custom MBeans to the operational deployment descriptor. The root element in this file must be the <mbeans> element.

  • cache-factory-config.xml – This override file is defined for the <configurable-cache-factory-config> element and is used to customize a configurable cache factory. This override file is typically only used to support container integrations. The <configurable-cache-factory-config> element is not commonly overridden.

  • cache-factory-builder-config.xml – This override file is defined for the <cache-factory-builder-config> element and is used to customize a cache factory builder. This override file is typically only used to support container integrations. The <cache-factory-builder-config> element is not commonly overridden.

The following example demonstrates a tangosol-coherence-override.xml file that is used to override the default cluster name. All other operational settings are loaded from the tangosol-coherence.xml file.

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <cluster-config>
      <member-identity>
         <cluster-name system-property="coherence.cluster">MyCluster
         </cluster-name>
      </member-identity>
   </cluster-config>
</coherence>

The following example demonstrates a tangosol-coherence-override.xml file that is used to disable local storage for the distributed cache service on this node. Notice the use of an id attribute to differentiate an element that can have multiple occurrences. The id attribute must match the id attribute of the element being overridden.

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <cluster-config>
      <services>
         <service id="3">
            <init-params>
               <init-param id="4">
                  <param-name>local-storage</param-name>
                  <param-value system-property="coherence.distributed.
                     localstorage">false</param-value>
               </init-param>
            </init-params>
         </service>
      </services>
   </cluster-config>
</coherence>

The following example demonstrates a custom-mbean.xml file that adds a standard MBean definition to the list of MBeans.

<mbeans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <mbean id="100">
      <mbean-class>com.oracle.customMBeans.Query</mbean-class>
      <mbean-name>type=Query</mbean-name>
      <enabled>true</enabled>
   </mbean>
</mbeans>

Defining Custom Override Files

Any element in the tangosol-coherence.xml deployment descriptor can be overridden using the predefined tangosol-coherence-override.xml file. However, there may be situations where more fine-grained configuration control is required. For example, a solution may want to allow changes to certain elements, but does not want to allow changes to the complete operational deployment descriptor. As another example, a solution may want to provide different configurations based on different use cases. Custom override files are used to support these types of scenarios.

Using the xml-override and id attributes

Override files are defined using the xml-override attribute and, if required, the id attribute. Both of these attributes are optional and are added to the operational element that is to be overridden. See Operational Configuration Attribute Reference.

The value of the xml-override attribute is the name of a document that is accessible to the classes contained in the coherence.jar library using the ClassLoader.getResourceAsStream(String name) method. In general, the file name contains a / prefix and is located in the classpath at run time. The attribute also supports the use of a URL when specifying the location of an override file.

For example, to define an override file named cluster-config.xml that is used to override the <cluster-config> element, add an xml-override attribute to the <cluster-config> element in the tangosol-coherence-override.xml file as shown below:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <cluster-config xml-override="/cluster-config.xml">
   ...
   </cluster-config>
</coherence>

To use this override file, create a document named cluster-config.xml and ensure that it and the base document (tangosol-coherence-override.xml in this case) are located in a directory that is in the classpath at run time. For this example, the override file's root element must be <cluster-config> as shown below.

<?xml version='1.0'?>

<cluster-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <multicast-listener>
      <join-timeout-milliseconds>4000</join-timeout-milliseconds>
   </multicast-listener>
</cluster-config>

An id attribute is used to distinguish elements that can occur multiple times.

For example, to define a custom override file named dist-service-config.xml that is used to override the <service> element for the distributed cache service, add an xml-override attribute to the <service> element whose id is number 3 as shown below

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <cluster-config>
      <services>
         <service id="3" xml-override="/dist-service-config.xml">
         </service>
      </services>
   </cluster-config>
</coherence>

To use this override file, create a document named dist-service-config.xml and ensure that it is located in a directory that is in the classpath at run time. For this example, the override file's root element must be <service> as shown below.

<?xml version='1.0'?>

<service id="3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <init-params>
      <init-param id="1">
         <param-name>standard-lease-milliseconds</param-name>
         <param-value>2</param-value>
      </init-param>
   </init-params>
</service>

Note:

If the element's id in the override document does not have a match in the base document, the elements are just appended to the base document.

Defining Multiple Override Files for the Same Element

Multiple override files can be defined for the same element to chain operational override files. This is typically done to allow operational configurations based on different deployment scenarios, such as staging and production.

As an example, the tangosol-coherence.xml operational deployment descriptor located in coherence.jar defines an operational override file for the <coherence> element as follows:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd"
   xml-override="{coherence.override/tangosol-coherence-override-{mode}
   .xml}">
   ...
</coherence>

The mode-specific override files are also located in coherence.jar and are used depending on the Coherence start mode (the value of the <license-mode> element). Each of the mode-specific operational override files, in turn, defines the default operational override file as follows:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd"
   xml-override="/tangosol-coherence-override.xml">
   ...
</coherence>

A fourth override file can be defined for the <coherence> element in the tangosol-coherence-override.xml file. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd"
   xml-override="/tangosol-coherence-override-staging.xml">
   ...
</coherence>

The chain can continue as required. The files are all loaded at run time if they are placed in a location in the classpath. Files higher up in the chain always override files below in the chain.

Changing Configuration Using System Properties

The command-line override feature allows operational and cache settings to be overridden using system properties.System properties are typically specified on the Java command line using the Java -D option. This allows configuration to be customized for each node in a cluster while using the same operational configuration file and cache configuration file across the nodes. System properties are also a convenient and quick way to change settings during development.

This section includes the following topics:

Using Preconfigured System Properties

Coherence includes many preconfigured system properties that are used to override different operational and cache settings. Table D-1 lists all the preconfigured system properties. The preconfigured system properties are defined within the tangosol-coherence.xml and coherence-cache-config.xml default deployment descriptors, respectively, using system-property attributes.

For example, the preconfigured coherence.log.level system property is defined in the tangosol-coherence.xml file as follows:

<logging-config>
   ...
   <severity-level system-property="coherence.log.level">5
   </severity-level>
   ...
</logging-config>

To use a preconfigured system property, add the system property as a Java -D option at startup. For the above example, the log level system property is specified as follows when starting a cache server:

java -Dcoherence.log.level=3 -cp COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

Note:

When using an operational override file and when creating a custom cache configuration file; the preconfigured system properties must always be included along with the element that is to be overridden; otherwise, the property is no longer available.

Creating Custom System Properties

Custom system properties can be created for any operational or cache configuration element. The names of the preconfigured system properties can also be changed as required.

System properties are defined by adding a system-property attribute to the element that is to be overridden. The value of the system-property attribute can be any user-defined name. Custom system properties are typically defined in an operational override file (such as tangosol-coherence-override.xml) and a custom cache configuration file.

Defining a System Property for an Operational Element

The following example defines a system property called multicast.join.timeout for the <join-timeout-milliseconds> operational element and is added to an operational override file:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <cluster-config>
      <multicast-listener>
         <join-timeout-milliseconds system-property="multicast.join.timeout">30000
         </join-timeout-milliseconds>
      </multicast-listener>
   </cluster-config>
</coherence>

Defining a System Property for a Cache Configuration element

The following example defines a system property called cache.name for a <cache-name> element and is added to a custom cache configuration file:

<?xml version='1.0'?>

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
   <caching-scheme-mapping>
    <cache-mapping>
      <cache-name system-property="cache.name"></cache-name>
      ...

Changing a Preconfigured System Property

The following example changes the preconfigured system property name for the <cluster-name> operational element and is added to an operational override file:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
   coherence-operational-config.xsd">
   <cluster-config>
      <member-identity>
         <cluster-name system-property="myapp.cluster.name"></cluster-name>
      </member-identity>
   </cluster-config>
</coherence>

Note:

To remove a system property, delete the system property attribute from the element. If a system property is used at run time and it does not exist, it is disregarded.