javawrapper.ParseReader Class Reference

Processes SAX parser output. More...

List of all members.

Public Member Functions

 ParseReader (GUIManager oManager)
 Constructor.
void TriggerSetup () throws ModelException
 The parser triggers this when it encounters the end of the "trees" tag.
void ReadDataTag (String sTagName, String sData, AttributesImpl oAttributes) throws ModelException
 Processes a data tag.
void EndFile () throws ModelException
 Call this to notify that the end of the file has been reached.
void ReadParentTag (String sTagName, Attributes oParentAttributes) throws ModelException
 Processes an opening tag.

Protected Member Functions

void FeedData () throws ModelException
 Feeds saved data to the data objects.
Grid FindGrid (String sXMLTag) throws ModelException
 Finds the grid for an XML tag.
boolean AssignDataObject (String sXMLTag, Attributes oAttributes, String sValue) throws ModelException
 Assigns the value of a single entity based on its XML tag.
boolean AssignDataVector () throws ModelException
 Assigns the values in mp_oValues to a vector-based data entity based on a match between its XML tag and m_sLastParentTagRead.
void AssignParentTag (String sXMLTag, Attributes oAttributes) throws ModelException
 Passes a parent tag (empty, no data) to the WorkerBase-descended objects for processing.

Protected Attributes

Vector< String > mp_oTagStack = new Vector<String>(0)
 Contains the stack of tags, in order, that led to the currently parsed tag.
String m_sStackQueue
 The next XML tag to push to the tag stack.
int m_iPopCounter = 0
 The number of tags that are currently waiting to be popped off the tag stack.

Private Member Functions

void ManageStack ()
 Manages the tag stack.

Private Attributes

GUIManager m_oManager
 GUIManager object - for access to objects.
TreePopulation m_oPop
 TreePopulation object.
Behavior m_oBehavior
 Behavior object - so we can refer back to it while parsing.
Grid m_oGrid = null
 Grid object - so we can refer back to it while parsing.
Vector< String > mp_oValues = new Vector<String>(0)
 List of values to collect until it's time to pass them.
Vector< AttributesImpl > mp_oAttributes = new Vector<AttributesImpl>(0)
 List of attributes collected.
Vector< String > mp_oTags = new Vector<String>(0)
 List of XML tags collected with a vector.
AttributesImpl m_oParentAttributes
 Attributes of a parent tag.
boolean[] mp_bAppliesTo
 Array of booleans, one per species, that for each says whether or not there's a value.
String m_sLastTagRead
 The last tag read.
String m_sLastParentTagRead
 The last parent tag read.
int m_iPackageIndex
 When parsing packages, this is the index of the current package (or -1 if the current map is not owned by this behavior).
int m_iCurrentXCell
 When parsing grid maps, the current X grid cell.
int m_iCurrentYCell
 When parsing grid maps, the current Y grid cell.


Detailed Description

Processes SAX parser output.

This object is notified by the parser in the following circumstances: 1) when a parent tag is read, and 2) when a data tag is read. The tag, its data, and any attributes are passed together. This class interfaces with the WorkerBase objects managed by the GUIManager to pass data to these objects.

There are two general types of SORTIE data: single pieces of information, and species-specific data where there is a value for each of several species. This class delays passing on the data for one tag reading so it can recognize patterns and act appropriately. For instance, a repeating tag indicates species-specific values. So while the DefaultHandler class delays sending data to this class until it knows enough about how to classify the data it is collecting, this class does the same. This means the data being assigned to WorkerBase objects is usually several elements behind what the parser is sending.

WorkerBase objects need context for their data, often caring what tag an XML element appeared inside. In order to pass along this information, this class maintains a hierarchy of the current chain of XML tags down to the one being processed. This hierarchy is functionally similar to a computer memory stack (last-in-first-out), so I refer to it as the "tag stack". The DefaultHandler class indicates when to push new tags onto the stack and pop off existing ones. But, since this class processes information at a delay, there's a lot of extra functionality to ensure that the tag stack represents the situation FOR THE XML ELEMENT CURRENTLY BEING PASSED TO WorkerBase OBJECTS, instead of for the data being passed by DefaultHandler.

