## gate.xml
Class GateFormatXmlDocumentHandler

    java.lang.Object
      |
      +--org.xml.sax.helpers.DefaultHandler
            |
            +--gate.xml.GateFormatXmlDocumentHandler

All Implemented Interfaces:
  org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public class GateFormatXmlDocumentHandler
extends org.xml.sax.helpers.DefaultHandler

Implements the behaviour of the XML reader. This is the reader for Gate Xml documents saved with DocumentImplementation.toXml() method.

Inner Class Summary
`(package private) class` `GateFormatXmlDocumentHandler.AnnotationObject` An inner class modeling the information contained by an annotation.

Field Summary
`private SimpleErrorHandler` `_seh` This object indicates what to do when the parser encounts an error
`private List` `colector` We need a colection to retain all the CustomObjects that will be transformed into annotation over the gate document...
`private GateFormatXmlDocumentHandler.AnnotationObject` `currentAnnot` This inner objects maps an annotation object.
`private AnnotationSet` `currentAnnotationSet` the current annotation set that is being created and filled with annotations
`private Stack` `currentElementStack` Holds the current element read.
`private String` `currentFeatureKeyClassName` The class name of the key in the current feature
`private String` `currentFeatureKeyItemClassName` If the key is a collection then we need to know the class name of the items present in this collection.
`private FeatureMap` `currentFeatureMap` A map holding current annotation's features
`private String` `currentFeatureName` A key of the current feature
`private String` `currentFeatureValue` The value of the current feature
`private String` `currentFeatureValueClassName` The class name for the value in the current feature
`private String` `currentFeatureValueItemClassName` If the value is a collection then we need to know the class name of the items present in this collection.
`private static boolean` `DEBUG` Debug flag
`private Document` `doc` A gate document
`private int` `elements` This reports the the number of elements that have beed processed so far
`(package private) static int` `ELEMENTS_RATE` This constant indicates when to fire the status listener.
`private Map` `id2Offset` Maps nodes Ids to their offset in the document text.
`protected List` `myStatusListeners` Listeners for status report
`private StringBuffer` `tmpDocContent` The content of the XML document, without any tag

Constructor Summary
`GateFormatXmlDocumentHandler(Document aDocument)`

Method Summary
`void` `addStatusListener(StatusListener listener)` This methos is called when a listener is registered with this class
`void` `characters(char[] text, int start, int length)` This method is called when the SAX parser encounts text in the XML doc.
`void` `comment(String text)` This method is called when the SAX parser encounts a comment It works only if the XmlDocumentHandler implements a com.sun.parser.LexicalEventListener
`private Object` `createFeatKey()` Creates a feature key using this information: currentFeatureKeyClassName, currentFeatureKeyItemClassName, currentFeatureName.
`private Object` `createFeatObject(String aFeatClassName, String aFeatItemClassName, String aFeatStringRepresentation)` This method tries to reconstruct an object given its class name and its string representation.
`private Object` `createFeatValue()` Creates a feature value using this information: currentFeatureValueClassName, currentFeatureValueItemClassName, currentFeatureValue.
`void` `endCDATA()` This method is called when the SAX parser encounts the end of a CDATA section.
`void` `endDocument()` This method is called when the SAX parser encounts the end of the XML document.
`void` `endElement(String uri, String qName, String elemName)` This method is called when the SAX parser encounts the end of an XML element.
`void` `endParsedEntity(String name, boolean included)` This method is called when the SAX parser encounts a parsed entity and informs the application if that entity was parsed or not It's working only if the CustomDocumentHandler implements a com.sun.parser.LexicalEventListener
`void` `error(org.xml.sax.SAXParseException ex)` Error method.We deal with this exception inside SimpleErrorHandler class
`void` `fatalError(org.xml.sax.SAXParseException ex)` FatalError method.
`protected void` `fireStatusChangedEvent(String text)` This methos is called whenever we need to inform the listener about an event.
`void` `ignorableWhitespace(char[] ch, int start, int length)` This method is called when the SAX parser encounts white spaces
`private void` `processAnnotationElement(org.xml.sax.Attributes atts)` This method deals with a Annotation element.
`private void` `processAnnotationSetElement(org.xml.sax.Attributes atts)` This method deals with a AnnotationSet element.
`private void` `processFeatureElement(org.xml.sax.Attributes atts)` This method deals with a Features element.
`private void` `processNameElement(org.xml.sax.Attributes atts)` This method deals with the start of a Name element
`private void` `processNodeElement(org.xml.sax.Attributes atts)` This method deals with a Node element.
`private void` `processTextOfNameElement(String text)` This method deals with a Text belonging to Name element.
`private void` `processTextOfTextWithNodesElement(String text)` This method deals with a Text belonging to TextWithNodes element.
`private void` `processTextOfValueElement(String text)` This method deals with a Text belonging to Value element.
`private void` `processValueElement(org.xml.sax.Attributes atts)` This method deals with the start of a Value element
`void` `removeStatusListener(StatusListener listener)` This methos is called when a listener is removed
`void` `startCDATA()` This method is called when the SAX parser encounts a start of a CDATA section It works only if the XmlDocumentHandler implements a com.sun.parser.LexicalEventListener
`void` `startDocument()` This method is called when the SAX parser encounts the beginning of the XML document.
`void` `startElement(String uri, String qName, String elemName, org.xml.sax.Attributes atts)` This method is called when the SAX parser encounts the beginning of an XML element.
`void` `startParsedEntity(String name)` This method is called when the SAX parser encounts a parsed Entity It works only if the XmlDocumentHandler implements a com.sun.parser.LexicalEventListener
`void` `warning(org.xml.sax.SAXParseException ex)` Warning method comment.

