SAX parameter file parse handler. More...
Public Member Functions | |
| ParameterFileParser (GUIManager oManager) | |
| Constructor. More... | |
| void | startElement (String sURI, String sLocalName, String sQName, Attributes oAttributes) throws SAXException |
| Function called when an opening tag is encountered. More... | |
| void | characters (char[] p_cCh, int iStart, int iLength) throws SAXException |
| Reads character data from the XML file. More... | |
| void | endElement (String sURI, String sLocalName, String sQName) throws SAXException |
| Called at the end of an XML tag. More... | |
| void | endDocument () throws SAXException |
| Called when the end of the document is reached. More... | |
Private Attributes | |
| ParseReader | m_oParseReader |
| Object that will take care of the data parsed out. More... | |
| AttributesImpl | m_oAttributes |
| Place to stash attributes of a tag. More... | |
| StringBuffer | m_sBuf |
| String buffer to collect data in our parser. More... | |
| String | m_sTagName |
| Where we'll store the tag name of the element being parsed. More... | |
| boolean | m_bWasData |
| Whether or not the last tag was a data tag. More... | |
Detailed Description
SAX parameter file parse handler.
SAX parsers are usually lightweight and fast, which is why we're using it to parse SORTIE parameter files. SAX parsers process each XML element one at a time (opening tag, tag contents, tag closing), sending them on to the handler and then forgetting about it.
It's up to this handler class and its helper class "ParseReader" to build up the XML information into something meaningful to pass on to the rest of the application. SORTIE data comes in two forms: single pieces of information, and species-specific data where there is a value for each of several species. The ParseReader helper class takes responsibility for differentiating between the two.
This class primarily makes sure that information is fed in the right order to ParseReader, and in the proper context. That means knowing the difference between parent tags and child tags, and between empty tags that just define the hierarchy and tags with actual data. After a tag's type has been established, this class makes sure tags are passed in the proper order (parent tags before child tags).
The tricky thing about an XML element (tag plus data) is that you don't know what it is until you have processed all its events: the opening tag, the (optional) content, and the closing tag. This class has to wait until it has enough information to be able to tell ParseReader what kind of element it is passing. This means that by the time this class passes an element on to ParseReader, it is actually one or more tags further along in the document. It stashes the data about an element until it knows enough about it to pass.
Here's how it works: this class handles three key events: parsing an opening tag, parsing tag data, and parsing a closing tag. Obviously, during the opening tag and tag data events, all information passed is saved. Flags are set during these events so the tag can be passed to ParseReader later.
When an opening tag is encountered, this class looks at accumulated data for the last element it parsed. If that last element had no content in it (known because the handler for tag contents didn't process any data), it is passed on to ParseReader as an empty parent tag (and the current tag being processed is its first child). If the last element DID have content, nothing is done yet.
When an ending tag is encountered, this class checks the data for the last element parsed (NOT the one whose tag is currently being parsed). If it was a content-having element, it is passed to ParseReader at this time. (Passing content-having elements here - at an end tag - ensures that parents get passed before children. Even though we're always one tag behind, it still works. If a parent tag has a group of children within it, the very last child gets passed when the closing tag of the parent is encountered.)
In addition, this class helps ParseReader maintain a tag hierarchy list. In this way, ParseReader always knows the tag immediately above the tag it's processing.
Copyright: Copyright (c) Charles D. Canham 2003
Company: Cary Institute of Ecosystem Studies
- Version
- 1.0
Edit history:
---------------—
December 8, 2011: Wiped the slate clean for version 7 (LEM)
Constructor & Destructor Documentation
◆ ParameterFileParser()
| sortie.sax.ParameterFileParser.ParameterFileParser | ( | GUIManager | oManager | ) |
Constructor.
- Parameters
-
oManager GUIManager object.
Member Function Documentation
◆ characters()
| void sortie.sax.ParameterFileParser.characters | ( | char [] | p_cCh, |
| int | iStart, | ||
| int | iLength | ||
| ) | throws SAXException |
Reads character data from the XML file.
The data is appended to the string buffer. This is done because, according to the SAX parser specs, it is free to call this function multiple times per tag if it wants. So this function collects the data into a single buffer.
- Parameters
-
p_cCh The characters from the XML document. iStart - The start position in the array. iLength - The number of characters to read from the array.
- Exceptions
-
SAXException if any of the described cases above is true.
◆ endDocument()
| void sortie.sax.ParameterFileParser.endDocument | ( | ) | throws SAXException |
Called when the end of the document is reached.
- Exceptions
-
SAXException if any leftover data cannot be assigned.
◆ endElement()
| void sortie.sax.ParameterFileParser.endElement | ( | String | sURI, |
| String | sLocalName, | ||
| String | sQName | ||
| ) | throws SAXException |
Called at the end of an XML tag.
If this was a data tag, the accumulated data in the StringBuffer m_sBuf is passed. If the tag appears in the tag hierarchy stack for ParseReader, this lets it know that it needs to be popped by incrementing the pop counter.
This is actually the only place in this parse object that cares to look at what a tag is. When the closing tag for trees is found, it lets the ParseReader object know to do setup. This is a hack, and a bad one, but better than any elegant alternative I can think of.
- Parameters
-
sURI the Namespace URI (ignored) sLocalName the local name (what this function looks at) sQName the qualified (prefixed) name (ignored)
- Exceptions
-
SAXException if there were problems assigning the data.
◆ startElement()
| void sortie.sax.ParameterFileParser.startElement | ( | String | sURI, |
| String | sLocalName, | ||
| String | sQName, | ||
| Attributes | oAttributes | ||
| ) | throws SAXException |
Function called when an opening tag is encountered.
This captures the tag's attributes and initializes our StringBuffer to hold the tag's character data. It will also pass data for the last tag if it was a parent, and puts a new tag in ParseReader's tag stack queue. It does not pass data tags to ParseReader - this is because if we pass data tags here instead of in endElement the very last tag will not get passed. It DOES pass parents here to ensure the parent tag is passed before its child tags.
- Parameters
-
sURI the Namespace URI (ignored) sLocalName the local name (what this function looks at) sQName the qualified (prefixed) name (ignored) oAttributes The tag's attributes
- Exceptions
-
SAXException if there are any problems.
Member Data Documentation
◆ m_bWasData
|
private |
Whether or not the last tag was a data tag.
◆ m_oAttributes
|
private |
Place to stash attributes of a tag.
◆ m_oParseReader
|
private |
Object that will take care of the data parsed out.
◆ m_sBuf
|
private |
String buffer to collect data in our parser.
◆ m_sTagName
|
private |
Where we'll store the tag name of the element being parsed.
The documentation for this class was generated from the following file:
