Clover coverage report - Code Coverage for hivemind release 1.1
Coverage timestamp: Tue Oct 25 2005 10:47:07 EDT
file stats: LOC: 194   Methods: 0
NCLOC: 22   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
Registry.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;
 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    }