Methods inherited from class org.xml.sax.helpers.DefaultHandler
`endPrefixMapping, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, skippedEntity, startPrefixMapping, unparsedEntityDecl`

Methods inherited from class java.lang.Object
`<clinit>, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait`

Field Detail

### DEBUG

    private static final boolean DEBUG

  Debug flag

### ELEMENTS_RATE

    static final int ELEMENTS_RATE

  This constant indicates when to fire the status listener. This listener will add an overhead and we don't want a big overhead. It will be callled from ELEMENTS_RATE to ELEMENTS_RATE

### _seh

    private SimpleErrorHandler _seh

  This object indicates what to do when the parser encounts an error

### tmpDocContent

    private StringBuffer tmpDocContent

  The content of the XML document, without any tag

### doc

    private Document doc

  A gate document

### myStatusListeners

    protected List myStatusListeners

  Listeners for status report

### elements

    private int elements

  This reports the the number of elements that have beed processed so far

### colector

    private List colector

  We need a colection to retain all the CustomObjects that will be transformed into annotation over the gate document... At the end of every annotation set read the objects in the colector are transformed into annotations...

### id2Offset

    private Map id2Offset

  Maps nodes Ids to their offset in the document text. Those offsets will be used when creating annotations

### currentElementStack

    private Stack currentElementStack

  Holds the current element read.

### currentAnnot

    private GateFormatXmlDocumentHandler.AnnotationObject currentAnnot

  This inner objects maps an annotation object. When an annotation from the xml document was read this structure is filled out

### currentFeatureMap

    private FeatureMap currentFeatureMap

  A map holding current annotation's features

### currentFeatureName

    private String currentFeatureName

  A key of the current feature

### currentFeatureValue

    private String currentFeatureValue

  The value of the current feature

### currentFeatureKeyClassName

    private String currentFeatureKeyClassName

  The class name of the key in the current feature

### currentFeatureKeyItemClassName

    private String currentFeatureKeyItemClassName

  If the key is a collection then we need to know the class name of the items present in this collection. The next field holds just that.

### currentFeatureValueClassName

    private String currentFeatureValueClassName

  The class name for the value in the current feature

### currentFeatureValueItemClassName

    private String currentFeatureValueItemClassName

  If the value is a collection then we need to know the class name of the items present in this collection. The next field holds just that.

### currentAnnotationSet

    private AnnotationSet currentAnnotationSet

  the current annotation set that is being created and filled with annotations

Constructor Detail

### GateFormatXmlDocumentHandler

    public GateFormatXmlDocumentHandler(Document aDocument)

Method Detail

### startDocument

    public void startDocument()
                       throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts the beginning of the XML document.
  Overrides:
    `startDocument` in class `org.xml.sax.helpers.DefaultHandler`

### endDocument

    public void endDocument()
                     throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts the end of the XML document. Here we set the content of the gate Document to be the one generated inside this class (tmpDocContent). After that we use the colector to generate all the annotation reffering this new gate document.
  Overrides:
    `endDocument` in class `org.xml.sax.helpers.DefaultHandler`

### startElement

    public void startElement(String uri,
                             String qName,
                             String elemName,
                             org.xml.sax.Attributes atts)

  This method is called when the SAX parser encounts the beginning of an XML element.
  Overrides:
    `startElement` in class `org.xml.sax.helpers.DefaultHandler`

### endElement

    public void endElement(String uri,
                           String qName,
                           String elemName)
                    throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts the end of an XML element.
  Overrides:
    `endElement` in class `org.xml.sax.helpers.DefaultHandler`

### characters

    public void characters(char[] text,
                           int start,
                           int length)
                    throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts text in the XML doc. Here we calculate the end indices for all the elements present inside the stack and update with the new values.
  Overrides:
    `characters` in class `org.xml.sax.helpers.DefaultHandler`

