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, Mp3MetadataSequencer, MSOfficeMetadataSequencer, 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

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()