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