Source code: org/apache/hivemind/Registry.java
1 // Copyright 2004, 2005 The Apache Software Foundation
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 package org.apache.hivemind;
16
17 import java.util.List;
18 import java.util.Locale;
19 import java.util.Map;
20
21 import org.apache.hivemind.internal.Module;
22
23 /**
24 * The HiveMind registry; primarily this is used to gain access to services.
25 * <p>
26 * In addition, Registry implements {@link org.apache.hivemind.SymbolSource} which allows
27 * programatic access to substitution symbols.
28 *
29 * @author Howard Lewis Ship
30 */
31
32 public interface Registry extends SymbolSource
33 {
34 /**
35 * Returns true if a configuration for the specified id exists.
36 *
37 * @param configurationId
38 * @return true if a configuration for the specified id exists
39 */
40 public boolean containsConfiguration(String configurationId);
41
42 /**
43 * Returns true if a single service for the specified service interface class exists.
44 *
45 * @param serviceInterface
46 * @return true if a single service for the specified service interface exists
47 */
48 public boolean containsService(Class serviceInterface);
49
50 /**
51 * Returns true if a service for the specified service id and service interface exists.
52 *
53 * @param serviceId
54 * @param serviceInterface
55 * @return true if a service for the specified service id and service interface exists
56 */
57 public boolean containsService(String serviceId, Class serviceInterface);
58
59 /**
60 * Returns a configuration as a List of elements (as defined by the schema for the configuration
61 * point, or as {@link org.apache.hivemind.Element}s if no configuration point does not define
62 * a schema.
63 *
64 * @param configurationId
65 * the fully qualified id of the configuration to obtain
66 * @return the configuration as an immutable List
67 * @throws ApplicationRuntimeException
68 * if the configuration does not exist, etc.
69 */
70 public List getConfiguration(String configurationId);
71
72 /**
73 * Returns true if the elements contributed to the given configuration point can be
74 * {@link #getConfigurationAsMap(String) retrieved as a Map}.
75 *
76 * @param configurationId
77 * the fully qualified id of the configuration
78 * @throws ApplicationRuntimeException
79 * if the configuration does not exist, etc.
80 * @see Module#isConfigurationMappable(String)
81 * @since 1.1
82 */
83 public boolean isConfigurationMappable(String configurationId);
84
85 /**
86 * Returns the elements of the given configuration point as an unmodifiable {@link Map}. It may
87 * be empty, but not null.
88 *
89 * @param configurationId
90 * the fully qualified id of the configuration
91 * @throws ApplicationRuntimeException
92 * if no public configuration point with the given id exists or if the elements
93 * can't be mapped.
94 * @see Module#getConfigurationAsMap(String)
95 * @see #isConfigurationMappable(String)
96 * @since 1.1
97 */
98 public Map getConfigurationAsMap(String configurationId);
99
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 }