1   /*
2    *  Document.java
3    *
4    *  Copyright (c) 1998-2001, The University of Sheffield.
5    *
6    *  This file is part of GATE (see http://gate.ac.uk/), and is free
7    *  software, licenced under the GNU Library General Public License,
8    *  Version 2, June 1991 (in the distribution as file licence.html,
9    *  and also available at http://gate.ac.uk/gate/licence.html).
10   *
11   *  Hamish Cunningham, 19/Jan/2000
12   *
13   *  $Id: Document.java,v 1.33 2001/10/17 14:18:10 marin Exp $
14   */
15  
16  package gate;
17  
18  import java.util.*;
19  import java.net.*;
20  
21  import gate.util.*;
22  import gate.event.*;
23  
24  
25  /** Represents the commonalities between all sorts of documents.
26   */
27  public interface Document extends LanguageResource, Comparable {
28  
29    /** Documents are identified by URLs
30     */
31    public URL getSourceUrl();
32  
33    /** Set method for the document's URL
34     */
35    public void setSourceUrl(URL sourceUrl);
36  
37    /** Documents may be packed within files; in this case an optional pair of
38     *  offsets refer to the location of the document.
39     */
40    public Long[] getSourceUrlOffsets();
41  
42    /** Documents may be packed within files; in this case an optional pair of
43     *  offsets refer to the location of the document. This method gets the
44     *  start offset.
45     */
46    public Long getSourceUrlStartOffset();
47  
48    /** Documents may be packed within files; in this case an optional pair of
49     *  offsets refer to the location of the document. This method gets the
50     *  end offset.
51     */
52    public Long getSourceUrlEndOffset();
53  
54    /** The content of the document: wraps e.g. String for text; MPEG for
55     *  video; etc.
56     */
57    public DocumentContent getContent();
58  
59    /** Set method for the document content
60     */
61    public void setContent(DocumentContent newContent);
62  
63    /** Get the default set of annotations. The set is created if it
64     *  doesn't exist yet.
65     */
66    public AnnotationSet getAnnotations();
67  
68    /** Get a named set of annotations. Creates a new set if one with this
69     *  name doesn't exist yet.
70     */
71    public AnnotationSet getAnnotations(String name);
72  
73    /** Returns a map with the named annotation sets
74      */
75    public Map getNamedAnnotationSets();
76  
77    /**
78     * Removes one of the named annotation sets.
79     * Note that the default annotation set cannot be removed.
80     * @param name the name of the annotation set to be removed
81     */
82    public void removeAnnotationSet(String name);
83  
84    /** Make the document markup-aware. This will trigger the creation
85     *  of a DocumentFormat object at Document initialisation time; the
86     *  DocumentFormat object will unpack the markup in the Document and
87     *  add it as annotations. Documents are <B>not</B> markup-aware by default.
88     *
89     *  @param b markup awareness status.
90     */
91    public void setMarkupAware(Boolean b);
92  
93    /** Get the markup awareness status of the Document.
94     *
95     *  @return whether the Document is markup aware.
96     */
97    public Boolean getMarkupAware();
98  
99    /** Returns a GateXml document. This document is actually a serialization of
100    *  a Gate Document in XML.
101     * @return a string representing a Gate Xml document
102     */
103   public String toXml();
104 
105   /** Returns an XML document aming to preserve the original markups(
106     * the original markup will be in the same place and format as it was
107     * before processing the document) and include (if possible)
108     * the annotations specified in the aSourceAnnotationSet.
109     * <b>Warning:</b> Annotations from the aSourceAnnotationSet will be lost
110     * if they will cause a crosed over situation.
111     * @param aSourceAnnotationSet is an annotation set containing all the
112     * annotations that will be combined with the original marup set.
113     * @return a string representing an XML document containing the original
114     * markup + dumped annotations form the aSourceAnnotationSet
115     */
116   public String toXml(Set aSourceAnnotationSet);
117 
118   /** Make changes to the content.
119    */
120   public void edit(Long start, Long end, DocumentContent replacement)
121     throws InvalidOffsetException;
122 
123   /**
124    * Adds a {@link gate.event.DocumentListener} to this document.
125    * All the registered listeners will be notified of changes occured to the
126    * document.
127    */
128   public void addDocumentListener(DocumentListener l);
129 
130   /**
131    * Removes one of the previously registered document listeners.
132    */
133   public void removeDocumentListener(DocumentListener l);
134 
135 
136   /** Documents may be packed within files; in this case an optional pair of
137     * offsets refer to the location of the document. This method sets the
138     * end offset.
139     */
140   public void setSourceUrlEndOffset(Long sourceUrlEndOffset);
141 
142 
143   /** Documents may be packed within files; in this case an optional pair of
144     * offsets refer to the location of the document. This method sets the
145     * start offset.
146     */
147   public void setSourceUrlStartOffset(Long sourceUrlStartOffset);
148 
149 } // interface Document
150 
151