public abstract class Connector extends Object
FederatedDocumentWriter
class should be used. This is
the base class for WritableConnector
and ReadOnlyConnector
which is what connector implementations are expected
to implement.Modifier and Type | Class and Description |
---|---|
class |
Connector.ExtraProperties |
Modifier and Type | Field and Description |
---|---|
protected static String |
DEFAULT_ROOT_ID |
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.
|
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.
|
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 |
getRootDocumentId()
Returns the connector-specific ID for the root document.
|
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 |
isCacheable()
Returns whether documents exposed by this connector should be cached by the repository or not.
|
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. |
protected static final String DEFAULT_ROOT_ID
public Connector()
initialize(javax.jcr.NamespaceRegistry, org.modeshape.jcr.api.nodetype.NodeTypeManager)
method.public String getSourceName()
non-null
string.public final String getRepositoryName()
public final Logger getLogger()
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).
log()
public final Logger log()
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).
getLogger()
public ExecutionContext getContext()
initialize(NamespaceRegistry, NodeTypeManager)
method.public MimeTypeDetector getMimeTypeDetector()
initialize(NamespaceRegistry, NodeTypeManager)
method.public boolean isCacheable()
true
if documents should be cached, false
otherwise.public Boolean isQueryable()
true
if the content should be indexed, false
otherwise.protected Connector.ExtraProperties extraPropertiesFor(String id, boolean update)
protected ExtraPropertiesStore extraPropertiesStore()
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.protected void setExtraPropertiesStore(ExtraPropertiesStore customExtraPropertiesStore)
initialization
if
it wants to provide its own implementation of an "extra" properties store.customExtraPropertiesStore
- the custom implementation of the ExtraPropertiesStore; may not be nullprotected void moveExtraProperties(String oldNodeId, String newNodeId)
oldNodeId
- the old identifier for the node; may not be nullnewNodeId
- the new identifier for the node; may not be nullprotected TransactionManager getTransactionManager()
non-null
TransactionManager
instanceprotected Environment getEnvironment()
non-null
Environment
instace.public String getRootDocumentId()
String
representing the ID of the root document.getDocumentById(String)
public void initialize(NamespaceRegistry registry, NodeTypeManager nodeTypeManager) throws RepositoryException, IOException
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.
registry
- the namespace registry that can be used to register custom namespaces; never nullnodeTypeManager
- the node type manager that can be used to register custom node types; never nullRepositoryException
- if operations on the NamespaceRegistry
or NodeTypeManager
failIOException
- if any stream based operations fail (like importing cnd files)public void shutdown()
public abstract Document getDocumentById(String id)
Document
instance representing the document with a given id. The document should have a "proper"
structure for it to be usable by ModeShape.id
- a non-null
stringDocument
instance or null
public abstract String getDocumentId(String externalPath)
externalPath
- a non-null
string representing an external path, or "/" for the top-level node exposed by the
connectornull
public abstract Collection<String> getDocumentPathsById(String id)
id
- a non-null
stringpublic abstract boolean isReadonly()
true
if the connector has been configured in read-only mode, false otherwise.public Document getChildReference(String parentKey, String childKey)
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.
parentKey
- the key for the parentchildKey
- the key for the childpublic ExternalBinaryValue getBinaryValue(String id)
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.
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.null
if there is no such value with the given id.public abstract boolean removeDocument(String id)
id
- a non-null
string.public abstract boolean hasDocument(String id)
id
- a non-null
string.true
if such a document exists, false
otherwise.public abstract void storeDocument(Document document)
document
- a non-null
Document
instance.DocumentAlreadyExistsException
- if there is already a new document with the same identifierDocumentNotFoundException
- if one of the modified documents was removed by another sessionpublic abstract void updateDocument(DocumentChanges documentChanges)
documentChanges
- a non-null
DocumentChanges
object which contains granular information about all the
changes.public abstract String newDocumentId(String parentId, Name newDocumentName, Name newDocumentPrimaryType)
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 documentnewDocumentPrimaryType
- a non-null
Name
which represents the child document's
primary type.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.DocumentStoreException
- if the connector is readonly.protected void checkFieldNotNull(Object fieldValue, String fieldName) throws RepositoryException
fieldValue
- the value of the fieldfieldName
- the name of the fieldRepositoryException
- if the field value is nullprotected DocumentTranslator translator()
protected DocumentReader readDocument(Document document)
DocumentReader
that can be used to read an existing document, typically used within the
storeDocument(Document)
and updateDocument(DocumentChanges)
methods.document
- the document that should be read; may not be nullprotected DocumentWriter newDocument(String id)
DocumentWriter
that can be used to construct a document, typically within the
getDocumentById(String)
method.id
- the identifier of the document; may not be nullprotected DocumentWriter writeDocument(Document document)
DocumentWriter
that can be used to update a document.document
- the document that should be updated; may not be nullprotected PageWriter newPageDocument(PageKey pageKey)
PageWriter
that can be used to construct a page of children, typically within the
Pageable.getChildren(PageKey)
method.pageKey
- the key for the page; may not be nullprotected Document newChildReference(String childId, String childName)
getChildReference(String, String)
method.childId
- the ID of the child node; may not be nullchildName
- the name of the child node; may not be nullprotected final ValueFactories factories()
protected final PropertyFactory propertyFactory()
protected final PathFactory pathFactory()
protected final Path pathFrom(String path)
Path
object from a string. This is equivalent to calling "
pathFactory().create(path)
", and is simply provided for convenience.path
- the string from which the path is to be createdValueFormatException
- if the conversion from a string could not be performedValueFactory.create(String)
,
pathFrom(Path, String)
protected final Path pathFrom(Path parentPath, String childPath)
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.parentPath
- the parent pathchildPath
- the child path as a stringValueFormatException
- if the conversion from a string could not be performedValueFactory.create(String)
,
pathFrom(String)
protected final Name nameFrom(String nameString)
Name
object from a string, using no decoding. This is equivalent to calling "
factories().getNameFactory().create(nameString)
", and is simply provided for convenience.nameString
- the string from which the name is to be createdValueFormatException
- if the conversion from a string could not be performedValueFactory.create(String, TextDecoder)
,
NameFactory.create(String, String, TextDecoder)
,
NameFactory.create(String, String)
,
nameFrom(String, String)
,
nameFrom(String, String, TextDecoder)
protected final Name nameFrom(String namespaceUri, String localName)
factories().getNameFactory().create(namespaceUri,localName)
", and is simply provided for convenience.namespaceUri
- the namespace URIlocalName
- the local nameIllegalArgumentException
- if the local name is null
or emptyValueFactory.create(String, TextDecoder)
,
NameFactory.create(String, String, TextDecoder)
,
NameFactory.create(String, String)
,
nameFrom(String)
,
nameFrom(String, String, TextDecoder)
protected final Name nameFrom(String namespaceUri, String localName, TextDecoder decoder)
factories().getNameFactory().create(namespaceUri,localName,decoder)
", and is simply provided for convenience.namespaceUri
- the namespace URIlocalName
- the local namedecoder
- the decoder that should be used to decode the qualified nameIllegalArgumentException
- if the local name is null
or emptyNameFactory.create(String, String, TextDecoder)
,
ValueFactory.create(String, TextDecoder)
,
NameFactory.create(String, String, TextDecoder)
,
NameFactory.create(String, String)
,
nameFrom(String)
,
nameFrom(String, String)
protected ConnectorChangeSet newConnectorChangedSet()
ConnectorChangeSet
for use in recording changesCopyright © 2008–2016 JBoss, a division of Red Hat. All rights reserved.