cox.jmatt.java.MathTools.util
Class MTXProcessor

java.lang.Object
  extended by org.xml.sax.helpers.DefaultHandler
      extended by cox.jmatt.java.MathTools.util.MTXErrorHandler
          extended by cox.jmatt.java.MathTools.util.MTXProcessor
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 MTXProcessor
extends MTXErrorHandler

The MathTools XML Processor processes the XML tags generated by the MathTools classes with a toXML() method. In order to function, this class MUST have appropriate XML equipment available. Specifically, MTXPro requires a SAXParserFactory capable of creating namespace-aware SAXParsers. Fortunately this is easy to check with the isAvailable() method. If it returns true, sufficient machinery is in place and MTXPro will function properly. If not, simply place a SAXParserFactory provider in the CLASSPATH or set the appropriate system properties; MTXPro uses the discovery mechanism to create a SAXParserFactory which it then uses to create parsers.

MTXProcessor is...

MTXPro is written to process the XML tags generated by the MathTools classes that have a toXML() of some description. It is NOT designed as an all-purpose XML or even MathML processor! Some MathTools classes, such as Question, natively generate XML. This XML markup is MathTools-specific and this class parses it as such.

MTXProcessor itself extends MTXErrorHandler and overrides methods germane to processing MathTools XML. It can be used as a DefaultHandler without modification. Simply create an instance and feed it to any SAXParser's parse() method as the DefaultHandler. When parsing is complete, call the getReturnList() method for a List of whatever was processed.

In addition to the DefaultHandler methods, MTXPro contains all the machinery necessary to actually parse MathTools XML content. The source can be a String, a file, or an org.xml.sax.InputSource. For file or String input, MTXPro wraps an InputSource around either a FileReader or StringReader and calls processInput(). It then creates a SAXParser, sets itself as the DefaultHandler and parses the document.

The XML markup recognized by MTXPro is, as stated previously, that generated by the MathTools classes. The XML itself must be well-formed but MTXPro is not picky past that. There must be a root tag but exactly what that tag is does not matter. An <MTest> tag will work, but so will any other properly-opened and -closed tag. The default tag, provided as a static String constant, is <MathTools>. If present, the 'id=' attribute on any parsed tag is sent to the process__() methods, as is any 'data=' tag. Since the Question tag is the only one with children, it is handled differently. Other tags are handled from the startElement() method. As soon as MTXPro has the necessary attributes it calls the appropriate process__() method. For Question tags, processing waits until the closing tag to present the id, Problem, and Answer components. MFormatElement tags, which may have content but no children, are also handled via endElement().

Default behavior for MTXPro parsing is to create an instance of the MathTools core class specified by each tag. If creation succeeds and the resulting instance is not null, it is added to the internal return List. This list is returned from the various parse__() methods or can be retrieved via getReturnList() if MTXPro is used as a handler.

Per MTXErrorHandler all SAX or XSLT warns and errors are reported at Debug level and fatals are reported at Error level. No error processing is done as this is beyond the scope of this class.

Loading Factories

MTXPro can use CapCom's Math ClassLoader to create SAXParserFactory, TransformerFactory, DocumentBuilderFactory, and XPathFactory instances. To do so two things must happen. First and foremost setMathClassLoader(true) sets the CapCom ClassLoader in place. Passing false clears it and both happen immediately.

The second step is to set the class name of the desired factory type. This is critical: the name of the class must be set or no custom factory will be created! If the Math ClassLoader is in place and the desired factory name is not null or blank, the next call to the appropriate isAvailable() method will try to instantiate the specified class using the Math ClassLoader. This is done on a per-type basis so it is quite possible to use a custom XPath factory while still using the standard ones for the rest. Simply enable the MathClassLoader and set the name of the XPathFactory while not setting or clearing the others.

Configuring SAX

SAX configuration options are minimal but present. MTXProcessor maintains global flags for SAX validation and namespace awareness. Once set these values take effect on the next call to the (basic) 'isAvailable()' method. They apply to the SAXParserFactory and remain at the values set until they are manually changed.

To set something other than validation or namespaces or to have the change take effect immediately use the 'setSAXFeature()' method. This must happen after at least one call to 'isAvailable()' otherwise no parser will be set. If a parser is set then the feature value is set immediately. If it cannot be set or if attempting to set it throws an Exception this is reported at Debug level and the method returns false, otherwise it returns true.

MTXProcessor and XSLT

MTXPro has a basic XSLT transformation capacity. It is present more for the sake of completeness than mathematical nececssity, though it can be useful in preparing mathematical XML documents. The transformer itself depends on two basic methods, both named transformData(). The actual transformation method accepts a javax.xml.transform.Source for the XML data and stylesheet and a Result for the output. If the stylesheet is null the identity transform is applied. Values for any <xsl:param > tags can be set with the setParameter() method. It accepts a String key (that must match the 'name=' attribute in the stylesheet tag) and a String value. When the transformation is done, all parameters set will be placed into the Transformer.

Scripts use the transformData() that accepts two Strings and two booleans. The first String is the XML data source, the second is the stylesheet. The booleans control whether to interpret the Strings as raw data (true) or as a filename (false). The result of the transform is returned as a String.

The isTransformAvailable() checks to see if XSLT equipment is in place, so it should be checked at least once per configuration or location change. If it returns false the MathClassLoader can be enabled and used.

DOM Processing

MTXProcessor's DOM processing capability is, like XLST, added for the sake of completeness. It allows scriptable XML generation beyond what MathXML provides. Specifically, it allows the creation of a blank DOM Document from which Elements and other things can be added. DOM Documents can also be parsed from Strings or files, manipulated, transformed, and printed out.

As with the SAX and XSLT methods, the isDOMAvailable() method checks the DOM equipment and prepares it; and the resetDOM() method clears it.

If necessary, DOM Attributes and Features can be set via the setDOMFeature() and setDOMAttribute() methods. These methods are called on the DocumentBuilderFactory before a DocumentBuilder is created so they will be in effect for all subsequent DOM activity. Calling resetDOM() clears all Attributes and Features, plus the current DocumentBuilder and DocumentBuilderFactory.

DOM and XPath

The DOM equipment includes basic XPath capability. An XPath can be applied to a DOM Document or Node with the result returned as a Node. The XPath equipment includes a factory class name and settable XPath features. As with DOM and transform equipment setting the XPath factory classname to a non-null, non-blank value uses whatever ClassLoader is set, if one is. The isXPathAvailable() method creates the necessary infrastructure and must be called before XPath can be used.

The applyXPath() method does the work. It accepts a String XPath and a DOM Node and returns a DOM Node. The method itself attempts to apply the XPath to the data Node. If an error occurs it is reported and the return value is null. The XPath instance itself is never directly exposed so any operations beyond the bare basics are beyond the scope of this class.

Oh yeah. Graphing!

The graphing.xml.* package produces simplified XML markup from graphing commands. The parseGraph() method here can convert that markup back into graphing classes. See the graphing package for exact details.


Field Summary
static java.lang.String MT_CLOSE
          Default closing tag for a MathTools XML document.
static java.lang.String MT_OPEN
          Default opening tag for a MathTools XML document.
static java.lang.String NSURI
          String constant for the MathTools namespace URI: 'cox.jmatt.java/MathTools'.
 
Constructor Summary
MTXProcessor()
          Standard constructor.
 
