1   /*
2    *  CreoleRegister.java
3    *
4    *  Copyright (c) 1998-2004, 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, 31/Aug/2000
12   *
13   *  $Id: CreoleRegister.java,v 1.30 2004/07/23 16:23:53 valyt Exp $
14   */
15  
16  package gate;
17  
18  import java.io.File;
19  import java.io.Serializable;
20  import java.net.URL;
21  import java.util.*;
22  
23  import gate.event.CreoleListener;
24  import gate.util.GateException;
25  
26  /** The CREOLE register records the set of resources that are currently
27    * known to the system. Each member of the register is a
28    * <A HREF=creole/ResourceData.html>ResourceData</A> object, indexed by
29    * the class name of the resource.
30    * <P>
31    * The register is accessible from the static method
32    * <A HREF=Gate.html#getCreoleRegister()>gate.Gate.getCreoleRegister
33    * </A>;
34    * there is only one per application of the GATE framework.
35    * <P>
36    * Clients use the register by adding URLs (using the
37    * <A HREF=#addDirectory(java.net.URL)>addDirectory</A> method)
38    * pointing to CREOLE directories. A <B>CREOLE directory</B> is a URL at
39    * which resides a file called <CODE>creole.xml</CODE> describing
40    * the resources present, and one or more Jar files implementing
41    * those resources. E.g., the CREOLE resources at
42    * <A HREF=http://gate.ac.uk/>gate.ac.uk</A> are registered by Gate.init()
43    * by registering the directory URL
44    * <A HREF=http://gate.ac.uk/creole/>http://gate.ac.uk/creole/</A>, under
45    * which lives a file called creole.xml.
46    * <P>
47    * To register resources clients use the <CODE>registerDirectories</CODE>
48    * methods. When resources have been registered they can be accessed via
49    * their <CODE>ResourceData</CODE> objects. So a typical use of the register
50    * is to: add the set of URLs containing CREOLE directories; register
51    * all resources found at those URLs; browse the set of registered
52    * resources.
53    * <P>
54    * In all cases, where a resource or a directory is added which is
55    * already present in the register, the new silently overwrites the old.
56    *
57    * The CreoleRegister notifies all registered listeners of all
58    * {@link gate.event.CreoleEvent}s that occur in the system regardless of
59    * whether they were initially fired by the {@link Factory}, the
60    * {@link DataStoreRegister} or the {@link CreoleRegister} itself.
61    *
62    * @see gate.Gate
63    * @see gate.creole.ResourceData
64    */
65  public interface CreoleRegister extends Map, Serializable, CreoleListener
66  {
67    /** Add a CREOLE directory URL. The directory is <B>not</B> registered. */
68    public void addDirectory(URL directoryUrl);
69  
70    /** Get the list of CREOLE directory URLs. */
71    public Set getDirectories();
72  
73    /** Register all the CREOLE directories that we know of.
74      * The <CODE>creole.xml</CODE> files
75      * at the URLs are parsed, and <CODE>CreoleData</CODE> objects added
76      * to the register.
77      */
78    public void registerDirectories() throws GateException;
79  
80    /** Register a single CREOLE directory. The <CODE>creole.xml</CODE>
81      * file at the URL is parsed, and <CODE>CreoleData</CODE> objects added
82      * to the register. If the directory URL has not yet been added it
83      * is now added.
84      */
85    public void registerDirectories(URL directoryUrl) throws GateException;
86  
87    /**
88     * Removes a CREOLE directory from the set of loaded directories.
89     * @param directory
90     */
91    public void removeDirectory(URL directory);
92    
93    /** Register resources that are built in to the GATE distribution.
94      * These resources are described by the <TT>creole.xml</TT> file in
95      * <TT>resources/creole</TT>.
96      */
97    public void registerBuiltins() throws GateException;
98  
99    /** This is a utility method for creating CREOLE directory files
100     * (typically called <CODE>creole.xml</CODE>) from a list of Jar
101     * files that contain resources. The method concatenates the
102     * <CODE>resource.xml</CODE> files that the Jars contain.
103     * <P>
104     * If Java allowed class methods in interfaces this would be static.
105     */
106   public File createCreoleDirectoryFile(File directoryFile, Set jarFileNames);
107 
108   /** Get the list of types of LR in the register. */
109   public Set getLrTypes();
110 
111   /** Get the list of types of PR in the register. */
112   public Set getPrTypes();
113 
114   /** Get the list of types of VR in the register. */
115   public Set getVrTypes();
116 
117   /** Get the list of types of VR in the register. */
118   public Set getControllerTypes();
119 
120   /** Get a list of all instantiations of LR in the register. */
121   public List getLrInstances();
122 
123   /** Get a list of all instantiations of PR in the register. */
124   public List getPrInstances();
125 
126   /** Get a list of all instantiations of VR in the register. */
127   public List getVrInstances();
128 
129   /** Get a list of instantiations of a type of LR in the register. */
130   public List getLrInstances(String resourceTypeName);
131 
132   /** Get a list of instantiations of a type of PR in the register. */
133   public List getPrInstances(String resourceTypeName);
134 
135   /** Get a list of instantiations of a type of VR in the register. */
136   public List getVrInstances(String resourceTypeName);
137 
138   /** Get a list of all non-private instantiations of LR in the register. */
139   public List getPublicLrInstances();
140 
141   /** Get a list of all non-private instantiations of PR in the register. */
142   public List getPublicPrInstances();
143 
144   /** Get a list of all non-private instantiations of VR in the register. */
145   public List getPublicVrInstances();
146 
147   /** Get a list of all non-private types of LR in the register. */
148   public List getPublicLrTypes();
149 
150   /** Get a list of all non-private types of PR in the register. */
151   public List getPublicPrTypes();
152 
153   /** Get a list of all non-private types of VR in the register. */
154   public List getPublicVrTypes();
155 
156   /** Get a list of all non-private types of Controller in the register. */
157   public List getPublicControllerTypes();
158 
159   /**
160    * Gets all the instantiations of a given type and all its derivate types;
161    * It doesn't return instances that have the hidden attribute set to "true"
162    */
163   public List getAllInstances(String type) throws GateException;
164 
165   /**
166    * Returns a list of strings representing class names for large VRs valid
167    * for a given type of language/processing resource.
168    * The default VR will be the first in the returned list.
169    */
170   public List getLargeVRsForResource(String resourceClassName);
171 
172   /**
173    * Returns a list of strings representing class names for small VRs valid
174    * for a given type of language/processing resource
175    * The default VR will be the first in the returned list.
176    */
177   public List getSmallVRsForResource(String resourceClassName);
178 
179   /**
180     * Returns a list of strings representing class names for annotation VRs
181     * that are able to display/edit all types of annotations.
182     * The default VR will be the first in the returned list.
183     */
184    public List getAnnotationVRs();
185 
186   /**
187     * Returns a list of strings representing class names for annotation VRs
188     * that are able to display/edit a given annotation type
189     * The default VR will be the first in the returned list.
190     */
191    public List getAnnotationVRs(String annotationType);
192 
193 
194   /**
195     * Returns a list of strings representing annotations types for which
196     * there are custom viewers/editor registered.
197     */
198    public List getVREnabledAnnotationTypes();
199 
200    /**
201     * Renames an existing resource.
202     */
203    public void setResourceName(Resource res, String newName);
204 
205   /**
206    * Registers a {@link gate.event.CreoleListener}with this CreoleRegister.
207    * The register will fire events every time a resource is added to or removed
208    * from the system and when a datastore is created, opened or closed.
209    */
210   public void addCreoleListener(CreoleListener l);
211 
212   /**
213    * Removes a {@link gate.event.CreoleListener} previously registered with this
214    * CreoleRegister. 
215    * @see #addCreoleListener(CreoleListener)
216    */
217   public void removeCreoleListener(CreoleListener l);
218 
219 } // interface CreoleRegister
220