## gate
Class DocumentFormat

    java.lang.Object
      |
      +--gate.util.AbstractFeatureBearer
            |
            +--gate.creole.AbstractResource
                  |
                  +--gate.creole.AbstractLanguageResource
                        |
                        +--gate.DocumentFormat

All Implemented Interfaces:
  FeatureBearer, LanguageResource, NameBearer, Resource, Serializable

Direct Known Subclasses:
  TextualDocumentFormat

public abstract class DocumentFormat
extends AbstractLanguageResource
implements LanguageResource

The format of Documents. Subclasses of DocumentFormat know about particular MIME types and how to unpack the information in any markup or formatting they contain into GATE annotations. Each MIME type has its own subclass of DocumentFormat, e.g. XmlDocumentFormat, RtfDocumentFormat, MpegDocumentFormat. These classes register themselves with a static index residing here when they are constructed. Static getDocumentFormat methods can then be used to get the appropriate format class for a particular document.

See Also:
  Serialized Form

Field Summary
`private static boolean` `DEBUG` Debug flag
`protected Map` `element2StringMap` This map is used inside uppackMarkup() method...
`private FeatureMap` `features` The features of this resource
`protected static boolean` `isGateXmlDocument` This fields indicates whether the document being processed is in a Gate XML custom format.
`protected static Map` `magic2mimeTypeMap` Map of Set of magic numbers to MimeType.
`protected Map` `markupElementsMap` Map of markup elements to annotation types.
`protected static Map` `mimeString2ClassHandlerMap` Map of MimeTypeString to ClassHandler class.
`protected static Map` `mimeString2mimeTypeMap` Map of MimeType to DocumentFormat Class.
`private org.w3c.www.mime.MimeType` `mimeType` The MIME type of this format.
`private Vector` `statusListeners` listeners for status report
`protected static Map` `suffixes2mimeTypeMap` Map of Set of file suffixes to MimeType.

Fields inherited from class gate.creole.AbstractLanguageResource
`dataStore, lrPersistentId, serialVersionUID`

Fields inherited from class gate.creole.AbstractResource
`name`

Constructor Summary
`DocumentFormat()` Default construction