Method Summary
 org.w3c.dom.Node applyXPath(java.lang.String pXPath, org.w3c.dom.Node pNode)
          This method applies the specified XPath to the supplied DOM Node.
 void characters(char[] pData, int pStart, int pLen)
          This method is used only by Problem, Answer, and some MFormatElement tags.
 void checkXML(java.lang.String pData, boolean pRawData)
          Use this method to check a document ONLY.
 void clearOutputProperties()
          Clear all previously-set Transformer Output Properties.
 void clearParameters()
          Remove all previously-set parameters.
 void endDocument()
          This method prints a debug-level message and nothing else.
 void endElement(java.lang.String uri, java.lang.String pName, java.lang.String qName)
          Handle processing of Question and its children and MFormatElement.
 java.util.List getReturnList()
          This method returns the internal List used to hold the components created by the various process__() methods.
 boolean isAvailable()
          This method checks to see if a SAXParser can be created.
 boolean isDOMAvailable()
          Check to see if XML DOM equipment is available.
 boolean isTransformAvailable()
          Check to see if an XSLT Transformer is avaiable.
 boolean isXPathAvailable()
          Check XPath availability.
 org.w3c.dom.Document newDocument()
          Create a new, blank DOM document.
 org.w3c.dom.Document parseDOM(java.lang.String pData, boolean pRawData)
          Parse XML into a DOM tree.
 java.util.List parseFile(java.lang.String pFile)
          Parse an XML file.
 GraphPaper parseGraph(GraphEngine pEngine, java.lang.String pGraphSource, boolean pRawData)
          This method is used to parse cox.jmatt.java.MathTools.graphing.xml package XML markup into a GraphPaper instance.
 java.util.List parseInput(org.xml.sax.InputSource pSource)
          Process XML from an InputSource.
 java.util.List parseString(java.lang.String pData)
          Parse MathTools XML contained in a String.
 java.lang.Object processMathStat(java.lang.String pData, java.lang.String pData2)
          The processor has a MathStat tag.
 java.lang.Object processMComplex(java.lang.String pCplx)
          Process a MComplex tag.
 java.lang.Object processMEquation(java.lang.String pData)
          The processor has data for a MEquation.
 java.lang.Object processMFraction(java.lang.String pID, java.lang.String pNumerator, java.lang.String pDenominator)
          The processor found a MFraction tag.
 java.lang.Object processMMatrix(java.lang.String pID, java.lang.String pData)
          The processor has detected a MMatrix tag.
 java.lang.Object processMRadical(java.lang.String pID, int pRadicand, int pIndex)
          Process a MRadical tag.
 java.lang.Object processMTFI(java.lang.String pType, java.lang.String pContent)
          Process a MFormatElement.
 java.lang.Object processPolynomial(java.lang.String pID, java.lang.String pData)
          The processor has detected a Polynomial tag.
 java.lang.Object processQuestion(java.lang.String pID, java.lang.String pProblem, java.lang.String pAnswer)
          The parser has completed a Question tag.
 void resetDOM()
          Clear and reset all DOM-related machinery except the DocumentBuilderFactory class name.
 void resetXPath()
          Reset the current XPath configuration.
 void setDOMAttribute(java.lang.String pName, java.lang.Object pValue)
          This method sets a DOM Attribute on the current DOM DocumentBuilderFactory.
 void setDOMFactoryClassName(java.lang.String pName)
          Set (or clear) the class name used to create a DOM DocumentBuilderFactory.
 void setDOMFeature(java.lang.String pName, boolean pValue)
          Use this method to set a DOM Feature on the DocumentBuilderFactory.
 void setMathClassLoader(boolean pEnable)
          Enable/disable CapCom's MathClassLoader.
 void setNamespaceAware(boolean pEnable)
          Enable/disable SAX Namespace awareness.
 void setOutputProperty(java.lang.String pKey, java.lang.String pValue)
          Set an Output Property to be used by the transformer.
 void setParameter(java.lang.String pKey, java.lang.String pValue)
          Set a stylesheet parameter used for the transformation.
 void setParametersFromGlobalPizza()
          Add the Global Pizza to the parameters fed to the transform.
 void setPFactoryClassName(java.lang.String pName)
          This method specifies the name of the factory class used to instantiate a SAXParserFactory.
 boolean setSAXFeature(java.lang.String pFeature, boolean pEnable)
          Enable/disable a SAX Feature on the current parser.
 void setTFactoryClassName(java.lang.String pName)
          This method specifies the name of the factory class used to instantiate a TransformerFactory.
 void setValidating(boolean pEnable)
          Set the validation flag for SAXParser instances created by the internal factory.
 void setXFactoryClassName(java.lang.String pName)
          This method specifies the name of the factory class for XPATHFactory instances.
 void setXFeature(java.lang.String pName, boolean pValue)
          Set an XPath feature.
 void startDocument()
          This method prints a debug-level message and initializes the internal return List.
 void startElement(java.lang.String uri, java.lang.String pName, java.lang.String qName, org.xml.sax.Attributes pAtts)
          Process the element properly.
 void transformData(javax.xml.transform.Source pData, javax.xml.transform.Source pStyle, javax.xml.transform.Result pResult)
          This method is the basic XLST Transform method.
 java.lang.String transformData(java.lang.String pData, java.lang.String pStyle, boolean pRawData, boolean pRawStyle)
          This is the scripting transform method.
 java.lang.String transformDOM(org.w3c.dom.Node pSource, java.lang.String pStyle, boolean pRawStyle)
          Transform a DOM Document (or any Node) via XSLT.
 java.lang.String transformFiles(java.lang.String pData, java.lang.String pStyle)
          This method transforms based on two filenames.
 org.w3c.dom.Node transformNode(org.w3c.dom.Node pSource, java.lang.String pStyle, boolean pRawStyle)
          Transform a DOM Node into another Node via XSLT.
 
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
 

Field Detail

NSURI

public static final java.lang.String NSURI
String constant for the MathTools namespace URI: 'cox.jmatt.java/MathTools'.

See Also:
Constant Field Values

MT_OPEN

public static final java.lang.String MT_OPEN
Default opening tag for a MathTools XML document. <MathTools> with the MathTools namespace.

See Also:
Constant Field Values

MT_CLOSE

public static final java.lang.String MT_CLOSE
Default closing tag for a MathTools XML document.

See Also:
Constant Field Values
Constructor Detail

MTXProcessor

public MTXProcessor()
Standard constructor. Used for scripting and for instantiating a default SAXParserFactory using the built-in (to Java!) lookup procedure.

Method Detail

isAvailable

public boolean isAvailable()
This method checks to see if a SAXParser can be created. ALWAYS check this method once! If a namespace-aware SAXParser cannot be created for whatever reason this class will not function! Use this method to check before a lot of extra work is done. If it returns true, all is well. If not, there either is no SAXParserFactory or no available SAXParser. Any Errors or Exceptions thrown during factory or parser creation are reported at debug level.


setValidating

public void setValidating(boolean pEnable)
Set the validation flag for SAXParser instances created by the internal factory. Changing this will not take effect until AFTER a call to isAvailable(). The default value is false.


setNamespaceAware

public void setNamespaceAware(boolean pEnable)
Enable/disable SAX Namespace awareness. Changing the value takes effect after the next call to isAvailable(). By default namespace awareness is enabled.


setSAXFeature

public boolean setSAXFeature(java.lang.String pFeature,
                             boolean pEnable)
Enable/disable a SAX Feature on the current parser. The feature is set (or not) immediately and remains in effect until the next call to isAvailable(). If, for whatever reason, a feature cannot be set (Exception thrown) this is reported at Debug level and the return value is false. If the feature is set the return value is true. No string validation is done; use with care! If no parser is set the method returns false immediately.

Parameters:
pFeature - The name of the SAX feature to set.
pEnable - The value to set for the specified feature.

setPFactoryClassName

public void setPFactoryClassName(java.lang.String pName)
This method specifies the name of the factory class used to instantiate a SAXParserFactory. Setting it to null or blank clears it.


setTFactoryClassName

public void setTFactoryClassName(java.lang.String pName)
This method specifies the name of the factory class used to instantiate a TransformerFactory. Setting it to null or blank clears it.


setXFactoryClassName

public void setXFactoryClassName(java.lang.String pName)
This method specifies the name of the factory class for XPATHFactory instances. Setting it to blank or null clears it.


setMathClassLoader

public void setMathClassLoader(boolean pEnable)
Enable/disable CapCom's MathClassLoader. The loader is set or cleared instantly but will not be used until the next call to one of the isAvailable() methods. NOTE: setting this to false does not clear any previously-set factory class names.

Parameters:
pEnable - true to set the MathClassLoader, false to disable it.

startDocument

