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.ClassResolver;
022 import org.apache.hivemind.ErrorHandler;
023 import org.apache.hivemind.Locatable;
024 import org.apache.hivemind.Location;
025 import org.apache.hivemind.Messages;
026 import org.apache.hivemind.SymbolSource;
027 import 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 */
042 public 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 }