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