public void startDocument()
This method prints a debug-level message and initializes the internal return List.

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

endDocument

public void endDocument()
This method prints a debug-level message and nothing else.

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

characters

public void characters(char[] pData,
                       int pStart,
                       int pLen)
This method is used only by Problem, Answer, and some MFormatElement tags. It accumulates content until the tag closes.

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

startElement

public void startElement(java.lang.String uri,
                         java.lang.String pName,
                         java.lang.String qName,
                         org.xml.sax.Attributes pAtts)
Process the element properly. Questions accumulate the Problem and Answer tags, MFormatElements accumulate content, all others are empty.

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 pName,
                       java.lang.String qName)
Handle processing of Question and its children and MFormatElement. All other types are instantiated in startElement().

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

parseFile

public java.util.List parseFile(java.lang.String pFile)
                         throws java.io.IOException,
                                org.xml.sax.SAXException
Parse an XML file. This method constructs an InputSource around pString and calls parseInput() on it. Return values and Exceptions are per that method. If called from MTApplet this method may fail due to security considerations. Use with care!

Parameters:
pFile - The name of the file to parse. If null or empty the method returns null.
Throws:
java.io.IOException
org.xml.sax.SAXException

parseString

public java.util.List parseString(java.lang.String pData)
                           throws java.io.IOException,
                                  org.xml.sax.SAXException
Parse MathTools XML contained in a String. Exceptions and return value per parseInput()

Parameters:
pData - A String containing MathTools XML markup.
Throws:
java.io.IOException
org.xml.sax.SAXException

parseInput

public java.util.List parseInput(org.xml.sax.InputSource pSource)
                          throws java.io.IOException,
                                 org.xml.sax.SAXException
Process XML from an InputSource. All other parsing methods reflect to this one. If pSource is null the return value is null. If isAvailable() returns false, the return value is null.

Parameters:
pSource - InputSource containing MathTools XML markup.
Returns:
A List of non-null Objects resulting from the various process__() methods.
Throws:
java.io.IOException - If the underlying IO operations do.
org.xml.sax.SAXException - If the parser does.

checkXML

public void checkXML(java.lang.String pData,
                     boolean pRawData)
Use this method to check a document ONLY. It parses XML without creating any MathTools or Graphing components, all it does is check for errors. The pData parameter can be raw XML or a filename. Any unhandled exceptions are reported at Error level.

Parameters:
pData - The data or file to check.
pRawData - true if pData is raw XML, false if it is a filename.

getReturnList

public java.util.List getReturnList()
This method returns the internal List used to hold the components created by the various process__() methods. It may be empty but will always be defined and will not contain any null entries. With that said, the ONLY time it is specifically valid is after an XML document has been parsed with MTXPro or a subclass as the DefaultHandler! This method is provided to allow use of MTXPro as a handler but without using its built-in parse__() methods.


processQuestion

public java.lang.Object processQuestion(java.lang.String pID,
                                        java.lang.String pProblem,
                                        java.lang.String pAnswer)
The parser has completed a Question tag. Override this method to do something with it. The default implementation creates a Question object around the data sent in and returns it. By default, endElement() calls this method and, if the return is not null, adds it to the list it returns. If the return is null, it is NOT added to the list.

Parameters:
pID - The ID from the Question tag. May be null.
pProblem - The content of the Problem tag. May be null.
pAnswer - The content of the Answer tag. May be null.
Returns:
An Object to add to the return list, or null to add nothing.

processMMatrix

public java.lang.Object processMMatrix(java.lang.String pID,
                                       java.lang.String pData)
The processor has detected a MMatrix tag. Override this method to do something with it. The default implementation creates and returns a MMatrix based on the data sent in. The ID is ignored, and if the data is null so is the return value.

Parameters:
pID - The value of the tag's 'id=' attribute, if present.
pData - The value of the tag's 'data=' attribute. If null, this method returns null.

processPolynomial

public java.lang.Object processPolynomial(java.lang.String pID,
                                          java.lang.String pData)
