org.modeshape.jcr.api.sequencer

## Class Sequencer

- java.lang.Object
- - org.modeshape.jcr.api.sequencer.Sequencer

- Direct Known Subclasses:
    AbstractSrampSequencer, AbstractTextSequencer, ClassFileSequencer, CndSequencer, DdlSequencer, ImageMetadataSequencer, JavaFileSequencer, ModelSequencer, Mp3MetadataSequencer, MSOfficeMetadataSequencer, VdbSequencer, XmlSequencer, ZipSequencer

      public abstract class Sequencer
      extends Object

  A component that reads recently-changed content (often uploaded files) and extracts additional information from the content.

  Each ModeShape repository can be configured with zero or more sequencers. Each sequencer is configured with a set of match conditions that define the acceptable patterns for the paths of changed nodes, as well as a path specification that defines where the derived (or generated) output should be placed. Then when clients change nodes with paths that satisfy the match conditions, the repository will create a new Session and invoke the sequencer, which is then expected to process the changed content and generate the derived information under the supplied parent node. The session will be saved automatically or, if an exception is thrown, discard the changes and close the session.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Sequencer.Context` The sequencer context represents the complete context of a sequencer invocation.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Sequencer()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract boolean` | `execute(Property inputProperty, Node outputNode, Sequencer.Context context)` Execute the sequencing operation on the specified property, which has recently been created or changed.
    `protected Set<String>` | `getAcceptedMimeTypes()` Utility method to obtain the set of accepted MIME types.
    `protected Logger` | `getLogger()`
    `String` | `getName()` Get the name for this sequencer.
    `String[]` | `getPathExpressions()` Obtain the path expressions as configured on the sequencer.
    `String` | `getRepositoryName()` Get the name of the repository.
    `UUID` | `getUniqueId()` Return the unique identifier for this sequencer.
    `boolean` | `hasAcceptedMimeTypes()` Determine if this sequencer requires the content to have a specific MIME type
    `void` | `initialize(NamespaceRegistry registry, NodeTypeManager nodeTypeManager)` Initialize the sequencer.
    `boolean` | `isAccepted(String mimeType)` Determine if this sequencer has been configured to accept and process content with the supplied MIME type.
    `protected void` | `registerDefaultMimeTypes(String... mimeTypes)` Set the MIME types that are accepted by default, if there are any.
    `protected boolean` | `registerNamespace(String namespacePrefix, String namespaceUri, NamespaceRegistry namespaceRegistry)` Registers a namespace using the given `NamespaceRegistry`, if the namespace has not been previously registered.
    `protected void` | `registerNodeTypes(InputStream cndStream, NodeTypeManager nodeTypeManager, boolean allowUpdate)` See `registerNodeTypes(String, org.modeshape.jcr.api.nodetype.NodeTypeManager, boolean)`
    `protected void` | `registerNodeTypes(String cndFile, NodeTypeManager nodeTypeManager, boolean allowUpdate)` Registers node types from a CND file, using the given `NodeTypeManager`.
    `String` | `toString()`

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

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

