# Package org.modeshape.jcr.federation.spi

This package provides a Service Provider Interface (SPI) for connectors to external systems.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  ConnectorChangeSet | This interface represents an atomic set of changes that have occurred to resources in the remit of a `Connector`.
  DocumentChanges | Interface which encapsulates the changes that occurred on a document during an update process.
  DocumentChanges.ChildrenChanges | Interface which encapsulates the changes to a document's children during an update operation.
  DocumentChanges.MixinChanges | Interface which encapsulates the changes to a document's mixins during an update operation.
  DocumentChanges.ParentChanges | Interface which encapsulates the changes to a document's parents during an update operation.
  DocumentChanges.PropertyChanges | Interface which encapsulates the changes to a document's properties during an update operation.
  DocumentChanges.ReferrerChanges | Interface which encapsulates the changes to a document's referrers during an update operation.
  DocumentReader | A reader which can be used read the structure of `Document` instances and expose the underlying information.
  DocumentWriter | A writer which can create and manipulate the structure of `EditableDocument` instances, that should be used by connectors when they want to return the information regarding external nodes.
  ExtraPropertiesStore | Store for extra properties, which a `Connector` implementation can use to store and retrieve "extra" properties on a node that cannot be persisted in the external system.
  Pageable | Interface that should be implemented by `Connector`(s) that want to expose children of nodes in a "page by page" fashion.
  PageWriter | A type of document writer that can add paging information to documents.

- Class Summary
  Class | Description
  --- | ---
  Connector | SPI of a generic external connector, representing the interface to an external system integrated with ModeShape.
  PageKey | The key used to uniquely identify a page of children.
  ReadOnlyConnector | A specialized abstract `Connector` class that is readable and can never update content.
  WritableConnector | A specialized abstract `Connector` class that is support both reads and writes.

- Exception Summary
  Exception | Description
  --- | ---
  ConnectorException | Exception class that can be thrown either by `Connector` implementations or in other exceptional cases involving federation operations.

## Package org.modeshape.jcr.federation.spi Description

This package provides a Service Provider Interface (SPI) for connectors to external systems. The ModeShape federation system uses these `Connector` implementations to enable a repository to access external systems and project the external information as structured nodes within the repository. External sources are configured in the `repository configuration JSON file` to use a specific `Connector` implementation (including connector-specific configuration properties), while the projections that define how and where the external content is bound into the repository content are created using the `FederationManager`:

     javax.jcr.Session jcrSession = ...
     Session session = (org.modeshape.jcr.api.Session)jcrSession;
     FederationManager fedMgr = session.getWorkspace().getFederationManager();

     javax.jcr.Node parentNode = ... // the parent of the federated content
     String parentPath = parentNode.getPath();
     String sourceName = ... // the name of the external source
     String externalPath = ... // the path of the node in the external source that is to appear as a child of 'parentNode'
     String alias = ... // Optional alias for the external node
     fedMgr.createExternalProjection(parentPath, sourceName, externalPath, alias);

To create a custom connector, simply create a `Connector` subclass and implement the necessary methods. If your connector is only to read information and never will update any external content, you can instead subclass the `ReadOnlyConnector` class, which implements the methods used to create/update/delete content by throwing the proper exception.

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