## gate.xml
Class XmlDocumentHandler

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

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

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

Implements the behaviour of the XML reader Methods of an object of this class are called by the SAX parser when events will appear. The idea is to parse the XML document and construct Gate annotations objects. This class also will replace the content of the Gate document with a new one containing anly text from the XML document.

Inner Class Summary
`(package private) class` `XmlDocumentHandler.CustomObject` The objects belonging to this class are used inside the stack.

Field Summary
`private SimpleErrorHandler` `_seh` This object inducates what to do when the parser encounts an error
`private AnnotationSet` `basicAS` An annotation set used for creating annotation reffering the doc
`private LinkedList` `colector` We need a colection to retain all the CustomObjects that will be transformed into annotation over the gate document...
`protected int` `customObjectsId` This is used to generate unique Ids for the CustomObjects read
`private static boolean` `DEBUG` Debug flag
`private Document` `doc` A gate document
`private Map` `element2StringMap`
`private int` `elements` This reports the the number of elements that have beed processed so far
`(package private) static int` `ELEMENTS_RATE`
`private Map` `markupElementsMap`
`protected List` `myStatusListeners` Listeners for status report
`private Stack` `stack` A stack used to remember elements and to keep the order
`private StringBuffer` `tmpDocContent` The content of the XML document, without any tag for internal use

Constructor Summary
`XmlDocumentHandler(Document aDocument, Map aMarkupElementsMap, Map anElement2StringMap)` Constructs a XmlDocumentHandler object.
`XmlDocumentHandler(Document aDocument, Map aMarkupElementsMap, Map anElement2StringMap, AnnotationSet anAnnotationSet)` Constructs a XmlDocumentHandler object.

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
`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.
`int` `getCustomObjectsId()` Accesor method for the customObjectsId field
`private String` `getMyLocalName(String aQName)` This method is a workaround of the java 4 non namespace supporting parser It receives a qualified name and returns its local name.
`private String` `getMyURI(String aQName)` Also a workaround for URI identifier.
`void` `ignorableWhitespace(char[] ch, int start, int length)` This method is called when the SAX parser encounts white spaces
`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

### markupElementsMap

    private Map markupElementsMap

### element2StringMap

    private Map element2StringMap

### _seh

    private SimpleErrorHandler _seh

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

### tmpDocContent

    private StringBuffer tmpDocContent

  The content of the XML document, without any tag for internal use

### stack

    private Stack stack

  A stack used to remember elements and to keep the order

### doc

    private Document doc

  A gate document

### basicAS

    private AnnotationSet basicAS

  An annotation set used for creating annotation reffering the doc

### 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 LinkedList colector

  We need a colection to retain all the CustomObjects that will be transformed into annotation over the gate document... the transformation will take place inside onDocumentEnd() method

### customObjectsId

    protected int customObjectsId

  This is used to generate unique Ids for the CustomObjects read

Constructor Detail

### XmlDocumentHandler

    public XmlDocumentHandler(Document aDocument,
                              Map aMarkupElementsMap,
                              Map anElement2StringMap)

  Constructs a XmlDocumentHandler object. The annotationSet set will be the default one taken from the gate document.
  Parameters:
    `aDocument` - the Gate document that will be processed.
    `aMarkupElementsMap` - this map contains the elements name that we want to create.
    `anElement2StringMap` - this map contains the strings that will be added to the text contained by the key element.

### XmlDocumentHandler

    public XmlDocumentHandler(Document aDocument,
                              Map aMarkupElementsMap,
                              Map anElement2StringMap,
                              AnnotationSet anAnnotationSet)

  Constructs a XmlDocumentHandler object.
  Parameters:
    `aDocument` - the Gate document that will be processed.
    `aMarkupElementsMap` - this map contains the elements name that we want to create.
    `anElement2StringMap` - this map contains the strings that will be added to the text contained by the key element.
    `anAnnotationSet` - is the annotation set that will be filled when the document was processed

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. Here we extract
  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. For entities, this method is called separatley regardless of the text sourinding the entity.
  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`

### 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.

### getMyLocalName

    private String getMyLocalName(String aQName)

  This method is a workaround of the java 4 non namespace supporting parser It receives a qualified name and returns its local name. For eg. if it receives gate:gateId it will return gateId

### getMyURI

    private String getMyURI(String aQName)

  Also a workaround for URI identifier. If the QName is gate it will return GATE's. Otherwhise it will return the empty string

### getCustomObjectsId

    public int getCustomObjectsId()

  Accesor method for the customObjectsId field