### ignorableWhitespace

    public void ignorableWhitespace(char[] ch,
                                    int start,
                                    int length)
                             throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts white spaces
  Overrides:
    `ignorableWhitespace` in class `org.xml.sax.helpers.DefaultHandler`

### error

    public void error(org.xml.sax.SAXParseException ex)
               throws org.xml.sax.SAXException

  Error method.We deal with this exception inside SimpleErrorHandler class
  Overrides:
    `error` in class `org.xml.sax.helpers.DefaultHandler`

### fatalError

    public void fatalError(org.xml.sax.SAXParseException ex)
                    throws org.xml.sax.SAXException

  FatalError method.
  Overrides:
    `fatalError` in class `org.xml.sax.helpers.DefaultHandler`

### warning

    public void warning(org.xml.sax.SAXParseException ex)
                 throws org.xml.sax.SAXException

  Warning method comment.
  Overrides:
    `warning` in class `org.xml.sax.helpers.DefaultHandler`

### processAnnotationSetElement

    private void processAnnotationSetElement(org.xml.sax.Attributes atts)

  This method deals with a AnnotationSet element.

### processNameElement

    private void processNameElement(org.xml.sax.Attributes atts)

  This method deals with the start of a Name element

### processValueElement

    private void processValueElement(org.xml.sax.Attributes atts)

  This method deals with the start of a Value element

### processAnnotationElement

    private void processAnnotationElement(org.xml.sax.Attributes atts)

  This method deals with a Annotation element.

### processFeatureElement

    private void processFeatureElement(org.xml.sax.Attributes atts)

  This method deals with a Features element.

### processNodeElement

    private void processNodeElement(org.xml.sax.Attributes atts)

  This method deals with a Node element.

### processTextOfTextWithNodesElement

    private void processTextOfTextWithNodesElement(String text)

  This method deals with a Text belonging to TextWithNodes element.

### processTextOfNameElement

    private void processTextOfNameElement(String text)
                                   throws GateSaxException

  This method deals with a Text belonging to Name element.

### processTextOfValueElement

    private void processTextOfValueElement(String text)
                                    throws GateSaxException

  This method deals with a Text belonging to Value element.

### createFeatKey

    private Object createFeatKey()

  Creates a feature key using this information: currentFeatureKeyClassName, currentFeatureKeyItemClassName, currentFeatureName. See createFeatObject() method for more details.

### createFeatValue

    private Object createFeatValue()

  Creates a feature value using this information: currentFeatureValueClassName, currentFeatureValueItemClassName, currentFeatureValue. See createFeatObject() method for more details.

### createFeatObject

    private Object createFeatObject(String aFeatClassName,
                                    String aFeatItemClassName,
                                    String aFeatStringRepresentation)

  This method tries to reconstruct an object given its class name and its string representation. If the object is a Collection then the items from its string representation must be separated by a ";". In that case, the currentFeatureValueItemClassName is used to create items belonging to this class.
  Parameters:
    `aFeatClassName` - represents the name of the class of the feat object being created. If it is null then the javaLang.String will be used as default.
    `aFeatItemClassName` - is it used only if aFeatClassName is a collection.If it is null then java.lang.String will be used as default;
    `aFeatStringRepresentation` - sais it all
  Returns:
    an Object created from aFeatClassName and its aFeatStringRepresentation. If not possible, then aFeatStringRepresentation is returned.
  Throws:
    `GateRuntimeException` - If it can't create an item, that does not comply with its class definition, to add to the collection.

### comment

    public void comment(String text)
                 throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts a comment It works only if the XmlDocumentHandler implements a com.sun.parser.LexicalEventListener

### startCDATA

    public void startCDATA()
                    throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts a start of a CDATA section It works only if the XmlDocumentHandler implements a com.sun.parser.LexicalEventListener

### endCDATA

    public void endCDATA()
                  throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts the end of a CDATA section. It works only if the XmlDocumentHandler implements a com.sun.parser.LexicalEventListener

### startParsedEntity

    public void startParsedEntity(String name)
                           throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts a parsed Entity It works only if the XmlDocumentHandler implements a com.sun.parser.LexicalEventListener

### endParsedEntity

    public void endParsedEntity(String name,
                                boolean included)
                         throws org.xml.sax.SAXException

  This method is called when the SAX parser encounts a parsed entity and informs the application if that entity was parsed or not It's working only if the CustomDocumentHandler implements a com.sun.parser.LexicalEventListener

### addStatusListener

    public void addStatusListener(StatusListener listener)

  This methos is called when a listener is registered with this class

### removeStatusListener

    public void removeStatusListener(StatusListener listener)

  This methos is called when a listener is removed

### fireStatusChangedEvent

    protected void fireStatusChangedEvent(String text)

  This methos is called whenever we need to inform the listener about an event.