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