|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
RegistryInfrastructure.java | - | - | - | - |
|
1 | // Copyright 2004, 2005 The Apache Software Foundation | |
2 | // | |
3 | // Licensed under the Apache License, Version 2.0 (the "License"); | |
4 | // you may not use this file except in compliance with the License. | |
5 | // You may obtain a copy of the License at | |
6 | // | |
7 | // http://www.apache.org/licenses/LICENSE-2.0 | |
8 | // | |
9 | // Unless required by applicable law or agreed to in writing, software | |
10 | // distributed under the License is distributed on an "AS IS" BASIS, | |
11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
12 | // See the License for the specific language governing permissions and | |
13 | // limitations under the License. | |
14 | ||
15 | package org.apache.hivemind.internal; | |
16 | ||
17 | import java.util.List; | |
18 | import java.util.Locale; | |
19 | import java.util.Map; | |
20 | ||
21 | import org.apache.hivemind.ErrorHandler; | |
22 | import org.apache.hivemind.Location; | |
23 | import org.apache.hivemind.SymbolSource; | |
24 | import org.apache.hivemind.schema.Translator; | |
25 | ||
26 | /** | |
27 | * Extension of {@link org.apache.hivemind.Registry} provided by some internals of HiveMind to | |
28 | * faciliate the creation of services and configurations. | |
29 | * | |
30 | * @author Howard Lewis Ship | |
31 | */ | |
32 | public interface RegistryInfrastructure extends SymbolSource | |
33 | { | |
34 | /** | |
35 | * Obtains a service from the registry. Typically, what's returned is a proxy, but that's | |
36 | * irrelevant to the caller, which simply will invoke methods of the service interface. | |
37 | * | |
38 | * @param serviceId | |
39 | * the fully qualified id of the service to obtain | |
40 | * @param serviceInterface | |
41 | * the class to which the service will be cast | |
42 | * @param module | |
43 | * the referencing module, used for visibility checks (null means no module, which | |
44 | * requires that the service be public) | |
45 | * @return the service | |
46 | * @throws org.apache.hivemind.ApplicationRuntimeException | |
47 | * if the service does not exist (or is not visible), or if it can't be cast to the | |
48 | * specified service interface | |
49 | */ | |
50 | ||
51 | public Object getService(String serviceId, Class serviceInterface, Module module); | |
52 | ||
53 | /** | |
54 | * Finds a service that implements the provided interface. Exactly one such service may exist or | |
55 | * an exception is thrown. | |
56 | * | |
57 | * @param serviceInterface | |
58 | * used to locate the service | |
59 | * @param module | |
60 | * the referencing module, used for visibility checks. If null, then only public | |
61 | * service points will be considered. | |
62 | * @throws org.apache.hivemind.ApplicationRuntimeException | |
63 | * if either 0, or more than 1, service point is visible to the module | |
64 | */ | |
65 | public Object getService(Class serviceInterface, Module module); | |
66 | ||
67 | /** | |
68 | * Returns the converted items contributed to the configuration point. | |
69 | * | |
70 | * @param configurationId | |
71 | * the fully qualified id of the configuration | |
72 | * @param module | |
73 | * the referencing module, used for visibility checks (null means no module, which | |
74 | * requires that the configuration be public) | |
75 | * @return List of converted elements | |
76 | * @throws org.apache.hivemind.ApplicationRuntimeException | |
77 | * if no such configuration extension point exists (or visible) | |
78 | */ | |
79 | ||
80 | public List getConfiguration(String configurationId, Module module); | |
81 | ||
82 | /** | |
83 | * Returns true if the elements contributed to the given configuration point can be | |
84 | * {@link #getConfigurationAsMap(String) retrieved as a Map}. | |
85 | * | |
86 | * @param configurationId | |
87 | * the fully qualified id of the configuration | |
88 | * @param module | |
89 | * the referencing module, used for visibility checks (null means no module, which | |
90 | * requires that the configuration be public) | |
91 | * @throws ApplicationRuntimeException | |
92 | * if no visible configuration point with the given id exists | |
93 | * @see Module#isConfigurationMappable(String) | |
94 | * @since 1.1 | |
95 | */ | |
96 | public boolean isConfigurationMappable(String configurationId, Module module); | |
97 | ||
98 | /** | |
99 | * Returns the elements of the given configuration point as an unmodifiable {@link Map}. It may | |
100 | * be empty, but not null. | |
101 | * | |
102 | * @param configurationId | |
103 | * the fully qualified id of the configuration | |
104 | * @param module | |
105 | * the referencing module, used for visibility checks (null means no module, which | |
106 | * requires that the configuration be public) | |
107 | * @throws ApplicationRuntimeException | |
108 | * if no visible configuration point with the given id exists or if the elements | |
109 | * can't be mapped. | |
110 | * @see Module#getConfigurationAsMap(String) | |
111 | * @see #isConfigurationMappable(String) | |
112 | * @since 1.1 | |
113 | */ | |
114 | public Map getConfigurationAsMap(String configurationId, Module module); | |
115 | ||
116 | /** | |
117 | * Returns the configuration point. | |
118 | * | |
119 | * @param configurationId | |
120 | * the fully qualified id of the configuration | |
121 | * @param module | |
122 | * the referencing module, used for visibility checks (null means no module, which | |
123 | * requires that the configuration be public) | |
124 | * @return ConfigurationPoint matching the configuration id | |
125 | * @throws org.apache.hivemind.ApplicationRuntimeException | |
126 | * if the configurationId does not exist (or is not visible) | |
127 | */ | |
128 | ||
129 | public ConfigurationPoint getConfigurationPoint(String configurationId, Module module); | |
130 | ||
131 | /** | |
132 | * Returns the identified service extension point. | |
133 | * | |
134 | * @param serviceId | |
135 | * fully qualified id of the service point | |
136 | * @param module | |
137 | * the referencing module, used for visibility checks (null means no module, which | |
138 | * requires that the service be public) | |
139 | * @throws org.apache.hivemind.ApplicationRuntimeException | |
140 | * if no such service extension point exists (or is visible to the module) | |
141 | */ | |
142 | ||
143 | public ServicePoint getServicePoint(String serviceId, Module module); | |
144 | ||
145 | /** | |
146 | * Expands any substitution symbols in the input string, replacing each symbol with the symbols | |
147 | * value (if known). If a symbol is unknown, then the symbol is passed through unchanged | |
148 | * (complete with the <code>${</code> and <code>}</code> delimiters) and an error is logged. | |
149 | * | |
150 | * @param input | |
151 | * input string to be converted, which may (or may not) contain any symbols. | |
152 | * @param location | |
153 | * the location from which the string was obtained, used if an error is logged. | |
154 | */ | |
155 | ||
156 | public String expandSymbols(String input, Location location); | |
157 | ||
158 | /** | |
159 | * Returns a named service-model factory | |
160 | */ | |
161 | ||
162 | public ServiceModelFactory getServiceModelFactory(String name); | |
163 | ||
164 | /** | |
165 | * Gets a {@link Translator} instance. The Translator may be a shared, cached instance | |
166 | * (Translators should be stateless). Translators are identified by a constructor, which may be | |
167 | * the name of a translator defined in the <code>hivemind.Translators</code> extension point | |
168 | * (a single builtin translator, <code>class</code>, is hardcoded). Alternately, the name may | |
169 | * consist of a translator name, a comma, and an initializer string for the service (example: | |
170 | * <code>int,min=5</code>). | |
171 | * | |
172 | * @param constructor | |
173 | * the name and optional initialization of a Translator | |
174 | * @return a {@link Translator} instance | |
175 | * @throws ApplicationRuntimeException | |
176 | * if the translator can not be constructed (i.e., the name is not known) | |
177 | */ | |
178 | public Translator getTranslator(String constructor); | |
179 | ||
180 | /** | |
181 | * Returns the locale for which the registry was created. | |
182 | */ | |
183 | ||
184 | public Locale getLocale(); | |
185 | ||
186 | /** | |
187 | * Returns the {@link org.apache.hivemind.ErrorHandler} for this Registry. | |
188 | */ | |
189 | ||
190 | public ErrorHandler getErrorHander(); | |
191 | ||
192 | /** | |
193 | * Returns true if a configuration for the specified id exists (and is visible to the specified | |
194 | * module). | |
195 | * | |
196 | * @param configurationId | |
197 | * to search for | |
198 | * @param module | |
199 | * the configuration must be visible to, or null for no module (the application's | |
200 | * view | |
201 | * @return true if a configuration for the specified id exists (and is visible to the module) | |
202 | * @since 1.1 | |
203 | */ | |
204 | public boolean containsConfiguration(String configurationId, Module module); | |
205 | ||
206 | /** | |
207 | * Returns true if a single service exists which implements the specified service interface and | |
208 | * is visible to the given module. | |
209 | * | |
210 | * @param serviceInterface | |
211 | * @param module | |
212 | * the service must be visible to the module (or null for the application's view) | |
213 | * @return true if a single visible service for the specified service interface exists | |
214 | * @since 1.1 | |
215 | */ | |
216 | public boolean containsService(Class serviceInterface, Module module); | |
217 | ||
218 | /** | |
219 | * Returns true if a single service with the given id exists which implements the specified | |
220 | * service interface and is visible to the given module. | |
221 | * | |
222 | * @param serviceId | |
223 | * @param serviceInterface | |
224 | * @param module | |
225 | * the service must be visible to the module (or null for the application's view) | |
226 | * @return true if a single visible service for the specified service id and service interface | |
227 | * exists | |
228 | * @since 1.1 | |
229 | */ | |
230 | public boolean containsService(String serviceId, Class serviceInterface, Module module); | |
231 | ||
232 | /** | |
233 | * Invoked once, just after the registry infrastructure is constructed. One time startup | |
234 | * operations occur, including execution of any contributions to <code>hivemind.Startup</code>. | |
235 | * | |
236 | * @since 1.1 | |
237 | */ | |
238 | ||
239 | public void startup(); | |
240 | ||
241 | /** | |
242 | * Shuts down the registry; this notifies all | |
243 | * {@link org.apache.hivemind.events.RegistryShutdownListener} services and objects. Once the | |
244 | * registry is shutdown, it is no longer valid to obtain new services or configurations, or even | |
245 | * use existing services and configurations. | |
246 | * | |
247 | * @since 1.1 | |
248 | */ | |
249 | ||
250 | public void shutdown(); | |
251 | ||
252 | /** | |
253 | * To be invoked at the start of each request in a multi-threaded environment. Ensures that the | |
254 | * receiving Registry will be used if any service proxies are de-serialized. | |
255 | * | |
256 | * @since 1.1 | |
257 | * @see org.apache.hivemind.internal.ser.ServiceSerializationHelper | |
258 | * @see org.apache.hivemind.internal.ser.ServiceSerializationSupport | |
259 | */ | |
260 | ||
261 | public void setupThread(); | |
262 | ||
263 | /** | |
264 | * Convienience for invoking | |
265 | * {@link org.apache.hivemind.service.ThreadEventNotifier#fireThreadCleanup()}. | |
266 | * | |
267 | * @since 1.1 | |
268 | */ | |
269 | ||
270 | public void cleanupThread(); | |
271 | ||
272 | /** | |
273 | * @param serviceInterface | |
274 | */ | |
275 | public List getServiceIds(Class serviceInterface); | |
276 | ||
277 | /** | |
278 | * Returns the module with the corresponding module id. | |
279 | * | |
280 | * @param moduleId | |
281 | * @return the module with the corresponding module id | |
282 | */ | |
283 | public Module getModule(String moduleId); | |
284 | } |
|