10/68

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

The following sections are included in this chapter:

- Overview of the Default Configuration Files

- Specifying an Operational Configuration File

- Specifying a Cache Configuration File

- Specifying a POF Configuration File

- Specifying Management Configuration Files

- Understanding the XML Override Feature

- Changing Configuration Using System Properties

## 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 Document Type Definition (DTD) files 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 DTD for this file is the `coherence.dtd` file. For a complete reference of the elements in this file, see Appendix A, "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.

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

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

- `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 DTD for this file is the `cache-config.dtd` file. For a complete reference of the elements in this file, see Appendix B, "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 DTD for this file is the `pof-config.dtd` file. For a complete reference of the elements in this file, see Appendix D, "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 the Coherence JAR. The files include a report group configuration file (`report-group.xml`, by default), which refers to any number of report definition files. Each report definition file results in the creation of a report file that displays management information for a particular metric. The DTD for these files are the `report-group.dtd` and `report-config.dtd`, respectively. For a complete reference of the elements in this file, see the "management-config" element in Appendix A, "Operational Configuration Elements."

- License configuration files – A set of files that are used to license specific Coherence server and client editions.

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

- Using the Default Operational Override File

- Specifying an Operational Override File

- Defining Override Files for Specific Operational Elements

- Viewing Which Operational Override Files are Loaded

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

### 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 is the same as the operational deployment descriptor 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'?>

       <!DOCTYPE coherence SYSTEM "coherence.dtd">

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

### 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 is the same as the operational deployment descriptor 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:

       <coherence>
          <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 as well as 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

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

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

       <cluster-config>
          <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 will be 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.

The following topics are included in this section:

- Using a Default Cache Configuration File

- Overriding the Default Cache Configuration File

- Using the Cache Configuration File System Property

- Viewing Which Cache Configuration File is Loaded

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

### 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` will be 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 should be used as a starting point for creating solution-specific cache configurations.

2. Make sure that the location where the `coherence-cache-config.xml` file is saved is in the classpath at runtime 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 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`.

       <coherence>
          <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. Make sure 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 `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 as well as 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

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

- Using the POF Configuration File System Property

- Combining Multiple POF Configuration Files

- Viewing Which POF Configuration Files are Loaded

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

### 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"?>

       <!DOCTYPE pof-config SYSTEM "pof-config.dtd">

       <pof-config>
          <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 as well as 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

### 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 as well as 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:

       <pof-config>
          <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, make sure 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. These include:

- `report-group.xml` – The default report group configuration file that 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, this file is located in the `/reports` directory of the `coherence.jar`. An additional report group definition file called `report-all.xml` is also located in the `/reports` directory and references a comprehensive set of reports. Custom report group definition files can be created as required.

- report definition files – A set of default report definition files that each results in the creation of a report file that displays management information for a particular metric. Report definition files must be referenced in a report group definition file in order to be used at run time. The default report definition files are located in the `/reports` directory of the `coherence.jar` and are referenced by the default report group definition file. Custom report definition 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/or monitored from any node within the cluster. Custom MBeans can be defined within any operational override file. However, it is recommended that the MBean configuration override file be used instead.

The following topics are included in this section:

- Specifying a Custom Report Group Configuration File

- Specifying an MBean Configuration File

- Viewing Which Management Configuration Files are Loaded

Refer to Part VI, "Managing Coherence" for detailed instructions on configuring management.

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

