| CreoleRegister.java |
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