1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // IReceiver.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.behavioral.command;
22
23 /**
24 * <b>Command Design Pattern</b>: Encapsulate a request as an object,
25 * thereby letting you parameterize clients with different
26 * requests, queue or log requests, and support undoable operations.
27 * (Gamma et al, Design Patterns)
28 * <br/><br/>
29 * <b>Responsibility</b>: Abstract generic definition of the "Receiver".
30 * <ul>
31 * <li>Knows how to perform the operations associated with carrying
32 * out the request.</li>
33 * </ul><br/>
34 *
35 * <br/>
36 * Example usage:
37 * <pre><code>
38 * //
39 * // Create Command Pattern elements
40 * //
41 * IInvoker myInvoker = new ConcreteInvoker();
42 * ICommand myCommand = new ConcreteCommand();
43 * IReceiver myReceiver = new ConcreteReceiver();
44 *
45 * //
46 * // Associate Command Pattern elements
47 * //
48 * myInvoker.setCommand(myCommand);
49 * myCommand.setReceiver(myReceiver);
50 *
51 * //
52 * // Optionally parameterize the Invoker
53 * //
54 * myInvoker.setParameter(new SomeParameter());
55 *
56 * //
57 * // Execute Invoker's invoke method that triggers execution of
58 * // Command and Receiver
59 * //
60 * myInvoker.invoke();
61 *
62 * //
63 * // Optionally and if the Command is synchronous, retrieve a result
64 * //
65 * System.out.println(myInvoker.getResult().toString());
66 * </code></pre>
67 *
68 * @param <P> Command Parameter context-specific
69 * @param <R> Command Result context-specific
70 *
71 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
72 * @version $Revision: 1.0 $ $Date: Jun 19, 2007 11:09:44 PM $
73 */
74 public
75 interface IReceiver<P, R>
76 {
77 //------------------------------------------------------------------------
78 // public
79 //------------------------------------------------------------------------
80 /**
81 * Sets the input parameter required for the execution of
82 * this <code>IReceiver</code>.
83 *
84 * @param aParameter Parameter required for executing the
85 * <code>IReceiver</code>.
86 * @throws IllegalArgumentException 'aParameter' must not be null.
87 */
88 public void
89 setParameter(P aParameter)
90 throws IllegalArgumentException;
91
92 //------------------------------------------------------------------------
93 /**
94 * Returns result out of executing this <code>IReceiver</code>.
95 *
96 * @return Result out of executing this <code>IReceiver</code>.
97 * @throws IllegalStateException No result available.
98 */
99 public R
100 getResult()
101 throws IllegalStateException;
102
103 //------------------------------------------------------------------------
104 /**
105 * Starts the execution of the <code>IReceiver</code>.
106 *
107 * @throws IllegalStateException Parameter not set.
108 */
109 public void
110 execute()
111 throws IllegalStateException;
112 }