Page History

Overview

Currently, the only way for a command developer to modify cluster configuration is through internal methods or to manually edit the configuration xml file while the cluster is offline.
It can be expected that a module developer will who create commands or functions that require information in or modification of will need to modify the cluster configuration .
Thereforeas well, therefore, we should expose a public API for to retrieve or manipulate the cluster configuration , to promote correctness and ease of use.persisted by the locator.

Background

The cache-1.0.xsd defines the permissible structure of the cluster config, currently represented in XML.
Developers can include their own cluster configuration elements in one of two places as defined in the cache-1.0.xsd: at the cache level or at the region level.
These accept any XML element, so long as the namespace does not match Geode's (i.e., {{http://geode.apache.org/schema/cache}}).

Goals

• Expose a clean Java API for retrieval and modification of the cluster configuration, as well as injection of elements into the cache and region levels of the cluster configuration.
• Do not require a developer to explicitly define methods to translate a configuration object to or from XML.
• Separate concerns of XML generation and function execution.

Approach

• The API is intended to be used by sub-module developers to create their own commands that would need to access/modify the cluster configuration.
• The API is intended to ONLY update the cluster or server-group's configuration saved by the locator(s). 
• The API should not be tied with XML. We should be able to change how we save cluster configuration internally without changing the api.

Anti-Goals

• This API is not to be confused with an API that app-developers can use from client or from servers to, say, create a region and update the cluster configuration at the same time. That API would entail a remote invocation of this lower-level api, but it's not the same.

Approach

• Define a no-op interfaces CacheElement and RegionElement to identify classes that may be saved to the cache and region XML entities, respectively.
• Leverage JAXB to generate an initial set of configuration objects .  from cache-1.0.xsd. These will be used internally to marshall/unmarshll from/to xml. Developers only need to work with these configuration objects, not directly with xml.
• Module developers will use their own xsd to create module specific configuration object. The api should allow developers to pass in these objects and be saved in the cluster configuration.
• Expose a public ClusterConfigurationService via a public abstract commandExpose ClusterConfigurationService via the cache, provided a locator is managing that cache.

Proposal

As a minimum viable product, we would require only two methods: a getter and an updater.

public interface ClusterConfigurationServiceConfigurationPersistenceService {
  /**
  * @param group The group to which the cluster configuration applies.
 *default For configuration that applies to every member, use the group is "cluster".
  * @param additionalBindClass custom Theseelement classes willcreated allowby the returned CacheConfig to include objects
 * if the bound types, rather than defaulting to {@link com.sun.org.apache.xerces.internal.dom.ElementNSImpl}
 * to represent the configuration elements XML.
 other modules if present.
  * @return The cluster configuration for the specified group.
  */
  CacheConfig getCacheConfig(String group, Class... additionalBindClass);
 
  /**
  * @param group The group to which the cluster configuration applies.
 *default For configuration that applies to every member, use the group is "cluster".
  * @param mutator Specification of how the cluster configuration should be altered.
  * @param additionalBindClass custom Theseelement classes willcreated allowby theother returned CacheConfig to include objects
 * if the bound types, rather than defaulting to {@link com.sun.org.apache.xerces.internal.dom.ElementNSImpl}
 * to represent the configuration elements XML.
 modules if present.
  */
  void updateCacheConfig(String group, UnaryOperator<CacheConfig> mutator, Class... additionalBindClass);
}

...

For additional utility, each method could assume group = "cluster" when not provided.

The ClusterConfigurationService will be made available from the Cache, provided the Cache is managed by a Locator.  The service is unavailable for other members.

Intended Use:

Given an interface as the above, we would be able to implement, for instance, the CreateIndexCommand instead as

public class CreateIndexCommand implements GfshCommandSingleGfshCommand {
  private static final CreateIndexFunction createIndexFunction = new CreateIndexFunction();

  @CliCommand(value = CliStrings.CREATE_INDEX, help = CliStrings.CREATE_INDEX__HELP)
  @CliMetaData(relatedTopic = {CliStrings.TOPIC_GEODE_REGION, CliStrings.TOPIC_GEODE_DATA})
  @ResourceOperation(resource = ResourcePermission.Resource.CLUSTER,
      operation = ResourcePermission.Operation.MANAGE, target = ResourcePermission.Target.QUERY)
  public Result createIndex(...){
 
  Result result;
  final Set<DistributedMember> targetMembers = findMembers(group, memberNameOrID);

  if (targetMembers.isEmpty()) {
    return ResultBuilder.createUserErrorResult(CliStrings.NO_MEMBERS_FOUND_MESSAGE);
  }

  // Objective: create this Index object.
  // This class was generated by JAXB
  RegionConfig.Index index = new RegionConfig.Index();
  index.setName(indexName);
  index.setExpression(indexedExpression);
  index.setTypesetFromClause(regionPath);
  if (indexType.name()); == IndexType.PRIMARY_KEY) {
    index.setFromClausesetKeyIndex(regionPathtrue);

  } //else Pass{
 the function to each member, where the index will be instantiated. index.setKeyIndex(false);
    index.setType(indexType.getName());
  }

  List<CliFunctionResult> functionResults =
      executeAndGetFunctionResult(createIndexFunction, index, targetMembers);
  result = ResultBuilder.buildResult(functionResults);

  ClusterConfigurationService service = getSharedConfiguration(result.setConfigObject(index);
  ifreturn (result.getStatus().equals(Result.Status.OK) && service != nullresult;
}
 
@Override
public void updateClusterConfig(String group, CacheConfig config, Object element) {
  RegionConfig.Index index // If the function executes successfully and the ClusterConfigurationService exists= (RegionConfig.Index) element;
  String regionPath //= getValidRegionName(i.e., the member executing this command is a Locator), then update the cluster config.index.getFromClause(), config);

  RegionConfig regionConfig UnaryOperator<CacheConfig> mutator = cc -> {= config.findRegionConfiguration(regionPath);
  if    RegionConfig (regionConfig =
= null) {
    throw new EntityNotFoundException("Region  cc.getRegion().stream().filter(x -> x.getName().equals(regionPath)).findFirst()
              .orElse(null" + index.getFromClause() + " not found.");
  }
    regionConfig.getIndex().add(index);
      return cc;
    };
    service.updateCacheConfig("cluster", mutator);
  }
  return result;
}

Here, we declaratively build the RegionConfig.Index object we would like to add to the configuration.
On successfull creation, we search for the RegionConfig object to which the index configuration should belong and add this index to that array.
With the mutator defined, we execute (a concurrency-safe) update to the cluster configuration.

Comments

Common operations, such as the above "find region config", could also be considered for initial inclusion to the public API.

The use of UnaryOperator<CacheConfig> could be replaced by a direct assignment, i.e., updateCacheConfig("cluster", myNewCacheConfig).
While this might present a cleaner API, it would also allow for race conditions between concurrent modifications of the configuration.

Long-term Goals

• Reduce duplication of effort by replacing "creation" classes (i.e., CacheCreation, RegionCreation, BindingCreation, et al) with JAXB-generated classes.
• Remove requirement of JAXB / XML annotations on configuration element classes.
• This api is meant to be used by commands that would modify the Cache configuration, e.g. create region, create gateway receiver etc. It's only available where these commands are executed. After this, we might expose another set of java API that would be available in other nodes like client or servers. That api would allow developer to create a region as well as modifying the cluster configuration at the same time. 

Resources

• JAXB generated CacheConfig class: CacheConfig.java
• An example of an extension's CacheElement: ConnectorService.java