SimpleCorpus.java
001 /*
002  *  SimpleCorpus.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  *  Kalina Bontcheva, 23/Jul/2004
013  *
014  *  $Id: SimpleCorpus.java 17434 2014-02-26 14:45:12Z markagreenwood $
015  */
016 
017 package gate;
018 
019 import gate.creole.ResourceInstantiationException;
020 import gate.util.NameBearer;
021 
022 import java.io.FileFilter;
023 import java.io.IOException;
024 import java.net.URL;
025 import java.util.List;
026 
027 /**
028  * Corpora are lists of Document. TIPSTER equivalent: Collection.
029  */
030 public interface SimpleCorpus extends LanguageResource, List<Document>, NameBearer {
031 
032   public static final String CORPUS_NAME_PARAMETER_NAME = "name";
033 
034   public static final String CORPUS_DOCLIST_PARAMETER_NAME = "documentsList";
035 
036   /**
037    * Gets the names of the documents in this corpus.
038    
039    @return {@link List} of Strings representing the names of the
040    *         documents in this corpus.
041    */
042   public List<String> getDocumentNames();
043 
044   /**
045    * Gets the name of a document in this corpus.
046    
047    @param index the index of the document
048    @return a String value representing the name of the document at
049    *         <tt>index</tt> in this corpus.
050    */
051   public String getDocumentName(int index);
052 
053   /**
054    * Fills this corpus with documents created on the fly from selected
055    * files in a directory. Uses a {@link FileFilter} to select which
056    * files will be used and which will be ignored. A simple file filter
057    * based on extensions is provided in the Gate distribution (
058    {@link gate.util.ExtensionFileFilter}).
059    
060    @param directory the directory from which the files will be picked.
061    *          This parameter is an URL for uniformity. It needs to be a
062    *          URL of type file otherwise an InvalidArgumentException
063    *          will be thrown. An implementation for this method is
064    *          provided as a static method at
065    *          {@link gate.corpora.CorpusImpl#populate(Corpus, URL, FileFilter, String, boolean)}
066    *          .
067    @param filter the file filter used to select files from the target
068    *          directory. If the filter is <tt>null</tt> all the files
069    *          will be accepted.
070    @param encoding the encoding to be used for reading the documents
071    @param recurseDirectories should the directory be parsed
072    *          recursively?. If <tt>true</tt> all the files from the
073    *          provided directory and all its children directories (on as
074    *          many levels as necessary) will be picked if accepted by
075    *          the filter otherwise the children directories will be
076    *          ignored.
077    */
078   public void populate(URL directory, FileFilter filter, String encoding,
079           boolean recurseDirectoriesthrows IOException,
080           ResourceInstantiationException;
081 
082   /**
083    * Fills this corpus with documents created on the fly from selected
084    * files in a directory. Uses a {@link FileFilter} to select which
085    * files will be used and which will be ignored. A simple file filter
086    * based on extensions is provided in the Gate distribution (
087    {@link gate.util.ExtensionFileFilter}).
088    
089    @param directory the directory from which the files will be picked.
090    *          This parameter is an URL for uniformity. It needs to be a
091    *          URL of type file otherwise an InvalidArgumentException
092    *          will be thrown. An implementation for this method is
093    *          provided as a static method at
094    *          {@link gate.corpora.CorpusImpl#populate(Corpus, URL, FileFilter, String, boolean)}
095    *          .
096    @param filter the file filter used to select files from the target
097    *          directory. If the filter is <tt>null</tt> all the files
098    *          will be accepted.
099    @param encoding the encoding to be used for reading the documents
100    *@param mimeType the mime type to be used when loading documents. If
101    *          null, then the mime type will be automatically determined.
102    @param recurseDirectories should the directory be parsed
103    *          recursively?. If <tt>true</tt> all the files from the
104    *          provided directory and all its children directories (on as
105    *          many levels as necessary) will be picked if accepted by
106    *          the filter otherwise the children directories will be
107    *          ignored.
108    */
109   public void populate(URL directory, FileFilter filter, String encoding,
110           String mimeType, boolean recurseDirectoriesthrows IOException,
111           ResourceInstantiationException;
112 
113   /**
114    * Fills the provided corpus with documents extracted from the
115    * provided trec file.
116    
117    @param singleConcatenatedFile the file with multiple documents in it.
118    @param documentRootElement content between the start and end of
119    *          this element is considered for documents.
120    @param encoding the encoding of the trec file.
121    @param numberOfDocumentsToExtract indicates the number of documents to
122    *          extract from the concatenated file. -1 to indicate all
123    *          files.
124    @param documentNamePrefix the prefix to use for document names when
125    *          creating from
126    @param mimeType the mime type which determines how the document is handled 
127    @return total length of populated documents in the corpus in number
128    *         of bytes
129    */
130  
131   public long populate(URL singleConcatenatedFile, String documentRootElement,
132       String encoding, int numberOfDocumentsToExtract,
133       String documentNamePrefix, String mimeType, boolean includeRootElementthrows IOException,
134       ResourceInstantiationException;
135 
136 // interface SimpleCorpus