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