Source code: org/apache/hivemind/internal/Module.java
1 // Copyright 2004, 2005 The Apache Software Foundation
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 package org.apache.hivemind.internal;
16
17 import java.util.List;
18 import java.util.Locale;
19 import java.util.Map;
20
21 import org.apache.hivemind.ClassResolver;
22 import org.apache.hivemind.ErrorHandler;
23 import org.apache.hivemind.Locatable;
24 import org.apache.hivemind.Location;
25 import org.apache.hivemind.Messages;
26 import org.apache.hivemind.SymbolSource;
27 import org.apache.hivemind.schema.Translator;
28
29 /**
30 * The definition of a HiveMind Module. A Module is a container of service extension points and
31 * configuration extension points. It also acts as a "gateway" so that services and configurations
32 * in other modules may be accessed.
33 * <p>
34 * Why do we expose the Module rather than the
35 * {@link org.apache.hivemind.internal.RegistryInfrastructure}? It's more than just qualifying ids
36 * before passing them up to the RI. At some future point, a concept of visibility will be added to
37 * HiveMind. This will make many services and configurations private to the module which defines
38 * them and the necessary visibility filtering logic will be here.
39 *
40 * @author Howard Lewis Ship
41 */
42 public interface Module extends Locatable, SymbolSource
43 {
44 /**
45 * Returns the unique identifier for this module.
46 */
47 public String getModuleId();
48
49 /**
50 * Returns true if a single service exists which implements the specified service interface and
51 * is visible to this module.
52 *
53 * @param serviceInterface
54 * @return true if a single visible service for the specified service interface exists
55 * @since 1.1
56 */
57 public boolean containsService(Class serviceInterface);
58
59 /**
60 * Looks up the {@link ServicePoint} (throwing an exception if not found) and invokes
61 * {@link ServicePoint#getService(Class)}.
62 *
63 * @param serviceId
64 * an unqualified id for a service within this module, or a fully qualified id for a
65 * service in this or any other module
66 * @param serviceInterface
67 * type the result will be cast to
68 */
69 public Object getService(String serviceId, Class serviceInterface);
70
71 /**
72 * Finds a service that implements the provided interface. Exactly one such service may exist or
73 * an exception is thrown.
74 *
75 * @param serviceInterface
76 * used to locate the service
77 */
78 public Object getService(Class serviceInterface);
79
80 /**
81 * Returns the identified service extension point.
82 *
83 * @param serviceId
84 * an unqualified id for a service within this module, or a fully qualified id for a
85 * service in this or any other module
86 * @throws org.apache.hivemind.ApplicationRuntimeException
87 * if no such service extension point exists
88 */
89
90 public ServicePoint getServicePoint(String serviceId);
91
92 /**
93 * Returns the {@link java.util.List} of elements for the specified configuration point. The
94 * returned List is unmodifiable. It may be empty, but won't be null.
95 * <p>
96 * It is expressly the <em>caller's</em> job to sort the elements into an appropriate order (a
97 * copy will have to be made since the returned List is unmodifiable).
98 *
99 * @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 }