001    package edu.nrao.sss.util;
002    
003    /**
004     * Thrown to indicate that an attempt to change a property from one value
005     * to another failed. 
006     * <p>
007     * This exception is similar, but not quite the same as, java's
008     * {@link IllegalArgumentException}.  One of the most appropriate
009     * places to use this exception is with status transitions of an
010     * object, especially when those transitions are the result of
011     * calling methods such as <tt>cancel()</tt> or <tt>execute()</tt>,
012     * as opposed to methods such as <tt>setStatus(newStatus)</tt>.</p>
013     * <p>
014     * The text returned by {@link #getMessage()} will look like:</p>
015     * <blockquote>
016     * Property '<i>propertyName</i>' may not be changed from
017     * '<i>currentValue</i>' to '<i>illegalValue</i>'.
018     * </blockquote>
019     * or
020     * <blockquote>
021     * Property '<i>propertyName</i>' may not be changed from
022     * '<i>currentValue</i>' to '<i>illegalValue</i>'.
023     * &nbsp;'<i>additionalInformation</i>'
024     * </blockquote>
025     * <p>
026     * <b>Version Info:</b>
027     * <table style="margin-left:2em">
028     *   <tr><td>$Revision: 2184 $</td></tr>
029     *   <tr><td>$Date: 2009-04-10 15:00:07 -0600 (Fri, 10 Apr 2009) $</td></tr>
030     *   <tr><td>$Author: dharland $ (last person to modify)</td></tr>
031     * </table></p>
032     * 
033     * @author David M. Harland
034     * @since 2007-08-17
035     */
036    public class IllegalTransitionException
037      extends Exception
038    {
039      private static final long serialVersionUID = 1;
040      
041      private String propertyName;
042      private String currentValue;
043      private String illegalValue;
044      private String additionalInformation;
045      
046      private String message;
047    
048      /**
049       * Creates a new exception with the given properties.
050       * See the {@link IllegalTransitionException class comments}
051       * for a description of how the parameters are used to form
052       * a message.
053       * <p>
054       * This is a convenience constructor that is equivalent to
055       * <tt>
056       * IllegalTransitionException(propertyName, currentValue, illegalValue, "")
057       * </tt>.</p>
058       */
059      public IllegalTransitionException(String propertyName,
060                                        String currentValue,
061                                        String illegalValue)
062      {
063        this(propertyName, currentValue, illegalValue, "");
064      }
065    
066      /**
067       * Creates a new exception with the given properties.
068       * See the {@link IllegalTransitionException class comments}
069       * for a description of how the parameters are used to form
070       * a message.
071       */
072      public IllegalTransitionException(String propertyName,
073                                        String currentValue,
074                                        String illegalValue,
075                                        String additionalInformation)
076      {
077        this.propertyName = propertyName == null ? "" : propertyName;
078        this.currentValue = currentValue == null ? "" : currentValue;
079        this.illegalValue = illegalValue == null ? "" : illegalValue;
080        
081        this.additionalInformation = 
082          additionalInformation == null ? "" : additionalInformation;
083      }
084      
085      private void constructMessage()
086      {
087        StringBuilder msg = new StringBuilder();
088        
089        msg.append("Property '").append(propertyName)
090           .append("' may not be changed from '").append(currentValue)
091           .append("' to '").append(illegalValue).append("'.");
092        
093        if (additionalInformation.length() > 0)
094        {
095          msg.append("  ").append(additionalInformation);
096        }
097        
098        message = msg.toString();
099      }
100      
101      @Override
102      public String getMessage()
103      {
104        if (message == null)
105          constructMessage();
106        
107        return message;
108      }
109    
110      /**
111       * Returns any additional information about this transition.
112       * The additional information typically gives the reasons why
113       * the transition in question is deemed illegal.
114       * <p>
115       * If this exception carries no additional information, the
116       * empty string (<tt>""</tt>) will be returned.</p>
117       */
118      public String getAdditionalInformation()
119      {
120        return additionalInformation;
121      }
122    
123      /**
124       * Returns the value of the property prior to the attempt to change it.
125       */
126      public String getCurrentValue()
127      {
128        return currentValue;
129      }
130    
131      /**
132       * Returns the value to which something tried to change the property.
133       */
134      public String getIllegalValue()
135      {
136        return illegalValue;
137      }
138    
139      /**
140       * Returns the name of the property for which an illegal transistion
141       * was attempted.
142       */
143      public String getPropertyName()
144      {
145        return propertyName;
146      }
147    }