com.vividsolutions.jump.io
Class GMLReader

java.lang.Object
  extended by org.xml.sax.helpers.DefaultHandler
      extended by com.vividsolutions.jump.io.GMLReader
All Implemented Interfaces:
JUMPReader, org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public class GMLReader
extends org.xml.sax.helpers.DefaultHandler
implements JUMPReader

GMLReader is a JUMPReader specialized to read GML files.

DataProperties for the JCSReader load(DataProperties) interface:

Parameter Meaning
File or DefaultValue File name for the input .xml file
InputTemplateFile Filename for the GMLInputTemplate .xml file
CompressedFile File name (a .zip or .gz) with a .jml/.xml/.gml inside (specified by File)
CompressedFileTemplateFile name (.zip or .gz) with the input template in (specified by InputTemplateFile)


NOTE: If InputTemplateFile is unspecified, GMLReader will try to read one off the top of the input .xml file (the JCS format). This is the same as specifying the File and TemplateFile to be the same.

Typically, you would write:
     gmlReader = new GMLReader();
     gmlReader.load( DriverProperties) ; // has InputFile and InputTemplate
  
or:
     gmlReader.setInputTemplate( GMLInputTemplate);
     gmlReader.load(  ,  );
  


Internal Details - This is based on a small finite state machine with these states:

STATE MEANING
0 Init
1 Waiting for Collection tag
2 Waiting for Feature tag
3 Getting jcs columns
4 Parsing geometry (goes back to state 3)
1000 Parsing Multi-geometry, recursion level =1
1001 Parsing Multi-geometry, recursion level =2
...


State Diagram

init
        0  ----->  1
                   |
                   | Collection start Tag
                   |
                -->2---------------->     FINISH
                \  |   End Collection tag
 End Feature tag \ |
                  \|
        4<-------->3
           Geometry start/end

For multi-geometries
On start Multi-geometry, increment state by 1 (or jump to 1000 if at state 4)
make sure recursivegeometry[state-1000] is null


on end multi-geometry,
build geometry in recursivegeometry[state-1000], add it to recursivegeometry[state-1000-1]
state= state-1

For single geometries - they will be stuck into recursivegeometry[0], which is the same
as geometry

For multi geometries - they will also be stuck into recursivegeometry[0], which is the same
as geometry. But, for the first nested geometry, it will be stuck into recursivegeometry[1],
which will then be geometry
  example of double GCs:
  START geometry     ->move to state 4
  START TAG: multi*  -> move to state 1000, geometry = recursivegeometry[0]
  

  -> added to geometry 

  -> added to geometry START TAG: multi* -> move to state 1001, geometry =
  recursivegeometry[1] 

  -> added to geometry 

  -> added to geometry END TAG: multi -> move to state 1000, build geometry in
  recursivegeometry[1], add to recursivegeometry[0], geometry =
  recursivegeometry[0] 

  -> added to geometry END TAG: multi ->  move to state 4, build
  geometry in recursivegeometry[0] (thats the result) and put it in
  finalGeometry END geometry -> add to feature collection example of simple
  geometry: START geometry ->move to state 4 BEGIN polygon ->clear out inner
  ring accumulator BEGIN outerboundary BEGIN linearring END linearring -> put
  points in linearRing END outerboundary -> put linearRing in outerBoundary
  BEGIN innerboundary BEGIN linearring END linearring -> put points in
  linearRing END innerboundary -> add linearRing to innerBoundary list END
  polygon -> build polygon (put in geometry, which is recursivegeometry[0] END
  geometry => add to feature collection
  
Most of the work is done in the endTag method!

New additions: Jan 2005 by Dave Blasby allow srid to be parsed from the GML file For example: .... The SRID of the created geometry will be 42102. It accepts srsNames of the form ":". ie. "EPSG:111" or "DAVE:222" or "BCGOV:333" etc... The Geometry's SRID will be the number. If you have a GEOMETRYCOLLECTION with more than one SRID specified the SRID of the result will be indeterminate (this isnt correct GML). Geometries without a srsName will get SRID 0. This functionality defaults to off for compatibility. To turn it on or off, call the acceptSRID(true|false) function. New Addition: Jan, 2005by Dave Blasby Added slightly better support for type=OBJECT. It sticks a String in. Before it would probably throw an error. Added support for multi-objects for example: ...1... ...2... ...3... Old behavior would be to for column 'b' to have value "...3...". New behavior (only if you set b's type to 'OBJECT' and set the GMLReader to processMultiItems as lists) ...1... --> b get the string "...1..." (as before) ...1......2......3... --> 'b' is a list of String ['...1...','...2...','...3...']


Field Summary
 boolean multiItemsAsLists
          true => for 'OBJECT' types, if you find more than 1 item, make a list and store all the results
 boolean parseSRID
           
 
Constructor Summary
GMLReader()
          Constructor - make a SAXParser and have this GMLReader be its ContentHandler and ErrorHandler.
 
