Skip Headers
Oracle® Coherence Developer's Guide
Release 3.7

Part Number E18677-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

3 Understanding Configuration

This chapter describes each of the default configuration files that are distributed with Coherence and details how applications and solutions override these files when creating their own Coherence configurations.

Note:

Coherence configuration files are described using XML Schema (XSD) and are no longer described using Document Type Definition (DTD). DTD files are deprecated and will be desupported. All configuration files that currently use the DTD files must be updated to reference and adhere to the appropriate XSD files.

The following sections are included in this chapter:

3.1 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:

3.2 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" for detailed information about the XML override feature.

The following topics are included in this section:

Refer to Part II, "Using Data Clusters" for detailed instructions on configuring the operational run time.

3.2.1 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="tangosol.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.

3.2.2 Specifying an Operational Override File

The tangosol.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 tangosol.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 port number:

    <?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>
             <port system-property="tangosol.coherence.clusterport">3059</port>
          </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 tangosol.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 -Dtangosol.coherence.override=cluster.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

3.2.3 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" for detailed information on defining override files for specific operational elements.

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 as described in "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
    

3.2.4 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.

3.3 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.

The following topics are included in this section:

Refer to Part III, "Using Caches" for detailed instructions on configuring caches.

3.3.1 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
    

3.3.2 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 as described in "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="tangosol.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
    

3.3.3 Using the Cache Configuration File System Property

The tangosol.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 tangosol.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 -Dtangosol.coherence.cacheconfig=MyConfig.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

3.3.4 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"

3.4 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 instance of pof-config.xml 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. The default coherence-cache-config.xml provides an example cache scheme that defines the POF serializer, but it is commented out by default.

The default POF configuration deployment descriptor that is distributed with Coherence is located in the root of the coherence.jar library. This file should be customized, replaced, or extended for a particular application or solution. By default, the deployment descriptor references the coherence-pof-config.xml file. This is where the Coherence specific user types are defined and should always be included when extending or creating a POF configuration file.

The following topics are included in this section:

Refer to Chapter 19, "Using Portable Object Format" for detailed instructions on configuring POF user types.

3.4.1 Using the POF Configuration File System Property

The tangosol.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 tangosol.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 -Dtangosol.pof.config=MyPOF.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer
    

3.4.2 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
    

3.4.3 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"

3.5 Specifying Management Configuration Files

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

The following topics are included in this section:

See Oracle Coherence Management Guide for detailed instructions on managing Coherence.

3.5.1 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.

3.5.1.1 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 as described in "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="tangosol.coherence.management">all
          </managed-nodes>
          <reporter>
             <configuration system-property="tangosol.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
    

3.5.1.2 Using the Report Group Configuration File System Property

The tangosol.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 tangosol.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 -Dtangosol.coherence.management=all -Dtangosol.coherence.management.report.configuration=my-group.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

3.5.2 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.

3.5.2.1 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
    

3.5.2.2 Using the MBean Configuration File System Property

The tangosol.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 tangosol.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 -Dtangosol.coherence.mbeans=my-mbeans.xml -cp COHERENCE_HOME;COHERENCE_HOME\lib\coherence.jar com.tangosol.net.DefaultCacheServer

3.5.3 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"

3.6 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.

3.7 Understanding the XML Override Feature

The XML override feature is a configuration mechanism that allows any operational settings to be changed 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.

The following topics are included in this section:

3.7.1 Using the Predefined Override Files

Two 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.

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="tangosol.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="tangosol.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>

3.7.2 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 "Attribute Reference" for a list of the operational elements that support the use of an override file.

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 more 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.

3.7.3 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="{tangosol.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.

3.8 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.

The following topics are included in this section:

3.8.1 Using Preconfigured System Properties

Coherence includes many preconfigured system properties that are used to override different operational and cache settings. Table C-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 tangosol.coherence.log.level system property is defined in the tangosol-coherence.xml file as follows:

<logging-config>
   ...   <severity-level system-property="tangosol.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 -Dtangosol.coherence.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.

3.8.2 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.