001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package com.sun.rave.designtime;
043:
044: import java.util.ArrayList;
045:
046: /**
047: * <p>A Result object represents the logical result of an operation. The <b>SUCCESS</b> and
048: * <b>FAILURE</b> Result objects are useful when returning an otherwise empty result with no user
049: * messages. <b>null</b> Results should never be returned, but if one is, it will be treated
050: * as Result.SUCCESS with no messages.</p>
051: *
052: * <p>Some Result objects may contain user messages, returned by the 'getMessages()' method. These
053: * messages will be displayed to the user in one of three ways:</p>
054: *
055: * <p><table border="1" width="100%">
056: * <tr>
057: * <td><b>Status Bar</b></td>
058: * <td>The Status Bar displays very low-importance messages. Any ResultMessage objects of type
059: * ResultMessage.TYPE_INFORMATION will be displayed here, as long as there are no result
060: * options returned from the 'getResultOptions()' method.</td>
061: * </tr>
062: * <tr>
063: * <td><b>Message Window</b></td>
064: * <td>The Message Window displays more important messages than the status bar, as they are
065: * persisted until the user clears the message window. Any ResultMessage objects of type
066: * ResultMessage.TYPE_WARNING will be displayed here, as long as there are no result
067: * options returned from the 'getResultOptions()' method.</td>
068: * </tr>
069: * <tr>
070: * <td><b>Message Dialog</b></td>
071: * <td>A pop-up modal Message Dialog displays the most important messages, as the user must stop
072: * work to 'handle' the dialog. Any ResultMessage objects of type ResultMessage.TYPE_CRITICAL
073: * will be displayed in an modal dialog. If there are any result options returned from the
074: * 'getResultOptions()' method, they will be displayed as buttons in the dialog, otherwise
075: * a default 'OK' button will be displayed. If a Result contains messages that are less
076: * than TYPE_CRITICAL, but result options are included - the messages will be 'upgraded' and
077: * displayed in the model dialog, as if they were TYPE_CRITICAL.</td>
078: * </tr>
079: * </table></p>
080: *
081: * <p>The three most important methods of this class are: 'isSuccess()', 'getMessages()', and
082: * 'getMessageOptions()'. These are called by the IDE to investigate the details of a Result
083: * object.</p>
084: *
085: * @author Joe Nuxoll
086: * @version 1.0
087: */
088: public class Result {
089:
090: /**
091: * Common instance of a successful result object
092: */
093: public static final Result SUCCESS = new Result(true);
094:
095: /**
096: * Common instance of a failed result object
097: */
098: public static final Result FAILURE = new Result(false);
099:
100: /**
101: * Protected storage for the 'success' property
102: */
103: protected boolean success;
104:
105: /**
106: * Protected storage for the message list (ResultMessage[])
107: */
108: protected ArrayList messages;
109:
110: /**
111: * Protected storage for the result option list (DisplayAction[])
112: */
113: protected ArrayList options;
114:
115: /**
116: * Constructs a Result object with the specified success status
117: *
118: * @param success <code>true</code> if successful, <code>false</code> if not
119: */
120: public Result(boolean success) {
121: this .success = success;
122: }
123:
124: /**
125: * Constructs a Result object with the specified success status and message
126: *
127: * @param success <code>true</code> if successful, <code>false</code> if not
128: * @param message A ResultMessage to display to the user
129: */
130: public Result(boolean success, ResultMessage message) {
131: this (success);
132: addMessage(message);
133: }
134:
135: /**
136: * Constructs a Result object with the specified success status and messages
137: *
138: * @param success <code>true</code> if successful, <code>false</code> if not
139: * @param messages A set of ResultMessage(s) to display to the user
140: */
141: public Result(boolean success, ResultMessage[] messages) {
142: this (success);
143: for (int i = 0; messages != null && i < messages.length; i++) {
144: addMessage(messages[i]);
145: }
146: }
147:
148: /**
149: * Constructs a Result object with the specified success status, messages, and options
150: *
151: * @param success <code>true</code> if successful, <code>false</code> if not
152: * @param messages A set of ResultMessage(s) to display to the user
153: * @param options A set of DisplayAction(s) to present to the user as option buttons
154: */
155: public Result(boolean success, ResultMessage[] messages,
156: DisplayAction[] options) {
157: this (success, messages);
158: for (int i = 0; options != null && i < options.length; i++) {
159: addResultOption(options[i]);
160: }
161: }
162:
163: /**
164: * Sets the success state of this Result
165: *
166: * @param success the success state of this Result
167: */
168: public void setSuccess(boolean success) {
169: this .success = success;
170: }
171:
172: /**
173: * Returns <code>true</code> if the operation represented by this Result object was successful
174: *
175: * @return <code>true</code> if the operation was successful, <code>false</code> if not
176: */
177: public boolean isSuccess() {
178: return success;
179: }
180:
181: /**
182: * Adds a ResultMessage to this Result to be displayed to the user
183: *
184: * @param message The ResultMessage to add
185: */
186: public void addMessage(ResultMessage message) {
187: if (message == null) {
188: return;
189: }
190: if (messages == null) {
191: messages = new ArrayList();
192: }
193: if (!messages.contains(message)) {
194: messages.add(message);
195: }
196: }
197:
198: /**
199: * Adds an array of ResultMessage to this Result to be displayed to the user
200: *
201: * @param messages The array of ResultMessage(s) to add
202: */
203: public void addMessages(ResultMessage[] messages) {
204: if (messages == null || messages.length < 1) {
205: return;
206: }
207: if (this .messages == null) {
208: this .messages = new ArrayList();
209: }
210: for (int i = 0; i < messages.length; i++) {
211: if (!this .messages.contains(messages[i])) {
212: this .messages.add(messages[i]);
213: }
214: }
215: }
216:
217: /**
218: * Removes a ResultMessage from the set to display to the user
219: *
220: * @param message the ResultMessage to remove from the set
221: */
222: public void removeMessage(ResultMessage message) {
223: if (messages == null || message == null) {
224: return;
225: }
226: messages.remove(message);
227: if (messages.size() == 0) {
228: messages = null;
229: }
230: }
231:
232: /**
233: * Removes an array of ResultMessage(s) from the set to display to the user
234: *
235: * @param messages the ResultMessage(s) to remove from the set
236: */
237: public void removeMessages(ResultMessage[] messages) {
238: if (this .messages == null || messages == null
239: || messages.length < 1) {
240: return;
241: }
242: for (int i = 0; i < messages.length; i++) {
243: this .messages.remove(messages[i]);
244: }
245: if (this .messages.size() == 0) {
246: this .messages = null;
247: }
248: }
249:
250: /**
251: * Returns the count of ResultMessage(s) in this Result
252: *
253: * @return the count of ResultMessage(s) in this Result
254: */
255: public int getMessageCount() {
256: return messages != null ? messages.size() : 0;
257: }
258:
259: /**
260: * Returns an (optional) set of ResultMessage objects from the completed operation. Any
261: * ResultMessage objects will be displayed to the user either via the status-line, message
262: * window, or in a dialog - depending on several conditions outlined above.
263: *
264: * @return An array of ResultMessage objects, or null if there the operation produced no
265: * messages
266: */
267: public ResultMessage[] getMessages() {
268: return messages != null ? (ResultMessage[]) messages
269: .toArray(new ResultMessage[messages.size()]) : null;
270: }
271:
272: /**
273: * Adds a DisplayAction to this Result to be displayed to the user as an option button in a
274: * dialog
275: *
276: * @param option The DisplayAction to add as an option button
277: */
278: public void addResultOption(DisplayAction option) {
279: if (option == null) {
280: return;
281: }
282: if (options == null) {
283: options = new ArrayList();
284: }
285: if (!options.contains(option)) {
286: options.add(option);
287: }
288: }
289:
290: /**
291: * Adds a set of DisplayAction(s) to this Result to be displayed to the user as option buttons
292: * in a dialog
293: *
294: * @param options The DisplayAction(s) to add as option buttons
295: */
296: public void addResultOptions(DisplayAction[] options) {
297: if (options == null || options.length < 1) {
298: return;
299: }
300: if (this .options == null) {
301: this .options = new ArrayList();
302: }
303: for (int i = 0; i < options.length; i++) {
304: if (!this .options.contains(options[i])) {
305: this .options.add(options[i]);
306: }
307: }
308: }
309:
310: /**
311: * Removes a DisplayAction (option button in a dialog) from this Result
312: *
313: * @param option The DisplayAction (option button) to remove
314: */
315: public void removeResultOption(DisplayAction option) {
316: if (options == null || option == null) {
317: return;
318: }
319: options.remove(option);
320: if (options.size() == 0) {
321: options = null;
322: }
323: }
324:
325: /**
326: * Removes an array of DisplayAction(s) (option buttons in a dialog) from this Result
327: *
328: * @param options The DisplayAction(s) (option buttons) to remove
329: */
330: public void removeResultOptions(DisplayAction[] options) {
331: if (this .options == null || options == null
332: || options.length < 1) {
333: return;
334: }
335: for (int i = 0; i < options.length; i++) {
336: this .options.remove(options[i]);
337: }
338: if (this .options.size() == 0) {
339: this .options = null;
340: }
341: }
342:
343: /**
344: * Returns the count of DisplayAction(s) in this Result which will be displayed to the user as
345: * option buttons in a dialog
346: *
347: * @return The count of option buttons to show in the dialog
348: */
349: public int getResultOptionCount() {
350: return options != null ? options.size() : 0;
351: }
352:
353: /**
354: * Returns an (optional) set of DisplayAction objects representing options in a dialog box for
355: * the user. If the returned array is non-null and has more than zero elements, a dialog box
356: * will automatically be shown to the user with a button for each returned DisplayAction. When
357: * the user 'clicks' a particular button, the DisplayAction will be 'invoked()'.
358: *
359: * @return An array of DisplayAction objects representing buttons in a dialog to show the user,
360: * or null
361: */
362: public DisplayAction[] getResultOptions() {
363: return options != null ? (DisplayAction[]) options
364: .toArray(new DisplayAction[options.size()]) : null;
365: }
366:
367: /**
368: * Protected storage for the 'resultDialogTitle' property
369: */
370: protected String dialogTitle;
371:
372: /**
373: * Sets the 'dialogTitle' property. The Result can only trigger a dialog if there is a
374: * ResultMessage of TYPE_CRITICAL or there are result options to display.
375: *
376: * @param dialogTitle The desired title for the result dialog
377: */
378: public void setDialogTitle(String dialogTitle) {
379: this .dialogTitle = dialogTitle;
380: }
381:
382: /**
383: * Returns the 'dialogTitle' property. The Result can only trigger a dialog if there is a
384: * ResultMessage of TYPE_CRITICAL or there are result options to display.
385: *
386: * @return The title for the result dialog
387: */
388: public String getDialogTitle() {
389: return dialogTitle;
390: }
391:
392: /**
393: * Protected storage for the 'dialogHelpKey' property
394: */
395: protected String helpKey;
396:
397: /**
398: * Sets the 'dialogHelpKey' property. The Result can only trigger a dialog if there is a
399: * ResultMessage of TYPE_CRITICAL or there are result options to display.
400: *
401: * @param dialogHelpKey The desired help key for the result dialog
402: */
403: public void setDialogHelpKey(String helpKey) {
404: this .helpKey = helpKey;
405: }
406:
407: /**
408: * Returns the 'dialogHelpKey' property. The Result can only trigger a dialog if there is a
409: * ResultMessage of TYPE_CRITICAL or there are result options to display.
410: *
411: * @return The help key for the result dialog
412: */
413: public String getDialogHelpKey() {
414: return helpKey;
415: }
416: }
|