Method Summary
 void acceptSRID(boolean parseTheSRID)
          parse SRID information in geometry tags
 void characters(char[] ch, int start, int length)
          SAX handler - store and accumulate tag bodies
 void endDocument()
          SAX HANDLER - move to state 0
 void endElement(java.lang.String uri, java.lang.String name, java.lang.String qName)
          SAX handler - handle state information and transitions based on ending elements Most of the work of the parser is done here.
 void error(org.xml.sax.SAXParseException exception)
           
 void fatalError(org.xml.sax.SAXParseException exception)
           
 void processMultiItems(boolean accept)
          Added slightly better support for type=OBJECT.
 FeatureCollection read(DriverProperties dp)
          Main Entry - load in a GML file
 FeatureCollection read(java.io.Reader r)
          Helper function - calls read(java.io.Reader r,String readerName) with the readerName "Unknown Stream".
 FeatureCollection read(java.io.Reader r, java.lang.String readerName)
          Main function to read a GML file.
 void setInputTemplate(GMLInputTemplate template)
          Attach a GMLInputTemplate information class.
 void startDocument()
          SAX handler - move to state 1
 void startElement(java.lang.String uri, java.lang.String name, java.lang.String qName, org.xml.sax.Attributes atts)
          SAX handler.
 void warning(org.xml.sax.SAXParseException exception)
           
 
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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

parseSRID

public boolean parseSRID

multiItemsAsLists

public boolean multiItemsAsLists
true => for 'OBJECT' types, if you find more than 1 item, make a list and store all the results

Constructor Detail

GMLReader

public GMLReader()
Constructor - make a SAXParser and have this GMLReader be its ContentHandler and ErrorHandler.

Method Detail

acceptSRID

public void acceptSRID(boolean parseTheSRID)
parse SRID information in geometry tags

Parameters:
parseTheSRID - true = parse

processMultiItems

public void processMultiItems(boolean accept)
Added slightly better support for type=OBJECT. It sticks a String in. Before it would probably throw an error. Added support for multi-objects for example: ...1... ...2... ...3... Old behavior would be to for column 'b' to have value "...3...". New behavior (only if you set b's type to 'OBJECT' and set the GMLReader to processMultiItems as lists) ...1... --> b get the string "b" (as before) ...1......2......3... --> 'b' is a list of String ['...1...','...2...','...3...']


setInputTemplate

public void setInputTemplate(GMLInputTemplate template)
Attach a GMLInputTemplate information class.

Parameters:
template - The new inputTemplate value

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws org.xml.sax.SAXException
SAX handler - store and accumulate tag bodies

Specified by:
characters in interface org.xml.sax.ContentHandler
Overrides:
characters in class org.xml.sax.helpers.DefaultHandler
Parameters:
ch - Description of the Parameter
start - Description of the Parameter
length - Description of the Parameter
Throws:
org.xml.sax.SAXException - Description of the Exception

endDocument

public void endDocument()
SAX HANDLER - move to state 0

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

endElement

public void endElement(java.lang.String uri,
                       java.lang.String name,
                       java.lang.String qName)
                throws org.xml.sax.SAXException
SAX handler - handle state information and transitions based on ending elements Most of the work of the parser is done here.

Specified by:
endElement in interface org.xml.sax.ContentHandler
Overrides:
endElement in class org.xml.sax.helpers.DefaultHandler
Parameters:
uri - Description of the Parameter
name - Description of the Parameter
qName - Description of the Parameter
Throws:
org.xml.sax.SAXException - Description of the Exception

error

public void error(org.xml.sax.SAXParseException exception)
           throws org.xml.sax.SAXException
Specified by:
error in interface org.xml.sax.ErrorHandler
Overrides:
error in class org.xml.sax.helpers.DefaultHandler
Throws:
org.xml.sax.SAXException

fatalError

public void fatalError(org.xml.sax.SAXParseException exception)
                throws org.xml.sax.SAXException
Specified by:
fatalError in interface org.xml.sax.ErrorHandler
Overrides:
fatalError in class org.xml.sax.helpers.DefaultHandler
Throws:
org.xml.sax.SAXException

read

public FeatureCollection read(DriverProperties dp)
                       throws IllegalParametersException,
                              java.lang.Exception
Main Entry - load in a GML file

Specified by:
read in interface JUMPReader
Parameters:
dp - Description of the Parameter
Returns:
Description of the Return Value
Throws:
IllegalParametersException - Description of the Exception
java.lang.Exception - Description of the Exception

read

public FeatureCollection read(java.io.Reader r)
                       throws java.lang.Exception
Helper function - calls read(java.io.Reader r,String readerName) with the readerName "Unknown Stream". You should have already called setInputTempalate().

Parameters:
r - reader to read the GML File from
Returns:
Description of the Return Value
Throws:
java.lang.Exception - Description of the Exception

read

public FeatureCollection read(java.io.Reader r,
                              java.lang.String readerName)
                       throws java.lang.Exception
Main function to read a GML file. You should have already called setInputTempalate().

Parameters:
r - reader to read the GML File from
readerName - what to call the reader for error reporting
Returns:
Description of the Return Value
Throws:
java.lang.Exception - Description of the Exception

startDocument

public void startDocument()
SAX handler - move to state 1

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

startElement

public void startElement(java.lang.String uri,
                         java.lang.String name,
                         java.lang.String qName,
                         org.xml.sax.Attributes atts)
                  throws org.xml.sax.SAXException
SAX handler. Handle state and state transitions based on an element starting

Specified by:
startElement in interface org.xml.sax.ContentHandler
Overrides:
startElement in class org.xml.sax.helpers.DefaultHandler
Parameters:
uri - Description of the Parameter
name - Description of the Parameter
qName - Description of the Parameter
atts - Description of the Parameter
Throws:
org.xml.sax.SAXException - Description of the Exception

warning

public void warning(org.xml.sax.SAXParseException exception)
             throws org.xml.sax.SAXException
Specified by:
warning in interface org.xml.sax.ErrorHandler
Overrides:
warning in class org.xml.sax.helpers.DefaultHandler
Throws:
org.xml.sax.SAXException