Clover coverage report - Code Coverage for hivemind-lib release 1.1.1
Coverage timestamp: Sat Jan 28 2006 10:19:55 PST
file stats: LOC: 80   Methods: 0
NCLOC: 5   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
StrategyRegistry.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.lib.util;
 16   
 17    /**
 18    * An implementation of the <b>strategy </b> pattern. The strategy pattern allows new functionality
 19    * to be assigned to an existing class. As implemented here, this is a smart lookup between a
 20    * particular class (called the <em>subject class</em>) and some object instance that can provide
 21    * the extra functionality (called the <em>strategy</em>). The implementation of the strategy is
 22    * not relevant to the StrategyRegistry class.
 23    * <p>
 24    * Strategies are registered before they can be used; the registration maps a particular class to a
 25    * strategy instance. The strategy instance will be used when the subject class matches the
 26    * registered class, or the subject class inherits from the registered class.
 27    * <p>
 28    * This means that a search must be made that walks the inheritance tree (upwards from the subject
 29    * class) to find a registered mapping.
 30    * <p>
 31    * In addition, strategies can be registered against <em>interfaces</em>. Searching of interfaces
 32    * occurs after searching of classes. The exact order is:
 33    * <ul>
 34    * <li>Search for the subject class, then each super-class of the subject class (excluding
 35    * java.lang.Object)
 36    * <li>Search interfaces, starting with interfaces implemented by the subject class, continuing
 37    * with interfaces implemented by the super-classes, then interfaces extended by earlier interfaces
 38    * (the exact order is a bit fuzzy)
 39    * <li>Search for a match for java.lang.Object, if any
 40    * </ul>
 41    * <p>
 42    * The first match terminates the search.
 43    * <p>
 44    * The StrategyRegistry caches the results of search; a subsequent search for the same subject class
 45    * will be resolved immediately.
 46    * <p>
 47    * StrategyRegistry does a minor tweak of the "natural" inheritance. Normally, the parent class of
 48    * an object array (i.e., <code>Foo[]</code>) is simply <code>Object</code>, even though you
 49    * may assign <code>Foo[]</code> to a variable of type <code>Object[]</code>. StrategyRegistry
 50    * "fixes" this by searching for <code>Object[]</code> as if it was the superclass of any object
 51    * array. This means that the search path for <code>Foo[]</code> is <code>Foo[]</code>,
 52    * <code>Object[]</code>, then a couple of interfaces {@link java.lang.Cloneable},
 53    * {@link java.io.Serializable}, etc. that are implicitily implemented by arrays), and then,
 54    * finally, <code>Object</code>
 55    * <p>
 56    * This tweak doesn't apply to arrays of primitives, since such arrays may <em>not</em> be
 57    * assigned to <code>Object[]</code>.
 58    *
 59    * @author Howard M. Lewis Ship
 60    * @see org.apache.hivemind.lib.util.StrategyRegistryImpl
 61    * @since 1.1
 62    */
 63    public interface StrategyRegistry
 64    {
 65    /**
 66    * Registers an adapter for a registration class.
 67    *
 68    * @throws IllegalArgumentException
 69    * if a strategy has already been registered for the given class.
 70    */
 71    public void register(Class registrationClass, Object strategy);
 72   
 73    /**
 74    * Gets the stategy object for the specified subjectClass.
 75    *
 76    * @throws IllegalArgumentException
 77    * if no strategy could be found.
 78    */
 79    public Object getStrategy(Class subjectClass);
 80    }