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 * '<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 }