THIS PAGE IS A WORK IN PROGRESS. Some of the class names are already out of date.
Overview
This page discusses generation and application of custom configuration elements, as well as their interaction with the ClusterConfigurationService interface.
Please note that, at time of writing, the ClusterConfigurationService is considered @Experimental. Method signatures are subject to change prior to full support.
Background
Historically, cluster member configuration would be saved in a cache.xml, which would be provided to each member at startup. This would require a cluster administrator to maintain individual XML files for each member.
Since Geode 1.0, we have provided as an alternative the cluster-configuration option. In essence, using cluster configuration allowed a cluster's locator(s) would create, store and distribute the necessary XML files to members that require them when the member attempts to join the cluster.
We wish to remove our current reliance on the XML format, and to make available to extension developers a programatic API to interact with the cluster configuration. This is discussed in more detail in the API proposal, linked below.
That public API will require an extension developer to indicate those classes that contain configuration information for their extension objects by having those classes implement CacheElement. Please note that these configuration classes are themselves distinct from the instantiated object whose configuration they represent.
Currently, we use the Java architecture for XML Binding (JAXB) to marshal and unmarshal these configuration objects to and from the XML maintained by the configuration service. As a result, configuration objects must contain the require JAXB annotations. If an extension developer's configuration is defined by an XSD, these files can be easily generated via xjc. An example generation script is provided below.
In a future iteration, the cluster configuration could sore configuration information not as XML, but as the raw configuration object itself. From that point onward, the configuration object's fields will not require the JAXB annotations, as marshaling and unmarshaling to XML will no longer occur.
Additional API proposal and discussion will occur as that date draws closer. In the interim, an extension developer's configuration classes will require the JAXB annotations so that it may interact properly with the existing services.
Note that all of the above discusses only those classes containing configuration information. To reiterate, these configuration classes are themselves distinct from any instantiated extension object or service. Until the internal reliance on XML has been overcome, it will remain that any extension class must implement Extension. In particular, this includes providing the XmlGenerator for your extension class.
WORK IN PROGRESS: It appears that Extension is an internal interface. I will now write a proposal about publicizing the Extension API, which will be linked here in a future revision.
Placement of Configuration Elements within the Configuration
In the past, the format of a configuration, as represented internally as XML, is specified in the file cache-1.0.xsd. This XSD motivates the generation of our Java configuration objects, as we move away from our reliance on XML.
This specification allows for custom configuration elements to appear in one of two places: in the top-level "cache" or in the first child-level "region."
Separate (non-conflicting) configuration information can exist for the entire cluster as well as each member group. Do not confuse the "cache" level to mean a global configuration. Indeed, each group can define different aspects of the total "cache" configuration.
The "cache" level is intended to contain configuration elements that effect cache member state and operation, where the "region" level is intended to contain configuration elements that effect management of data. For instance, the Lucene Index configuration object is stored as a "region" element, since it acts on a region's data.
When separation is not clear-cut, a developer may choose to store a configuration element in the "cache" that references a region. For instance, the JDBC Connection configuration is stored as a "cache" element containing a region-name reference. At the developer's discretion, this may be less a data concern and more a member I/O concern.
Where a particular configuration is kept is left to the developer's discretion.
Creating Configuration Classes
WORK IN PROGRESS: The interface name and structure is probably going to change soon.
Whether your configuration element will exist at the "cache" level or at the "region" level, your custom configuration class should implement org.apache.geode.cache.configuration.CacheElement. This requires your configuration object to be Serializable and Identifiable<String>.
If your custom configuration elements are themselves defined by an XSD, compatible configuration classes can be generated using JAXB. A simple bindings file similar to that below can impose implementation of CacheElement on generated classes. See the Resources section below for example bindings and scripts to generate classes using JAXB and the command-line tool xjc. Alternatively, generation can be performed by some IDEs, such as IDEA IntelliJ, and XJC plugins exist for Maven, Ant, and Gradle build systems.
JAXB generation provides a good starting point for your configuration classes. However, manual adjustment of generated classes will likely be required. For instance, if your configuration object does not define an id field, the generated class will need to be updated to implement a getId as part of the CacheElement interface.
Interacting with the Cluster Configuration Service
See the Cluster Configuration Service proposals for examples on how your configuration object will interact with the configuration persistence service.
Resources
- Example generation files. Unpack these in your Apache Geode root directory.
- Also refer to