01: // Copyright 2004, 2005 The Apache Software Foundation
02: //
03: // Licensed under the Apache License, Version 2.0 (the "License");
04: // you may not use this file except in compliance with the License.
05: // You may obtain a copy of the License at
06: //
07: // http://www.apache.org/licenses/LICENSE-2.0
08: //
09: // 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: * Registers an adapter for a registration class.
66: *
67: * @throws IllegalArgumentException
68: * if a strategy has already been registered for the given class.
69: */
70: public void register(Class registrationClass, Object strategy);
71:
72: /**
73: * Gets the stategy object for the specified subjectClass.
74: *
75: * @throws IllegalArgumentException
76: * if no strategy could be found.
77: */
78: public Object getStrategy(Class subjectClass);
79: }
|