- - ### Constructor Detail

    - #### Sequencer

          public Sequencer()

  - ### Method Detail

    - #### getUniqueId

          public final UUID getUniqueId()

      Return the unique identifier for this sequencer.
      Returns:
        the unique identifier; never null

    - #### getName

          public final String getName()

      Get the name for this sequencer.
      Returns:
        the name, or null if there is no description

    - #### getRepositoryName

          public final String getRepositoryName()

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

    - #### getPathExpressions

          public final String[] getPathExpressions()

      Obtain the path expressions as configured on the sequencer. This method always returns a copy to prevent modification of the values.
      Returns:
        the path expressions; never null but possibly empty

    - #### initialize

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

      Initialize the sequencer. This is called automatically by ModeShape once for each Sequencer instance, and should not be called by the sequencer.

      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, sequencers can use the supplied `registry` and `nodeTypeManager` objects to register custom namesapces and node types required by the generated content.

      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)

    - #### execute

          public abstract boolean execute(Property inputProperty,
                        Node outputNode,
                        Sequencer.Context context)
                                   throws Exception

      Execute the sequencing operation on the specified property, which has recently been created or changed.

      Each sequencer is expected to process the value of the property, extract information from the value, and write a structured representation (in the form of a node or a subgraph of nodes) using the supplied output node. Note that the output node will either be:

      1. the selected node, in which case the sequencer was configured to generate the output information directly under the selected input node; or
      2. a newly created node in a different location than node being sequenced (in this case, the primary type of the new node will be 'nt:unstructured', but the sequencer can easily change that using `Node.setPrimaryType(String)`)

      The implementation is expected to always clean up all resources that it acquired, even in the case of exceptions.

      Note: This method must be threadsafe: ModeShape will likely invoke this method concurrently in separate threads, and the method should never modify the state or fields of the Sequencer implementation class. All initialization should be performed in `initialize(NamespaceRegistry, NodeTypeManager)`.

      Parameters:
        `inputProperty` - the property that was changed and that should be used as the input; never null
        `outputNode` - the node that represents the output for the derived information; never null, and will either be `new` if the output is being placed outside of the selected node, or will not be new when the output is to be placed on the selected input node
        `context` - the context in which this sequencer is executing, and which may contain additional parameters useful when generating the output structure; never null
      Returns:
        true if the sequencer's output should be saved, or false otherwise
      Throws:
        `Exception` - if there was a problem with the sequencer that could not be handled. All exceptions will be logged automatically as errors by ModeShape.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### registerNamespace

          protected boolean registerNamespace(String namespacePrefix,
                                  String namespaceUri,
                                  NamespaceRegistry namespaceRegistry)
                                       throws RepositoryException

      Registers a namespace using the given `NamespaceRegistry`, if the namespace has not been previously registered.
      Parameters:
        `namespacePrefix` - a non-null `String`
        `namespaceUri` - a non-null `String`
        `namespaceRegistry` - a `NamespaceRegistry` instance.
      Returns:
        true if the namespace has been registered, or false if it was already registered
      Throws:
        `RepositoryException` - if anything fails during the registration process

    - #### registerNodeTypes

          protected void registerNodeTypes(String cndFile,
                               NodeTypeManager nodeTypeManager,
                               boolean allowUpdate)
                                    throws RepositoryException,
                                           IOException

      Registers node types from a CND file, using the given `NodeTypeManager`. Any namespaces defined in the CND file will be automatically registered as well.
      Parameters:
        `cndFile` - the relative path to the cnd file, which is loaded using via `Class.getResourceAsStream(String)`
        `nodeTypeManager` - the node type manager with which the cnd will be registered
        `allowUpdate` - a boolean which indicates whether updates on existing node types are allowed or no. See `NodeTypeManager.registerNodeType(javax.jcr.nodetype.NodeTypeDefinition, boolean)`
      Throws:
        `RepositoryException` - if anything fails
        `IOException` - if any stream related operations fail

    - #### registerNodeTypes

          protected void registerNodeTypes(InputStream cndStream,
                               NodeTypeManager nodeTypeManager,
                               boolean allowUpdate)
                                    throws RepositoryException,
                                           IOException

      See `registerNodeTypes(String, org.modeshape.jcr.api.nodetype.NodeTypeManager, boolean)`
      Parameters:
        `cndStream` - the input stream containing the CND file; may not be null
        `nodeTypeManager` - the node type manager with which the node types in the CND file should be registered; may not be null
        `allowUpdate` - a boolean which indicates whether updates on existing node types are allowed or no. See `NodeTypeManager.registerNodeType(javax.jcr.nodetype.NodeTypeDefinition, boolean)`
      Throws:
        `RepositoryException` - if anything fails
        `IOException` - if any stream related operations fail

    - #### getLogger

          protected final Logger getLogger()

    - #### registerDefaultMimeTypes

          protected final void registerDefaultMimeTypes(String... mimeTypes)

      Set the MIME types that are accepted by default, if there are any. This method should be called from the `initialize(NamespaceRegistry, NodeTypeManager)` method in the subclass.

      This method can be called more than once to add additional mime types.

      Parameters:
        `mimeTypes` - the array of MIME types that are accepted by this sequencer
      See Also:
        `isAccepted(String)`

    - #### getAcceptedMimeTypes

          protected final Set<String> getAcceptedMimeTypes()

      Utility method to obtain the set of accepted MIME types. The resulting set will either be those set by default in the subclass' overridden `initialize(NamespaceRegistry, NodeTypeManager)` method or the MIME types explicitly set in the sequencers configuration.
      Returns:
        the set of MIME types that are accepted by this Sequencer instance; never null but possibly empty if this Sequencer instance accepts all MIME types

    - #### hasAcceptedMimeTypes

          public final boolean hasAcceptedMimeTypes()

      Determine if this sequencer requires the content to have a specific MIME type
      Returns:
        true if this sequencer can only process certain MIME types, or false if there are no restrictions

    - #### isAccepted

          public final boolean isAccepted(String mimeType)

      Determine if this sequencer has been configured to accept and process content with the supplied MIME type.
      Parameters:
        `mimeType` - the MIME type
      Returns:
        true if content with the supplied the MIME type is to be processed (or when `mimeType` is null and therefore not known), or false otherwise
      See Also:
        `hasAcceptedMimeTypes()`

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