Method Summary
`void` `addStatusListener(StatusListener l)`
`protected static boolean` `areEqual(org.w3c.www.mime.MimeType aMimeType, org.w3c.www.mime.MimeType anotherMimeType)` Tests if two MimeType objects are equal.
`protected static org.w3c.www.mime.MimeType` `decideBetweenThreeMimeTypes(org.w3c.www.mime.MimeType aMimeTypeFromWebServer, org.w3c.www.mime.MimeType aMimeTypeFromFileSuffix, org.w3c.www.mime.MimeType aMimeTypeFromMagicNumbers)` This method decides what mimeType is in majority
`protected static org.w3c.www.mime.MimeType` `decideBetweenTwoMimeTypes(org.w3c.www.mime.MimeType aMimeType, org.w3c.www.mime.MimeType anotherMimeType)` Decide between two mimeTypes.
`protected void` `fireStatusChanged(String e)`
`static DocumentFormat` `getDocumentFormat(Document aGateDocument, org.w3c.www.mime.MimeType mimeType)` Find a DocumentFormat implementation that deals with a particular MIME type, given that type.
`static DocumentFormat` `getDocumentFormat(Document aGateDocument, String fileSuffix)` Find a DocumentFormat implementation that deals with a particular MIME type, given the file suffix (e.g.
`static DocumentFormat` `getDocumentFormat(Document aGateDocument, URL url)` Find a DocumentFormat implementation that deals with a particular MIME type, given the URL of the Document.
`Map` `getElement2StringMap()` Get the element 2 string map
`FeatureMap` `getFeatures()` Get the feature set
`private static String` `getFileSufix(URL url)` Return the fileSuffix or null if the url doesn't have a file suffix If the url is null then the file suffix will be null also
`Map` `getMarkupElementsMap()` Get the markup elements map
`org.w3c.www.mime.MimeType` `getMimeType()` Gets the mime Type
`private static org.w3c.www.mime.MimeType` `getMimeType(String fileSufix)` Returns a MimeType having as input a fileSufix.
`private static org.w3c.www.mime.MimeType` `getMimeType(URL url)` Returns a MymeType having as input a URL object.
`protected static org.w3c.www.mime.MimeType` `guessTypeUsingMagicNumbers(InputStream aInputStream, String anEncoding)` This method tries to guess the mime Type using some magic numbers.
`void` `removeStatusListener(StatusListener l)`
`protected static org.w3c.www.mime.MimeType` `runMagicNumbers(InputStreamReader aReader)` Performs magic over Gate Document
`void` `setElement2StringMap(Map anElement2StringMap)` Set the element 2 string map
`void` `setFeatures(FeatureMap features)` Set the features map
`void` `setMarkupElementsMap(Map markupElementsMap)` Set the markup elements map
`void` `setMimeType(org.w3c.www.mime.MimeType aMimeType)` Set the mime type
`abstract void` `unpackMarkup(Document doc)` Unpack the markup in the document.
`void` `unpackMarkup(Document doc, String originalContentFeatureType)` Unpack the markup in the document.

Methods inherited from class gate.creole.AbstractLanguageResource
`cleanup, getDataStore, getLRPersistenceId, setDataStore, setLRPersistenceId, sync`

Methods inherited from class gate.creole.AbstractResource
`checkParameterValues, getName, getParameterValue, getParameterValue, init, removeResourceListeners, setName, setParameterValue, setParameterValue, setParameterValues, setParameterValues, setResourceListeners`

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

Methods inherited from interface gate.LanguageResource
`getDataStore, getLRPersistenceId, setDataStore, setLRPersistenceId, sync`

Methods inherited from interface gate.Resource
`cleanup, getParameterValue, init, setParameterValue, setParameterValues`

Methods inherited from interface gate.util.NameBearer
`getName, setName`

Field Detail

### DEBUG

    private static final boolean DEBUG

  Debug flag

### isGateXmlDocument

    protected static boolean isGateXmlDocument

  This fields indicates whether the document being processed is in a Gate XML custom format. Detection is done in runMagicNumbers().

### mimeType

    private org.w3c.www.mime.MimeType mimeType

  The MIME type of this format.

### mimeString2ClassHandlerMap

    protected static Map mimeString2ClassHandlerMap

  Map of MimeTypeString to ClassHandler class. This is used to find the language resource that deals with the specific Document format

### mimeString2mimeTypeMap

    protected static Map mimeString2mimeTypeMap

  Map of MimeType to DocumentFormat Class. This is used to find the DocumentFormat subclass that deals with a particular MIME type.

### suffixes2mimeTypeMap

    protected static Map suffixes2mimeTypeMap

  Map of Set of file suffixes to MimeType. This is used to figure out what MIME type a document is from its file name.

### magic2mimeTypeMap

    protected static Map magic2mimeTypeMap

  Map of Set of magic numbers to MimeType. This is used to guess the MIME type of a document, when we don't have any other clues.

### markupElementsMap

    protected Map markupElementsMap

  Map of markup elements to annotation types. If it is null, the unpackMarkup() method will convert all markup, using the element names for annotation types. If it is non-null, only those elements specified here will be converted.

### element2StringMap

    protected Map element2StringMap

  This map is used inside uppackMarkup() method... When an element from the map is encounted, The corresponding string element is added to the document content

### features

    private FeatureMap features

  The features of this resource

### statusListeners

    private transient Vector statusListeners

  listeners for status report

Constructor Detail

### DocumentFormat

    public DocumentFormat()

  Default construction

Method Detail

### unpackMarkup

    public abstract void unpackMarkup(Document doc)
                               throws DocumentFormatException

  Unpack the markup in the document. This converts markup from the native format (e.g. XML, RTF) into annotations in GATE format. Uses the markupElementsMap to determine which elements to convert, and what annotation type names to use.

### unpackMarkup

    public void unpackMarkup(Document doc,
                             String originalContentFeatureType)
                      throws DocumentFormatException

  Unpack the markup in the document. This method calls unpackMarkup on the GATE document, but after it saves its content as a feature atached to the document. This method is usefull if one wants to save the content of the document being unpacked. After the markups have been unpacked, the content of the document will be replaced with a new one containing the text between markups.
  Parameters:
    `doc` - the document that will be upacked
    `originalContentFeatureType` - the name of the feature that will hold the document's content.

### getMimeType

    private static org.w3c.www.mime.MimeType getMimeType(String fileSufix)

  Returns a MimeType having as input a fileSufix. If the file sufix is null or not recognised then, null will be returned.
  Parameters:
    `fileSufix` - The file sufix associated with a recognisabe mime type.
  Returns:
    The MimeType associated with this file suffix.

### getMimeType

    private static org.w3c.www.mime.MimeType getMimeType(URL url)

  Returns a MymeType having as input a URL object. If the MimeType wasn't recognized it returns null.
  Parameters:
    `url` - The URL object from which the MimeType will be extracted
  Returns:
    A MimeType object for that URL, or null if the Mime Type is unknown.

### decideBetweenThreeMimeTypes

    protected static org.w3c.www.mime.MimeType decideBetweenThreeMimeTypes(org.w3c.www.mime.MimeType aMimeTypeFromWebServer,
                                                                           org.w3c.www.mime.MimeType aMimeTypeFromFileSuffix,
                                                                           org.w3c.www.mime.MimeType aMimeTypeFromMagicNumbers)

  This method decides what mimeType is in majority
  Parameters:
    `aMimeTypeFromWebServer` - a MimeType
    `aMimeTypeFromFileSuffix` - a MimeType
    `aMimeTypeFromMagicNumbers` - a MimeType
  Returns:
    the MimeType which occurs most. If all are null, then returns null

### decideBetweenTwoMimeTypes

    protected static org.w3c.www.mime.MimeType decideBetweenTwoMimeTypes(org.w3c.www.mime.MimeType aMimeType,
                                                                         org.w3c.www.mime.MimeType anotherMimeType)

  Decide between two mimeTypes. The decistion is made on "Priority" parameter set into decideBetweenThreeMimeTypes method. If both mimeTypes doesn't have "Priority" paramether set, it will return one on them.
  Parameters:
    `aMimeType` - a MimeType object with "Prority" parameter set
    `anotherMimeType` - a MimeType object with "Prority" parameter set
  Returns:
    One of the two mime types.

### areEqual

    protected static boolean areEqual(org.w3c.www.mime.MimeType aMimeType,
                                      org.w3c.www.mime.MimeType anotherMimeType)

  Tests if two MimeType objects are equal.
  Returns:
    true only if boths MimeType objects are different than null and their Types and Subtypes are equals. The method is case sensitive.

### guessTypeUsingMagicNumbers

    protected static org.w3c.www.mime.MimeType guessTypeUsingMagicNumbers(InputStream aInputStream,
                                                                          String anEncoding)

  This method tries to guess the mime Type using some magic numbers.
  Parameters:
    `aInputStream` - a InputStream which has to be transformed into a InputStreamReader
    `anEncoding` - the encoding. If is null or unknown then a InputStreamReader with default encodings will be created.
  Returns:
    the mime type associated with magic numbers

### runMagicNumbers

    protected static org.w3c.www.mime.MimeType runMagicNumbers(InputStreamReader aReader)

  Performs magic over Gate Document

### getFileSufix

    private static String getFileSufix(URL url)

  Return the fileSuffix or null if the url doesn't have a file suffix If the url is null then the file suffix will be null also

### getDocumentFormat

    public static DocumentFormat getDocumentFormat(Document aGateDocument,
                                                   org.w3c.www.mime.MimeType mimeType)

  Find a DocumentFormat implementation that deals with a particular MIME type, given that type.
  Parameters:
    `aGateDocument` - this document will receive as a feature the associated Mime Type. The name of the feature is MimeType and its value is in the format type/subtype
    `mimeType` - the mime type that is given as input

### getDocumentFormat

    public static DocumentFormat getDocumentFormat(Document aGateDocument,
                                                   String fileSuffix)

  Find a DocumentFormat implementation that deals with a particular MIME type, given the file suffix (e.g. ".txt") that the document came from.
  Parameters:
    `aGateDocument` - this document will receive as a feature the associated Mime Type. The name of the feature is MimeType and its value is in the format type/subtype
    `fileSuffix` - the file suffix that is given as input

### getDocumentFormat

    public static DocumentFormat getDocumentFormat(Document aGateDocument,
                                                   URL url)

  Find a DocumentFormat implementation that deals with a particular MIME type, given the URL of the Document. If it is an HTTP URL, we can ask the web server. If it has a recognised file extension, we can use that. Otherwise we need to use a map of magic numbers to MIME types to guess the type, and then look up the format using the type.
  Parameters:
    `aGateDocument` - this document will receive as a feature the associated Mime Type. The name of the feature is MimeType and its value is in the format type/subtype
    `url` - the URL that is given as input

### getFeatures

    public FeatureMap getFeatures()

  Get the feature set
  Specified by:
    `getFeatures` in interface `FeatureBearer`
  Overrides:
    `getFeatures` in class `AbstractFeatureBearer`

### getMarkupElementsMap

    public Map getMarkupElementsMap()

  Get the markup elements map

### getElement2StringMap

    public Map getElement2StringMap()

  Get the element 2 string map

### setMarkupElementsMap

    public void setMarkupElementsMap(Map markupElementsMap)

  Set the markup elements map

### setElement2StringMap

    public void setElement2StringMap(Map anElement2StringMap)

  Set the element 2 string map

### setFeatures

    public void setFeatures(FeatureMap features)

  Set the features map
  Specified by:
    `setFeatures` in interface `FeatureBearer`
  Overrides:
    `setFeatures` in class `AbstractFeatureBearer`

### setMimeType

    public void setMimeType(org.w3c.www.mime.MimeType aMimeType)

  Set the mime type

### getMimeType

    public org.w3c.www.mime.MimeType getMimeType()

  Gets the mime Type

### removeStatusListener

    public void removeStatusListener(StatusListener l)

### addStatusListener

    public void addStatusListener(StatusListener l)

### fireStatusChanged

    protected void fireStatusChanged(String e)