ITS Processor Interface

Initial thoughts on an ITS processor interface.

I would see two interfaces:

• One to ste the rules and apply them.
• One to travers the document, and aplly the inherited ITS values as the tree is traversed.

org.w3c.its.IProcess

This interface would offers the following methods:

addExternalRules (Document rulesDoc, URI docURI)

Adds a set of global rules to the document to process. The rules are added to the internal storage of the document, not to the document tree.

• The docRules parameter is the document where the global rules are declared.
• The docURI parameter is the URI of the document to process. This might be needed because implementing xlink:href will need a initial location.

addExternalRules (URI docURI)

Same as the method above, but with just the path of the document where the rules are located. This could be used for loading an external rules file for example.

• The docURI parameter is the URI of the document to process.

applyRules (int dataCategories)

Applies the current ITS rules to the document. This method decorates the document tree with special flags that are used for getting the different ITS information later.

• The dataCategories flag indicating what data categories to apply. The value is a set of flags combined with a OR operator.

void disapplyRules ()

Removes all the special attributes added when applying the ITS rules. This may be needed if the implementation used for example attributes to decorate the tree.

org.w3c.its.ITraversal

This interface would provide the means to go through a document that has been decorated with ITS markers (using IProcess), and to easily get the ITS-related information for each node.

In this scenario the inheritance is done as the traversal is progressing.

void startTraversal ()

Starts the traversal of the document. Initialize any internal variable that needs to be set to restart the traversal process.

Node nextNode ()

Moves to the next node in the traversal of the document. The method returns null if there is no more node to go through, otherwise it returns the current node.

boolean backtracking ()

Indicates whether the current node is found while backtracking. For example, for an element node, this indicate the equivalent of a closing tag. This method returns true if the current node is found while backtracking, false otherwise.

boolean translate ()

Indicates if the current node of the traversal is translatable. The method return true is the node is a translatable element, false otherwise.

boolean translate (String attrName)

Indicates if a given attribute of the current node of the traversal is translatable. The method returns true if the value for the given attribute name is translatable, false otherwise.

int getDirectionality ()

Gets the directionality of the current node. The returned value is one of: DIR_RTL, DIR_LTR, DIR_RLO, DIR_LRO.

int getDirectionality (String attrName)

Gets the directionality of a given attribute of the current node. The method returns a value that is one of: DIR_RTL, DIR_LTR, DIR_RLO, DIR_LRO.

int getWithinText ()

Gets the withinText-related information for the current element. The method returns a value that is one of: WITHINTEXT_NO, WITHINTEXT_YES, WITHINTEXT_NESTED.

Etc...

...Each data category having one associated method (or more if needed) to provide the information to the caller.

Example of Usage

Here is an example of usage in Java:

try {
 DocumentBuilderFactory fact = DocumentBuilderFactory.newInstance();
 fact.setNamespaceAware(true);
 fact.setValidating(false);
 String inputPath = "testdata//test01.xml";
 InputStream input = new FileInputStream(inputPath);
 Document doc = fact.newDocumentBuilder().parse(input);
 // The document has been loaded, now we apply any existing internal rules
 URI inputURI = new URI("file:///"+inputPath);
 ITSEngine itsEng = new ITSEngine(doc, inputURI);
 itsEng.applyRules(IProcessor.DC_ALL);
 // We initialize for the traversal
 itsEng.startTraversal();
 Node node;
 // And then we walk through the document tree
 while ( (node = itsEng.nextNode()) != null ) {
  switch ( node.getNodeType() ) {
  case Node.ELEMENT_NODE:
   if ( itsEng.backTracking() ) {
    System.out.println("end of "+node.getLocalName());
   }
   else {
    System.out.println("start of "+node.getLocalName());
    System.out.println(String.format("translate=%s",
     (itsEng.translate() ? "yes" : "no")));
   }
   break;
  }
 }
}
catch ( Exception e ) {
 e.printStackTrace();
}

Additional Notes

• The applyRules method of the IProcessor interface may need one extra parameter: a boolean to indicate if the ITS information needs to be set on all nodes (basically if the inheritance needs to be applied). This would allow random access to the nodes.
• In the same vein, all the information-related methods (translate(), getDirectionality(), etc.) may need to be in a separate interface, distinct from ITraversal, so they could be used on engines that implement random access (vs traversal).