org.openxml.x3p
Interface ProcessorEngine


public abstract interface ProcessorEngine

Interface defines a processor engine. The engine is activated and its life cycle controlled by the processor. The engine indicates which nodes it wishes to process and provides a single method to process each of these nodes.

An engine is created from a ProcessorEngineCreator with the controlling process context. The engine is then queried to determine what nodes should be passed to it, returning a bit mask of node types. The process(org.openxml.x3p.ProcessContext, org.w3c.dom.Node) method is called for each of the nodes in a depth-first traversal order. Once the engine is no longer required, it's destroy(org.openxml.x3p.ProcessContext) method is called.

The process(org.openxml.x3p.ProcessContext, org.w3c.dom.Node) method may return one of four valid values:

The engine should not attempt to modify nodes that are not the source node passed to it or a child node of the source node. If the engine requires to make modification higher up in the tree, it should find some other way to do so (e.g. to perform such processing higher up the tree).

Note that process(org.openxml.x3p.ProcessContext, org.w3c.dom.Node) may be called for nodes that the engine is not interested in, and then engine should behave accordingly by returning each node as is.

The engine need not be thread-safe. An instance of the engine will only be called to process on behalf of a single processor / process context, and in sequential order.

Version:
$Revision: 1.6 $ $Date: 1999/04/12 06:12:43 $
Author:
Assaf Arkin
See Also:
Processor, ProcessorEngineCreator

Field Summary
static int PROCESS_ALL
          Process all nodes.
static int PROCESS_COMMENT
          Process comments.
static int PROCESS_DEFAULT
          Process default nodes.
static int PROCESS_ELEMENT
          Process elements.
static int PROCESS_ENTITYREF
          Process entity references.
static int PROCESS_PI
          Process PIs.
static int PROCESS_TEXT
          Process text.
static int PROCESS_TOP
          Process only the top node in the tree.
 
Method Summary
 void destroy(ProcessContext ctx)
          Called once to tell the engine it is no longer needed.
 Node process(ProcessContext ctx, Node source)
          Process the node.
 int whatToProcess()
          The engine tells the processor which nodes it is interested in processing by returning a bit mask of node types.
 

Field Detail

PROCESS_DEFAULT

public static final int PROCESS_DEFAULT
Process default nodes. Engine wishes to process element and textual nodes.

PROCESS_TOP

public static final int PROCESS_TOP
Process only the top node in the tree.

PROCESS_ALL

public static final int PROCESS_ALL
Process all nodes. Engine wishes to process all nodes in the tree..

PROCESS_ELEMENT

public static final int PROCESS_ELEMENT
Process elements. Engine wishes to process only element nodes.

PROCESS_TEXT

public static final int PROCESS_TEXT
Process text. Engine wishes to process only text node (Text and CDATASection).

PROCESS_ENTITYREF

public static final int PROCESS_ENTITYREF
Process entity references. Engine wishes to process only entity references.

PROCESS_PI

public static final int PROCESS_PI
Process PIs. Engine wishes to process only processing instruction nodes.

PROCESS_COMMENT

public static final int PROCESS_COMMENT
Process comments. Engine wishes to process only comment nodes.
Method Detail

process

public Node process(ProcessContext ctx,
                    Node source)
             throws ProcessorException
Process the node. This method is called for each node the engine is interested in processing (and even one it's not). The engine may return the same source node, a replacement node or null. If the engine returns null, the source node is removed from the document tree. If the engine returns a replacement node, that node replaces the original source node in the document tree and processing resumes at the replacement node. The engine should not modify the document tree above the source node.
Parameters:
ctx - The process context
source - The node to process
Returns:
The source node intact or processed, or a replacement node
Throws:
ProcessorException - Indicates that an error occured during processing

destroy

public void destroy(ProcessContext ctx)
Called once to tell the engine it is no longer needed. After this call, the engine instance will not be used anymore in this context.
Parameters:
ctx - The process context

whatToProcess

public int whatToProcess()
The engine tells the processor which nodes it is interested in processing by returning a bit mask of node types. If the return value is -1 the engine indicates it is interested in processing all nodes. If the return value is 0, the engine indicates it is only interested in processing the top node of the tree.
Returns:
The node type mask or zero