org.modeshape.jcr.spi.federation

## Class Connector

- java.lang.Object
- - org.modeshape.jcr.spi.federation.Connector

- Direct Known Subclasses:
    ReadOnlyConnector, WritableConnector

      public abstract class Connector
      extends Object

  SPI of a generic external connector, representing the interface to an external system integrated with ModeShape. Since it is expected that the documents are well formed (structure-wise), the `FederatedDocumentWriter` class should be used. This is the base class for `WritableConnector` and `ReadOnlyConnector` which is what connector implementations are expected to implement.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `Connector.ExtraProperties`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Connector()` Ever connector is expected to have a no-argument constructor, although the class should never initialize any of the data at this time.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `checkFieldNotNull(Object fieldValue, String fieldName)` Utility method that checks whether the field with the supplied name is set.
    `protected Connector.ExtraProperties` | `extraPropertiesFor(String id, boolean update)`
    `protected ExtraPropertiesStore` | `extraPropertiesStore()` Get the "extra" properties store.
    `protected ValueFactories` | `factories()` Get the set of value factory objects that the connector can use to create property value objects.
    `ExternalBinaryValue` | `getBinaryValue(String id)` Returns a binary value which is connector specific and which is never stored by ModeShape.
    `Integer` | `getCacheTtlSeconds()` Returns the default value, for this connector, of the maximum number of seconds an external document should be stored in the workspace cache.
    `Document` | `getChildReference(String parentKey, String childKey)` Returns a document representing a single child reference from the supplied parent to the supplied child.
    `ExecutionContext` | `getContext()` Get the execution context for this connector instance.
    `abstract Document` | `getDocumentById(String id)` Returns a `Document` instance representing the document with a given id.
    `abstract String` | `getDocumentId(String externalPath)` Returns the id of an external node located at the given external path within the connector's exposed tree of content.
    `abstract Collection<String>` | `getDocumentPathsById(String id)` Return the path(s) of the external node with the given identifier.
    `protected Environment` | `getEnvironment()` Returns the repository environment that was set during connector initialization
    `Logger` | `getLogger()` Get the I18n-compatible logger for this connector instance.
    `MimeTypeDetector` | `getMimeTypeDetector()` Get the MIME type detector for this connector instance.
    `String` | `getRepositoryName()` Get the name of the repository.
    `String` | `getSourceName()` Returns the name of the source which this connector interfaces with.
    `protected TransactionManager` | `getTransactionManager()` Returns the transaction manager instance that was set on the connector during initialization.
    `abstract boolean` | `hasDocument(String id)` Checks if a document with the given id exists in the end-source.
    `void` | `initialize(NamespaceRegistry registry, NodeTypeManager nodeTypeManager)` Initialize the connector.
    `Boolean` | `isQueryable()` Indicates if content exposed by this connector should be indexed by the repository or not.
    `abstract boolean` | `isReadonly()` Indicates if the connector instance has been configured in read-only mode.
    `Logger` | `log()` Get the simpler, String-based logger for this connector instance.
    `protected Name` | `nameFrom(String nameString)` Helper method that creates a `Name` object from a string, using no decoding.
    `protected Name` | `nameFrom(String namespaceUri, String localName)` Create a name from the given namespace URI and local name.
    `protected Name` | `nameFrom(String namespaceUri, String localName, TextDecoder decoder)` Create a name from the given namespace URI and local name.
    `protected Document` | `newChildReference(String childId, String childName)` Obtain a new child reference document that is useful in the `getChildReference(String, String)` method.
    `protected ConnectorChangeSet` | `newConnectorChangedSet()`
    `protected DocumentWriter` | `newDocument(String id)` Obtain a new `DocumentWriter` that can be used to construct a document, typically within the `getDocumentById(String)` method.
    `abstract String` | `newDocumentId(String parentId, Name newDocumentName, Name newDocumentPrimaryType)` Generates an identifier which will be assigned when a new document (aka. child) is created under an existing document (aka.parent).
    `protected PageWriter` | `newPageDocument(PageKey pageKey)` Obtain a new `PageWriter` that can be used to construct a page of children, typically within the `Pageable.getChildren(PageKey)` method.
    `protected PathFactory` | `pathFactory()`
    `protected Path` | `pathFrom(Path parentPath, String childPath)` Helper method that creates a `Path` object from a parent path and a child path string.
    `protected Path` | `pathFrom(String path)` Helper method that creates a `Path` object from a string.
    `protected PropertyFactory` | `propertyFactory()`
    `protected DocumentReader` | `readDocument(Document document)` Obtain a new `DocumentReader` that can be used to read an existing document, typically used within the `storeDocument(Document)` and `updateDocument(DocumentChanges)` methods.
    `abstract boolean` | `removeDocument(String id)` Removes the document with the given id.
    `protected void` | `setExtraPropertiesStore(ExtraPropertiesStore customExtraPropertiesStore)` Method that can be called by a connector during `initialization` if it wants to provide its own implementation of an "extra" properties store.
    `void` | `shutdown()` Shutdown the connector by releasing all resources.
    `abstract void` | `storeDocument(Document document)` Stores the given document.
    `protected DocumentTranslator` | `translator()`
    `abstract void` | `updateDocument(DocumentChanges documentChanges)` Updates a document using the provided changes.
    `protected DocumentWriter` | `writeDocument(Document document)` Obtain a new `DocumentWriter` that can be used to update a document.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Connector

          public Connector()

      Ever connector is expected to have a no-argument constructor, although the class should never initialize any of the data at this time. Instead, all initialization should be performed in the `initialize(javax.jcr.NamespaceRegistry, org.modeshape.jcr.api.nodetype.NodeTypeManager)` method.

  - ### Method Detail

    - #### getSourceName

          public String getSourceName()

      Returns the name of the source which this connector interfaces with.
      Returns:
        a `non-null` string.

    - #### getRepositoryName

          public final String getRepositoryName()

      Get the name of the repository.
      Returns:
        the repository name; never null

    - #### getLogger

          public final Logger getLogger()

      Get the I18n-compatible logger for this connector instance. This is available for use in or after the `initialize(NamespaceRegistry, NodeTypeManager)` method.

      This logger is a bit more complicated than the `simple logger` because it requires use of ModeShape's internationalization and localization framework. All of ModeShape's code uses this I18n framework, making it much easier to localize ModeShape to other languages. Using this logger would make it just as easy to localize the Connector implementation. But since it is more complicated, it may not be for every developer. Subclasses can use this logger or the simpler logger; you can even mix and match (though we'd recommend that you just pick one and only use it).

      Returns:
        the logger that requires using ModeShape I18n framework; never null
      See Also:
        `log()`

    - #### log

          public final Logger log()

      Get the simpler, String-based logger for this connector instance. This is available for use in or after the `initialize(NamespaceRegistry, NodeTypeManager)` method.

      This logger is much simpler than the `I18n-compatible logger`, especially since all of the log messages take simple strings. However, this simple logger is not easily internationalized. Subclasses can use this logger or the more formal, I18n-compatible logger; you can even mix and match (though we'd recommend that you just pick one and only use it).

      Returns:
        the simple logger that requires String messages; never null
      See Also:
        `getLogger()`

    - #### getContext

          public ExecutionContext getContext()

      Get the execution context for this connector instance. This is available for use in or after the `initialize(NamespaceRegistry, NodeTypeManager)` method.
      Returns:
        the context; never null

    - #### getMimeTypeDetector

          public MimeTypeDetector getMimeTypeDetector()

      Get the MIME type detector for this connector instance. This is available for use in or after the `initialize(NamespaceRegistry, NodeTypeManager)` method.
      Returns:
        the MIME type detector; never null

    - #### getCacheTtlSeconds

          public Integer getCacheTtlSeconds()

      Returns the default value, for this connector, of the maximum number of seconds an external document should be stored in the workspace cache.
      Returns:
        an `Integer` value. If `null`, it means that no special value is configured and the default workspace cache configuration will be used. If negative, it means an entry will be cached forever.

    - #### isQueryable

          public Boolean isQueryable()

      Indicates if content exposed by this connector should be indexed by the repository or not.
      Returns:
        `true` if the content should be indexed, `false` otherwise.

    - #### extraPropertiesFor

          protected Connector.ExtraProperties extraPropertiesFor(String id,
                                                     boolean update)

    - #### extraPropertiesStore

          protected ExtraPropertiesStore extraPropertiesStore()

      Get the "extra" properties store. Connectors can directly use this, although it's probably easier to `create` an `Connector.ExtraProperties` object for each node and use it to `add`, `remove` and then `store or update` the extra properties in the extra properties store.
      Returns:
        the storage for extra properties; never null

    - #### setExtraPropertiesStore

          protected void setExtraPropertiesStore(ExtraPropertiesStore customExtraPropertiesStore)

      Method that can be called by a connector during `initialization` if it wants to provide its own implementation of an "extra" properties store.
      Parameters:
        `customExtraPropertiesStore` - the custom implementation of the ExtraPropertiesStore; may not be null

    - #### getTransactionManager

          protected TransactionManager getTransactionManager()

      Returns the transaction manager instance that was set on the connector during initialization.
      Returns:
        a `non-null` `TransactionManager` instance

    - #### getEnvironment

          protected Environment getEnvironment()

      Returns the repository environment that was set during connector initialization
      Returns:
        a `non-null` `Environment` instace.

    - #### initialize

          public void initialize(NamespaceRegistry registry,
                        NodeTypeManager nodeTypeManager)
                          throws RepositoryException,
                                 IOException

      Initialize the connector. This is called automatically by ModeShape once for each Connector instance, and should not be called by the connector. By the time this method is called, ModeShape will hav already set the `context`, `logger`, `name`, and `repositoryName` plus any fields that match configuration properties for the connector.

      By default this method does nothing, so it should be overridden by implementations to do a one-time initialization of any internal components. For example, connectors can use the supplied `registry` and `nodeTypeManager` objects to register custom namesapces and node types required by the external content.

      This is an excellent place for connector to validate the connector-specific fields set by ModeShape via reflection during instantiation.

      Parameters:
        `registry` - the namespace registry that can be used to register custom namespaces; never null
        `nodeTypeManager` - the node type manager that can be used to register custom node types; never null
      Throws:
        `RepositoryException` - if operations on the `NamespaceRegistry` or `NodeTypeManager` fail
        `IOException` - if any stream based operations fail (like importing cnd files)

    - #### shutdown

          public void shutdown()

      Shutdown the connector by releasing all resources. This is called automatically by ModeShape when this Connector instance is no longer needed, and should never be called by the connector.

    - #### getDocumentById

          public abstract Document getDocumentById(String id)

      Returns a `Document` instance representing the document with a given id. The document should have a "proper" structure for it to be usable by ModeShape.
      Parameters:
        `id` - a `non-null` string
      Returns:
        either an `Document` instance or `null`

    - #### getDocumentId

          public abstract String getDocumentId(String externalPath)

      Returns the id of an external node located at the given external path within the connector's exposed tree of content.
      Parameters:
        `externalPath` - a `non-null` string representing an external path, or "/" for the top-level node exposed by the connector
      Returns:
        either the id of the document or `null`

    - #### getDocumentPathsById

          public abstract Collection<String> getDocumentPathsById(String id)

      Return the path(s) of the external node with the given identifier. The resulting paths are from the point of view of the connector. For example, the "root" node exposed by the connector wil have a path of "/".
      Parameters:
        `id` - a `non-null` string
      Returns:
        the connector-specific path(s) of the node, or an empty document if there is no such document; never null

    - #### isReadonly

          public abstract boolean isReadonly()

      Indicates if the connector instance has been configured in read-only mode.
      Returns:
        `true` if the connector has been configured in read-only mode, false otherwise.

    - #### getChildReference

          public Document getChildReference(String parentKey,
                                   String childKey)

      Returns a document representing a single child reference from the supplied parent to the supplied child. This method is called when there are an unknown number of children on a node.

      This method should be implemented and will be called if and only if a `connector uses paging` and specifies an `unknown number of children` in the `PageWriter.addPage(String, int, long, long)` or `PageWriter.addPage(String, String, long, long)` methods.

      Parameters:
        `parentKey` - the key for the parent
        `childKey` - the key for the child
      Returns:
        the document representation of a child reference, of null if the parent does not contain a child with the given key

    - #### getBinaryValue

          public ExternalBinaryValue getBinaryValue(String id)

      Returns a binary value which is connector specific and which is never stored by ModeShape. Connectors who need this feature must return an object that is an instance of a subclasses of `ExternalBinaryValue`, either `UrlBinaryValue` or a custom subclass with connector-specific information.

      Normally, the `getDocumentById(String)` method implementation will set binary values on properties of nodes, which should create the same ExternalBinaryValue subclass that is returned by this method. The `ExternalBinaryValue.getId()` value from that instance will be passed into this method.

      Parameters:
        `id` - a `String` representing the identifier of the external binary which should have connector-specific meaning. This identifier need not be the SHA-1 hash of the content.
      Returns:
        either a binary value implementation or `null` if there is no such value with the given id.

    - #### removeDocument

          public abstract boolean removeDocument(String id)

      Removes the document with the given id.
      Parameters:
        `id` - a `non-null` string.
      Returns:
        true if the document was removed, or false if there was no document with the given id

    - #### hasDocument

          public abstract boolean hasDocument(String id)

      Checks if a document with the given id exists in the end-source.
      Parameters:
        `id` - a `non-null` string.
      Returns:
        `true` if such a document exists, `false` otherwise.

    - #### storeDocument

          public abstract void storeDocument(Document document)

      Stores the given document.
      Parameters:
        `document` - a `non-null` `Document` instance.
      Throws:
        `DocumentAlreadyExistsException` - if there is already a new document with the same identifier
        `DocumentNotFoundException` - if one of the modified documents was removed by another session

    - #### updateDocument

          public abstract void updateDocument(DocumentChanges documentChanges)

      Updates a document using the provided changes.
      Parameters:
        `documentChanges` - a `non-null` `DocumentChanges` object which contains granular information about all the changes.

    - #### newDocumentId

          public abstract String newDocumentId(String parentId,
                             Name newDocumentName,
                             Name newDocumentPrimaryType)

      Generates an identifier which will be assigned when a new document (aka. child) is created under an existing document (aka.parent). This method should be implemented only by connectors which support writing.
      Parameters:
        `parentId` - a `non-null` `String` which represents the identifier of the parent under which the new document will be created.
        `newDocumentName` - a `non-null` `Name` which represents the name that will be given to the child document
        `newDocumentPrimaryType` - a `non-null` `Name` which represents the child document's primary type.
      Returns:
        either a `non-null` `String` which will be assigned as the new identifier, or `null` which means that no "special" id format is required. In this last case, the repository will auto-generate a random id.
      Throws:
        `DocumentStoreException` - if the connector is readonly.

    - #### checkFieldNotNull

          protected void checkFieldNotNull(Object fieldValue,
                               String fieldName)
                                    throws RepositoryException

      Utility method that checks whether the field with the supplied name is set.
      Parameters:
        `fieldValue` - the value of the field
        `fieldName` - the name of the field
      Throws:
        `RepositoryException` - if the field value is null

    - #### translator

          protected DocumentTranslator translator()

    - #### readDocument

          protected DocumentReader readDocument(Document document)

      Obtain a new `DocumentReader` that can be used to read an existing document, typically used within the `storeDocument(Document)` and `updateDocument(DocumentChanges)` methods.
      Parameters:
        `document` - the document that should be read; may not be null
      Returns:
        the document reader; never null

    - #### newDocument

          protected DocumentWriter newDocument(String id)

      Obtain a new `DocumentWriter` that can be used to construct a document, typically within the `getDocumentById(String)` method.
      Parameters:
        `id` - the identifier of the document; may not be null
      Returns:
        the document writer; never null

    - #### writeDocument

          protected DocumentWriter writeDocument(Document document)

      Obtain a new `DocumentWriter` that can be used to update a document.
      Parameters:
        `document` - the document that should be updated; may not be null
      Returns:
        the document writer; never null

    - #### newPageDocument

          protected PageWriter newPageDocument(PageKey pageKey)

      Obtain a new `PageWriter` that can be used to construct a page of children, typically within the `Pageable.getChildren(PageKey)` method.
      Parameters:
        `pageKey` - the key for the page; may not be null
      Returns:
        the page writer; never null

    - #### newChildReference

          protected Document newChildReference(String childId,
                                   String childName)

      Obtain a new child reference document that is useful in the `getChildReference(String, String)` method.
      Parameters:
        `childId` - the ID of the child node; may not be null
        `childName` - the name of the child node; may not be null
      Returns:
        the child reference document; never null

    - #### factories

          protected final ValueFactories factories()

      Get the set of value factory objects that the connector can use to create property value objects.
      Returns:
        the collection of factories; never null

    - #### propertyFactory

          protected final PropertyFactory propertyFactory()

    - #### pathFactory

          protected final PathFactory pathFactory()

    - #### pathFrom

          protected final Path pathFrom(String path)

      Helper method that creates a `Path` object from a string. This is equivalent to calling " `pathFactory().create(path)`", and is simply provided for convenience.
      Parameters:
        `path` - the string from which the path is to be created
      Returns:
        the value, or null if the supplied string is null
      Throws:
        `ValueFormatException` - if the conversion from a string could not be performed
      See Also:
        `ValueFactory.create(String)`, `pathFrom(Path, String)`

    - #### pathFrom

          protected final Path pathFrom(Path parentPath,
                      String childPath)

      Helper method that creates a `Path` object from a parent path and a child path string. This is equivalent to calling " `pathFactory().create(parentPath,childPath)`", and is simply provided for convenience.
      Parameters:
        `parentPath` - the parent path
        `childPath` - the child path as a string
      Returns:
        the value, or null if the supplied string is null
      Throws:
        `ValueFormatException` - if the conversion from a string could not be performed
      See Also:
        `ValueFactory.create(String)`, `pathFrom(String)`

    - #### nameFrom

          protected final Name nameFrom(String nameString)

      Helper method that creates a `Name` object from a string, using no decoding. This is equivalent to calling " `factories().getNameFactory().create(nameString)`", and is simply provided for convenience.
      Parameters:
        `nameString` - the string from which the name is to be created
      Returns:
        the value, or null if the supplied string is null
      Throws:
        `ValueFormatException` - if the conversion from a string could not be performed
      See Also:
        `ValueFactory.create(String, TextDecoder)`, `NameFactory.create(String, String, TextDecoder)`, `NameFactory.create(String, String)`, `nameFrom(String, String)`, `nameFrom(String, String, TextDecoder)`

    - #### nameFrom

          protected final Name nameFrom(String namespaceUri,
                      String localName)

      Create a name from the given namespace URI and local name. This is equivalent to calling " `factories().getNameFactory().create(namespaceUri,localName)`", and is simply provided for convenience.
      Parameters:
        `namespaceUri` - the namespace URI
        `localName` - the local name
      Returns:
        the new name
      Throws:
        `IllegalArgumentException` - if the local name is `null` or empty
      See Also:
        `ValueFactory.create(String, TextDecoder)`, `NameFactory.create(String, String, TextDecoder)`, `NameFactory.create(String, String)`, `nameFrom(String)`, `nameFrom(String, String, TextDecoder)`

    - #### nameFrom

          protected final Name nameFrom(String namespaceUri,
                      String localName,
                      TextDecoder decoder)

      Create a name from the given namespace URI and local name. This is equivalent to calling " `factories().getNameFactory().create(namespaceUri,localName,decoder)`", and is simply provided for convenience.
      Parameters:
        `namespaceUri` - the namespace URI
        `localName` - the local name
        `decoder` - the decoder that should be used to decode the qualified name
      Returns:
        the new name
      Throws:
        `IllegalArgumentException` - if the local name is `null` or empty
      See Also:
        `NameFactory.create(String, String, TextDecoder)`, `ValueFactory.create(String, TextDecoder)`, `NameFactory.create(String, String, TextDecoder)`, `NameFactory.create(String, String)`, `nameFrom(String)`, `nameFrom(String, String)`

    - #### newConnectorChangedSet

          protected ConnectorChangeSet newConnectorChangedSet()

      Returns:
        a fresh `ConnectorChangeSet` for use in recording changes

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