001/* 002 * ============================================================================ 003 * Copyright © 2002-2023 by Thomas Thrien. 004 * All Rights Reserved. 005 * ============================================================================ 006 * Licensed to the public under the agreements of the GNU Lesser General Public 007 * License, version 3.0 (the "License"). You may obtain a copy of the License at 008 * 009 * http://www.gnu.org/licenses/lgpl.html 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 014 * License for the specific language governing permissions and limitations 015 * under the License. 016 */ 017 018package org.tquadrat.foundation.exception; 019 020import static java.lang.String.format; 021import static org.apiguardian.api.API.Status.STABLE; 022import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument; 023import static org.tquadrat.foundation.lang.Objects.requireNotEmptyArgument; 024 025import java.io.Serial; 026import java.lang.reflect.Method; 027 028import org.apiguardian.api.API; 029import org.tquadrat.foundation.annotation.ClassVersion; 030 031/** 032 * This implementation of 033 * {@link RuntimeException} 034 * will be thrown when an attempted operation is not valid for the current 035 * context. 036 * 037 * @extauthor Thomas Thrien - thomas.thrien@tquadrat.org 038 * @version $Id: IllegalOperationException.java 1060 2023-09-24 19:21:40Z tquadrat $ 039 * @since 0.1.0 040 * 041 * @UMLGraph.link 042 */ 043@SuppressWarnings( "ClassWithTooManyConstructors" ) 044@ClassVersion( sourceVersion = "$Id: IllegalOperationException.java 1060 2023-09-24 19:21:40Z tquadrat $" ) 045@API( status = STABLE, since = "0.1.0" ) 046public class IllegalOperationException extends RuntimeException 047{ 048 /*-----------*\ 049 ====** Constants **======================================================== 050 \*-----------*/ 051 /** 052 * The message for the illegal attempt to perform an operation: {@value}. 053 */ 054 public static final String MSG_IllegalOperation = "Illegal attempt to perform the operation '%s'"; 055 056 /** 057 * The message for the illegal attempt to perform an operation, enhanced 058 * with an explanation: {@value}. 059 */ 060 public static final String MSG_IllegalOperationWithExplanation = "Illegal attempt to perform the operation '%s' (Reason: %s)"; 061 062 /*------------------------*\ 063 ====** Static Initialisations **=========================================== 064 \*------------------------*/ 065 /** 066 * The serial version UID for objects of this class: {@value}. 067 * 068 * @hidden 069 */ 070 @Serial 071 private static final long serialVersionUID = 2233464685783981770L; 072 073 /*--------------*\ 074 ====** Constructors **===================================================== 075 \*--------------*/ 076 /** 077 * Constructs a new {@code IllegalOperationException} with a detail 078 * message composed of the given operation name. The cause is not 079 * initialized, and may subsequently be initialized by a call to 080 * {@link #initCause}. 081 * 082 * @param operationName The name of the illegally attempted operation; 083 * usually, this is the method name. The detail message constructed 084 * from it is saved for later retrieval by the 085 * {@link #getMessage()} 086 * method. 087 */ 088 public IllegalOperationException( final String operationName ) 089 { 090 super( format( MSG_IllegalOperation, requireNotEmptyArgument( operationName, "operationName" ) ) ); 091 } // IllegalOperationException() 092 093 /** 094 * Constructs a new {@code IllegalOperationException} with a detail 095 * message composed of the name of the given operation. The cause is not 096 * initialized, and may subsequently be initialized by a call to 097 * {@link #initCause}. 098 * 099 * @param operation The illegally attempted operation. The detail 100 * message constructed from its name is saved for later retrieval by 101 * the 102 * {@link #getMessage()} 103 * method. 104 */ 105 public IllegalOperationException( final Method operation ) 106 { 107 this( requireNonNullArgument( operation, "operation" ).toGenericString() ); 108 } // IllegalOperationException() 109 110 /** 111 * <p>{@summary Constructs a new {@code IllegalOperationException} with a 112 * detail message composed of the given operation name and the given 113 * explanation.} The cause is not initialized, and may subsequently be 114 * initialized by a call to 115 * {@link #initCause}.</p> 116 * <p>The detail message constructed from the operation name and the 117 * explanation is saved for later retrieval by the 118 * {@link #getMessage()} 119 * method.</p> 120 * 121 * @param operationName The name of the illegally attempted operation; 122 * usually, this is the method name. 123 * @param explanation The additional explanation. 124 */ 125 public IllegalOperationException( final String operationName, final String explanation ) 126 { 127 super( format( MSG_IllegalOperationWithExplanation, requireNotEmptyArgument( operationName, "operationName" ), requireNotEmptyArgument( explanation, "explanation" ) ) ); 128 } // IllegalOperationException() 129 130 /** 131 * <p>{@summary Constructs a new {@code IllegalOperationException} with a 132 * detail message composed of the name of the given operation name and the 133 * given explanation.} The cause is not initialized, and may subsequently 134 * be initialized by a call to 135 * {@link #initCause}.</p> 136 * <p>The detail message constructed from the operation name and the 137 * explanation is saved for later retrieval by the 138 * {@link #getMessage()} 139 * method.</p> 140 * 141 * @param operation The illegally attempted operation. 142 * @param explanation The additional explanation. 143 */ 144 public IllegalOperationException( final Method operation, final String explanation ) 145 { 146 this( requireNonNullArgument( operation, "operation" ).toGenericString(), explanation ); 147 } // IllegalOperationException() 148 149 /** 150 * Constructs a new {@code IllegalOperationException} with a detail 151 * message composed of the given operation name, and the cause. 152 * 153 * @note The detail message associated with {@code cause} is <i>not</i> 154 * automatically incorporated in this exception's detail message. 155 * 156 * @param operationName The name of the illegally attempted operation; 157 * usually, this is the method name. The detail message constructed 158 * from it is saved for later retrieval by the 159 * {@link #getMessage()} 160 * method. 161 * @param cause The cause, which is saved for later retrieval by the 162 * {@link #getCause()} 163 * method. A {@code null} value is <i>not</i> permitted! 164 */ 165 public IllegalOperationException( final String operationName, final Throwable cause ) 166 { 167 super( format( MSG_IllegalOperation, requireNotEmptyArgument( operationName, "operationName" ) ), requireNonNullArgument( cause, "cause" ) ); 168 } // IllegalOperationException() 169 170 /** 171 * Constructs a new {@code IllegalOperationException} with a detail 172 * message composed of the name of the given operation, and the cause. 173 * 174 * @note The detail message associated with {@code cause} is <i>not</i> 175 * automatically incorporated in this exception's detail message. 176 * 177 * @param operation The illegally attempted operation. The detail 178 * message constructed from its name is saved for later retrieval by 179 * the 180 * {@link #getMessage()} 181 * method. 182 * @param cause The cause, which is saved for later retrieval by the 183 * {@link #getCause()} 184 * method. A {@code null} value is <i>not</i> permitted! 185 */ 186 public IllegalOperationException( final Method operation, final Throwable cause ) 187 { 188 this( requireNonNullArgument( operation, "operation" ).toGenericString(), cause ); 189 } // IllegalOperationException() 190 191 /** 192 * <p>{@summary Constructs a new {@code IllegalOperationException} with 193 * the cause and a detail message composed of the given operation name and 194 * the given explanation.}</p> 195 * <p>The detail message constructed from the operation name and the 196 * explanation is saved for later retrieval by the 197 * {@link #getMessage()} 198 * method.</p> 199 * 200 * @note The detail message associated with {@code cause} is <i>not</i> 201 * automatically incorporated in this exception's detail message. 202 * 203 * @param operationName The name of the illegally attempted operation; 204 * usually, this is the method name. 205 * @param explanation The additional explanation. 206 * @param cause The cause, which is saved for later retrieval by the 207 * {@link #getCause()} 208 * method. A {@code null} value is <i>not</i> permitted! 209 */ 210 public IllegalOperationException( final String operationName, final String explanation, final Throwable cause ) 211 { 212 super( 213 format( MSG_IllegalOperationWithExplanation, 214 requireNotEmptyArgument( operationName, "operationName" ), 215 requireNotEmptyArgument( explanation, "explanation" ) ), 216 requireNonNullArgument( cause, "cause" ) ); 217 } // IllegalOperationException() 218 219 /** 220 * <p>{@summary Constructs a new {@code IllegalOperationException} with 221 * the cause and a detail message composed of the name of the given 222 * operation and the given explanation.}</p> 223 * <p>The detail message constructed from the operation name and the 224 * explanation is saved for later retrieval by the 225 * {@link #getMessage()} 226 * method.</p> 227 * 228 * @note The detail message associated with {@code cause} is <i>not</i> 229 * automatically incorporated in this exception's detail message. 230 * 231 * @param operation The illegally attempted operation. 232 * @param explanation The additional explanation. 233 * @param cause The cause, which is saved for later retrieval by the 234 * {@link #getCause()} 235 * method. A {@code null} value is <i>not</i> permitted! 236 */ 237 public IllegalOperationException( final Method operation, final String explanation, final Throwable cause ) 238 { 239 this( requireNonNullArgument( operation, "operation" ).toGenericString(), explanation, cause ); 240 } // IllegalOperationException() 241} 242// class IllegalOperationException 243 244/* 245 * End of File 246 */