Document.java
001 /*
002  *  Document.java
003  *
004  *  Copyright (c) 1995-2012, The University of Sheffield. See the file
005  *  COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
006  *
007  *  This file is part of GATE (see http://gate.ac.uk/), and is free
008  *  software, licenced under the GNU Library General Public License,
009  *  Version 2, June 1991 (in the distribution as file licence.html,
010  *  and also available at http://gate.ac.uk/gate/licence.html).
011  *
012  *  Hamish Cunningham, 19/Jan/2000
013  *
014  *  $Id: Document.java 18042 2014-06-01 15:43:56Z johann_p $
015  */
016 
017 package gate;
018 
019 import gate.corpora.DocumentStaxUtils;
020 import gate.event.DocumentListener;
021 import gate.util.InvalidOffsetException;
022 
023 import java.util.Map;
024 import java.util.Set;
025 
026 
027 /** Represents the commonalities between all sorts of documents.
028  */
029 public interface Document extends SimpleDocument {
030 
031   /**
032   * The parameter name that determines whether or not a document is markup aware
033   */
034   public static final String
035     DOCUMENT_MARKUP_AWARE_PARAMETER_NAME = "markupAware";
036 
037   public static final String
038     DOCUMENT_ENCODING_PARAMETER_NAME = "encoding";
039 
040   public static final String
041     DOCUMENT_PRESERVE_CONTENT_PARAMETER_NAME = "preserveOriginalContent";
042 
043   public static final String
044     DOCUMENT_STRING_CONTENT_PARAMETER_NAME = "stringContent";
045 
046   public static final String
047     DOCUMENT_MIME_TYPE_PARAMETER_NAME = "mimeType";
048   
049   public static final String
050     DOCUMENT_REPOSITIONING_PARAMETER_NAME = "collectRepositioningInfo";
051 
052   public static final String
053     DOCUMENT_START_OFFSET_PARAMETER_NAME = "sourceUrlStartOffset";
054 
055   public static final String
056     DOCUMENT_END_OFFSET_PARAMETER_NAME = "sourceUrlEndOffset";
057  
058   /* parameter to store additional info about the document type, 
059    * e.g. publication, javadoc, etc. */
060   public static final String
061   DOCUMENT_TYPE_PARAMETER_NAME = "documentType";
062   
063   /** Documents may be packed within files; in this case an optional pair of
064    *  offsets refer to the location of the document.
065    */
066   public Long[] getSourceUrlOffsets();
067 
068   /** Documents may be packed within files; in this case an optional pair of
069    *  offsets refer to the location of the document. This method gets the
070    *  start offset.
071    */
072   public Long getSourceUrlStartOffset();
073 
074   /** Documents may be packed within files; in this case an optional pair of
075    *  offsets refer to the location of the document. This method gets the
076    *  end offset.
077    */
078   public Long getSourceUrlEndOffset();
079 
080   /** Returns a map with the named annotation sets
081     */
082   public Map<String, AnnotationSet> getNamedAnnotationSets();
083 
084   /** Make the document markup-aware. This will trigger the creation
085    *  of a DocumentFormat object at Document initialisation time; the
086    *  DocumentFormat object will unpack the markup in the Document and
087    *  add it as annotations. Documents are <B>not</B> markup-aware by default.
088    *
089    *  @param b markup awareness status.
090    */
091   public void setMarkupAware(Boolean b);
092 
093   /** Get the markup awareness status of the Document.
094    *
095    *  @return whether the Document is markup aware.
096    */
097   public Boolean getMarkupAware();
098 
099   /**
100    * Allow/disallow preserving of the original document content.
101    * If is <B>true</B> the original content will be retrieved from
102    * the DocumentContent object and preserved as document feature.
103    */
104   public void setPreserveOriginalContent(Boolean b);
105 
106   /** Get the preserving of content status of the Document.
107    *
108    *  @return whether the Document should preserve it's original content.
109    */
110   public Boolean getPreserveOriginalContent();
111 
112   /**
113    *  Allow/disallow collecting of repositioning information.
114    *  If is <B>true</B> information will be retrieved and preserved
115    *  as document feature.<BR>
116    *  Preserving of repositioning information give the possibilities
117    *  for converting of coordinates between the original document content and
118    *  extracted from the document text.
119    */
120   public void setCollectRepositioningInfo(Boolean b);
121 
122   /** Get the collectiong and preserving of repositioning information
123    *  for the Document. <BR>
124    *  Preserving of repositioning information give the possibilities
125    *  for converting of coordinates between the original document content and
126    *  extracted from the document text.
127    *
128    *  @return whether the Document should collect and preserve information.
129    */
130   public Boolean getCollectRepositioningInfo();
131 
132   /** Returns a GateXml document. This document is actually a serialization of
133    *  a Gate Document in XML. The <code>writeDocument</code> methods of
134    *  {@link DocumentStaxUtils} provide the standard implementation of this
135    *  serialization format which will work for any Document implementation.
136    *  Implementations of <code>toXml</code> will typically delegate to
137    *  <code>DocumentStaxUtils</code>, and in many cases it will be more
138    *  efficient for callers to use that directly rather than calling
139    *  <code>toXml</code>.
140    *  @see DocumentStaxUtils
141     @return a string representing a Gate Xml document
142     */
143   public String toXml();
144 
145   /** Returns an XML document aming to preserve the original markups(
146     * the original markup will be in the same place and format as it was
147     * before processing the document) and include (if possible)
148     * the annotations specified in the aSourceAnnotationSet.
149     <b>Warning:</b> Annotations from the aSourceAnnotationSet will be lost
150     * if they will cause a crosed over situation.
151     @param aSourceAnnotationSet is an annotation set containing all the
152     * annotations that will be combined with the original marup set.
153     @param includeFeatures determines whether or not features and gate IDs
154     * of the annotations should be included as attributes on the tags or not.
155     * If false, then only the annotation types are exported as tags, with no
156     * attributes.
157     @return a string representing an XML document containing the original
158     * markup + dumped annotations form the aSourceAnnotationSet
159     */
160   public String toXml(Set<Annotation> aSourceAnnotationSet, boolean includeFeatures);
161 
162   /**
163    * Equivalent to toXml(aSourceAnnotationSet, true).
164    */
165   public String toXml(Set<Annotation> aSourceAnnotationSet);
166 
167   /** 
168    * Make changes to the document content and adapt affected annotations.
169    
170    * This method replaces the document content ranging from the start to the
171    * end offset with the new DocumentContent provided as a replacement. If
172    * the original content should be removed, null can be used as a a replacement.
173    * In addition, annotations in all annotation sets are removed or adapted to 
174    * the changed documents see 
175    {@link gate.annotation.AnnotationSetImpl#edit(java.lang.Long, java.lang.Long, gate.DocumentContent) AnnotationSetImpl.edit(long,long,DocumentContent) }
176    * for information on how annotations get adapted.
177    
178    */
179   public void edit(Long start, Long end, DocumentContent replacement)
180     throws InvalidOffsetException;
181 
182   /**
183    * Adds a {@link gate.event.DocumentListener} to this document.
184    * All the registered listeners will be notified of changes occured to the
185    * document.
186    */
187   public void addDocumentListener(DocumentListener l);
188 
189   /**
190    * Removes one of the previously registered document listeners.
191    */
192   public void removeDocumentListener(DocumentListener l);
193 
194 
195   /** Documents may be packed within files; in this case an optional pair of
196     * offsets refer to the location of the document. This method sets the
197     * end offset.
198     */
199   public void setSourceUrlEndOffset(Long sourceUrlEndOffset);
200 
201 
202   /** Documents may be packed within files; in this case an optional pair of
203     * offsets refer to the location of the document. This method sets the
204     * start offset.
205     */
206   public void setSourceUrlStartOffset(Long sourceUrlStartOffset);
207 
208 // interface Document