MessageStack


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 2004 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.modules.junit;
21  
22  /**
23   * Manager of layered messages.
24   * It serves for management of messages layered over. When a message is to be
25   * displayed, it is put into a certain layer. When there is another message
26   * set in an upper layer, the topmost message does not change. Conversely,
27   * when the topmost message is cleared, another message becomes the topmost
28   * message and needs to be displayed. This class handles all these changes
29   * and returns information what message needs to be displayed after each
30   * addition/removal of message.
31   * <p>
32   * The stack has a fixed number of layers
33   * (specified by calling the constructor). Each layer has its number,
34   * beginning with <code>0</code> (the topmost layer) and ending with
35   * <code><var>n</var> - 1</code> where <code><var>n</var></code>
36   * is the number of layers.
37   * <p>
38   * There is one special layer for displaying volatile messages.
39   * Volatile messages are those messages that are always displayed
40   * on the top of all other messages but are cleared/overwritten
41   * as soon as another message is to be displayed.
42   *
43   * @see  #setMessage
44   * @author Marian Petras
45   */
46  public final class MessageStack {
47      
48      /*
49       * The class is final only for performance reasons.
50       */
51      
52      /** layer number of the special layer for volatile messages */
53      public static final int LAYER_VOLATILE = -1;
54      
55      /**
56       * messages in layers (index <code>0</code> means the topmost layer)
57       */
58      private final String  [] messageLayers;
59      /**
60       * index of the visible (topmost non-empty) layer.
61       * If the stack is empty, it has value <code>-1</code>.
62       */
63      private int visibleLayerIndex = -1;
64      /** currently displayed volatile message (or <code>null</code>) */
65      private String   volatileMsg;
66      
67      /**
68       * Creates a new <code>MessageStack</code> with a given number of layers.
69       *
70       * @param  size  number of layers in the stack
71       */
72      public MessageStack(int size) {
73          if (size <= 0) {
74              throw new IllegalArgumentException  (
75                      "number of layers must be positive");               //NOI18N
76          }
77          messageLayers = new String  [size];
78      }
79  
80      /**
81       * Returns the currently &quot;displayed&quot; message.
82       *
83       * @return  message that should be currently displayed according to
84       *          performed display modifications;
85       *          or <code>null</code> if no message should be displayed
86       */
87      public String   getDisplayedMessage() {
88          return volatileMsg != null ? volatileMsg
89                                     : getTopmostStackMessage();
90      }
91      
92      /**
93       * Returns the topmost message on the stack.
94       *
95       * @return  the topmost non-empty message on the stack;
96       *          or <code>null</code> if the stack is empty
97       */
98      private String   getTopmostStackMessage() {
99          return visibleLayerIndex != -1 ? messageLayers[visibleLayerIndex]
100                                        : null;
101     }
102     
103     /**
104      * Clears this message stack.
105      * After cleaning, both volatile message and all of the stack messages
106      * are empty.
107      */
108     public void clear() {
109         volatileMsg = null;
110         if (visibleLayerIndex != -1) {
111             for (int i = visibleLayerIndex; i < messageLayers.length; i++) {
112                 messageLayers[i] = null;
113             }
114             visibleLayerIndex = -1;
115         }
116     }
117 
118     /**
119      * Puts a message on the given layer of the stack.
120      * Putting a message on the special layer for volatile messages
121      * (layer number <code>LAYER_VOLATILE</code>) has the same effect
122      * as calling {@link #setVolatileMessage(String)}.
123      *
124      * @param  layer  layer number
125      * @param  message  message to be displayed, or <code>null</code>
126      *                  if the existing message should be removed from the layer
127      * @return  message that needs to be displayed in order to show the topmost
128      *          message of the (updated) stack, or <code>null</code> if no
129      *          change of display is necessary
130      * @exception  java.lang.IllegalArgumentException
131      *             if value of the <code>msgType</code> parameter is illegal
132      */
133     public String   setMessage(final int layer, String   message)
134             throws IllegalArgumentException   {
135         
136         /* check parameters: */
137         if (layer == LAYER_VOLATILE) {
138             return setVolatileMessage(message);
139         }
140         if (layer < 0 || layer >= messageLayers.length) {
141             throw new IllegalArgumentException  (
142                     java.text.MessageFormat.format(
143                         "Message type out of bounds (0 .. {1}): {0}",   //NOI18N
144                         new Object  [] { new Integer  (layer),
145                                        new Integer  (messageLayers.length) }));
146         }
147         
148         /* unify parameters: */
149         if ((message != null) && (message.trim().length() == 0)) {
150             message = null;
151         }
152 
153         final String   oldDisplayed = getDisplayedMessage();
154 
155         /* update the register of messages: */
156         volatileMsg = null;
157         messageLayers[layer] = message;
158 
159         /* update the visible layer index: */
160         if (message != null) {
161             if ((visibleLayerIndex == -1) || (layer < visibleLayerIndex)) {
162                 visibleLayerIndex = layer;
163             }
164         } else if (layer == visibleLayerIndex) {
165             for (int i = layer + 1; i < messageLayers.length; i++) {
166                 if (messageLayers[i] != null) {
167                     visibleLayerIndex = i;
168                     break;
169                 }
170             }
171             if (visibleLayerIndex == layer) {    //no visible layer found
172                 visibleLayerIndex = -1;
173             }
174         }
175 
176         /* compare the old and new display: */
177         return checkDisplayModified(oldDisplayed, getDisplayedMessage());
178     }
179 
180     /**
181      * Clears a message on the given layer of the stack.
182      * Calling this method has the same effect as calling
183      * <code>setMessage(layer, null)</code> (on the same layer).
184      *
185      * @param  layer  layer number
186      * @return  message that needs to be displayed in order to show the topmost
187      *          message of the (updated) stack, or <code>null</code> if no
188      *          change of display is necessary
189      * @see  #setMessage
190      */
191     public String   clearMessage(final int layer) {
192         return setMessage(layer, null);
193     }
194     
195     /**
196      * Displays a volatile message on top of all existing messages.
197      *
198      * @param  message to be displayed, or <code>null</code>
199      *         if the previous volatile message should be removed
200      * @return  message that needs to be displayed in order to show the message
201      *          on the top of the stack, or <code>null</code> if no change
202      *          of display is necessary
203      */
204     public String   setVolatileMessage(String   message) {
205         
206         /* unify parameters: */
207         if ((message != null) && (message.trim().length() == 0)) {
208             message = null;
209         }
210 
211         final String   oldDisplayed = getDisplayedMessage();
212 
213         /* update the register of messages: */
214         volatileMsg = message;
215 
216         /* compare the old and new display: */
217         return checkDisplayModified(oldDisplayed, getDisplayedMessage());
218     }
219     
220     /**
221      * Clears the previous volatile message (if any).
222      * Calling this method has the same effect as calling
223      * <code>setVolatileMessage(null)</code>.
224      *
225      * @return  message that needs to be displayed in order to show the message
226      *          on the top of the stack or an empty string
227      *          (<code>&quot;&quot;</code>) if no message should be displayed
228      * @see  #setVolatileMessage
229      */
230     public String   clearVolatileMessage() {
231         return setVolatileMessage(null);
232     }
233 
234     /**
235      * Compares the previous and the new displayed message.
236      *
237      * @return <code>null</code> if both messages are the same (possibly empty),
238      *         an empty string (<code>&quot;&quot;</code>) if the previous
239      *         message was non-empty and the new message is empty,
240      *         or the new message if it is non-empty and different from
241      *         the old message
242      */
243     private String   checkDisplayModified(String   oldDisplay, String   newDisplay) {
244         if ((newDisplay == null) && (oldDisplay != null)) {
245             return "";                                                  //NOI18N
246         }
247         if ((newDisplay != null) && !newDisplay.equals(oldDisplay)) {
248             return newDisplay;
249         }
250         return null;
251     }
252     
253 }
254
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags