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;
016
017import java.util.List;
018import java.util.Locale;
019import java.util.Map;
020
021import org.apache.hivemind.internal.Module;
022
023/**
024 * The HiveMind registry; primarily this is used to gain access to services.
025 * <p>
026 * In addition, Registry implements {@link org.apache.hivemind.SymbolSource} which allows
027 * programatic access to substitution symbols.
028 * 
029 * @author Howard Lewis Ship
030 */
031
032public interface Registry extends SymbolSource
033{
034    /**
035     * Returns true if a configuration for the specified id exists.
036     * 
037     * @param configurationId
038     * @return true if a configuration for the specified id exists
039     */
040    public boolean containsConfiguration(String configurationId);
041
042    /**
043     * Returns true if a single service for the specified service interface class exists.
044     * 
045     * @param serviceInterface
046     * @return true if a single service for the specified service interface exists
047     */
048    public boolean containsService(Class serviceInterface);
049
050    /**
051     * Returns true if a service for the specified service id and service interface exists.
052     * 
053     * @param serviceId
054     * @param serviceInterface
055     * @return true if a service for the specified service id and service interface exists
056     */
057    public boolean containsService(String serviceId, Class serviceInterface);
058
059    /**
060     * Returns a configuration as a List of elements (as defined by the schema for the configuration
061     * point, or as {@link org.apache.hivemind.Element}s if no configuration point does not define
062     * a schema.
063     * 
064     * @param configurationId
065     *            the fully qualified id of the configuration to obtain
066     * @return the configuration as an immutable List
067     * @throws ApplicationRuntimeException
068     *             if the configuration does not exist, etc.
069     */
070    public List getConfiguration(String configurationId);
071
072    /**
073     * Returns true if the elements contributed to the given configuration point can be
074     * {@link #getConfigurationAsMap(String) retrieved as a Map}.
075     * 
076     * @param configurationId
077     *            the fully qualified id of the configuration
078     * @throws ApplicationRuntimeException
079     *             if the configuration does not exist, etc.
080     * @see Module#isConfigurationMappable(String)
081     * @since 1.1
082     */
083    public boolean isConfigurationMappable(String configurationId);
084
085    /**
086     * Returns the elements of the given configuration point as an unmodifiable {@link Map}. It may
087     * be empty, but not null.
088     * 
089     * @param configurationId
090     *            the fully qualified id of the configuration
091     * @throws ApplicationRuntimeException
092     *             if no public configuration point with the given id exists or if the elements
093     *             can't be mapped.
094     * @see Module#getConfigurationAsMap(String)
095     * @see #isConfigurationMappable(String)
096     * @since 1.1
097     */
098    public Map getConfigurationAsMap(String configurationId);
099
100    /**
101     * Expands any substitution symbols in the input string, replacing each symbol with the symbols
102     * value (if known). If a symbol is unknown, then the symbol is passed through unchanged
103     * (complete with the <code>${</code> and <code>}</code> delimiters) and an error is logged.
104     * 
105     * @param input
106     *            input string to be converted, which may (or may not) contain any symbols.
107     * @param location
108     *            the location from which the string was obtained, used if an error is logged.
109     */
110
111    public String expandSymbols(String input, Location location);
112
113    /**
114     * Obtains a service from the registry. Typically, what's returned is a proxy, but that's
115     * irrelevant to the caller, which simply will invoke methods of the service interface.
116     * 
117     * @param serviceId
118     *            the fully qualified id of the service to obtain
119     * @param serviceInterface
120     *            the class to which the service will be cast
121     * @return the service
122     * @throws ApplicationRuntimeException
123     *             if the service does not exist, or if it can't be cast to the specified service
124     *             interface
125     */
126
127    public Object getService(String serviceId, Class serviceInterface);
128
129    /**
130     * Convenience method to obtain a service with a single implementation from the registry.
131     * Exactly one service point must implement the service.
132     * 
133     * @param serviceInterface
134     *            the class to which the service will be cast.
135     * @return the service implementing the given interface.
136     * @throws ApplicationRuntimeException
137     *             if there are no service extension points implementing the given interface, or if
138     *             there multiple service points implementing it.
139     * @see #getService(String, Class)
140     */
141
142    public Object getService(Class serviceInterface);
143
144    /**
145     * Returns the locale for which the registry was created.
146     */
147
148    public Locale getLocale();
149
150    /**
151     * Shuts down the registry; this notifies all
152     * {@link org.apache.hivemind.events.RegistryShutdownListener} services and objects. Once the
153     * registry is shutdown, it is no longer valid to obtain new services or configurations, or even
154     * use existing services and configurations.
155     */
156
157    public void shutdown();
158
159    /**
160     * To be invoked at the start of each request in a multi-threaded environment. Ensures that the
161     * receiving Registry will be used if any service proxies are de-serialized.
162     * 
163     * @since 1.1
164     * @see org.apache.hivemind.internal.ser.ServiceSerializationHelper
165     * @see org.apache.hivemind.internal.ser.ServiceSerializationSupport
166     */
167
168    public void setupThread();
169
170    /**
171     * Convienience for invoking
172     * {@link org.apache.hivemind.service.ThreadEventNotifier#fireThreadCleanup()}.
173     */
174
175    public void cleanupThread();
176
177    /**
178     * Returns a list of service ids for service points which implement the desired service
179     * interface.
180     * 
181     * @return Returns an empty List if no matching service points exist.
182     * @since 1.1
183     */
184    public List getServiceIds(Class serviceInterface);
185
186    /**
187     * Returns the Messages object for the specified module.
188     * 
189     * @param moduleId
190     *            the module id
191     * @return the Messages object for the specified module.
192     */
193    public Messages getModuleMessages(String moduleId);
194}