1 /*
2 * Scope: a generic MVC framework.
3 * Copyright (c) 2000-2002, The Scope team
4 * All rights reserved.
5 *
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 *
11 * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 *
14 * Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in the
16 * documentation and/or other materials provided with the distribution.
17 *
18 * Neither the name "Scope" nor the names of its contributors
19 * may be used to endorse or promote products derived from this software
20 * without specific prior written permission.
21 *
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
27 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
28 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
29 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 *
35 *
36 * $Id: Control.java,v 1.8 2002/09/11 19:12:29 ludovicc Exp $
37 */
38 package org.scopemvc.core;
39
40
41 import org.scopemvc.util.Debug;
42
43 /***
44 * <P>
45 *
46 * A token passed up the chain of Controllers to invoke a piece of presentation
47 * logic. Controllers match against the ID of a Control passed into {@link
48 * org.scopemvc.core.Controller#handleControl handleControl} If the ID is
49 * recognised then the Controller can execute some presentation logic. If the
50 * Control ID is not recognised, the Control should be sent back on its journey
51 * up the chain of responsibility by passing it to the parent Controller. See
52 * {@link org.scopemvc.core.Controller#handleControl Controller.handleControl()}
53 * and {@link org.scopemvc.controller.basic.BasicController#passControlToParent
54 * BasicController.passControlToParent()}. </P> <P>
55 *
56 * Controls are received by a Controller from either a View or a child
57 * Controller. </P> <P>
58 *
59 * Controls can optionally contain an Object parameter: see {@link
60 * #getParameter} </P> <P>
61 *
62 * The Control ID is used by Controllers to recognise a Control and also as a
63 * key to the user-readable version of the the Control's name in {@link
64 * org.scopemvc.util.UIStrings UIStrings} presented to the user by the default
65 * error-handling mechanism in {@link org.scopemvc.controller.basic.BasicController
66 * BasicController}. </P>
67 *
68 * @author <A HREF="mailto:smeyfroi@users.sourceforge.net">Steve Meyfroidt</A>
69 * @created 05 August 2002
70 * @version $Revision: 1.8 $ $Date: 2002/09/11 19:12:29 $
71 * @see View
72 * @see Controller
73 */
74 public class Control {
75
76 private String id;
77
78 private Object parameter;
79
80 private boolean matched;
81
82
83 /***
84 * Create a Control with a unique String ID and no parameter.
85 *
86 * @param inID The unique ID identifying the Control
87 */
88 public Control(String inID) {
89 if (inID == null) {
90 throw new IllegalArgumentException("Can't create a Control with a null ControlID");
91 }
92 matched = false;
93 id = inID;
94 }
95
96
97 /***
98 * Create a Control with a unique String ID and a parameter.
99 *
100 * @param inID The unique ID identifying the Control
101 * @param inParameter A parameter for the Control
102 */
103 public Control(String inID, Object inParameter) {
104 this(inID);
105 parameter = inParameter;
106 }
107
108
109 /***
110 * For matching a Control in a Controller's doHandleControl, always use
111 * {@link #matchesID} not this method.
112 *
113 * @return The name value
114 * @deprecated use {@link #matchesID} not this method which will be removed
115 * at some point.
116 */
117 public final String getName() {
118 return id;
119 }
120
121
122 /***
123 * Has this Control been matched by a Controller yet?
124 *
125 * @return The matched value
126 */
127 public final boolean isMatched() {
128 return matched;
129 }
130
131
132 /***
133 * Get the parameter for the Control
134 *
135 * @return The parameter value
136 */
137 public final Object getParameter() {
138 return parameter;
139 }
140
141
142 /***
143 * Set a parameter for the Control
144 *
145 * @param inParameter The new parameter value
146 */
147 public final void setParameter(Object inParameter) {
148 parameter = inParameter;
149 }
150
151
152 /***
153 * Mark the Control as unmatched.
154 */
155 public final void markUnmatched() {
156 matched = false;
157 }
158
159
160 /***
161 * Mark the Control as matched. <br>
162 * Matched controls won't be handled to the parent controller.
163 */
164 public final void markMatched() {
165 matched = true;
166 }
167
168
169 /***
170 * Tests if this Control matches the given ID. <br>
171 * Use this method in Controller's doHandleControl to discover Controls that
172 * you want to handle.
173 *
174 * @param inID The ID to test against
175 * @return true if this control ID matches the passed ID.
176 */
177 public final boolean matchesID(String inID) {
178 if (Debug.ON) {
179 Debug.assertTrue(id != null);
180 }
181 if (inID == null) {
182 throw new IllegalArgumentException("Can't match against a null ID.");
183 }
184 if (matched) {
185 throw new RuntimeException("Already matched this Control once.");
186 }
187
188 matched = (id.equals(inID));
189 return matched;
190 }
191
192
193 /***
194 * For use by a ControlException handler only, not for application writers.
195 *
196 * @param inException exception to populate with info from this Control.
197 */
198 public void populateControlException(ControlException inException) {
199 inException.setSourceControlID(id);
200 }
201
202
203 /***
204 * Tests for equality
205 *
206 * @param obj the reference object with which to compare.
207 * @return <code>true</code> if this object is the same as the obj argument;
208 * <code>false</code> otherwise.
209 */
210 public boolean equals(Object obj) {
211 if (!(obj instanceof Control)) {
212 return false;
213 }
214 Control o = (Control) obj;
215 return (id.equals(o.id)
216 && (parameter == null && o.parameter == null)
217 || (parameter != null && parameter.equals(o.parameter)));
218 }
219
220
221 /***
222 * Returns the hashCode
223 *
224 * @return the hashCode
225 */
226 public int hashCode() {
227 return id.hashCode();
228 }
229
230
231 /***
232 * Returns a string representation of the object.
233 *
234 * @return a string representation of the object.
235 */
236 public String toString() {
237 return "Control(" + id + "," + parameter + ")";
238 }
239 }
This page was automatically generated by Maven