001 // Copyright 2004, 2005 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.hivemind.internal;
016
017 import java.util.List;
018 import java.util.Locale;
019 import java.util.Map;
020
021 import org.apache.hivemind.ErrorHandler;
022 import org.apache.hivemind.Location;
023 import org.apache.hivemind.SymbolSource;
024 import org.apache.hivemind.schema.Translator;
025
026 /**
027 * Extension of {@link org.apache.hivemind.Registry} provided by some internals of HiveMind to
028 * faciliate the creation of services and configurations.
029 *
030 * @author Howard Lewis Ship
031 */
032 public interface RegistryInfrastructure extends SymbolSource
033 {
034 /**
035 * Obtains a service from the registry. Typically, what's returned is a proxy, but that's
036 * irrelevant to the caller, which simply will invoke methods of the service interface.
037 *
038 * @param serviceId
039 * the fully qualified id of the service to obtain
040 * @param serviceInterface
041 * the class to which the service will be cast
042 * @param module
043 * the referencing module, used for visibility checks (null means no module, which
044 * requires that the service be public)
045 * @return the service
046 * @throws org.apache.hivemind.ApplicationRuntimeException
047 * if the service does not exist (or is not visible), or if it can't be cast to the
048 * specified service interface
049 */
050
051 public Object getService(String serviceId, Class serviceInterface, Module module);
052
053 /**
054 * Finds a service that implements the provided interface. Exactly one such service may exist or
055 * an exception is thrown.
056 *
057 * @param serviceInterface
058 * used to locate the service
059 * @param module
060 * the referencing module, used for visibility checks. If null, then only public
061 * service points will be considered.
062 * @throws org.apache.hivemind.ApplicationRuntimeException
063 * if either 0, or more than 1, service point is visible to the module
064 */
065 public Object getService(Class serviceInterface, Module module);
066
067 /**
068 * Returns the converted items contributed to the configuration point.
069 *
070 * @param configurationId
071 * the fully qualified id of the configuration
072 * @param module
073 * the referencing module, used for visibility checks (null means no module, which
074 * requires that the configuration be public)
075 * @return List of converted elements
076 * @throws org.apache.hivemind.ApplicationRuntimeException
077 * if no such configuration extension point exists (or visible)
078 */
079
080 public List getConfiguration(String configurationId, Module module);
081
082 /**
083 * Returns true if the elements contributed to the given configuration point can be
084 * {@link #getConfigurationAsMap(String) retrieved as a Map}.
085 *
086 * @param configurationId
087 * the fully qualified id of the configuration
088 * @param module
089 * the referencing module, used for visibility checks (null means no module, which
090 * requires that the configuration be public)
091 * @throws ApplicationRuntimeException
092 * if no visible configuration point with the given id exists
093 * @see Module#isConfigurationMappable(String)
094 * @since 1.1
095 */
096 public boolean isConfigurationMappable(String configurationId, Module module);
097
098 /**
099 * 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 }