ptolemy.plot.plotml

Class PlotBoxMLParser

java.lang.Object

com.microstar.xml.HandlerBase

ptolemy.plot.plotml.PlotBoxMLParser

All Implemented Interfaces:

com.microstar.xml.XmlHandler

Direct Known Subclasses:

PlotMLParser

public class PlotBoxMLParser
extends com.microstar.xml.HandlerBase

This class constructs a plot from specifications in PlotML (Plot Markup Language), which is an XML language. This class supports only the subset that applies to the PlotBox base class. It ignores all other elements in the DTD. The class contains an instance of the Microstar Ælfred XML parser and implements callback methods to interpret the parsed XML. The way to use this class is to construct it with a reference to a PlotBox object and then call its parse() method.

Since:

Ptolemy II 0.4

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	PlotML_DTD_1 The standard PlotML DTD, represented as a string.

Constructor Summary

Constructors

Constructor and Description
PlotBoxMLParser(PlotBox plot) Construct an parser to parse commands for the specified plot object.

Method Summary

Modifier and Type	Method and Description
void	attribute(java.lang.String name, java.lang.String value, boolean specified) Handle an attribute assignment that is part of an XML element.
void	charData(char[] chars, int offset, int length) Handle character data.
void	endDocument() End the document.
void	endElement(java.lang.String elementName) End an element.
void	error(java.lang.String message, java.lang.String systemID, int line, int column) Indicate a fatal XML parsing error.
void	parse(java.net.URL base, java.io.InputStream input) Parse the given stream as a PlotML file.
void	parse(java.net.URL base, java.io.Reader reader) Parse the given stream as a PlotML file.
void	parse(java.net.URL base, java.lang.String text) Parse the given text as PlotML.
java.lang.Object	resolveEntity(java.lang.String publicID, java.lang.String systemID) Resolve an external entity.
void	startDocument() Start a document.
void	startElement(java.lang.String elementName) Start an element.
void	startExternalEntity(java.lang.String systemID) Handle the start of an external entity.

Methods inherited from class com.microstar.xml.HandlerBase

doctypeDecl, endExternalEntity, ignorableWhitespace, processingInstruction

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PlotML_DTD_1

public static java.lang.String PlotML_DTD_1

The standard PlotML DTD, represented as a string. This is used to parse PlotML data when a compatible PUBLIC DTD is specified.

Constructor Detail

PlotBoxMLParser

public PlotBoxMLParser(PlotBox plot)

Construct an parser to parse commands for the specified plot object.

Parameters:

plot - The plot object to which to apply the commands.

Method Detail

attribute

public void attribute(java.lang.String name,
                      java.lang.String value,
                      boolean specified)
               throws com.microstar.xml.XmlException

Handle an attribute assignment that is part of an XML element. This method is called prior to the corresponding startElement() call, so it simply accumulates attributes in a hashtable for use by startElement().

Specified by:

attribute in interface com.microstar.xml.XmlHandler

Overrides:

attribute in class com.microstar.xml.HandlerBase

Parameters:

name - The name of the attribute.

value - The value of the attribute, or null if the attribute is #IMPLIED and not specified.

specified - True if the value is specified, false if the value comes from the default value in the DTD rather than from the XML file.

Throws:

com.microstar.xml.XmlException - If the name or value is null.

See Also:

XmlHandler.attribute(java.lang.String, java.lang.String, boolean)

charData

public void charData(char[] chars,
                     int offset,
                     int length)

Handle character data. In this implementation, the character data is accumulated in a buffer until the end element. Ælfred will call this method once for each chunk of character data found in the contents of elements. Note that the parser may break up a long sequence of characters into smaller chunks and call this method once for each chunk.

Specified by:

charData in interface com.microstar.xml.XmlHandler

Overrides:

charData in class com.microstar.xml.HandlerBase

Parameters:

chars - The character data.

offset - The starting position in the array.

length - The number of characters available.

See Also:

XmlHandler.charData(char[], int, int)

endDocument

public void endDocument()
                 throws java.lang.Exception

End the document. In this implementation, do nothing. Ælfred will call this method once, when it has finished parsing the XML document. It is guaranteed that this will be the last method called.

Specified by:

endDocument in interface com.microstar.xml.XmlHandler

Overrides:

endDocument in class com.microstar.xml.HandlerBase

Throws:

java.lang.Exception - The handler may throw any exception.

See Also:

XmlHandler.endDocument()

endElement

public void endElement(java.lang.String elementName)
                throws java.lang.Exception

End an element. For most elements this method calls the appropriate PlotBox method. Ælfred will call this method at the end of each element (including EMPTY elements).

Specified by:

endElement in interface com.microstar.xml.XmlHandler

Overrides:

endElement in class com.microstar.xml.HandlerBase

Parameters:

elementName - The element type name.

Throws:

java.lang.Exception - If thrown while invoking a method on the Plot object.

See Also:

XmlHandler.endElement(java.lang.String)

error

public void error(java.lang.String message,
                  java.lang.String systemID,
                  int line,
                  int column)
           throws com.microstar.xml.XmlException

Indicate a fatal XML parsing error. Ælfred will call this method whenever it encounters a serious error. This method simply throws an XmlException.

Specified by:

error in interface com.microstar.xml.XmlHandler

Overrides:

error in class com.microstar.xml.HandlerBase

Parameters:

message - The error message.

systemID - The URI of the entity that caused the error.

line - The approximate line number of the error.

column - The approximate column number of the error.

Throws:

com.microstar.xml.XmlException - If called.

See Also:

XmlHandler.error(java.lang.String, java.lang.String, int, int)

parse

public void parse(java.net.URL base,
                  java.io.InputStream input)
           throws java.lang.Exception

Parse the given stream as a PlotML file. For example, an applet might use this method as follows:

     PlotBoxMLParser parser = new PlotBoxMLParser();
     URL docBase = getDocumentBase();
     URL xmlFile = new URL(docBase, modelURL);
     parser.parse(xmlFile.openStream());
  

A variety of exceptions might be thrown if the parsed data does not represent a valid PlotML file.

Parameters:

base - The base URL for relative references, or null if there is none.

input - The stream from which to read XML.

Throws:

java.lang.Exception - If the parser fails.

parse

public void parse(java.net.URL base,
                  java.io.Reader reader)
           throws java.lang.Exception

Parse the given stream as a PlotML file. A variety of exceptions might be thrown if the parsed data does not represent a valid PlotML file.

Parameters:

base - The base URL for relative references, or null if there is none.

reader - The stream from which to read XML.

Throws:

java.lang.Exception - If the parser fails.

parse

public void parse(java.net.URL base,
                  java.lang.String text)
           throws java.lang.Exception

Parse the given text as PlotML. A variety of exceptions might be thrown if the parsed data does not represent valid PlotML data.

Parameters:

base - The base URL for relative references, or null if there is none.

text - The PlotML data.

Throws:

java.lang.Exception - If the parser fails.

resolveEntity

public java.lang.Object resolveEntity(java.lang.String publicID,
                                      java.lang.String systemID)

Resolve an external entity. If the first argument is the name of the PlotML PUBLIC DTD ("-//UC Berkeley//DTD PlotML 1//EN"), then return a StringReader that will read the locally cached version of this DTD (the public variable PlotML_DTD_1). Otherwise, return null, which has the effect of deferring to Ælfred for resolution of the URI. Derived classes may return a a modified URI (a string), an InputStream, or a Reader. In the latter two cases, the input character stream is provided.

Specified by:

resolveEntity in interface com.microstar.xml.XmlHandler

Overrides:

resolveEntity in class com.microstar.xml.HandlerBase

Parameters:

publicID - The public identifier, or null if none was supplied.

systemID - The system identifier.

Returns:

Null, indicating to use the default system identifier.

See Also:

XmlHandler.resolveEntity(java.lang.String, java.lang.String)

startDocument

public void startDocument()

Start a document. This method is called just before the parser attempts to read the first entity (the root of the document). It is guaranteed that this will be the first method called.

Specified by:

startDocument in interface com.microstar.xml.XmlHandler

Overrides:

startDocument in class com.microstar.xml.HandlerBase

See Also:

XmlHandler.startDocument()

startElement

public void startElement(java.lang.String elementName)
                  throws com.microstar.xml.XmlException

Start an element. This is called at the beginning of each XML element. By the time it is called, all of the attributes for the element will already have been reported using the attribute() method. Unrecognized elements are ignored.

Specified by:

startElement in interface com.microstar.xml.XmlHandler

Overrides:

startElement in class com.microstar.xml.HandlerBase

Parameters:

elementName - The element type name.

Throws:

com.microstar.xml.XmlException - If the element produces an error in constructing the model.

See Also:

XmlHandler.startElement(java.lang.String)

startExternalEntity

public void startExternalEntity(java.lang.String systemID)

Handle the start of an external entity. This pushes the stack so that error reporting correctly reports the external entity that causes the error.

Specified by:

startExternalEntity in interface com.microstar.xml.XmlHandler

Overrides:

startExternalEntity in class com.microstar.xml.HandlerBase

Parameters:

systemID - The URI for the external entity.

See Also:

XmlHandler.startExternalEntity(java.lang.String)