cox.jmatt.java.MathTools.graphing
Class GraphHandler

java.lang.Object
  extended by org.xml.sax.helpers.DefaultHandler
      extended by cox.jmatt.java.MathTools.util.MTXErrorHandler
          extended by cox.jmatt.java.MathTools.graphing.GraphHandler
All Implemented Interfaces:
javax.xml.transform.ErrorListener, org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public class GraphHandler
extends MTXErrorHandler

This class is designed specifically to parse graphing.xml.* package markup and convert it into a GraphPaper instance containing the components described in the XML data. It should not be used for any other purpose otherwise the universe will shatter.

GraphHandler extends MTXErrorHandler and is used as such. The only methods defined are several from the org.xml.sax.ContentHandler and ErrorHandler interfaces. The latter simply reports parser warns and errors to CapCom.debug() and fatals to CapCom.error() If desired, an alternate ErrorHandler can be set without affecting the main operations of this class.

The ContentHandler methods defined are the fewest necessary to accomplish GraphHandler's task: converting graphing package XML into graphing components. MTXProcessor uses this class in its parseGraph() method. It simply substitutes an instance of this class for its handler when parsing the XML markup.

Using GraphHandler

To use this class from an external application, first create an instance. Next set a GraphEngine of the desired output type using the setGraphEngine() method. Obtain a SAXParser instance, set GraphHandler as its ContentHandler (at LEAST), and parse the XML content. If no external ErrorHandler is necessary, set this class as that and use MathTools' logging tools! When the document finishes, the graph will be ready. Call getResult() to retrieve a complete GraphPaper instance from the GraphEngine sent it. This is exactly what MTXProcessor does when it parses a graph!

As with the graphing.xml.* implementation, all Object data must be String. If not, the GraphPaper must know how to convert the Strings returned by the XML parse into whatever Objects it needs. Also, be very, VERY careful if editing the graphing XML or generating it from an external source. GraphHandler is NOT TOLERANT of bad XML markup! A complete, albeit short, example of GraphingXML is the file XMLGraph.xml in the docs/SampleScripts/ folder. This shows the root, Renderable tags, and content tags exactly as they should be!

When the document is parsed, the three general attributes are set as follows:

Instance-specific attributes (xmin, height, closed, scale, etc.) are set when the instances to which they apply are created. NOTE: Although Transforms are not added with a String key, the graphing.xml.* package DOES assign a simple ID attribute to them. When parsed, this is ignored.

USE CAUTION when parsing XML not generated by the graphing.xml.* implementation! Some Exceptions are caught and handled gracefully while others are handled less so. MTXProcessor.parseGraph() defines an all-encompassing try/catch block and several methods in this class will handle some errors, but it is a BAD IDEA to count on that behavior! It is a much better idea to make sure the XML is good before it is parsed!


Constructor Summary
GraphHandler()
          This constructor builds a standard GraphHandler.
 
Method Summary
 void characters(char[] pChars, int pStart, int pLen)
          This method is used to accumulate data for tags that have character content: <Expression> <Limit> <Vertices> and <Param>.
 void endDocument()
          Clean up any mess left behind by the parsing process.
 void endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)
          If the element is Renderable, add it to the GraphPaper.
 GraphPaper getResult()
          Return the GraphPaper instance parsed.
 void setGraphEngine(GraphEngine pEngine)
          This method sets the GraphEngine used to build the graph described in the XML document.
 void startDocument()
          Prints a debug message.
 void startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attrs)
          Start an element.
 
Methods inherited from class cox.jmatt.java.MathTools.util.MTXErrorHandler
error, error, fatalError, fatalError, warning, warning
 
Methods inherited from class org.xml.sax.helpers.DefaultHandler
endPrefixMapping, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, skippedEntity, startPrefixMapping, unparsedEntityDecl
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GraphHandler

public GraphHandler()
This constructor builds a standard GraphHandler. Nothing else is needed.

Method Detail

setGraphEngine

public void setGraphEngine(GraphEngine pEngine)
This method sets the GraphEngine used to build the graph described in the XML document. If set to (or left as) null, the default engine used is GraphEngineXML. This GraphEngine must be able to make sense of Strings in Object parameter spots as that is how they are set.

Parameters:
pEngine - The GraphEngine to use in constructing the graph.

startDocument

public void startDocument()
Prints a debug message. If no GraphEngine has been set, install a default (XML) one.

Specified by:
startDocument in interface org.xml.sax.ContentHandler
Overrides:
startDocument in class MTXErrorHandler

startElement

public void startElement(java.lang.String uri,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes attrs)
Start an element. First determine what the element is and how to deal with it.

Specified by:
startElement in interface org.xml.sax.ContentHandler
Overrides:
startElement in class org.xml.sax.helpers.DefaultHandler

endElement

public void endElement(java.lang.String uri,
                       java.lang.String localName,
                       java.lang.String qName)
If the element is Renderable, add it to the GraphPaper.

Specified by:
endElement in interface org.xml.sax.ContentHandler
Overrides:
endElement in class org.xml.sax.helpers.DefaultHandler

characters

public void characters(char[] pChars,
                       int pStart,
                       int pLen)
This method is used to accumulate data for tags that have character content: <Expression> <Limit> <Vertices> and <Param>.

Specified by:
characters in interface org.xml.sax.ContentHandler
Overrides:
characters in class org.xml.sax.helpers.DefaultHandler

endDocument

public void endDocument()
Clean up any mess left behind by the parsing process.

Specified by:
endDocument in interface org.xml.sax.ContentHandler
Overrides:
endDocument in class MTXErrorHandler

getResult

public GraphPaper getResult()
Return the GraphPaper instance parsed. This method is only valid AFTER the parsing process! Beforehand the return value is indeterminate. All specified components will have been added per their specifications in the XML document. The GraphPaper instance will, of course, belong to the GraphEngine set before parsing started.