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
015package org.apache.hivemind.internal;
016
017import java.util.List;
018import java.util.Locale;
019import java.util.Map;
020
021import org.apache.hivemind.ErrorHandler;
022import org.apache.hivemind.Location;
023import org.apache.hivemind.SymbolSource;
024import 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 */
032public 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}