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: * Returns true if a configuration for the specified id exists.
035: *
036: * @param configurationId
037: * @return true if a configuration for the specified id exists
038: */
039: public boolean containsConfiguration(String configurationId);
040:
041: /**
042: * Returns true if a single service for the specified service interface class exists.
043: *
044: * @param serviceInterface
045: * @return true if a single service for the specified service interface exists
046: */
047: public boolean containsService(Class serviceInterface);
048:
049: /**
050: * Returns true if a service for the specified service id and service interface exists.
051: *
052: * @param serviceId
053: * @param serviceInterface
054: * @return true if a service for the specified service id and service interface exists
055: */
056: public boolean containsService(String serviceId,
057: 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: }
|