View Javadoc

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&lt;IDelegate&gt; 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&lt;IPrinter&gt; 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 }