|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectcom.microstar.xml.HandlerBase
ptolemy.moml.MoMLParser
This class constructs Ptolemy II models from specifications in MoML (modeling markup language), which is based on XML. 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 call its parse() method. The returned value is top-level composite entity of the model.
For convenience, there are several forms of the parse method. Most of these take two arguments, a base, and some specification of the MoML to parse (a stream or the text itself). The base is used to interpret relative URLs that might be present in the MoML. For example, the base might be the document base of an applet. An applet might use this class as follows:
MoMLParser parser = new MoMLParser(); URL docBase = getDocumentBase(); URL xmlFile = new URL(docBase, modelURL); NamedObj toplevel = parser.parse(docBase, xmlFile);If the first argument to parse() is null, then it is assumed that all URLs in the MoML file are absolute.
It can be difficult to create an appropriate URL to give as a base, particularly if what you have is a file or file name in the directory that you want to use as a base. The easiest technique is to use the toURL() method of the File class. Some of the URL constructors, for reasons we don't understand, create URLs that do not work.
The MoML code given to a parse() method may be a fragment, and does not need to include the "<?xml ... >" element nor the DOCTYPE specification. However, if the DOCTYPE specification is not given, then the DTD will not be read. The main consequence of this, given the parser we are using, is that default values for attributes will not be set. This could cause errors. The parser itself is not a validating parser, however, so it makes very limited use of the DTD. This may change in the future, so it is best to give the DOCTYPE element.
The parse() methods can be used for incremental parsing. After creating an initial model using a call to parse(), further MoML fragments without top-level entity or derived objects can be evaluated to modify the model. You can specify the context in which the MoML to be interpreted by calling setContext(). However, the XML parser limits each fragment to one element. So there always has to be one top-level element. If you wish to evaluate a group of MoML elements in some context, set the context and then place your MoML elements within a group element, as follows:
<group> ... sequence of MoML elements ... </group>The group element is ignored, and just serves to aggregate the MoML elements, unless it has a name attribute. If it has a name attribute, then the name becomes a prefix (separated by a colon) of all the names of items immediately in the group element. If the value of the name attribute is "auto", then the group is treated specially. Each item immediately contained by the group (i.e. not deeply contained) will be created with its specified name or a modified version of that name that does not match a pre-existing object already contained by the container. That is, when name="auto" is specified, each item is forced to be created with unique name, rather than possibly matching a pre-existing item.
The parse methods throw a variety of exceptions if the parsed data does not represent a valid MoML file or if the stream cannot be read for some reason.
This parser supports the way Ptolemy II handles hierarchical models, where components are instances cloned from reference models called "classes." A model (a composite entity) is a "class" in Ptolemy II if the elementName field of its MoMLInfo object is the string "class". If a component is cloned from a class, then when that component exports MoML, it references the class from which it was cloned and exports only differences from that class. I.e., if further changes are made to the component, it is important that when the component exports MoML, that those changes are represented in the exported MoML. This effectively implements an inheritance mechanism, where a component inherits all the features of the master from which it is cloned, but then extends the model with its own changes.
This class always processes MoML commands in the following order within a "class" or "entity" element, irrespective of the order in which they appear:
This class works closely with MoMLChangeRequest to implement another feature of Ptolemy II hierarchy. In particular, if an entity is cloned from another that identifies itself as a "class", then any changes that are made to the class via a MoMLChangeRequest are also made to the clone. This parser ensures that those changes are not exported when MoML is exported by the clone, because they will be exported when the master exports MoML.
MoMLChangeRequest
| Red (johnr) |
| Red (eal) |
| Field Summary | |
static java.util.List |
inputFileNamesToSkip
List of Strings that name files to be skipped. |
static java.lang.String |
MoML_DTD_1
The standard MoML DTD, represented as a string. |
static java.lang.String |
MoML_PUBLIC_ID_1
The public ID for version 1 MoML. |
| Constructor Summary | |
MoMLParser()
Construct a parser that creates a new workspace into which to put the entities created by the parse() method. |
|
MoMLParser(Workspace workspace)
Construct a parser that creates entities in the specified workspace. |
|
MoMLParser(Workspace workspace,
java.lang.ClassLoader loader)
Construct a parser that creates entities in the specified workspace. |
|
| Method Summary | |
protected java.lang.String |
_currentExternalEntity()
Get the the URI for the current external entity. |
void |
addMoMLFilter(MoMLFilter filter)
Add a MoMLFilter to the end of the list of MoMLFilters used to translate names. |
void |
addMoMLFilters(java.util.List filterList)
Add a List of MoMLFilters to the end of the list of MoMLFilters used to translate names. |
void |
attribute(java.lang.String name,
java.lang.String value,
boolean specified)
Handle an attribute assignment that is part of an XML element. |
void |
changeExecuted(ChangeRequest change)
React to a change request has been successfully executed. |
void |
changeFailed(ChangeRequest change,
java.lang.Exception exception)
React to a change request has resulted in an exception. |
void |
charData(char[] chars,
int offset,
int length)
Handle character data. |
void |
doctypeDecl(java.lang.String name,
java.lang.String publicID,
java.lang.String systemID)
If a public ID is given, and is not that of MoML, then throw a CancelException, which causes the parse to abort and return null. |
void |
endDocument()
End the document. |
void |
endElement(java.lang.String elementName)
End an element. |
void |
endExternalEntity(java.lang.String systemID)
Handle the end of an external entity. |
void |
error(java.lang.String message,
java.lang.String systemID,
int line,
int column)
Indicate a fatal XML parsing error. |
java.net.URL |
fileNameToURL(java.lang.String source,
java.net.URL base)
Given a file name or URL description, find a URL on which openStream() will work. |
static ErrorHandler |
getErrorHandler()
Get the error handler to handle parsing errors. |
java.util.List |
getMoMLFilters()
Get the List of MoMLFilters used to translate names. |
NamedObj |
getToplevel()
Get the top-level entity associated with this parser, or null if none. |
static boolean |
isModified()
Return the value set by setModified(), or false if setModified() has yet not been called. |
NamedObj |
parse(java.lang.String text)
Parse the given string, which contains MoML. |
NamedObj |
parse(java.net.URL base,
java.io.InputStream input)
Parse the given stream, using the specified url as the base to expand any external references within the MoML file. |
NamedObj |
parse(java.net.URL base,
java.io.Reader reader)
Parse the given stream, using the specified url as the base to expand any external references within the MoML file. |
NamedObj |
parse(java.net.URL base,
java.lang.String text)
Parse the given string, which contains MoML, using the specified base to evaluate relative references. |
NamedObj |
parse(java.net.URL base,
java.net.URL input)
Parse the MoML file at the given URL, which may be a file on the local file system, using the specified base to expand any relative references within the MoML file. |
NamedObj |
parseFile(java.lang.String filename)
Parse the file with the given name, which contains MoML. |
void |
processingInstruction(java.lang.String target,
java.lang.String data)
Handle a processing instruction. |
static void |
purgeModelRecord(java.lang.String filename)
Purge any record of a model opened from the specified file name. |
static void |
purgeModelRecord(java.net.URL url)
Purge any record of a model opened from the specified URL. |
void |
reset()
Reset the MoML parser, forgetting about any previously parsed models. |
java.lang.Object |
resolveEntity(java.lang.String publicID,
java.lang.String systemID)
Resolve an external entity. |
ComponentEntity |
searchForClass(java.lang.String name,
java.lang.String source)
Given the name of a MoML class and a source URL, check to see whether this class has already been instantiated, and if so, return the previous instance. |
void |
setContext(NamedObj context)
Set the context for parsing. |
static void |
setErrorHandler(ErrorHandler handler)
Set the error handler to handle parsing errors. |
static void |
setModified(boolean modified)
Record whether the parsing of the moml modified the data. |
void |
setMoMLFilters(java.util.List filterList)
Set the list of MoMLFilters used to translate names. |
void |
setToplevel(NamedObj toplevel)
Set the top-level entity. |
void |
setUndoable(boolean undoable)
Set the current context as undoable. |
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 |
ignorableWhitespace |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static java.lang.String MoML_DTD_1
public static java.lang.String MoML_PUBLIC_ID_1
public static java.util.List inputFileNamesToSkip
| Constructor Detail |
public MoMLParser()
public MoMLParser(Workspace workspace)
workspace - The workspace into which to place entities.
public MoMLParser(Workspace workspace,
java.lang.ClassLoader loader)
workspace - The workspace into which to place entities.loader - The class loader that will be used to create classes,
or null if the the bootstrap class loader is to be used.| Method Detail |
public void addMoMLFilter(MoMLFilter filter)
filter - The MoMLFilter to add to the list of MoMLFilters.addMoMLFilters(List filterList),
getMoMLFilters(),
setMoMLFilters(List filterList)public void addMoMLFilters(java.util.List filterList)
filterList - The list of MoMLFilters to add to the
list of MoMLFilters to be used to translate names.addMoMLFilter(MoMLFilter filter),
getMoMLFilters(),
setMoMLFilters(List filterList)
public void attribute(java.lang.String name,
java.lang.String value,
boolean specified)
throws XmlException
attribute in interface XmlHandlerattribute in class HandlerBasename - 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.
XmlException - If the name or value is null.XmlHandler.attribute(java.lang.String, java.lang.String, boolean)public void changeExecuted(ChangeRequest change)
changeExecuted in interface ChangeListenerchange - The change that has been executed, or null if
the change was not done via a ChangeRequest.
public void changeFailed(ChangeRequest change,
java.lang.Exception exception)
changeFailed in interface ChangeListenerchange - The change that was attempted or null if
the change was not done via a ChangeRequest.exception - The exception that resulted.
public void charData(char[] chars,
int offset,
int length)
charData in interface XmlHandlercharData in class HandlerBasechars - The character data.offset - The starting position in the array.length - The number of characters available.XmlHandler.charData(char[], int, int)
public void doctypeDecl(java.lang.String name,
java.lang.String publicID,
java.lang.String systemID)
throws CancelException
doctypeDecl in interface XmlHandlerdoctypeDecl in class HandlerBasename - The name of the document type.publicID - The public ID of the document type.systemID - The system ID of the document type.
CancelException - If the public ID is not that of MoML.XmlHandler.doctypeDecl(java.lang.String, java.lang.String, java.lang.String)
public void endDocument()
throws java.lang.Exception
endDocument in interface XmlHandlerendDocument in class HandlerBaseCancelException - If an error occurs parsing one of the
parameter values, and the user clicks on "cancel" to cancel the
parse.
java.lang.Exception - Derived methods may throw exceptions.XmlHandler.endDocument()
public void endElement(java.lang.String elementName)
throws java.lang.Exception
endElement in interface XmlHandlerendElement in class HandlerBaseelementName - The element type name.
java.lang.Exception - Derived methods may throw exceptions.XmlHandler.endElement(java.lang.String)public void endExternalEntity(java.lang.String systemID)
endExternalEntity in interface XmlHandlerendExternalEntity in class HandlerBasesystemID - The URI for the external entity.XmlHandler.endExternalEntity(java.lang.String)
public void error(java.lang.String message,
java.lang.String systemID,
int line,
int column)
throws XmlException
error in interface XmlHandlererror in class HandlerBasemessage - 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.
XmlException - If called.XmlHandler.error(java.lang.String, java.lang.String, int, int)
public java.net.URL fileNameToURL(java.lang.String source,
java.net.URL base)
throws java.lang.Exception
NOTE: This may trigger a dialog with the user (about security concerns), and hence should be called in the event thread.
source - A file name or URL description.base - The base URL for relative references, or null if
there is none.
java.lang.Exception - If the file or URL cannot be found or
if the user cancels on being warned of a security concern.public static ErrorHandler getErrorHandler()
public java.util.List getMoMLFilters()
addMoMLFilter(MoMLFilter filter),
setMoMLFilters(List filterList)public NamedObj getToplevel()
public static boolean isModified()
setModified(boolean)
public NamedObj parse(java.net.URL base,
java.net.URL input)
throws java.lang.Exception
base - The base URL for relative references, or null if
not known.input - The stream from which to read XML.
java.lang.Exception - If the parser fails.purgeModelRecord(URL)
public NamedObj parse(java.net.URL base,
java.io.InputStream input)
throws java.lang.Exception
base - The base URL for relative references, or null if
not known.input - The stream from which to read XML.
java.lang.Exception - If the parser fails.
public NamedObj parse(java.net.URL base,
java.io.Reader reader)
throws java.lang.Exception
base - The base URL for relative references, or null if
not known.reader - The reader from which to read XML.
java.lang.Exception - If the parser fails.
public NamedObj parse(java.lang.String text)
throws java.lang.Exception
text - The string from which to read MoML.
java.lang.Exception - If the parser fails.
java.lang.SecurityException - If the user.dir system property is
not available.
public NamedObj parse(java.net.URL base,
java.lang.String text)
throws java.lang.Exception
base - The base URL for relative references, or null if
not known.text - The string from which to read MoML.
java.lang.Exception - If the parser fails.
public NamedObj parseFile(java.lang.String filename)
throws java.lang.Exception
If you have an absolute pathname, rather than calling this method, you may want to try:
CompositeActor toplevel = (CompositeActor) parser.parse(null,
new File(xmlFilename).toURL());
Note that this method attempts to read the user.dir system property, which is not generally available in applets. Hence it is probably not a good idea to use this method in applet code, since it will probably fail outright.
If the file has already been parsed, then return the model that previously parsed. Note that this means that an application that opens and then closes a model and expects to re-parse the XML when re-opening should call purgeModelRecord() when closing it.
filename - The file name from which to read MoML.
java.lang.Exception - If the parser fails.
java.lang.SecurityException - If the user.dir system property is
not available.purgeModelRecord(String)
public void processingInstruction(java.lang.String target,
java.lang.String data)
processingInstruction in interface XmlHandlerprocessingInstruction in class HandlerBasetarget - The name of the processing instruction.data - The body of the processing instruction.XmlHandler.processingInstruction(java.lang.String, java.lang.String)public static void purgeModelRecord(java.net.URL url)
url - The URL.parse(URL, URL)
public static void purgeModelRecord(java.lang.String filename)
throws java.net.MalformedURLException
Note that this method attempts to read the user.dir system property, which is not generally available in applets. Hence it is probably not a good idea to use this method in applet code, since it will probably fail outright.
filename - The file name from which to read MoML.
java.net.MalformedURLException - If the file name cannot be converted to a URL.
java.lang.SecurityException - If the user.dir system property is
not available.parse(URL, String)public void reset()
public java.lang.Object resolveEntity(java.lang.String publicID,
java.lang.String systemID)
resolveEntity in interface XmlHandlerresolveEntity in class HandlerBasepublicID - The public identifier, or null if none was supplied.systemID - The system identifier.
XmlHandler.resolveEntity(java.lang.String, java.lang.String)
public ComponentEntity searchForClass(java.lang.String name,
java.lang.String source)
throws java.lang.Exception
name - The name of the MoML class to search for.source - The URL source
java.lang.Exceptionpublic void setContext(NamedObj context)
context - The context for parsing.public static void setErrorHandler(ErrorHandler handler)
handler - The ErrorHandler to call.public void setMoMLFilters(java.util.List filterList)
filterList - The List of MoMLFilters.addMoMLFilter(MoMLFilter filter),
getMoMLFilters()public static void setModified(boolean modified)
modified - True if the data was modified while parsing.isModified(),
MoMLFilterpublic void setToplevel(NamedObj toplevel)
toplevel - The top-level to associate with this parser.public void setUndoable(boolean undoable)
undoable - The new Undoable valuepublic void startDocument()
startDocument in interface XmlHandlerstartDocument in class HandlerBaseendDocument()
public void startElement(java.lang.String elementName)
throws XmlException
startElement in interface XmlHandlerstartElement in class HandlerBaseelementName - The element type name.
XmlException - If the element produces an error
in constructing the model.XmlHandler.startElement(java.lang.String)public void startExternalEntity(java.lang.String systemID)
startExternalEntity in interface XmlHandlerstartExternalEntity in class HandlerBasesystemID - The URI for the external entity.XmlHandler.startExternalEntity(java.lang.String)protected java.lang.String _currentExternalEntity()
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||