1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // IInvoker.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 "Invoker".
30 * <ul>
31 * <li>Asks the command to carry out the request.</li>
32 * </ul><br/>
33 *
34 * <br/>
35 * Example usage:
36 * <pre><code>
37 * //
38 * // Create Command Pattern elements
39 * //
40 * IInvoker myInvoker = new ConcreteInvoker();
41 * ICommand myCommand = new ConcreteCommand();
42 * IReceiver myReceiver = new ConcreteReceiver();
43 *
44 * //
45 * // Associate Command Pattern elements
46 * //
47 * myInvoker.setCommand(myCommand);
48 * myCommand.setReceiver(myReceiver);
49 *
50 * //
51 * // Optionally parameterize the Invoker
52 * //
53 * myInvoker.setParameter(new SomeParameter());
54 *
55 * //
56 * // Execute Invoker's invoke method that triggers execution of
57 * // Command and Receiver
58 * //
59 * myInvoker.invoke();
60 *
61 * //
62 * // Optionally and if the Command is synchronous, retrieve a result
63 * //
64 * System.out.println(myInvoker.getResult().toString());
65 * </code></pre>
66 *
67 * @param <P> Command Parameter context-specific
68 * @param <R> Command Result context-specific
69 *
70 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
71 * @version $Revision: 1.0 $ $Date: Jun 19, 2007 11:11:00 PM $
72 */
73 public
74 interface IInvoker<P, R>
75 {
76 //------------------------------------------------------------------------
77 // public
78 //------------------------------------------------------------------------
79 /**
80 * Sets the <code>ICommand</code> to start as result of executing the
81 * invoke method.
82 *
83 * @param aCommand <code>ICommand</code> to set.
84 */
85 public void
86 setCommand(ICommand<P, R> aCommand);
87
88 //------------------------------------------------------------------------
89 /**
90 * Returns the result of the execution of the <code>ICommand</code>.
91 *
92 * @return Result of the execution of the <code>ICommand</code>.
93 * @throws IllegalStateException 'ICommand was not set'
94 * @throws IllegalStateException 'No results available'
95 */
96 public R
97 getResult()
98 throws IllegalStateException;
99
100 //------------------------------------------------------------------------
101 /**
102 * Starts the appropriate <code>ICommand</code>.
103 *
104 * @throws IllegalStateException 'ICommand was not set'
105 */
106 public void
107 invoke()
108 throws IllegalStateException;
109
110 //------------------------------------------------------------------------
111 /**
112 * Sets the parameter required for the execution of the target
113 * <code>ICommand</code>.
114 *
115 * @param aParameter Parameter required for the execution of the target
116 * <code>ICommand</code>.
117 *
118 * @throws IllegalArgumentException Underlying implementations will
119 * impose different preconditions on the aParameter argument
120 */
121 public void
122 setParameter(P aParameter);
123 }