#### 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 an empty `<report-group>` node as follows:

       <?xml version='1.0'?>

       <!DOCTYPE report-group SYSTEM "report-group.dtd">

       <report-group>
       </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`.

       <coherence>
          <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. Make sure 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 `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 as well as 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

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

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

       <mbeans>
       </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 `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 as well as 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

### 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 cache configuration from resource "file:/D:/coherence/my-group.xml

MBean Configuration Override File

The MBean configuration message is emitted together 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"

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

- Using the Predefined Override Files

- Defining Custom Override Files

- Defining Multiple Override Files for the Same Element

### Using the Predefined Override Files

Two override files are predefined and can be used to 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.

    <coherence>
       <cluster-config>
          <member-identity>
             <cluster-name>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.

    <coherence>
       <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>
    </coherence>

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

    <mbeans>
       <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 wish 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. Table A-65 lists the operational elements which can contain `xml-override` and `id` attributes.

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, this means that 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:

    <coherence>
       <cluster-config xml-override="/cluster-config.xml">
       ...
       </cluster-config>
    </coherence>

To use this override file, create a document named `cluster-config.xml` and make sure 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.

    <cluster-config>
       <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 than once.

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

    <coherence>
       <services>
          <service id="3" xml-override="/dist-service-config.xml">
          </service>
       </services>
    </coherence>

To use this override file, create a document named `dist-service-config.xml` and make sure 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.

    <service id="3">
       <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 form a chain of 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:

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

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

    <coherence xml-override="/tangosol-coherence-override-staging.xml">
       ...
    </coherence>

The chain can continue as required. The files are all loaded at run time as long as 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.

The following topics are included in this section:

- Using Preconfigured System Properties

- Creating Custom System Properties

### Using Preconfigured System Properties

Coherence includes many preconfigured system properties that can be used to override different operational and cache settings. Table 3-1 lists all the preconfigured system properties.

To use a preconfigured system property, add the system property as a Java `-D` option at startup. The following example demonstrates using the `tangosol.coherence.log.level` system property to specify a log level when starting a cache server:

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

Table 3-1 Preconfigured System Properties

System Property | Setting
--- | ---
`tangosol.coherence.cacheconfig` | Cache configuration descriptor filename. See "configurable-cache-factory-config".
`tangosol.coherence.cluster` | Cluster name. See "member-identity".
`tangosol.coherence.clusteraddress` | Cluster (multicast) IP address. See `<multicast-listener-address>` subelement of "multicast-listener"
`tangosol.coherence.clusterport` | Cluster (multicast) IP port. See `<multicast-listener-port>` subelement of "multicast-listener".
`tangosol.coherence.distributed.backup` | Data backup storage location. See `backup-storage/type` subelement in "DistributedCache Service Parameters".
`tangosol.coherence.distributed.backupcount` | Number of data backups. See `backup-count` subelement in "DistributedCache Service Parameters".
`tangosol.coherence.distributed.localstorage` | Local partition management enabled. See local-storage subelement in "DistributedCache Service Parameters".
`tangosol.coherence.distributed.threads` | Thread pool size. See `thread-count` subelement in "DistributedCache Service Parameters".
`tangosol.coherence.distributed.transfer` | Partition transfer threshold. See `transfer-threshold` subelement in"DistributedCache Service Parameters".
`tangosol.coherence.edition` | Product edition. See "license-config".
`tangosol.coherence.invocation.threads` | Invocation service thread pool size. See `thread-count` subelement in "InvocationService Parameters".
`tangosol.coherence.localhost` | Unicast IP address. See `<unicast-listener-address>` subelement in "unicast-listener".
`tangosol.coherence.localport` | Unicast IP port. See `<unicast-listener-port>` subelement in "unicast-listener".
`tangosol.coherence.localport.adjust` | Unicast IP port auto assignment. See `<unicast-listener-auto>` subelement in "unicast-listener".
`tangosol.coherence.log` | Logging destination. See `<logging-config-destination>` subelement in "logging-config".
`tangosol.coherence.log.level` | Logging level. See `<logging-config-level>` subelement in "logging-config".
`tangosol.coherence.log.limit` | Log output character limit. See `<logging-config-limit>` subelement in "logging-config".
`tangosol.coherence.machine` | Machine name. See "member-identity".
`tangosol.coherence.management` | JMX management mode. See "management-config".
`tangosol.coherence.management.readonly` | JMX management read-only flag. "management-config".
`tangosol.coherence.management.remote` | Remote JMX management enabled flag. See"management-config".
`tangosol.coherence.member` | Member name. See "member-identity".
`tangosol.coherence.mode` | Operational mode. See "license-config".
`tangosol.coherence.override` | Operational configuration override filename.
`tangosol.coherence.priority` | Priority. See "member-identity".
`tangosol.coherence.process` | Process name"member-identity".
`tangosol.coherence.proxy.threads` | Coherence*Extend service thread pool size. See `thread-count` subelement in "ProxyService Parameters".
`tangosol.coherence.rack` | Rack name. See "member-identity".
`tangosol.coherence.role` | Role name. See "member-identity".
`tangosol.coherence.security` | Cache access security enabled flag. See "security-config".
`tangosol.coherence.security.keystore` | Security access controller keystore file name. See "security-config".
`tangosol.coherence.security.password` | Keystore or cluster encryption password. "Encryption Filters".
`tangosol.coherence.security.permissions` | Security access controller permissions file name. See "security-config".
`tangosol.coherence.shutdownhook` | Shutdown listener action. See "shutdown-listener".
`tangosol.coherence.site` | Site name. See "member-identity".
`tangosol.coherence.tcmp.enabled` | TCMP enabled flag. See `<packet-publisher-enabled>` subelement in "packet-publisher".
`tangosol.coherence.tcpring` | !TCP ring enabled flag. See "tcp-ring-listener".
`tangosol.coherence.ttl` | Multicast packet time to live (TTL). See `<mulitcast-listener-ttl>` subelement in "multicast-listener".
`tangosol.coherence.wka` | Well known IP address. See "well-known-addresses".
`tangosol.coherence.wka.port` | Well known IP port. See "well-known-addresses".

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

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

    <cache-config>
      <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:

    <coherence>
       <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 that does not exist, Coherence disregards the system property.