Enabling Your Plugin For Replication

The core replication engine is capable of replicating documents, assets, and images under /content, and of replicating HST configuration. If you have a plugin that defines its own content model you may need to extend the replication engine. An example of an addon that does this is the Relevance Module.

Such a plugin must a) implement a component that tells replication about its model's units of replication, i.e. which nodes should be replicated atomically, and b) configure an additional content root if needed.

You may optionally implement the PropertyFilter interface to filter out properties that should not be replicated.

ReplicationScopeProvider

To let the replication engine know about your plugin's content model you implement a ReplicationScopeProvider.

/**
 * Extension point that allows the replication engine to know how to deal with the content model of
 * a given sub system.
 */
public interface ReplicationScopeProvider {

    /**
     * Maps the given {@code node} to a {@link ReplicationScope}. This lets the engine
     * know whether to treat the node as the root of a unit of replication (ReplicationScope.REPLICABLE),
     * to include it within the scope of the an ancestor unit of replication (ReplicationScope.NONE),
     * to exclude it from replication (ReplicationScope.EXCLUDED), or to ignore it (ReplicationScope.IGNORED).
     * <p>
     * This method should return {@code null} if this provider does not know about the node in question, in
     * order that another provider may be consulted.
     */
    ReplicationScope getReplicationScope(Node node) throws RepositoryException;

    /**
     * Whether the {@code event} in question could have had the effect that the node associated with
     * this event changed {@link ReplicationScope}.
     * For instance, a published variant has ReplicationScope.REPLICABLE when it is live, otherwise
     * it is ReplicationScope.EXCLUDED.
     * <p>
     * This method should return {@code null} if this provider does not know about the event in question, in
     * order that another provider may be consulted.
     */
    Boolean isReplicationScopeChangeEvent(final Event event, final Session session) throws RepositoryException;


}

When changes are processed on the source repository, the changed nodes are mapped to a unit of replication. This is done with the help of ReplicationScopeProviders. A node may be not be replicable at all, may be the root of a unit of replication, or may be a descendant of such a root. When an event is processed, the change log monitor checks with these providers to see if the node involved in the event should be replicated, and if so, which unit of replication is involved. When the time comes for the replication package to be created and sent to the target, the xml serializer needs to know which nodes to include and which nodes to exclude. For that task it also uses the ReplicationScopeProviders. Your component may additionally implement a PropertyFilter to prevent certain properties from being replicated.

Registering the provider

The provider must be registered with the replication engine. This is done by adding a node of type hipposys:moduleconfig with a property className containing the fully qualified classname as a child of /hippo:configuration/hippo:modules/replication/hippo:moduleconfig/metadata.

example_content_replication_provider.yaml

definitions:
  config:
    /hippo:configuration/hippo:modules/replication/hippo:moduleconfig/metadata/examplecontent:
      jcr:primaryType: hipposys:moduleconfig
      className: com.example.replication.ExampleReplicationScopeProvider

Configure the replication root

For a certain node to be included, it not only needs to be mapped by a ReplicationScopeProvider, but its path must also be configured as mentioned on the replication configuration page. For instance, for the Relevance Module, the path /targeting:targeting must be added to the includedpaths property of the /hippo:configuration/hippo:modules/replication/hippo:moduleconfig/metadata. To add such a value to that property, use the add operation in a YAML definition:

definitions:
  config:
    /hippo:configuration/hippo:modules/replication/hippo:moduleconfig/metadata:
      includedpaths:
        operation: add
        type: string
        value: [/example]