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.ClassResolver;
022import org.apache.hivemind.ErrorHandler;
023import org.apache.hivemind.Locatable;
024import org.apache.hivemind.Location;
025import org.apache.hivemind.Messages;
026import org.apache.hivemind.SymbolSource;
027import org.apache.hivemind.schema.Translator;
028
029/**
030 * The definition of a HiveMind Module. A Module is a container of service extension points and
031 * configuration extension points. It also acts as a "gateway" so that services and configurations
032 * in other modules may be accessed.
033 * <p>
034 * Why do we expose the Module rather than the
035 * {@link org.apache.hivemind.internal.RegistryInfrastructure}? It's more than just qualifying ids
036 * before passing them up to the RI. At some future point, a concept of visibility will be added to
037 * HiveMind. This will make many services and configurations private to the module which defines
038 * them and the necessary visibility filtering logic will be here.
039 * 
040 * @author Howard Lewis Ship
041 */
042public interface Module extends Locatable, SymbolSource
043{
044    /**
045     * Returns the unique identifier for this module.
046     */
047    public String getModuleId();
048
049    /**
050     * Returns true if a single service exists which implements the specified service interface and
051     * is visible to this module.
052     * 
053     * @param serviceInterface
054     * @return true if a single visible service for the specified service interface exists
055     * @since 1.1
056     */
057    public boolean containsService(Class serviceInterface);
058
059    /**
060     * Looks up the {@link ServicePoint} (throwing an exception if not found) and invokes
061     * {@link ServicePoint#getService(Class)}.
062     * 
063     * @param serviceId
064     *            an unqualified id for a service within this module, or a fully qualified id for a
065     *            service in this or any other module
066     * @param serviceInterface
067     *            type the result will be cast to
068     */
069    public Object getService(String serviceId, Class serviceInterface);
070
071    /**
072     * Finds a service that implements the provided interface. Exactly one such service may exist or
073     * an exception is thrown.
074     * 
075     * @param serviceInterface
076     *            used to locate the service
077     */
078    public Object getService(Class serviceInterface);
079
080    /**
081     * Returns the identified service extension point.
082     * 
083     * @param serviceId
084     *            an unqualified id for a service within this module, or a fully qualified id for a
085     *            service in this or any other module
086     * @throws org.apache.hivemind.ApplicationRuntimeException
087     *             if no such service extension point exists
088     */
089
090    public ServicePoint getServicePoint(String serviceId);
091
092    /**
093     * Returns the {@link java.util.List} of elements for the specified configuration point. The
094     * returned List is unmodifiable. It may be empty, but won't be null.
095     * <p>
096     * It is expressly the <em>caller's</em> job to sort the elements into an appropriate order (a
097     * copy will have to be made since the returned List is unmodifiable).
098     * 
099     * @param configurationId
100     *            an unqualified id for a configuration within this module, or a fully qualified id
101     *            for a configuration in this or any other module
102     * @throws ApplicationRuntimeException
103     *             if this module does not contain the specified configuration extension point.
104     */
105    public List getConfiguration(String configurationId);
106
107    /**
108     * Returns true if the elements contributed to the given configuration point can be
109     * {@link #getConfigurationAsMap(String) retrieved as a Map}.
110     * 
111     * @see ConfigurationPoint#areElementsMappable()
112     * @since 1.1
113     */
114    public boolean isConfigurationMappable(String configurationId);
115
116    /**
117     * Returns the elements of the given configuration point as an unmodifiable {@link Map}. It may
118     * be empty, but not null.
119     * 
120     * @param configurationId
121     *            an unqualified id for a configuration within this module, or a fully qualified id
122     *            for a configuration in this or any other module.
123     * @throws ApplicationRuntimeException
124     *             if no configuration point with the given id exists or if the elements can't be
125     *             mapped.
126     * @see ConfigurationPoint#getElementsAsMap()
127     * @see #isConfigurationMappable(String)
128     * @since 1.1
129     */
130    public Map getConfigurationAsMap(String configurationId);
131
132    /**
133     * Returns the resource resolver for this module. The resource resolver is used to locate
134     * classes by name (using the correct classloader).
135     */
136    public ClassResolver getClassResolver();
137
138    /**
139     * Returns the class matching the type. First, attempts to resolve the type exactly as is. If
140     * that fails, resolves the type within the module's defined package.
141     * 
142     * @param type
143     *            the Java type to convert into a class. May be a primitive type, or an array of
144     *            objects or primitives.
145     * @return the corresponding {@link Class} object.
146     * @throws org.apache.hivemind.ApplicationRuntimeException
147     *             if the type may not be converted into a Class.
148     * @since 1.1
149     */
150
151    public Class resolveType(String type);
152
153    /**
154     * Returns an object that can provide and format localized messages for this module. The
155     * messages come from a properties file, <code>hivemodule.properties</code> (localized) stored
156     * with the HiveMind deployment descriptor in the META-INF folder.
157     */
158
159    public Messages getMessages();
160
161    /**
162     * @see RegistryInfrastructure#getTranslator(String)
163     */
164    public Translator getTranslator(String translator);
165
166    /**
167     * @see RegistryInfrastructure#getServiceModelFactory(String)
168     */
169    public ServiceModelFactory getServiceModelFactory(String name);
170
171    /**
172     * @see org.apache.hivemind.Registry#getLocale()
173     */
174    public Locale getLocale();
175
176    /**
177     * @see org.apache.hivemind.internal.RegistryInfrastructure#expandSymbols(String, Location)
178     */
179    public String expandSymbols(String input, Location location);
180
181    /**
182     * Returns the {@link org.apache.hivemind.ErrorHandler} for this Registry.
183     */
184
185    public ErrorHandler getErrorHandler();
186}