The processor has detected a Polynomial tag. Override this method to do something with it. The default implementation creates and returns a Polynomial based on the data sent in. The ID is ignored, and if the data is null so is the return value.

Parameters:
pID - The value of the tag's 'id=' attribute, if present.
pData - The value of the tag's 'data=' attribute. If null, this method returns null.

processMFraction

public java.lang.Object processMFraction(java.lang.String pID,
                                         java.lang.String pNumerator,
                                         java.lang.String pDenominator)
The processor found a MFraction tag. The numerator and denominator attributes are passed as String; the default implementation concatenates them around a slash character and creates a MFraction to return. If either is null or empty the return is null.

Parameters:
pID - The value of the tag's id attribute, if present.
pNumerator - The String value of the tag's 'numerator=' attribute.
pDenominator - The String value of the tag's 'denominator=' attribute.

processMathStat

public java.lang.Object processMathStat(java.lang.String pData,
                                        java.lang.String pData2)
The processor has a MathStat tag. This method creates a new MathStat instance from it.

Parameters:
pData - The primary data set as a space-separated String.
pData2 - The second data set, space-separated.

processMEquation

public java.lang.Object processMEquation(java.lang.String pData)
The processor has data for a MEquation. The raw data string is sent and converted here. If the data String is not properly constructed, null is returned.


processMRadical

public java.lang.Object processMRadical(java.lang.String pID,
                                        int pRadicand,
                                        int pIndex)
Process a MRadical tag. The radicand and index are converted when the tag is parsed; if either is not a valid int, this method is not called.


processMComplex

public java.lang.Object processMComplex(java.lang.String pCplx)
Process a MComplex tag. The return value will never be null.


processMTFI

public java.lang.Object processMTFI(java.lang.String pType,
                                    java.lang.String pContent)
Process a MFormatElement. This is the ONE valid use of the class constructor! Proper types and content are not enforced; USE WITH CAUTION!

Parameters:
pType - The MFormatElement type. If null or empty the return value is null.
pContent - The element content.

isTransformAvailable

public boolean isTransformAvailable()
Check to see if an XSLT Transformer is avaiable. Always check this method once! If it returns true, XSLT machinery is in place. If not, download the JAR, add the file's URL, set the TransformerFactory class, and try again.


transformData

public void transformData(javax.xml.transform.Source pData,
                          javax.xml.transform.Source pStyle,
                          javax.xml.transform.Result pResult)
                   throws javax.xml.transform.TransformerConfigurationException,
                          javax.xml.transform.TransformerException
This method is the basic XLST Transform method. It transforms pData by means of pStyle into pResult. All other transform methods use this one. If the stylesheet is null the identity transform is used.

Parameters:
pData - The XML data to be transformed.
pStyle - The XLST Stylesheet to use for the transformation.
pResult - The result of transforming pData by pStyle.
Throws:
javax.xml.transform.TransformerConfigurationException - If something goes wrong instantiating a Transformer.
javax.xml.transform.TransformerException - If there is a problem transforming the data.

transformData

public java.lang.String transformData(java.lang.String pData,
                                      java.lang.String pStyle,
                                      boolean pRawData,
                                      boolean pRawStyle)
This is the scripting transform method. It can use a file or String as the data or the stylesheet and it returns the result as a String.

Parameters:
pData - The raw XML data or the name of the file where it lives.
pStyle - The XSLT Stylesheet or the name of the file containing it.
pRawData - true to interpret pData as raw data, false to interpret as a filename.
pRawStyle - true to interpret pStyle as the raw stylesheet, false for a filename.
Returns:
The result of the transform as a String.

transformFiles

public java.lang.String transformFiles(java.lang.String pData,
                                       java.lang.String pStyle)
This method transforms based on two filenames. That is, transformData(String, String, false, false).

Parameters:
pData - The XML data file to be used.
pStyle - The XSLT stylesheet to transform the data.
Returns:
A String containing the result of the transformation.

setParameter

public void setParameter(java.lang.String pKey,
                         java.lang.String pValue)
Set a stylesheet parameter used for the transformation. Null or empty keys or values are silently ignored.


setParametersFromGlobalPizza

