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