org.modeshape.connector.filesystem

Class FileSystemConnector

java.lang.Object

org.modeshape.jcr.federation.spi.Connector

org.modeshape.jcr.federation.spi.WritableConnector

org.modeshape.connector.filesystem.FileSystemConnector

All Implemented Interfaces:

Pageable

Direct Known Subclasses:

LargeFileSystemConnector

public class FileSystemConnector
extends WritableConnector
implements Pageable

Connector implementation that exposes a single directory on the local file system. This connector has several properties that must be configured via the RepositoryConfiguration:

• directoryPath - The path to the file or folder that is to be accessed by this connector.
• readOnly - A boolean flag that specifies whether this source can create/modify/remove files and directories on the file system to reflect changes in the JCR content. By default, sources are not read-only.
• addMimeTypeMixin - A boolean flag that specifies whether this connector should add the 'mix:mimeType' mixin to the 'nt:resource' nodes to include the 'jcr:mimeType' property. If set to true, the MIME type is computed immediately when the 'nt:resource' node is accessed, which might be expensive for larger files. This is false by default.
• extraPropertyStorage - An optional string flag that specifies how this source handles "extra" properties that are not stored via file system attributes. See extraPropertiesStorage for details. By default, extra properties are stored in the same Infinispan cache that the repository uses.
• exclusionPattern - Optional property that specifies a regular expression that is used to determine which files and folders in the underlying file system are not exposed through this connector. Files and folders with a name that matches the provided regular expression will not be exposed by this source.
• inclusionPattern - Optional property that specifies a regular expression that is used to determine which files and folders in the underlying file system are exposed through this connector. Files and folders with a name that matches the provided regular expression will be exposed by this source.

Inclusion and exclusion patterns can be used separately or in combination. For example, consider these cases:

Inclusion Pattern	Exclusion Pattern	Examples
(.+)\\.txt$		Includes only files and directories whose names end in ".txt" (e.g., "something.txt" ), but does not include files and other folders such as "something.jar" or "something.txt.zip".
(.+)\\.txt$	my.txt	Includes only files and directories whose names end in ".txt" (e.g., "something.txt" ) with the exception of "my.txt", and does not include files and other folders such as "something.jar" or " something.txt.zip".
my.txt	.+	Excludes all files and directories except any named "my.txt".

Nested Class Summary

Nested classes/interfaces inherited from class org.modeshape.jcr.federation.spi.Connector

Connector.ExtraProperties

Constructor Summary

Constructors

Constructor and Description
FileSystemConnector()

Method Summary

Methods

Modifier and Type	Method and Description
protected ExternalBinaryValue	binaryFor(File file) Utility method for creating a BinaryValue for the given File object.
protected void	checkFileNotExcluded(String id, File file) Utility method to ensure that the file is writable by this connector.
protected boolean	contentBasedSha1()
protected ExternalBinaryValue	createBinaryValue(File file) Utility method to create a BinaryValue object for the given file.
protected File	createFileForUrl(URL url)
protected URL	createUrlForFile(File file) Construct a URL object for the given file, to be used within the Binary value representing the "jcr:data" property of a 'nt:resource' node.
protected File	fileFor(String id) Utility method for obtaining the File object that corresponds to the supplied identifier.
ExternalBinaryValue	getBinaryValue(String id) Returns a binary value which is connector specific and which is never stored by ModeShape.
Document	getChildren(PageKey pageKey) Returns a document which represents the document of a parent node to which an optiona page of children has been added.
Document	getDocumentById(String id) Returns a Document instance representing the document with a given id.
String	getDocumentId(String path) Returns the id of an external node located at the given external path within the connector's exposed tree of content.
Collection<String>	getDocumentPathsById(String id) Return the path(s) of the external node with the given identifier.
boolean	hasDocument(String id) Checks if a document with the given id exists in the end-source.
protected String	idFor(File file) Utility method for determining the node identifier for the supplied file.
void	initialize(NamespaceRegistry registry, NodeTypeManager nodeTypeManager) Initialize the connector.
protected boolean	isContentNode(String id) Utility method for determining if the supplied identifier is for the "jcr:content" child node of a file. * Subclasses may override this method to change the format of the identifiers, but in that case should also override the fileFor(String), isRoot(String), and idFor(File) methods.
protected boolean	isExcluded(File file) Utility method to determine if the file is excluded by the inclusion/exclusion filter.
protected boolean	isRoot(String id) Utility method for determining if the node identifier is the identifier of the root node in this external source.
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).
boolean	removeDocument(String id) Removes the document with the given id.
protected String	sha1(File file) Computes the SHA1 for the given file.
void	storeDocument(Document document) Stores the given document.
void	updateDocument(DocumentChanges documentChanges) Updates a document using the provided changes.

Methods inherited from class org.modeshape.jcr.federation.spi.WritableConnector

isReadonly

Methods inherited from class org.modeshape.jcr.federation.spi.Connector

checkFieldNotNull, extraPropertiesFor, extraPropertiesStore, factories, getCacheTtlSeconds, getChildReference, getContext, getEnvironment, getLogger, getMimeTypeDetector, getRepositoryName, getSourceName, getTransactionManager, isQueryable, log, nameFrom, nameFrom, nameFrom, newChildReference, newConnectorChangedSet, newDocument, newPageDocument, pathFactory, pathFrom, pathFrom, propertyFactory, readDocument, setExtraPropertiesStore, shutdown, translator, writeDocument

Methods inherited from class java.lang.Object

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

Constructor Detail

FileSystemConnector

public FileSystemConnector()

Method Detail

initialize

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

Description copied from class: Connector

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 Connector.context, Connector.logger, Connector.name, and Connector.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.

Overrides:

initialize in class Connector

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)

isContentNode

protected boolean isContentNode(String id)

Utility method for determining if the supplied identifier is for the "jcr:content" child node of a file. * Subclasses may override this method to change the format of the identifiers, but in that case should also override the fileFor(String), isRoot(String), and idFor(File) methods.

Parameters:

id - the identifier; may not be null

Returns:

true if the identifier signals the "jcr:content" child node of a file, or false otherwise

See Also:

isRoot(String), fileFor(String), idFor(File)

fileFor

protected File fileFor(String id)

Utility method for obtaining the File object that corresponds to the supplied identifier. Subclasses may override this method to change the format of the identifiers, but in that case should also override the isRoot(String), isContentNode(String), and idFor(File) methods.

Parameters:

id - the identifier; may not be null

Returns:

the File object for the given identifier

See Also:

isRoot(String), isContentNode(String), idFor(File)

isRoot

protected boolean isRoot(String id)

Utility method for determining if the node identifier is the identifier of the root node in this external source. Subclasses may override this method to change the format of the identifiers, but in that case should also override the fileFor(String), isContentNode(String), and idFor(File) methods.

Parameters:

id - the identifier; may not be null

Returns:

true if the identifier is for the root of this source, or false otherwise

See Also:

isContentNode(String), fileFor(String), idFor(File)

idFor

protected String idFor(File file)

Utility method for determining the node identifier for the supplied file. Subclasses may override this method to change the format of the identifiers, but in that case should also override the fileFor(String), isContentNode(String), and isRoot(String) methods.

Parameters:

file - the file; may not be null

Returns:

the node identifier; never null

See Also:

isRoot(String), isContentNode(String), fileFor(String)

binaryFor

protected ExternalBinaryValue binaryFor(File file)

Utility method for creating a BinaryValue for the given File object. Subclasses should rarely override this method.

Parameters:

file - the file; may not be null

Returns:

the BinaryValue; never null

createBinaryValue

protected ExternalBinaryValue createBinaryValue(File file)
                                         throws IOException

Utility method to create a BinaryValue object for the given file. Subclasses should rarely override this method, since the UrlBinaryValue will be applicable in most situations.