There is a string variable where DefaultHandler can place a tag that needs to be pushed onto the stack (m_sStackQueue). Once this class has finished all other processing, it always immediately empties the stack queue. Due to the way DefaultHandler passes parent tags, there can never be more than one tag to push without this class getting a chance to handle it.

When DefaultHandler encounters closing tags of tags within the stack, it increments a counter of number of times the stack needs popping. The counter is used because, if the DefaultHandler encounters several closing tags in a row, it's probably going to wait until it encounters another opening tag before notifying ParseReader. ParseReader may be a couple tags behind. If there's a tag in the stack queue when ParseReader is notified to process an element (indicating that the parser has moved on to a new parent tag at least at the same level as the lowest stack level), it knows that the element it's passing on to the WorkerBase objects is the last in its particular parent tag and it's safe to pop the stack. It pops the stack the requested number of times and then pushes on the tag in the queue. If there is no tag in the queue, even if the pop counter is greater than 0, ParseReader won't pop the stack because it knows that it's not finished processing the elements for the current stack configuration.

The way the tag stack works, when processing species-specific data, the lowest tag in the hierarchy is actually the species-specific tag itself, not its immediate parent. The parent is one level up. It's easier to check for this when finding the parent than to prevent it.

Copyright: Copyright (c) Charles D. Canham 2003

Company: Institute of Ecosystem Studies

Author:
Lora E. Murphy
Version:
1.0

Edit history:
------------------
April 28, 2004: Submitted in beta version (LEM)
January 4, 2005: Added the tag stack (LEM)
April 12, 2011: Set this to ignore ghosts (LEM)

Constructor & Destructor Documentation

javawrapper.ParseReader.ParseReader ( GUIManager  oManager  ) 

Constructor.

Parameters:
oManager GUIManager object.


Member Function Documentation

void javawrapper.ParseReader.TriggerSetup (  )  throws ModelException

The parser triggers this when it encounters the end of the "trees" tag.

I know this is kludgy, but I don't have a better way to do it. Doing it at the start of another tag is dangerous; you can't be sure what it will be. You must set up before any grid maps are read, but if you trigger it on encountering a grid tag in this object, you might call setup multiple times. Which is not good. This is inelegant but it works.

Exceptions:
ModelException if the GUIManager does.

void javawrapper.ParseReader.ReadDataTag ( String  sTagName,
String  sData,
AttributesImpl  oAttributes 
) throws ModelException

Processes a data tag.

Some tags are handled directly by this object.

  • behaviorName - the behavior corresponding to this tag is found and a reference to it stashed.
  • version - the version number is compared to the behavior's version and an error is thrown if it doesn't match.
When a tag is not to be handled by this object, it is compared with the last tag read. If they are different, the PREVIOUS tag is known to be a single value and is passed with its data for assignment to the WorkerBase objects. If the tag is the same as the last tag read, then its value is added to a vector and saved up for passing all at once.
Parameters:
sTagName Tag name.
sData Data inside the tag.
oAttributes Attributes of the tag.
Exceptions:
ModelException if there is a problem processing the data.

void javawrapper.ParseReader.ManageStack (  )  [private]

Manages the tag stack.

This should be called after all current data processing needs have been met. This method updates the stack with any events queued up. First, it checks to see if it needs to pop the stack. There must be a tag waiting in the stack queue before popping, to ensure that we are finished processing the tags under the existing tag configuration. This pops the stack until the pop counter is at zero. Then it will push any tag waiting in the queue onto the stack.

There are a few tags (all within the core data structure) which don't fit in the normal SORTIE structure and will mess up the stack if we let them in. We trap for those tags and keep them off the stack altogether.

void javawrapper.ParseReader.FeedData (  )  throws ModelException [protected]

Feeds saved data to the data objects.

