001 /*
002 * $Id: ExceptionFactoryMBean.java,v 1.7 2010/09/06 09:19:11 oboehm Exp $
003 *
004 * Copyright (c) 2009 by Oliver Boehm
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 package patterntesting.exception;
019
020 import patterntesting.runtime.jmx.Description;
021
022 /**
023 * The Interface ExceptionFactoryMBean.
024 */
025 @Description("ExceptionFactory to control exceptions")
026 public interface ExceptionFactoryMBean {
027
028 /** The default value for {@link #setScope(String)} if nothing was set. */
029 final String ALL_CLASSES = "all classes";
030
031 /**
032 * Checks if is active.
033 *
034 * @return true, if is active
035 */
036 boolean isActive();
037
038 /**
039 * You can only provoke Exceptions if the active flag is set.
040 *
041 * @param activ true or false
042 */
043 @Description("exceptions can only be provoked it is set to active")
044 void setActive(boolean activ);
045
046 /**
047 * You can only provoke Exceptions if the active flag is set.
048 * Call this method to set it.
049 */
050 @Description("Exceptions will be provoked until the deactivate method is called")
051 void activate();
052
053 /**
054 * If you want to provoke an Exception only for the next time use this
055 * method.
056 */
057 @Description("Exceptions will be only provoked once")
058 void activateOnce();
059
060 /**
061 * You don't want to provoke an exception any longer? Then call this
062 * method.
063 */
064 @Description("Exceptions will be no longer provoked")
065 void deactivate();
066
067 /**
068 * To see if the (Sun) Java-VM was called with the option "-ea"
069 * ("enable asserts") this getter shows it.
070 *
071 * @return true if asserts are enabled
072 */
073 @Description("JavaVM started with '-ea'?")
074 boolean isAssertsEnabled();
075
076 /**
077 * Gets the last provoked exception.
078 *
079 * @return the last exception which was thrown by one of the provoke methods
080 */
081 @Description("returns the last provoked exception")
082 Throwable getLastProvoked();
083
084 /**
085 * Only exceptions of this returned type are thrown.
086 * The return value is a String because of the use as MBean (works better
087 * in the JConsole).
088 *
089 * @return the limitedTo (e.g. "java.lang.Throwable")
090 * @deprecated replaced by {@link #getFire()} (will be removed with 1.2)
091 */
092 @Deprecated
093 @Description("only exception of this sub type are thrown")
094 String getLimitedTo();
095
096 /**
097 * You want to limit the provoked exceptions to IOException?
098 * Then give it as parameter to this setter method.
099 * <br>
100 * For better use with the JConsole the class could given as String.
101 * But don't forget to give the complete classname (with package) as
102 * String.
103 *
104 * @param limitedTo e.g. "java.io.IOException"
105 *
106 * @throws ClassNotFoundException the class not found exception
107 * @deprecated replaced by {@link #setFire(String)} (will be removed with 1.2)
108 */
109 @Deprecated
110 @Description("limit the exceptions only to methods which have it in the signature")
111 void setLimitedTo(String limitedTo)
112 throws ClassNotFoundException;
113
114 /**
115 * Only exceptions of this returned type will be fired.
116 * The return value is a String because of the use as MBean (works better
117 * in the JConsole).
118 *
119 * @return the exeption to be fired (e.g. "java.lang.Throwable")
120 * @since 1.1
121 */
122 @Description("only exception of this sub type are thrown")
123 String getFire();
124
125 /**
126 * You want to provoked an SocketException whenever it is possible?
127 * Then give it as parameter to this setter method.
128 * </br>
129 * If you want to reset it and want to provoke any exception set it to
130 * Throwable or call the resetFire() method.
131 * <br>
132 * For better use with the JConsole the class could given as String.
133 * But don't forget to give the complete classname (with package) as
134 * String.
135 *
136 * @param classname e.g. "java.io.IOException"
137 * @throws ClassNotFoundException if parameter is not a class name
138 * @since 1.1
139 */
140 @Description("fire this exception whenver it is possible")
141 void setFire(String classname) throws ClassNotFoundException;
142
143 /**
144 * Allows again that all exceptions would be fired.
145 * @since 1.1
146 */
147 @Description("enables all exceptions again")
148 void resetFire();
149
150 /**
151 * Gets the number of provoked exceptions.
152 *
153 * @return the number of provoked exceptions
154 */
155 @Description("total number of provoked exceptions")
156 long getNumberOfProvoked();
157
158 /**
159 * Limit the number of provoked maximal total number of provoked exceptions
160 * to n.
161 *
162 * @param n the maximal number of provoked exceptions
163 * (default is Long.MAX_VALUE)
164 */
165 @Description("how many exceptions should be provoked?")
166 void setMaxNumberOfProvoked(long n);
167
168 /**
169 * Gets the max number of provoked exceptions.
170 *
171 * @return the maximal number of provoked exceptions
172 * (default is Long.MAX_VALUE)
173 */
174 @Description("gets the max number of provoked exceptions")
175 long getMaxNumberOfProvoked();
176
177 /**
178 * To limit the exception to be thrown for a given class you can use
179 * this method here.
180 * At the moment a scope is only limited to the class itself.
181 * Perhaps in the future this can change - than super classes or interfaces
182 * may be also supported as parameter.
183 * <br/>
184 * A string is excepted instead of a Class object because of the jconsole.
185 * With the jconsole only basic types or strings are available as input
186 * fields.
187 *
188 * @since 1.1
189 * @param classname for which an exception should be thrown
190 */
191 @Description("the factory can be registered for a given classname")
192 void setScope(String classname);
193
194 /**
195 * To set the scope back to "all classes" use this method here.
196 *
197 * @since 1.1
198 */
199 @Description("to set the scope back to all classes")
200 void resetScope();
201
202 /**
203 * Returns the scope for which the exceptions will be thrown.
204 * The default value is "all classes" if the scope is not set.
205 *
206 * @since 1.1
207 * @return class for which an exception will be thrown.
208 */
209 @Description("returns the scope for which the exceptions will be thrown")
210 String getScope();
211
212 /**
213 * Resets all preferences.
214 * @since 1.1
215 */
216 @Description("resets all preferences")
217 void reset();
218
219 }