Parameters:

file - the file for which the BinaryValue is to be created; never null

Returns:

the binary value; never null

Throws:

IOException - if there is an error creating the value

sha1

protected String sha1(File file)

Computes the SHA1 for the given file. By default, this method will look at the contentBasedSha1() flag and either take the URL of the file (using @see java.util.File#toURI().toURL() and return the SHA1 of the URL string or return the SHA1 of the entire file content.

Parameters:

file - a File instance; never null

Returns:

the SHA1 of the file.

createUrlForFile

protected URL createUrlForFile(File file)
                        throws IOException

Construct a URL object for the given file, to be used within the Binary value representing the "jcr:data" property of a 'nt:resource' node.

Subclasses can override this method to transform the URL into something different. For example, if the files are being served by a web server, the overridden method might transform the file-based URL into the corresponding HTTP-based URL.

Parameters:

file - the file for which the URL is to be created; never null

Returns:

the URL for the file; never null

Throws:

IOException - if there is an error creating the URL

createFileForUrl

protected File createFileForUrl(URL url)
                         throws URISyntaxException

Throws:

URISyntaxException

contentBasedSha1

protected boolean contentBasedSha1()

isExcluded

protected boolean isExcluded(File file)

Utility method to determine if the file is excluded by the inclusion/exclusion filter.

Parameters:

file - the file

Returns:

true if the file is excluded, or false if it is to be included

checkFileNotExcluded

protected void checkFileNotExcluded(String id,
                        File file)

Utility method to ensure that the file is writable by this connector.

Parameters:

id - the identifier of the node

file - the file

Throws:

DocumentStoreException - if the file is expected to be writable but is not or is excluded, or if the connector is readonly

hasDocument

public boolean hasDocument(String id)

Description copied from class: Connector

Checks if a document with the given id exists in the end-source.

Specified by:

hasDocument in class Connector

Parameters:

id - a non-null string.

Returns:

true if such a document exists, false otherwise.

getDocumentById

public Document getDocumentById(String id)

Description copied from class: Connector

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.

Specified by:

getDocumentById in class Connector

Parameters:

id - a non-null string

Returns:

either an Document instance or null

getDocumentId

public String getDocumentId(String path)

Description copied from class: Connector

Returns the id of an external node located at the given external path within the connector's exposed tree of content.

Specified by:

getDocumentId in class Connector

Parameters:

path - 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 Collection<String> getDocumentPathsById(String id)

Description copied from class: Connector

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 "/".

Specified by:

getDocumentPathsById in class Connector

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

getBinaryValue

public ExternalBinaryValue getBinaryValue(String id)

Description copied from class: Connector

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 Connector.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.

Overrides:

getBinaryValue in class Connector

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 boolean removeDocument(String id)

Description copied from class: Connector

Removes the document with the given id.

Specified by:

removeDocument in class Connector

Parameters:

id - a non-null string.

Returns:

true if the document was removed, or false if there was no document with the given id

storeDocument

public void storeDocument(Document document)

Description copied from class: Connector

Stores the given document.

Specified by:

storeDocument in class Connector

Parameters:

document - a non-null Document instance.

newDocumentId

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

Description copied from class: Connector

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.

Specified by:

newDocumentId in class Connector

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.

updateDocument

public void updateDocument(DocumentChanges documentChanges)

Description copied from class: Connector

Updates a document using the provided changes.

Specified by:

updateDocument in class Connector

Parameters:

documentChanges - a non-null DocumentChanges object which contains granular information about all the changes.

getChildren

public Document getChildren(PageKey pageKey)

Description copied from interface: Pageable

Returns a document which represents the document of a parent node to which an optiona page of children has been added. In order to add a next page, PageWriter.addPage(String, String, long, long) should be used to add a new page of children.

Specified by:

getChildren in interface Pageable

Parameters:

pageKey - a non-null PageKey instance, which offers information about the page that should be retrieved.

Returns:

a non-null document representing the parent document.