StrategyRegistry


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  }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags