Appendix C Advanced Caching Topics : Specifying Operational Override File Locations

Specifying Operational Override File Locations
As explained in Overriding and Extending the Operational Deployment Descriptor, in order to define additional elements or add system properties for existing elements, you use an override file.
You can actually use two or more tiers of override files depending on your needs:
The reason for using multiple tiers is to enable all (or many) nodes to use the first tier overrides, while providing additional second tier overrides to selected nodes. For example, you may want to enable verbose logging on only one or two nodes for diagnostic purposes. To do so you would provide those settings in a second tier override file that you then reference in the selected nodes’ engine property files.
How the First Tier Override File Default Location is Specified
The operational descriptor file, tangosol-coherence.xml (located in BE_HOME/lib/ext/coherence.jar) contains an xml-override property configured to point to a default override file:
<coherence xml-override="{tangosol.coherence.override /tangosol-coherence-override-{mode}.xml}">
The structure of the property is:
xml-override={property default-property-value}
where property is the name of the override property, and default-property-value is the filepath and name of the file.
How BusinessEvents Uses the Override Property
The object management layer looks for the specified override file in the classpath.
The default location of the file specified by tangosol.coherence.override is a file at the root level of the class path. BusinessEvents uses the first instance of this file that it finds at the root level of the classpath. For example, if you put an instance of this file at the root level of a different JAR file that is located closer to the beginning of the classpath, then that file is used instead of the one in coherence.jar.
If a user overrides the default override location, BusinessEvents looks for the file specified in the same way.
Optional User-Defined Property for Flexibility in the Filename
You can use a user-defined property such as {mode} to define name patterns that provide flexibility. You can place multiple files that use the name pattern in the specified override location. For example, each of the following has a different value for {mode}: tangosol-coherence-override-dev.xml, tangosol-coherence-override-test.xml, and tangosol-coherence-override-prod.xml files. Then you can easily switch between files that have values appropriate for those environments at engine start-up.
You specify the value to use for the user-defined property in your TRA file, or at the command line.
For example, using {mode} as the user defined property, to specify the value in the TRA file, use:
java.property.mode Mode_Value
To override the value at the command line, use
-Dmode Mode_Value
Where (still using the example defined above) the Mode_Value is one of test, prod, or dev.
The default value for {mode} is prod (defined in the tangosol-coherence.xml descriptor). Therefore the default value for the first tier override file is /tangosol-coherence-override-prod.xml.
How to Specify a Different Location for the First Tier Override File
To override the default location of the first tier override file, you provide a value for the tangosol.coherence.override property either at the command line or using an engine property. You can do this one time only, on engine startup. The value and file contents must be the same on all nodes in a cluster.
The value of the property can be a file path or a JAR URL. It must be a location in the classpath.
To specify the override using an engine property, add the property name (specified in the xml-override property) and its value to the TRA files. All nodes in a cache cluster must specify the same file. For example:
java.property.tangosol.coherence.override=file:/c:/tmp/my_tangosol-coherence-override.xml
For URL locations inside any JAR, specify the path as in the following example:
java.property.tangosol.coherence.override=file:/home/jsmith/tmp/client/lib/coherence.jar!/my_tangosol-coherence.override.xml
You can alternatively specify the override as a system property, that is, a command line parameter at engine start-up. For example,:
-Dtangosol.coherence.override=file:/C:/tmp/my_tc-override.xml
How a Second Tier Override File Default Location is Specified and Overridden
The first tier override file can itself specify the default location and name of a second tier override file, again using the xml-override property:
xml-override={property default-property-value}
You would configure the property using different values, but the mechanism is the same. For example, you might use the property name be.coherence.override. You can also use another user property for part of the filename, if you want to provide that flexibility, for example:
<coherence xml-override="{be.coherence.override /be-coherence-override-{be.coherence.environment}.xml}"
As explained above, if you want to specify a file of this pattern, for example, be-coherence-override-dev, you could specify the value in the TRA files or at the command line on engine start-up. Here is an example showing how the system property value is defined at the command line:
-Dbe.coherence.environment=dev
Similarly, if you want to specify a different location and filename for the second-tier override file, you would use the be.coherence.override property, for example:
-Dbe.coherence.override=file:C:/tmp/tango-coherence-override.xml