CreoleRegister.java
001 /*
002  *  CreoleRegister.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, 31/Aug/2000
013  *
014  *  $Id: CreoleRegister.java 18729 2015-05-29 16:10:29Z markagreenwood $
015  */
016 
017 package gate;
018 
019 import gate.creole.ResourceData;
020 import gate.creole.metadata.CreoleResource;
021 import gate.event.CreoleListener;
022 import gate.event.PluginListener;
023 import gate.util.GateException;
024 
025 import java.io.Serializable;
026 import java.net.URL;
027 import java.util.List;
028 import java.util.Map;
029 import java.util.Set;
030 
031 /** The CREOLE register records the set of resources that are currently
032   * known to the system. Each member of the register is a
033   * <A HREF=creole/ResourceData.html>ResourceData</A> object, indexed by
034   * the class name of the resource.
035   <P>
036   * The register is accessible from the static method
037   * <A HREF=Gate.html#getCreoleRegister()>gate.Gate.getCreoleRegister
038   </A>;
039   * there is only one per application of the GATE framework.
040   <P>
041   * Clients use the register by adding URLs (using the
042   * <A HREF=#addDirectory(java.net.URL)>addDirectory</A> method)
043   * pointing to CREOLE directories. A <B>CREOLE directory</B> is a URL at
044   * which resides a file called <CODE>creole.xml</CODE> describing
045   * the resources present, and one or more Jar files implementing
046   * those resources. E.g., the CREOLE resources at
047   * <A HREF=http://gate.ac.uk/>gate.ac.uk</A> are registered by Gate.init()
048   * by registering the directory URL
049   * <A HREF=http://gate.ac.uk/creole/>http://gate.ac.uk/creole/</A>, under
050   * which lives a file called creole.xml.
051   <P>
052   * To register resources clients use the <CODE>registerDirectories</CODE>
053   * methods. When resources have been registered they can be accessed via
054   * their <CODE>ResourceData</CODE> objects. So a typical use of the register
055   * is to: add the set of URLs containing CREOLE directories; register
056   * all resources found at those URLs; browse the set of registered
057   * resources.
058   <P>
059   * In all cases, where a resource or a directory is added which is
060   * already present in the register, the new silently overwrites the old.
061   *
062   * The CreoleRegister notifies all registered listeners of all
063   {@link gate.event.CreoleEvent}s that occur in the system regardless of
064   * whether they were initially fired by the {@link Factory}, the
065   {@link DataStoreRegister} or the {@link CreoleRegister} itself.
066   *
067   @see gate.Gate
068   @see gate.creole.ResourceData
069   */
070 public interface CreoleRegister extends Map<String, ResourceData>, Serializable, CreoleListener
071 {
072   /** Get the list of CREOLE directory URLs. */
073   public Set<URL> getDirectories();
074 
075   /**
076    * Given the class object for a class with {@link CreoleResource}
077    * annotations, register that class is if it was found in a scanned jar
078    * file with no additional creole.xml information.
079    *
080    * This API is intended for use in embedded GATE applications where
081    * the 'application' is created via the API. Components registered with this
082    *  API won't work in saved applications, but they can be added
083    *  to saved applications at runtime.
084    *
085    @param clazz Class object for class with CreoleResource annotations.
086    */
087   public void registerComponent(Class<? extends Resource> clazzthrows GateException;
088 
089   /** Register a single CREOLE directory. The <CODE>creole.xml</CODE>
090     * file at the URL is parsed, and <CODE>CreoleData</CODE> objects added
091     * to the register. If the directory URL has not yet been added it
092     * is now added. If any other plugins that nees top be loaded for this
093     * plugin to load (specified by <CODE>REQUIRES</Code> elements in
094     <code>creole.xml</code>) will also be loaded.
095     */
096   public void registerDirectories(URL directoryUrlthrows GateException;
097   
098   /**
099    * Register a single CREOLE directory. The <CODE>creole.xml</CODE> file at the
100    * URL is parsed, and <CODE>CreoleData</CODE> objects added to the register.
101    * If the directory URL has not yet been added it is now added. If any other
102    * plugins that nees top be loaded for this plugin to load (specified by
103    <CODE>REQUIRES</Code> elements in <code>creole.xml</code>) will only be
104    * loaded if the <code>loadDependencies</code> param is true. It is useful to
105    * be able to ignore dependencies when loading an xgapp where we know they
106    * have already been resolved.
107    */
108   public void registerDirectories(URL directoryUrl, boolean loadDependencies)
109       throws GateException;
110 
111   /**
112    * Removes a CREOLE directory from the set of loaded directories.
113    @param directory
114    */
115   public void removeDirectory(URL directory);
116 
117   /** Register resources that are built in to the GATE distribution.
118     * These resources are described by the <TT>creole.xml</TT> file in
119     <TT>resources/creole</TT>.
120     */
121   public void registerBuiltins() throws GateException;
122 
123   /** Get the list of types of LR in the register. */
124   public Set<String> getLrTypes();
125 
126   /** Get the list of types of PR in the register. */
127   public Set<String> getPrTypes();
128 
129   /** Get the list of types of VR in the register. */
130   public Set<String> getVrTypes();
131 
132   /** Get the list of types of VR in the register. */
133   public Set<String> getControllerTypes();
134   
135   /** Get the list of packaged application types in the register. */
136   public Set<String> getApplicationTypes();
137 
138   /** Get the list of types of tool in the register. */
139   public Set<String> getToolTypes();
140 
141   /** Get a list of all instantiations of LR in the register. */
142   public List<LanguageResource> getLrInstances();
143 
144   /** Get a list of all instantiations of PR in the register. */
145   public List<ProcessingResource> getPrInstances();
146 
147   /** Get a list of all instantiations of VR in the register. */
148   public List<VisualResource> getVrInstances();
149 
150   /**
151    * Get a list of all the known Language Resource instances in the register
152    * whose class is <code>resourceTypeName</code>.  This is only direct
153    * instances of the specified class, not its sub-classes, so if
154    <code>resourceTypeName</code> refers to an interface or abstract class an
155    * empty list will be returned.
156    */
157   public List<LanguageResource> getLrInstances(String resourceTypeName);
158 
159   /**
160    * Get a list of all the known Processing Resource instances in the register
161    * whose class is <code>resourceTypeName</code>.  This is only direct
162    * instances of the specified class, not its sub-classes, so if
163    <code>resourceTypeName</code> refers to an interface or abstract class an
164    * empty list will be returned.
165    */
166   public List<ProcessingResource> getPrInstances(String resourceTypeName);
167 
168   /**
169    * Get a list of all the known Visual Resource instances in the register
170    * whose class is <code>resourceTypeName</code>.  This is only direct
171    * instances of the specified class, not its sub-classes, so if
172    <code>resourceTypeName</code> refers to an interface or abstract class an
173    * empty list will be returned.
174    */
175   public List<VisualResource> getVrInstances(String resourceTypeName);
176 
177   /** Get a list of all non-private instantiations of LR in the register. */
178   public List<LanguageResource> getPublicLrInstances();
179 
180   /** Get a list of all non-private instantiations of PR in the register. */
181   public List<ProcessingResource> getPublicPrInstances();
182 
183   /** Get a list of all non-private instantiations of VR in the register. */
184   public List<VisualResource> getPublicVrInstances();
185 
186   /** Get a list of all non-private types of LR in the register. */
187   public List<String> getPublicLrTypes();
188 
189   /** Get a list of all non-private types of PR in the register. */
190   public List<String> getPublicPrTypes();
191 
192   /** Get a list of all non-private types of VR in the register. */
193   public List<String> getPublicVrTypes();
194 
195   /** Get a list of all non-private types of Controller in the register. */
196   public List<String> getPublicControllerTypes();
197 
198   /**
199    * Get a list of all the known Resource instances in the register that are of
200    * the specified (class or interface) type or one of its sub-types.
201    * Specifically, all known Resources <code>r</code> such that
202    <pre>
203    * Gate.getClassLoader().loadClass(type).isInstance(r)
204    </pre>
205    *
206    * Instances that are hidden (<code>Gate.getHiddenAttribute(r.getFeatures())
207    * == true</code>) are not included in the returned list.
208    */
209   public List<Resource> getAllInstances(String typethrows GateException;
210 
211   /**
212    * Returns a list of strings representing class names for large VRs valid
213    * for a given type of language/processing resource.
214    * The default VR will be the first in the returned list.
215    */
216   public List<String> getLargeVRsForResource(String resourceClassName);
217 
218   /**
219    * Returns a list of strings representing class names for small VRs valid
220    * for a given type of language/processing resource
221    * The default VR will be the first in the returned list.
222    */
223   public List<String> getSmallVRsForResource(String resourceClassName);
224 
225   /**
226     * Returns a list of strings representing class names for annotation VRs
227     * that are able to display/edit all types of annotations.
228     * The default VR will be the first in the returned list.
229     */
230    public List<String> getAnnotationVRs();
231 
232   /**
233     * Returns a list of strings representing class names for annotation VRs
234     * that are able to display/edit a given annotation type
235     * The default VR will be the first in the returned list.
236     */
237    public List<String> getAnnotationVRs(String annotationType);
238 
239 
240   /**
241     * Returns a list of strings representing annotations types for which
242     * there are custom viewers/editor registered.
243     */
244    public List<String> getVREnabledAnnotationTypes();
245 
246    /**
247     * Renames an existing resource.
248     */
249    public void setResourceName(Resource res, String newName);
250 
251   /**
252    * Registers a {@link gate.event.CreoleListener}with this CreoleRegister.
253    * The register will fire events every time a resource is added to or removed
254    * from the system and when a datastore is created, opened or closed.
255    */
256   public void addCreoleListener(CreoleListener l);
257 
258   /**
259    * Removes a {@link gate.event.CreoleListener} previously registered with this
260    * CreoleRegister.
261    @see #addCreoleListener(CreoleListener)
262    */
263   public void removeCreoleListener(CreoleListener l);
264   
265   public void addPluginListener(PluginListener l);
266   
267   public void removePluginListener(PluginListener l);
268 
269 // interface CreoleRegister