public void setParametersFromGlobalPizza()
Add the Global Pizza to the parameters fed to the transform. NOTE: The Global Pizza cannot be un-added! Use with caution. Any Exceptions are reported at Debug level.


clearParameters

public void clearParameters()
Remove all previously-set parameters. This does NOT affect default values in the stylesheet, only those from setParameter().


setOutputProperty

public void setOutputProperty(java.lang.String pKey,
                              java.lang.String pValue)

Set an Output Property to be used by the transformer. Output properties set with this method are collected and added when the Transformer is created. Any Exceptions thrown are reported at Debug level. Add properties carefully; if the Transformer chokes on multiple entries there will be multiple stack traces printed! Empty or null keys or values are silently ignored.

Regardless of badd Output Property values, the transform will continue.


clearOutputProperties

public void clearOutputProperties()
Clear all previously-set Transformer Output Properties.


isDOMAvailable

public boolean isDOMAvailable()

Check to see if XML DOM equipment is available. Details are reported at Debug level. This method should be checked at least once when the MathTools environmentor configuration changes.

Calling this method creates a DOM DocumentBuilderFactory and a DocumentBuilder. These instances remain in effect until cleared by a call to resetDOM(). Any DOM Features or Attributes must be set before calling this method, otherwise they will be ignored. Care should also be exercised in calling resetDOM() as this will ALSO clear all Features and Attributes. The ideal sequence of events to ensure proper setting is:

  1. Issue a call to resetDOM(). If the script is just starting this is not necessary.
  2. Set all Attributes and Features.
  3. Call isDOMAvailable() to create a DocumentBuilderFactory with all Attributes and Features set.
If an Attribute or Feature cannot be set that Attribute or Feature only is reported at Debug level. Attempts to set all remaining Features and Attributes will be made.


setDOMFactoryClassName

public void setDOMFactoryClassName(java.lang.String pName)
Set (or clear) the class name used to create a DOM DocumentBuilderFactory. If a ClassLoader is set and this name is not null or empty, the full version of DocumentBuilderFactory.newInstance() is used. ClassLoader rules are per the SAX parser and Transformers; they share the same ClassLoader.

Parameters:
pName - The fully-qualified class name of the DOM DocumentBuilderFactory to be used, or null to clear it.

resetDOM

public void resetDOM()

Clear and reset all DOM-related machinery except the DocumentBuilderFactory class name. If the name is set it must be cleared manually.

NOTE: Calling this method does clear all previously-set Features and Attributes.


newDocument

public org.w3c.dom.Document newDocument()
Create a new, blank DOM document. This method does call isDOMAvailable() and returns null if it is not.


transformDOM

public java.lang.String transformDOM(org.w3c.dom.Node pSource,
                                     java.lang.String pStyle,
                                     boolean pRawStyle)
Transform a DOM Document (or any Node) via XSLT. If pStyle is null the identity transform is used.

Parameters:
pSource - The DOM Node to transform. If null, an empty String is returned.
pStyle - The XSLT Stylesheet to use for the transformation.
pRawStyle - true to interpret the stylesheet as raw data, false to read it as a file.
Returns:
The String containing the transformed data.

transformNode

public org.w3c.dom.Node transformNode(org.w3c.dom.Node pSource,
                                      java.lang.String pStyle,
                                      boolean pRawStyle)
Transform a DOM Node into another Node via XSLT. Any Exceptions are reported at Error level and the result will be null.

Parameters:
pSource - The DOM Node to transform. If null, an empty String is returned.
pStyle - The XSLT Stylesheet to use for the transformation or null for the identity transform.
pRawStyle - true to interpret the stylesheet as raw data, false to read it as a file.
Returns:
The transformed Node, or null if some catastrophe occurred.

parseDOM

public org.w3c.dom.Document parseDOM(java.lang.String pData,
                                     boolean pRawData)
