1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // IDelegate.java Copyright (c) 2009 Giovanni Azua Garcia
5 // bravegag@hotmail.com
6 //
7 // This program is free software; you can redistribute it and/or
8 // modify it under the terms of the GNU General Public License
9 // as published by the Free Software Foundation; either version 3
10 // of the License, or (at your option) any later version.
11 //
12 // This program is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 // GNU General Public License for more details.
16 //
17 // You should have received a copy of the GNU General Public License
18 // along with this program; if not, see <http://www.gnu.org/licenses/>.
19 //
20 //----------------------------------------------------------------------
21 package org.perfectjpattern.core.api.extras.delegate;
22
23 /**
24 * <b>Delegates Design Pattern</b>: Allows multiple objects implementing
25 * methods with different names but compatible signatures to be used
26 * interchangeably. It will also work with or without a target interface
27 * to implement i.e. using <code>IDelegate</code>.
28 * <br/><br/>
29 * The <code>IDelegator</code> interface simplifies and generalizes the
30 * steps in creating an Adapter. Delegates are simple to use, and
31 * a single delegate instance may be reused multiple times.
32 * <br/><br/>
33 * <b>Responsibility</b>: Definition of "Delegate" interface.
34 * Default target interface that should be used when there is no
35 * an explicitly defined target interface.
36 * <br/><br/>
37 * <b>Notes</b>: Base source code implemented by Steve Lewis and Wilhelm
38 * Fitzpatrick and adapted to fit PerfectJPattern componentization
39 * criteria and code conventions.
40 *
41 * <br/><br/>
42 * Example usage:
43 * <pre><code>
44 * //
45 * // Example class that defines two methods that match in signature
46 * //
47 * class Example
48 * {
49 * //--------------------------------------------------------------------
50 * public static void
51 * staticMethod(String aValue)
52 * {
53 * System.out.println(aValue);
54 * }
55 *
56 * //--------------------------------------------------------------------
57 * public void
58 * memberMethod(String aValue)
59 * {
60 * System.out.println(aValue);
61 * }
62 * }
63 *
64 * //
65 * // Defines a common interface with method printValue
66 * //
67 * interface IPrinter
68 * {
69 * //--------------------------------------------------------------------
70 * public void
71 * printValue(String aValue);
72 * }
73 *
74 * //
75 * // Create instance of example class
76 * //
77 * Example myInstance = new Example();
78 *
79 * //
80 * // Example using DynamicDelegator without well defined target interface
81 * //
82 * IDelegator<IDelegate> myDynamicDelegator = new DynamicDelegator(
83 * Void.TYPE, String.class);
84 *
85 * //
86 * // Build appropriate IDelegate references
87 * //
88 * IDelegate myDelegate1 = myDynamicDelegator.build(Example.class,
89 * "staticMethod");
90 * IDelegate myDelegate2 = myDynamicDelegator.build(myInstance,
91 * "memberMethod");
92 *
93 * //
94 * // Use the Delegate references to invoke the target methods.
95 * //
96 * myDelegate1.invoke("Value1");
97 * myDelegate2.invoke("Value2");
98 *
99 * //
100 * // Example using well defined target interface
101 * //
102 * IDelegator<IPrinter> myPrinterDelegator = new Delegator(
103 * IPrinter.class);
104 *
105 * //
106 * // Build appropriate IPrinter references
107 * //
108 * IPrinter myPrinter1 = myPrinterDelegator.build(Example.class,
109 * "staticMethod");
110 * IPrinter myPrinter2 = myPrinterDelegator.build(myInstance,
111 * "memberMethod");
112 *
113 * //
114 * // Use the IPrinter interface reference.
115 * //
116 * myPrinter1.printValue("Value1");
117 * myPrinter2.printValue("Value2");
118 * </code></pre>
119 *
120 * @see <a href="http://www.onjava.com/pub/a/onjava/2003/05/21/delegates.html">
121 * Article: A Java Programmer Looks at C-Sharp Delegates</a>
122 *
123 * @author <a href="mailto:smlewis@lordjoe.com">Steve Lewis</a>
124 * @author <a href="mailto:wilhelmf@agileinformatics.com">Wilhelm
125 * Fitzpatrick</a>
126 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
127 * @version $Revision: 2.0 $ $Date: Jun 24, 2007 12:28:16 PM $
128 */
129 public interface
130 IDelegate
131 {
132 //------------------------------------------------------------------------
133 // public
134 //------------------------------------------------------------------------
135 /**
136 * Returns the Result of the target call; primitive types are wrapped;
137 * may return void result.
138 *
139 * Executes the target method using the input arguments and returns the
140 * appropriate result if any.
141 *
142 * @param anArguments List of input arguments.
143 * @return Result of the target call; primitive types are wrapped;
144 * may return void result.
145 */
146 public Object
147 invoke(Object... anArguments);
148 }