cwi.GraphXML
Class AbstractParser

java.lang.Object
  extended bycwi.GraphXML.AbstractParser
All Implemented Interfaces:
ParserError
Direct Known Subclasses:
XercesParser

public abstract class AbstractParser
extends java.lang.Object
implements ParserError

Abstract parser. This is a superclass for various xml parsers using different XML packages. It implements the management of error listeners, and provides the basic interface to access the real parser.

The code relies on the fact that entity reference nodes are expanded by the parser. Although some defence mechanisms are built in (to catch and ignore DOM node types for entities), entities are not expanded by the rest of the code!

Here is a typical usage of the parser (using the IBM parser as an example):

        AbstractParser theParser = new IBMParser();
        theParser.setGraphSemantics(new MyGraphSemantics());
        theParser.addParserErrorListener(new ParserListenerAdapter());
        
        theParser.interpret("XMLFileName");
 
Which uses a specific implementation of a parser, uses a graph semantic class instance, (which should implement the GraphSemantics interface), a default parser listener for error handling (which prints all messages on the standard error). It then calls the parser to interpret a specific file.

By default, a validating parser is used. However, if the system property XMLGraph_Validate is set to No, no, False, or false, a non-validating parser is used instead.

The error listener mechanism follows the standard Java style, and allows for several error reactions to be 'checked in' to the parser.

The parser mechanism is "reentrant", ie no static variables are used. This means that the parser can be invoked recursively by creating a new Parser instance. This may be important when handling, for example, metanodes.

The code ensures the DTDPATH facility: if the system property DTDPATH is set, it is considered to be a series of directory specification (much like the CLASSPATH variable) and it looks for a dtd file in those directory. This is preceded by an attempt to locate the dtd file in the same directory as the xml file itself, in the case this latter is specified in term of a file and not as a stream. Note, however, that this feature may not work with all xml parser implementation. It is known to work with xml4j from IBM, but it does not work properly with JAX version 1.0 of SUN.

Author:
Ivan Herman
See Also:
GraphSemantics

Field Summary
protected  org.xml.sax.EntityResolver entityResolver
           
 
Constructor Summary
AbstractParser()
           
 
Method Summary
 void addParserErrorListener(ParserErrorListener l)
          Add new listener.
 StructureIterator decompose(java.io.InputStream xmlStream)
          Decompose the document into a structure for a partial interpretation of a document.
 StructureIterator decompose(java.lang.String xmlFile)
          Decompose the document into a structure for a partial interpretation of a document.
 void fireParserError(java.lang.String m)
          Fire parser error.
 void fireParserFatalError(java.lang.String m)
          Fire fatal parser error.
 void fireParserWarning(java.lang.String m)
          Fire parser warning.
static java.lang.String[] getKeywords()
          Return the GraphXML keywords.
static java.lang.String[] getStoppers()
          Return the 'stopper' keywords.
 void interpret(java.io.InputStream xmlStream)
          Parse and iterpret an xml graph
 void interpret(java.lang.String xmlFile)
          Parse and interpret an xml graph file as one unit.
 org.w3c.dom.Document parse(java.io.InputStream xmlStream)
          Parse a document, return a Document element.
protected abstract  org.w3c.dom.Document parse(java.io.InputStream xmlStream, boolean validate)
          Parse a document, return a Document element.
 org.w3c.dom.Document parse(java.lang.String xmlFile)
          Parse a document, return a Document element.
 void removeParserErrorListener(ParserErrorListener l)
          Remove a listener
 void setGraphSemantics(GraphSemantics semantics)
          Set the collection of graph semantic methods.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

entityResolver

protected org.xml.sax.EntityResolver entityResolver
Constructor Detail

AbstractParser

public AbstractParser()
Method Detail

getStoppers

public static java.lang.String[] getStoppers()
Return the 'stopper' keywords. These are the keywords which follow the 'preamble' in a graph or GraphXML specification. They are used to stop cycles when rolling through the elements, to avoid unnecessary cycles (for example when extension elements are looked for.

At this time, these are "graph", "edit", "edit-bundle", "node", and "edge"


getKeywords

public static java.lang.String[] getKeywords()
Return the GraphXML keywords.


addParserErrorListener

public void addParserErrorListener(ParserErrorListener l)
Add new listener.

Parameters:
l - new listener

removeParserErrorListener

public void removeParserErrorListener(ParserErrorListener l)
Remove a listener


fireParserWarning

public void fireParserWarning(java.lang.String m)
Fire parser warning. Subclasses have to call this method from the parser dependend error routines.

Specified by:
fireParserWarning in interface ParserError
Parameters:
m - warning message

fireParserError

public void fireParserError(java.lang.String m)
Fire parser error. Subclasses have to call this method from the parser dependend error routines.

Specified by:
fireParserError in interface ParserError
Parameters:
m - warning message

fireParserFatalError

public void fireParserFatalError(java.lang.String m)
Fire fatal parser error. Subclasses have to call this method from the parser dependend error routines.

Specified by:
fireParserFatalError in interface ParserError
Parameters:
m - warning message

parse

public org.w3c.dom.Document parse(java.lang.String xmlFile)
Parse a document, return a Document element. The interpretation of the document is left to the caller.

This access to the parser is rarely used; use the interpret and decompose methods below instead.

Parameters:
xmlFile - the xml file to parse.

parse

public org.w3c.dom.Document parse(java.io.InputStream xmlStream)
Parse a document, return a Document element. The interpretation of the document is left to the caller.

This access to the parser is rarely used; use the interpret and decompose methods below instead.

The system property XMLGraph_Validate is checked agains a "true" or "false" value to decide whether a validating or a non-validating parser is used. If the property is not set, validation is used.

Parameters:
xmlStream - the xml stream to parse.

parse

protected abstract org.w3c.dom.Document parse(java.io.InputStream xmlStream,
                                              boolean validate)
Parse a document, return a Document element. The interpretation of the document is left to the caller.

This access to the parser is rarely used; use the interpret and decompose methods below instead.

This is the only abstract method in the class, which should be 'filled in' by the XML parser specific sub-class. All other methods can be left intact.

The subclass should take care of including the following code:

      theParser.setEntityResolver(entityResolver);
 

This is a SAX call which should be used to ensure the DTDPATH facility, ie, that DTD calls may refer to dtd files at various places in the local file directory. Note that not all parser implementation may include that feature yet, or their behaviour might not be appropriate.

Parameters:
xmlStream - the xml stream to parse
validate - decide whether the parser is validating or not

setGraphSemantics

public void setGraphSemantics(GraphSemantics semantics)
Set the collection of graph semantic methods.

Parameters:
semantics - GraphSemantics class instance

interpret

public void interpret(java.lang.String xmlFile)
Parse and interpret an xml graph file as one unit.

Parameters:
xmlFile - The xml file

interpret

public void interpret(java.io.InputStream xmlStream)
Parse and iterpret an xml graph

Parameters:
xmlStream - the xml stream to parse.

decompose

public StructureIterator decompose(java.lang.String xmlFile)
Decompose the document into a structure for a partial interpretation of a document. The document is parsed, broken into its main constituents only, and this structure is returned to the caller. The idea is that the caller can make a step-by-step interpretation of the content, taking each graph and edit block separately.

Parameters:
xmlFile - the xml file to parse.
Returns:
the iteratable structure of the document

decompose

public StructureIterator decompose(java.io.InputStream xmlStream)
Decompose the document into a structure for a partial interpretation of a document. The document is parsed, broken into its main constituents only, and this structure is returned to the caller. The idea is that the caller can make a step-by-step interpretation of the content, taking each graph and edit block separately.

Parameters:
xmlStream - the xml stream to parse.
Returns:
the iteratable structure of the document