Parse XML into a DOM tree. The source data String can be interpreted as raw data or as a filename. MTXPro sets itself as the ErrorHandler and will receive all parsing error messages at the appropriate level. (Per the other parse__() methods. The only difference is that a DOM Document is returned. Any non-parsing errors are reported at Error level, and if they occur the return value is null.

Parameters:
pData - The XML to parse into a DOM tree. If blank or empty, this method returns null.
pRawData - true to interpret pSource as raw data, false to interpret as a filename.
Returns:
A fresh DOM Document, or null if an error occurred.

setDOMFeature

public void setDOMFeature(java.lang.String pName,
                          boolean pValue)

Use this method to set a DOM Feature on the DocumentBuilderFactory. These features are saved and set when the DocumentBuilder is actually created, so any incompatibilities will be reported then. NOTE: calling this method after isDOMAvailable() will NOT work! Features must be set before the factory itself is instantiated. Calling resetDOM() before setting features or attributes clears everything and guarantees that any feature set before the next call to isDOMAvailable() will attempt to set the features stored.

If a feature cannot be set it is reported at the Debug level but does NOT interrupt setting of other features. If pName is null or empty it is ignored silently.

Parameters:
pName - The name of the feature to set. Ignored if null or empty.
pValue - The boolean value to set the feature to.

setDOMAttribute

public void setDOMAttribute(java.lang.String pName,
                            java.lang.Object pValue)
This method sets a DOM Attribute on the current DOM DocumentBuilderFactory. As with features, these are stored until a new factory is instantiated. Set them before a call to isDOMAvailable() but after resetDOM(). If the Attribute name is null or empty it is ignored. If the Object value is null it is ignored.

Parameters:
pName - The name of the Attribute to set.
pValue - The Object value to be set.

isXPathAvailable

public boolean isXPathAvailable()
Check XPath availability. As with other methods of this type calling it attempts to create the necessary XPath equipment, so it should be checked at minimum once per configuration change. Any creation errors are reported at DEBUG level.

Returns:
true if an XPathFactory is successfully instantiated, false otherwise.

setXFeature

public void setXFeature(java.lang.String pName,
                        boolean pValue)
Set an XPath feature. If pName is null or blank this method returns silently. If no XPathFactory instance has been created this method returns silently; call isXPathAvailable() to create the factory. Any exceptions thrown are reported at DEBUG level.

Parameters:
pName - The name of the feature to set.
pValue - true to enable the feature, false to disable.

resetXPath

public void resetXPath()
Reset the current XPath configuration. This does NOT change the class name; if that is set it must be cleared manually.


applyXPath

public org.w3c.dom.Node applyXPath(java.lang.String pXPath,
                                   org.w3c.dom.Node pNode)

This method applies the specified XPath to the supplied DOM Node. If pXPath is null or blank or pNode is null the return value is null. If an error occurs it is reported at ERROR level and the return value is null. This method does not check the availability method but does ensure that an XPath factory is defined; if not it returns null.

Internally the XPath application specifies a NodeList. If this list contains one element it is returned. If it contains more than one element each Node is added to a DocumentFragment which is cast as Node and returned. The DocumentFragment is created from the first node's owning Document, if it exists. If not then the return value is the first node in the list. If the list contains only one Node then it is returned.

The XPath context object and method return values are both DOM Node instances. This allows multiple successive XPath applications. The final result can then be transformed into whatever form or format is desired.

Parameters:
pXPath - The XPath string to evaluate against the Node supplied.
pNode - The DOM Node the XPath is applied against.
Returns:
The result, as a DOM Node, of applying the XPath to the Node sent in.

parseGraph

public GraphPaper parseGraph(GraphEngine pEngine,
                             java.lang.String pGraphSource,
                             boolean pRawData)
This method is used to parse cox.jmatt.java.MathTools.graphing.xml package XML markup into a GraphPaper instance. Specific details are here. If pGraphSource is null or blank the method returns null immediately. Any parse errors are reported at Error level, although some internal errors are reported at Debug.

Parameters:
pEngine - The GraphEngine to use in building the graph. If null, GraphEngineXML is used.
pGraphSource - The source of the XML to convert.
pRawData - true to parse the source as raw data, false to interpret it as a filename.
Returns:
A GraphPaper from the supplied engine, complete with components properly added.