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
020 import org.apache.hivemind.ErrorHandler;
021
022 /**
023 * Extension of {@link org.apache.hivemind.Registry} provided by some internals of HiveMind to
024 * faciliate the creation of services and configurations.
025 *
026 * @author Howard Lewis Ship
027 */
028 public interface RegistryInfrastructure
029 {
030 /**
031 * Obtains a service from the registry. Typically, what's returned is a proxy, but that's
032 * irrelevant to the caller, which simply will invoke methods of the service interface.
033 *
034 * @param serviceId
035 * the fully qualified id of the service to obtain
036 * @param serviceInterface
037 * the class to which the service will be cast
038 * @param module
039 * the referencing module, used for visibility checks (null means no module, which
040 * requires that the service be public)
041 * @return the service
042 * @throws org.apache.hivemind.ApplicationRuntimeException
043 * if the service does not exist (or is not visible), or if it can't be cast to the
044 * specified service interface
045 */
046
047 public Object getService(String serviceId, Class serviceInterface, Module module);
048
049 /**
050 * Finds a service that implements the provided interface. Exactly one such service may exist or
051 * an exception is thrown.
052 *
053 * @param serviceInterface
054 * used to locate the service
055 * @param module
056 * the referencing module, used for visibility checks. If null, then only public
057 * service points will be considered.
058 * @throws org.apache.hivemind.ApplicationRuntimeException
059 * if either 0, or more than 1, service point is visible to the module
060 */
061 public Object getService(Class serviceInterface, Module module);
062
063 /**
064 * Returns the specified configuration.
065 *
066 * @param configurationId
067 * the fully qualified id of the configuration
068 * @param module
069 * the referencing module, used for visibility checks (null means no module, which
070 * requires that the configuration be public)
071 * @return the configuration
072 * @throws org.apache.hivemind.ApplicationRuntimeException
073 * if no such configuration extension point exists (or visible)
074 */
075 public Object getConfiguration(String configurationId, Module module);
076
077 /**
078 * Finds a configuration of the specified type. Exactly one such configuration may exist or
079 * an exception is thrown.
080 *
081 * @param configurationType
082 * the configuration type
083 * @param module
084 * the referencing module, used for visibility checks (null means no module, which
085 * requires that the configuration be public)
086 * @return the configuration
087 * @throws org.apache.hivemind.ApplicationRuntimeException
088 * if no such configuration extension point exists (or visible)
089 */
090 public Object getConfiguration(Class configurationType, Module module);
091
092 /**
093 * Returns the configuration point.
094 *
095 * @param configurationId
096 * the fully qualified id of the configuration
097 * @param module
098 * the referencing module, used for visibility checks (null means no module, which
099 * requires that the configuration be public)
100 * @return ConfigurationPoint matching the configuration id
101 * @throws org.apache.hivemind.ApplicationRuntimeException
102 * if the configurationId does not exist (or is not visible)
103 */
104
105 public ConfigurationPoint getConfigurationPoint(String configurationId, Module module);
106
107 /**
108 * Returns the identified service extension point.
109 *
110 * @param serviceId
111 * fully qualified id of the service point
112 * @param module
113 * the referencing module, used for visibility checks (null means no module, which
114 * requires that the service be public)
115 * @throws org.apache.hivemind.ApplicationRuntimeException
116 * if no such service extension point exists (or is visible to the module)
117 */
118
119 public ServicePoint getServicePoint(String serviceId, Module module);
120
121 /**
122 * Returns a named service-model factory
123 */
124
125 public ServiceModelFactory getServiceModelFactory(String name);
126
127 /**
128 * Returns the locale for which the registry was created.
129 */
130
131 public Locale getLocale();
132
133 /**
134 * Returns the {@link org.apache.hivemind.ErrorHandler} for this Registry.
135 */
136
137 public ErrorHandler getErrorHander();
138
139 /**
140 * Returns true if a configuration for the specified id exists (and is visible to the specified
141 * module).
142 *
143 * @param configurationId
144 * to search for
145 * @param module
146 * the configuration must be visible to, or null for no module (the application's
147 * view
148 * @return true if a configuration for the specified id exists (and is visible to the module)
149 * @since 1.1
150 */
151 public boolean containsConfiguration(String configurationId, Module module);
152
153 /**
154 * Returns true if a single service exists which implements the specified service interface and
155 * is visible to the given module.
156 *
157 * @param serviceInterface
158 * @param module
159 * the service must be visible to the module (or null for the application's view)
160 * @return true if a single visible service for the specified service interface exists
161 * @since 1.1
162 */
163 public boolean containsService(Class serviceInterface, Module module);
164
165 /**
166 * Returns true if a single service with the given id exists which implements the specified
167 * service interface and is visible to the given module.
168 *
169 * @param serviceId
170 * @param serviceInterface
171 * @param module
172 * the service must be visible to the module (or null for the application's view)
173 * @return true if a single visible service for the specified service id and service interface
174 * exists
175 * @since 1.1
176 */
177 public boolean containsService(String serviceId, Class serviceInterface, Module module);
178
179 /**
180 * Invoked once, just after the registry infrastructure is constructed. One time startup
181 * operations occur, including execution of any contributions to <code>hivemind.Startup</code>.
182 *
183 * @since 1.1
184 */
185
186 public void startup();
187
188 /**
189 * Shuts down the registry; this notifies all
190 * {@link org.apache.hivemind.events.RegistryShutdownListener} services and objects. Once the
191 * registry is shutdown, it is no longer valid to obtain new services or configurations, or even
192 * use existing services and configurations.
193 *
194 * @since 1.1
195 */
196
197 public void shutdown();
198
199 /**
200 * To be invoked at the start of each request in a multi-threaded environment. Ensures that the
201 * receiving Registry will be used if any service proxies are de-serialized.
202 *
203 * @since 1.1
204 * @see org.apache.hivemind.internal.ser.ServiceSerializationHelper
205 * @see org.apache.hivemind.internal.ser.ServiceSerializationSupport
206 */
207
208 public void setupThread();
209
210 /**
211 * Convienience for invoking
212 * {@link org.apache.hivemind.service.ThreadEventNotifier#fireThreadCleanup()}.
213 *
214 * @since 1.1
215 */
216
217 public void cleanupThread();
218
219 /**
220 * @param serviceInterface
221 */
222 public List getServiceIds(Class serviceInterface);
223
224 /**
225 * Returns the module with the corresponding module id.
226 *
227 * @param moduleId
228 * @return the module with the corresponding module id
229 */
230 public Module getModule(String moduleId);
231
232 }