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 import java.util.Map;
020
021 import org.apache.hivemind.internal.Module;
022
023 /**
024 * The HiveMind registry; primarily this is used to gain access to services.
025 * <p>
026 * In addition, Registry implements {@link org.apache.hivemind.SymbolSource} which allows
027 * programatic access to substitution symbols.
028 *
029 * @author Howard Lewis Ship
030 */
031
032 public interface Registry extends SymbolSource
033 {
034 /**
035 * Returns true if a configuration for the specified id exists.
036 *
037 * @param configurationId
038 * @return true if a configuration for the specified id exists
039 */
040 public boolean containsConfiguration(String configurationId);
041
042 /**
043 * Returns true if a single service for the specified service interface class exists.
044 *
045 * @param serviceInterface
046 * @return true if a single service for the specified service interface exists
047 */
048 public boolean containsService(Class serviceInterface);
049
050 /**
051 * Returns true if a service for the specified service id and service interface exists.
052 *
053 * @param serviceId
054 * @param serviceInterface
055 * @return true if a service for the specified service id and service interface exists
056 */
057 public boolean containsService(String serviceId, Class serviceInterface);
058
059 /**
060 * Returns a configuration as a List of elements (as defined by the schema for the configuration
061 * point, or as {@link org.apache.hivemind.Element}s if no configuration point does not define
062 * a schema.
063 *
064 * @param configurationId
065 * the fully qualified id of the configuration to obtain
066 * @return the configuration as an immutable List
067 * @throws ApplicationRuntimeException
068 * if the configuration does not exist, etc.
069 */
070 public List getConfiguration(String configurationId);
071
072 /**
073 * Returns true if the elements contributed to the given configuration point can be
074 * {@link #getConfigurationAsMap(String) retrieved as a Map}.
075 *
076 * @param configurationId
077 * the fully qualified id of the configuration
078 * @throws ApplicationRuntimeException
079 * if the configuration does not exist, etc.
080 * @see Module#isConfigurationMappable(String)
081 * @since 1.1
082 */
083 public boolean isConfigurationMappable(String configurationId);
084
085 /**
086 * Returns the elements of the given configuration point as an unmodifiable {@link Map}. It may
087 * be empty, but not null.
088 *
089 * @param configurationId
090 * the fully qualified id of the configuration
091 * @throws ApplicationRuntimeException
092 * if no public configuration point with the given id exists or if the elements
093 * can't be mapped.
094 * @see Module#getConfigurationAsMap(String)
095 * @see #isConfigurationMappable(String)
096 * @since 1.1
097 */
098 public Map getConfigurationAsMap(String configurationId);
099
100 /**
101 * Expands any substitution symbols in the input string, replacing each symbol with the symbols
102 * value (if known). If a symbol is unknown, then the symbol is passed through unchanged
103 * (complete with the <code>${</code> and <code>}</code> delimiters) and an error is logged.
104 *
105 * @param input
106 * input string to be converted, which may (or may not) contain any symbols.
107 * @param location
108 * the location from which the string was obtained, used if an error is logged.
109 */
110
111 public String expandSymbols(String input, Location location);
112
113 /**
114 * Obtains a service from the registry. Typically, what's returned is a proxy, but that's
115 * irrelevant to the caller, which simply will invoke methods of the service interface.
116 *
117 * @param serviceId
118 * the fully qualified id of the service to obtain
119 * @param serviceInterface
120 * the class to which the service will be cast
121 * @return the service
122 * @throws ApplicationRuntimeException
123 * if the service does not exist, or if it can't be cast to the specified service
124 * interface
125 */
126
127 public Object getService(String serviceId, Class serviceInterface);
128
129 /**
130 * Convenience method to obtain a service with a single implementation from the registry.
131 * Exactly one service point must implement the service.
132 *
133 * @param serviceInterface
134 * the class to which the service will be cast.
135 * @return the service implementing the given interface.
136 * @throws ApplicationRuntimeException
137 * if there are no service extension points implementing the given interface, or if
138 * there multiple service points implementing it.
139 * @see #getService(String, Class)
140 */
141
142 public Object getService(Class serviceInterface);
143
144 /**
145 * Returns the locale for which the registry was created.
146 */
147
148 public Locale getLocale();
149
150 /**
151 * Shuts down the registry; this notifies all
152 * {@link org.apache.hivemind.events.RegistryShutdownListener} services and objects. Once the
153 * registry is shutdown, it is no longer valid to obtain new services or configurations, or even
154 * use existing services and configurations.
155 */
156
157 public void shutdown();
158
159 /**
160 * To be invoked at the start of each request in a multi-threaded environment. Ensures that the
161 * receiving Registry will be used if any service proxies are de-serialized.
162 *
163 * @since 1.1
164 * @see org.apache.hivemind.internal.ser.ServiceSerializationHelper
165 * @see org.apache.hivemind.internal.ser.ServiceSerializationSupport
166 */
167
168 public void setupThread();
169
170 /**
171 * Convienience for invoking
172 * {@link org.apache.hivemind.service.ThreadEventNotifier#fireThreadCleanup()}.
173 */
174
175 public void cleanupThread();
176
177 /**
178 * Returns a list of service ids for service points which implement the desired service
179 * interface.
180 *
181 * @return Returns an empty List if no matching service points exist.
182 * @since 1.1
183 */
184 public List getServiceIds(Class serviceInterface);
185
186 /**
187 * Returns the Messages object for the specified module.
188 *
189 * @param moduleId
190 * the module id
191 * @return the Messages object for the specified module.
192 */
193 public Messages getModuleMessages(String moduleId);
194 }