Exceptions:
ModelException if the data cannot be assigned.

void javawrapper.ParseReader.EndFile (  )  throws ModelException

Call this to notify that the end of the file has been reached.

Exceptions:
ModelException if any leftover data cannot be assigned.

void javawrapper.ParseReader.ReadParentTag ( String  sTagName,
Attributes  oParentAttributes 
) throws ModelException

Processes an opening tag.

If there is outstanding data, it is sent for reading. Certain tags get special processing. They are:

  • tr_species - treated like a data tag with its attributes added to the attributes vector.
  • tr_sizeClass - treated like a data tag with its attributes added to the attributes vector.
  • applyTo - species and type attributes are removed and assigned directly to the behavior in m_oBehavior
Parameters:
sTagName Tag name.
oParentAttributes Attributes of this parent tag.
Exceptions:
ModelException if data cannot be assigned.

Grid javawrapper.ParseReader.FindGrid ( String  sXMLTag  )  throws ModelException [protected]

Finds the grid for an XML tag.

Parameters:
sXMLTag The grid's name.
Returns:
The Grid object.
Exceptions:
ModelException if the grid cannot be found.

boolean javawrapper.ParseReader.AssignDataObject ( String  sXMLTag,
Attributes  oAttributes,
String  sValue 
) throws ModelException [protected]

Assigns the value of a single entity based on its XML tag.

This loops through all WorkerBase-descended objects under management by the GUIManager and hands them each the data to see if they are successful at finding the object to which it belongs.

Parameters:
sXMLTag XML tag
oAttributes of XML tag to assign
sValue Value to assign
Returns:
true if object to which the data should be assigned was successfully found, false if not.
Exceptions:
ModelException if the data cannot be assigned to the object to which it belongs.

boolean javawrapper.ParseReader.AssignDataVector (  )  throws ModelException [protected]

Assigns the values in mp_oValues to a vector-based data entity based on a match between its XML tag and m_sLastParentTagRead.

This loops through all WorkerBase-descended objects under management by the GUIManager and hands them each the data to see if they are successful at finding the object to which it belongs.

Returns:
true if value was successfully set, false if not.
Exceptions:
ModelException if the data cannot be assigned to the object to which it belongs.

void javawrapper.ParseReader.AssignParentTag ( String  sXMLTag,
Attributes  oAttributes 
) throws ModelException [protected]

Passes a parent tag (empty, no data) to the WorkerBase-descended objects for processing.

Exceptions:
ModelException if there is a problem with the data.
Parameters:
sXMLTag tag XML tag to pass.
oAttributes Attributes of the tag.


Member Data Documentation

Vector<String> javawrapper.ParseReader.mp_oTagStack = new Vector<String>(0) [protected]

Contains the stack of tags, in order, that led to the currently parsed tag.

The root tag is at 0, descending from there.

The next XML tag to push to the tag stack.

The number of tags that are currently waiting to be popped off the tag stack.

GUIManager object - for access to objects.

TreePopulation object.

Behavior object - so we can refer back to it while parsing.

Grid object - so we can refer back to it while parsing.

Vector<String> javawrapper.ParseReader.mp_oValues = new Vector<String>(0) [private]

List of values to collect until it's time to pass them.

Vector<AttributesImpl> javawrapper.ParseReader.mp_oAttributes = new Vector<AttributesImpl>(0) [private]

List of attributes collected.

Vector<String> javawrapper.ParseReader.mp_oTags = new Vector<String>(0) [private]

List of XML tags collected with a vector.

Attributes of a parent tag.

Array of booleans, one per species, that for each says whether or not there's a value.

The last tag read.

The last parent tag read.

When parsing packages, this is the index of the current package (or -1 if the current map is not owned by this behavior).

When parsing grid maps, the current X grid cell.

When parsing grid maps, the current Y grid cell.


The documentation for this class was generated from the following file:

Generated on Tue Apr 19 13:59:43 2011 for SORTIE Java Interface by  doxygen 1.5.6