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 void	moveExtraProperties(String oldNodeId, String newNodeId) Moves a set of extra properties from an old to a new node after their IDs have changed.
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

moveExtraProperties

protected void moveExtraProperties(String oldNodeId,
                       String newNodeId)

Moves a set of extra properties from an old to a new node after their IDs have changed.

Parameters:

oldNodeId - the old identifier for the node; may not be null

newNodeId - the new identifier for the node; 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