1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // ICommand.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 "Command".
30 * <ul>
31 * <li>Declares an interface for executing an operation.</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:09:51 PM $
72 */
73 public
74 interface ICommand<P, R>
75 {
76 //------------------------------------------------------------------------
77 // public
78 //------------------------------------------------------------------------
79 /**
80 * Returns the result of this <code>ICommand</code> execution.
81 *
82 * @return Result of this <code>ICommand</code> execution.
83 * @throws IllegalStateException IReceiver was not set.
84 * @throws IllegalStateException No result available.
85 */
86 public R
87 getResult()
88 throws IllegalStateException;
89
90 //------------------------------------------------------------------------
91 /**
92 * Sets the parameter required for the execution of the target
93 * <code>IReceiver</code>.
94 *
95 * @param aParameter Parameter required for the execution of the target
96 * <code>IReceiver</code>.
97 * @throws IllegalArgumentException 'aParameter' must not be null.
98 */
99 public void
100 setParameter(P aParameter)
101 throws IllegalArgumentException;
102
103 //------------------------------------------------------------------------
104 /**
105 * Sets the <code>IReceiver</code> associated to this <code>ICommand</code>
106 *
107 * @param aReceiver to set
108 * @throws IllegalArgumentException 'aReceiver' must not be null.
109 */
110 public void
111 setReceiver(IReceiver<P, R> aReceiver)
112 throws IllegalArgumentException;
113
114 //------------------------------------------------------------------------
115 /**
116 * Executes the <code>ICommand</code>.
117 *
118 * @throws IllegalStateException IReceiver was not set.
119 */
120 public void
121 execute()
122 throws IllegalStateException;
123 }