Clover coverage report - Code Coverage for hivemind release 1.1-rc-1
Coverage timestamp: Fri Sep 23 2005 10:46:55 EDT
file stats: LOC: 284   Methods: 0
NCLOC: 31   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
RegistryInfrastructure.java - - - -
coverage
 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.internal;
 16   
 17    import java.util.List;
 18    import java.util.Locale;
 19    import java.util.Map;
 20   
 21    import org.apache.hivemind.ErrorHandler;
 22    import org.apache.hivemind.Location;
 23    import org.apache.hivemind.SymbolSource;
 24    import org.apache.hivemind.schema.Translator;
 25   
 26    /**
 27    * Extension of {@link org.apache.hivemind.Registry} provided by some internals of HiveMind to
 28    * faciliate the creation of services and configurations.
 29    *
 30    * @author Howard Lewis Ship
 31    */
 32    public interface RegistryInfrastructure extends SymbolSource
 33    {
 34    /**
 35    * Obtains a service from the registry. Typically, what's returned is a proxy, but that's
 36    * irrelevant to the caller, which simply will invoke methods of the service interface.
 37    *
 38    * @param serviceId
 39    * the fully qualified id of the service to obtain
 40    * @param serviceInterface
 41    * the class to which the service will be cast
 42    * @param module
 43    * the referencing module, used for visibility checks (null means no module, which
 44    * requires that the service be public)
 45    * @return the service
 46    * @throws org.apache.hivemind.ApplicationRuntimeException
 47    * if the service does not exist (or is not visible), or if it can't be cast to the
 48    * specified service interface
 49    */
 50   
 51    public Object getService(String serviceId, Class serviceInterface, Module module);
 52   
 53    /**
 54    * Finds a service that implements the provided interface. Exactly one such service may exist or
 55    * an exception is thrown.
 56    *
 57    * @param serviceInterface
 58    * used to locate the service
 59    * @param module
 60    * the referencing module, used for visibility checks. If null, then only public
 61    * service points will be considered.
 62    * @throws org.apache.hivemind.ApplicationRuntimeException
 63    * if either 0, or more than 1, service point is visible to the module
 64    */
 65    public Object getService(Class serviceInterface, Module module);
 66   
 67    /**
 68    * Returns the converted items contributed to the configuration point.
 69    *
 70    * @param configurationId
 71    * the fully qualified id of the configuration
 72    * @param module
 73    * the referencing module, used for visibility checks (null means no module, which
 74    * requires that the configuration be public)
 75    * @return List of converted elements
 76    * @throws org.apache.hivemind.ApplicationRuntimeException
 77    * if no such configuration extension point exists (or visible)
 78    */
 79   
 80    public List getConfiguration(String configurationId, Module module);
 81   
 82    /**
 83    * Returns true if the elements contributed to the given configuration point can be
 84    * {@link #getConfigurationAsMap(String) retrieved as a Map}.
 85    *
 86    * @param configurationId
 87    * the fully qualified id of the configuration
 88    * @param module
 89    * the referencing module, used for visibility checks (null means no module, which
 90    * requires that the configuration be public)
 91    * @throws ApplicationRuntimeException
 92    * if no visible configuration point with the given id exists
 93    * @see Module#isConfigurationMappable(String)
 94    * @since 1.1
 95    */
 96    public boolean isConfigurationMappable(String configurationId, Module module);
 97   
 98    /**
 99    * Returns the elements of the given configuration point as an unmodifiable {@link Map}. It may
 100    * be empty, but not null.
 101    *
 102    * @param configurationId
 103    * the fully qualified id of the configuration
 104    * @param module
 105    * the referencing module, used for visibility checks (null means no module, which
 106    * requires that the configuration be public)
 107    * @throws ApplicationRuntimeException
 108    * if no visible configuration point with the given id exists or if the elements
 109    * can't be mapped.
 110    * @see Module#getConfigurationAsMap(String)
 111    * @see #isConfigurationMappable(String)
 112    * @since 1.1
 113    */
 114    public Map getConfigurationAsMap(String configurationId, Module module);
 115   
 116    /**
 117    * Returns the configuration point.
 118    *
 119    * @param configurationId
 120    * the fully qualified id of the configuration
 121    * @param module
 122    * the referencing module, used for visibility checks (null means no module, which
 123    * requires that the configuration be public)
 124    * @return ConfigurationPoint matching the configuration id
 125    * @throws org.apache.hivemind.ApplicationRuntimeException
 126    * if the configurationId does not exist (or is not visible)
 127    */
 128   
 129    public ConfigurationPoint getConfigurationPoint(String configurationId, Module module);
 130   
 131    /**
 132    * Returns the identified service extension point.
 133    *
 134    * @param serviceId
 135    * fully qualified id of the service point
 136    * @param module
 137    * the referencing module, used for visibility checks (null means no module, which
 138    * requires that the service be public)
 139    * @throws org.apache.hivemind.ApplicationRuntimeException
 140    * if no such service extension point exists (or is visible to the module)
 141    */
 142   
 143    public ServicePoint getServicePoint(String serviceId, Module module);
 144   
 145    /**
 146    * Expands any substitution symbols in the input string, replacing each symbol with the symbols
 147    * value (if known). If a symbol is unknown, then the symbol is passed through unchanged
 148    * (complete with the <code>${</code> and <code>}</code> delimiters) and an error is logged.
 149    *
 150    * @param input
 151    * input string to be converted, which may (or may not) contain any symbols.
 152    * @param location
 153    * the location from which the string was obtained, used if an error is logged.
 154    */
 155   
 156    public String expandSymbols(String input, Location location);
 157   
 158    /**
 159    * Returns a named service-model factory
 160    */
 161   
 162    public ServiceModelFactory getServiceModelFactory(String name);
 163   
 164    /**
 165    * Gets a {@link Translator} instance. The Translator may be a shared, cached instance
 166    * (Translators should be stateless). Translators are identified by a constructor, which may be
 167    * the name of a translator defined in the <code>hivemind.Translators</code> extension point
 168    * (a single builtin translator, <code>class</code>, is hardcoded). Alternately, the name may
 169    * consist of a translator name, a comma, and an initializer string for the service (example:
 170    * <code>int,min=5</code>).
 171    *
 172    * @param constructor
 173    * the name and optional initialization of a Translator
 174    * @return a {@link Translator} instance
 175    * @throws ApplicationRuntimeException
 176    * if the translator can not be constructed (i.e., the name is not known)
 177    */
 178    public Translator getTranslator(String constructor);
 179   
 180    /**
 181    * Returns the locale for which the registry was created.
 182    */
 183   
 184    public Locale getLocale();
 185   
 186    /**
 187    * Returns the {@link org.apache.hivemind.ErrorHandler} for this Registry.
 188    */
 189   
 190    public ErrorHandler getErrorHander();
 191   
 192    /**
 193    * Returns true if a configuration for the specified id exists (and is visible to the specified
 194    * module).
 195    *
 196    * @param configurationId
 197    * to search for
 198    * @param module
 199    * the configuration must be visible to, or null for no module (the application's
 200    * view
 201    * @return true if a configuration for the specified id exists (and is visible to the module)
 202    * @since 1.1
 203    */
 204    public boolean containsConfiguration(String configurationId, Module module);
 205   
 206    /**
 207    * Returns true if a single service exists which implements the specified service interface and
 208    * is visible to the given module.
 209    *
 210    * @param serviceInterface
 211    * @param module
 212    * the service must be visible to the module (or null for the application's view)
 213    * @return true if a single visible service for the specified service interface exists
 214    * @since 1.1
 215    */
 216    public boolean containsService(Class serviceInterface, Module module);
 217   
 218    /**
 219    * Returns true if a single service with the given id exists which implements the specified
 220    * service interface and is visible to the given module.
 221    *
 222    * @param serviceId
 223    * @param serviceInterface
 224    * @param module
 225    * the service must be visible to the module (or null for the application's view)
 226    * @return true if a single visible service for the specified service id and service interface
 227    * exists
 228    * @since 1.1
 229    */
 230    public boolean containsService(String serviceId, Class serviceInterface, Module module);
 231   
 232    /**
 233    * Invoked once, just after the registry infrastructure is constructed. One time startup
 234    * operations occur, including execution of any contributions to <code>hivemind.Startup</code>.
 235    *
 236    * @since 1.1
 237    */
 238   
 239    public void startup();
 240   
 241    /**
 242    * Shuts down the registry; this notifies all
 243    * {@link org.apache.hivemind.events.RegistryShutdownListener} services and objects. Once the
 244    * registry is shutdown, it is no longer valid to obtain new services or configurations, or even
 245    * use existing services and configurations.
 246    *
 247    * @since 1.1
 248    */
 249   
 250    public void shutdown();
 251   
 252    /**
 253    * To be invoked at the start of each request in a multi-threaded environment. Ensures that the
 254    * receiving Registry will be used if any service proxies are de-serialized.
 255    *
 256    * @since 1.1
 257    * @see org.apache.hivemind.internal.ser.ServiceSerializationHelper
 258    * @see org.apache.hivemind.internal.ser.ServiceSerializationSupport
 259    */
 260   
 261    public void setupThread();
 262   
 263    /**
 264    * Convienience for invoking
 265    * {@link org.apache.hivemind.service.ThreadEventNotifier#fireThreadCleanup()}.
 266    *
 267    * @since 1.1
 268    */
 269   
 270    public void cleanupThread();
 271   
 272    /**
 273    * @param serviceInterface
 274    */
 275    public List getServiceIds(Class serviceInterface);
 276   
 277    /**
 278    * Returns the module with the corresponding module id.
 279    *
 280    * @param moduleId
 281    * @return the module with the corresponding module id
 282    */
 283    public Module getModule(String moduleId);
 284    }