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;
016
017 import java.util.List;
018 import java.util.Locale;
019
020 /**
021 * The HiveMind registry; primarily this is used to gain access to services.
022 * <p>
023 *
024 * @author Howard Lewis Ship
025 */
026 public interface Registry
027 {
028 /**
029 * Returns true if a configuration for the specified id exists.
030 *
031 * @param configurationId
032 * @return true if a configuration for the specified id exists
033 */
034 public boolean containsConfiguration(String configurationId);
035
036 /**
037 * Returns true if a single service for the specified service interface class exists.
038 *
039 * @param serviceInterface
040 * @return true if a single service for the specified service interface exists
041 */
042 public boolean containsService(Class serviceInterface);
043
044 /**
045 * Returns true if a service for the specified service id and service interface exists.
046 *
047 * @param serviceId
048 * @param serviceInterface
049 * @return true if a service for the specified service id and service interface exists
050 */
051 public boolean containsService(String serviceId, Class serviceInterface);
052
053 /**
054 * Returns the container of the configuration point.
055 *
056 * @param configurationId
057 * the fully qualified id of the configuration to obtain
058 * @return the configuration
059 * @throws ApplicationRuntimeException
060 * if the configuration does not exist, etc.
061 */
062 public Object getConfiguration(String configurationId);
063
064 /**
065 * Finds a configuration of the specified type. Exactly one such configuration may exist or
066 * an exception is thrown.
067 *
068 * @param configurationType
069 * the configuration type
070 * @return the configuration
071 * @throws org.apache.hivemind.ApplicationRuntimeException
072 * if no such configuration extension point exists (or visible)
073 */
074 public Object getConfiguration(Class configurationType);
075
076 /**
077 * Obtains a service from the registry. Typically, what's returned is a proxy, but that's
078 * irrelevant to the caller, which simply will invoke methods of the service interface.
079 *
080 * @param serviceId
081 * the fully qualified id of the service to obtain
082 * @param serviceInterface
083 * the class to which the service will be cast
084 * @return the service
085 * @throws ApplicationRuntimeException
086 * if the service does not exist, or if it can't be cast to the specified service
087 * interface
088 */
089
090 public Object getService(String serviceId, Class serviceInterface);
091
092 /**
093 * Convenience method to obtain a service with a single implementation from the registry.
094 * Exactly one service point must implement the service.
095 *
096 * @param serviceInterface
097 * the class to which the service will be cast.
098 * @return the service implementing the given interface.
099 * @throws ApplicationRuntimeException
100 * if there are no service extension points implementing the given interface, or if
101 * there multiple service points implementing it.
102 * @see #getService(String, Class)
103 */
104
105 public Object getService(Class serviceInterface);
106
107 /**
108 * Returns the locale for which the registry was created.
109 */
110
111 public Locale getLocale();
112
113 /**
114 * Shuts down the registry; this notifies all
115 * {@link org.apache.hivemind.events.RegistryShutdownListener} services and objects. Once the
116 * registry is shutdown, it is no longer valid to obtain new services or configurations, or even
117 * use existing services and configurations.
118 */
119
120 public void shutdown();
121
122 /**
123 * To be invoked at the start of each request in a multi-threaded environment. Ensures that the
124 * receiving Registry will be used if any service proxies are de-serialized.
125 *
126 * @since 1.1
127 * @see org.apache.hivemind.internal.ser.ServiceSerializationHelper
128 * @see org.apache.hivemind.internal.ser.ServiceSerializationSupport
129 */
130
131 public void setupThread();
132
133 /**
134 * Convienience for invoking
135 * {@link org.apache.hivemind.service.ThreadEventNotifier#fireThreadCleanup()}.
136 */
137
138 public void cleanupThread();
139
140 /**
141 * Returns a list of service ids for service points which implement the desired service
142 * interface.
143 *
144 * @return Returns an empty List if no matching service points exist.
145 * @since 1.1
146 */
147 public List getServiceIds(Class serviceInterface);
148
149 /**
150 * Returns the Messages object for the specified module.
151 *
152 * @param moduleId
153 * the module id
154 * @return the Messages object for the specified module.
155 */
156 public Messages getModuleMessages(String moduleId);
157 }