org.modeshape.connector.filesystem

## Class FileSystemConnector

- java.lang.Object
- - org.modeshape.jcr.spi.federation.Connector
  - - org.modeshape.jcr.spi.federation.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.spi.federation.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 String` | `contentChildId(String fileId, boolean isRoot)`
    `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` | `shutdown()` Shutdown the connector by releasing all resources.
    `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.spi.federation.WritableConnector

      `isReadonly`

    - ### Methods inherited from class org.modeshape.jcr.spi.federation.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, 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)

    - #### shutdown

          public void shutdown()

      Description copied from class: `Connector`
      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.
      Overrides:
        `shutdown` in class `Connector`

    - #### 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`

    - #### contentChildId

          protected String contentChildId(String fileId,
                              boolean isRoot)

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

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