org.modeshape.jcr.federation.spi

## Interface ConnectorChangeSet

- All Known Implementing Classes:
    ConnectorChangeSetImpl

      @NotThreadSafe
      public interface ConnectorChangeSet

  This interface represents an atomic set of changes that have occurred to resources in the remit of a `Connector`.

  Note that ModeShape will correctly generate events for all changes to the external system initiated by ModeShape, and therefore the connector should not record any such changes. However, if the external system undergoes changes due to non-ModeShape activities, such changes can/should be captured by the connector so that ModeShape and its clients are notified of these changes. Therefore, the recording of changes will likely be through an asynchronous activity.

  When an external system undergoes some independent changes, the connector can `obtain` a new change set, call methods on the change set to record events of interest in the property order, and then `publish(Map)` all of the changes that have been recorded. Only when a change set is `published` will the repository be notified of the recorded changes and forward them to its appropriate listeners.

  Connectors may expose a single document at multiple paths. In such cases the Connector will likely generate events for only one of those paths (i.e., the "primary" path, whatever the Connector chooses to use). However, Connectors may choose to generate mutliple events for single resources available at multiple paths.

  It is safe to only call methods on a `ConnectorChangeSet` instance from a single thread. If a connector uses multiple threads to record changes, the connector should either use separate ConnectorChangeSet instances for each thread or (if the changes from multiple threads are to be recorded as a single atomic set) ensure that it calls the methods in a synchronized fashion.

  See Also:
    `Connector.newConnectorChangedSet()`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `nodeCreated(String docId, String parentDocId, String path, Map<Name,Property> properties)` Signal that a new node resource was created.
    `void` | `nodeMoved(String docId, String newParentDocId, String oldParentDocId, String newPath, String oldPath)` Signal that a node resource (and all descendants) was moved from one parent to another.
    `void` | `nodeRemoved(String docId, String parentDocId, String path)` Signal that a node resource (and all descendants) was removed.
    `void` | `nodeReordered(String docId, String parentDocId, String newPath, String oldNameSegment, String reorderedBeforeNameSegment)` Signal that a node resource (and all descendants) was placed into a new location within the same parent.
    `void` | `propertyAdded(String docId, String nodePath, Property property)` Signal that a property was added to a node resource.
    `void` | `propertyChanged(String docId, String nodePath, Property newProperty, Property oldProperty)` Signal that a property resource was changed on a node resource.
    `void` | `propertyRemoved(String docId, String nodePath, Property property)` Signal that a property was removed from a node resource.
    `void` | `publish(Map<String,String> data)` Finish the construction of this change-set and make it available for publication into the repository.

- - ### Method Detail

    - #### nodeCreated

          void nodeCreated(String docId,
                         String parentDocId,
                         String path,
                         Map<Name,Property> properties)

      Signal that a new node resource was created.
      Parameters:
        `docId` - the connector's identifier for the new node; may not be null
        `parentDocId` - the connector's identifier for the parent of the new node; may not be null
        `path` - the path to the new node; may not be null
        `properties` - the properties in the new node, or null if there are none

    - #### nodeRemoved

          void nodeRemoved(String docId,
                         String parentDocId,
                         String path)

      Signal that a node resource (and all descendants) was removed. Note that it is not common to fire an event for all nodes below a node that is also deleted within the same change set.
      Parameters:
        `docId` - the connector's identifier for the removed node; may not be null
        `parentDocId` - the connector's identifier for the parent of the removed node; may not be null
        `path` - the path to the removed node; may not be null

    - #### nodeMoved

          void nodeMoved(String docId,
                       String newParentDocId,
                       String oldParentDocId,
                       String newPath,
                       String oldPath)

      Signal that a node resource (and all descendants) was moved from one parent to another.
      Parameters:
        `docId` - the connector's identifier for the node; may not be null
        `newParentDocId` - the connector's identifier for the new parent of the node; may not be null
        `oldParentDocId` - the connector's identifier for the old parent for the node; may not be null
        `newPath` - the new path for the node after it has been moved; may not be null
        `oldPath` - the old path for the node before it was moved; may not be null

    - #### nodeReordered

          void nodeReordered(String docId,
                           String parentDocId,
                           String newPath,
                           String oldNameSegment,
                           String reorderedBeforeNameSegment)

      Signal that a node resource (and all descendants) was placed into a new location within the same parent.
      Parameters:
        `docId` - the connector's identifier for the node; may not be null
        `parentDocId` - the connector's identifier for the parent of the node; may not be null
        `newPath` - the new path for the node after it has been reordered; may not be null
        `oldNameSegment` - the name segment (i.e., the name and if applicable the SNS index) for the node before it was reordered; may not be null
        `reorderedBeforeNameSegment` - the name segment of the node (in the same parent) before which the node was moved; or null if the node was reordered to the end of the list of children of the parent node

    - #### propertyAdded

          void propertyAdded(String docId,
                           String nodePath,
                           Property property)

      Signal that a property was added to a node resource.
      Parameters:
        `docId` - the connector's identifier for the node; may not be null
        `nodePath` - the path of the node that was changed
        `property` - the new property, with name and value(s); may not be null

    - #### propertyRemoved

          void propertyRemoved(String docId,
                             String nodePath,
                             Property property)

      Signal that a property was removed from a node resource.
      Parameters:
        `docId` - the connector's identifier for the node; may not be null
        `nodePath` - the path of the node that was changed
        `property` - the property that was removed, with name and value(s); may not be null

    - #### propertyChanged

          void propertyChanged(String docId,
                             String nodePath,
                             Property newProperty,
                             Property oldProperty)

      Signal that a property resource was changed on a node resource.
      Parameters:
        `docId` - the connector's identifier for the node; may not be null
        `nodePath` - the path of the node that was changed
        `newProperty` - the new property, with name and value(s); may not be null
        `oldProperty` - the old property, with name and value(s); may not be null

    - #### publish

          void publish(Map<String,String> data)

      Finish the construction of this change-set and make it available for publication into the repository. This also empties the record of change events and prepares to accept a new record.

      Once a change set has been published, it may not be used again.

      Parameters:
        `data` - the name-value pairs that may be associated with the set of changes; may be null or empty

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.