001 package patterntesting.runtime.monitor;
002
003 import java.io.Serializable;
004 import java.net.URI;
005 import java.net.URL;
006 import java.util.NoSuchElementException;
007
008 import patterntesting.runtime.jmx.Description;
009
010 /**
011 * All the methods which might help you to find classpath problems are
012 * collected in this JMX interface.
013 * Most of the methods returns a String because this can be easily shown in
014 * the JConsole.
015 *
016 * @author oliver
017 * @version $Revision: 1.8 $
018 */
019 @Description("Classpath Monitor to be able to inspect the classpath and to find doublets")
020 public interface ClasspathMonitorMBean extends Serializable {
021
022 /**
023 * Looks if the given resource can be found in the classpath.
024 * <br/>
025 * To avoid problems like "java.rmi.UnmarshalException: failed to unmarshal
026 * class java.lang.Object; nested exception is: java.io.IOException: unknown
027 * protocol: zip" no longer a URL but URI is now returned
028 *
029 * @param name of a resource e.g. "log4j.properties"
030 * @return URI of the given resource (or null if resource was not found)
031 */
032 @Description("returns the URI of the given resource")
033 URI whichResource(String name);
034
035 /**
036 * Looks if the given classname can be found in the classpath.
037 * <br/>
038 * To avoid problems like "java.rmi.UnmarshalException: failed to unmarshal
039 * class java.lang.Object; nested exception is: java.io.IOException: unknown
040 * protocol: zip" no longer a URL but URI is now returned
041 *
042 * @param name of a class e.g. "java.lang.String"
043 * @return URI of the given resource (or null if resource was not found)
044 */
045 @Description("return the URI if the given class")
046 URI whichClass(String name);
047
048 /**
049 * Get number of resources.
050 *
051 * @param name of the resource
052 * @return how often the resource was found
053 */
054 @Description("how often the given resource is found in the classpath")
055 int getNoResources(String name);
056
057 /**
058 * Get the number of different versions of the given class.
059 *
060 * @param classname the name of the class
061 * @return how often the classname was found in the classpath
062 */
063 @Description("how often the given class is found in the classpath")
064 int getNoClasses(String classname);
065
066 /**
067 * Is the given classname or resource a doublet, e.g. can it be found
068 * several times in the classpath?
069 * If the classname or resource is not in the classpath a
070 * java.util.NoSuchElementException will be thrown.
071 *
072 * @param name a classname or resource
073 * @return true if more than one classname or resource was found in the
074 * classpath
075 * @throws java.util.NoSuchElementException if no classname or resource was found
076 */
077 @Description("is the given classname or resource found more than once in the classpath?")
078 boolean isDoublet(String name) throws NoSuchElementException;
079
080 /**
081 * Returns the first doublet of the given classname or resource.
082 *
083 * @param name a classname or resource
084 * @return the first doublet
085 */
086 @Description("returns the first doublet of the given classname or resource")
087 URL getFirstDoublet(String name);
088
089 /**
090 * Looks for each loaded class if it is a doublet or not.
091 *
092 * @return a sorted array with the found doublets
093 */
094 @Description("returns a sorted array of all found doublets")
095 String[] getDoublets();
096
097 /**
098 * Looks for each found doublet in which classpath it was found.
099 *
100 * @return the classpath where doublets were found
101 */
102 @Description("returns the classpath where doublets were found")
103 String[] getDoubletClasspath();
104
105 /**
106 * Returns the n'th doublet of the given classname or resource
107 *
108 * @param name a classname or resource
109 * @param n number of wanted doublet
110 * @return the n'th doublet URL
111 */
112 @Description("returns the n'th doublet of the given classname or resource")
113 URL getDoublet(String name, int n);
114
115 /**
116 * Returns the packages which were loaded by the classloader.
117 * The loaded packages are returned as string array so that it can
118 * be displayed by the 'jconsole'.
119 *
120 * @return the packages as string array
121 */
122 @Description("returns an array of all loaded packages")
123 String[] getLoadedPackages();
124
125 /**
126 * Returns the classes which were loaded by the classloader.
127 * The loaded packages are returned as string array so that it can
128 * be displayed by the 'jconsole'.
129 *
130 * @return the classes as string array
131 */
132 @Description("returns an array of all loaded classes")
133 String[] getLoadedClasses();
134
135 /**
136 * Is the given classname already loaded?
137 *
138 * @param classname the name of the class
139 * @return true if given classname is already loaded
140 */
141 @Description("is the given classname already loaded?")
142 boolean isLoaded(String classname);
143
144 /**
145 * Returns the classes which are not yet loaded. These are the classes
146 * returned by getClasspathClasses() but not by getLoadedClasses().
147 *
148 * @return the classes which are not yet loaded
149 */
150 @Description("returns all classes which are not yet loaded")
151 String[] getUnusedClasses();
152
153 /**
154 * Gets the loaded classpath (without the bootclasspath) as URI array.
155 *
156 * @return the loaded classpath (sorted)
157 */
158 @Description("returns the classpath with the loaded classes")
159 String[] getUsedClasspath();
160
161 /**
162 * The unused classpath is this path which are not used in past.
163 *
164 * @return the unused classpath (sorted)
165 */
166 @Description("returns the classpath which were not yet used")
167 String[] getUnusedClasspath();
168
169 /**
170 * Gets the boot classpath.
171 *
172 * @return boot classpath
173 */
174 @Description("return ths boot classpath")
175 String[] getBootClasspath();
176
177 /**
178 * Gets the normal classpath which is also available by the
179 * system property "java.class.path".
180 *
181 * @return the classpath as String array
182 */
183 @Description("returns the complete classpath which is seen by the application")
184 String[] getClasspath();
185
186 /**
187 * Looks in the normal classpath after all classes and returns it as
188 * String array.
189 *
190 * @return all found classes in the classpath
191 */
192 @Description("returns all classes of the classpath")
193 String[] getClasspathClasses();
194
195 /**
196 * @param classname the name of the class
197 * @return the serialVersionUID of the given class
198 * (or null if the class does not have one)
199 * @throws IllegalAccessException e.g. if there is no SerialVersionUID
200 */
201 @Description("returns the servialSerialVersionUID of the given class")
202 Long getSerialVersionUID(String classname) throws IllegalAccessException;
203
204 /**
205 * If a MANIFEST is found for a given class the attributes in this
206 * file should be returned as a string array.
207 * E.g. for commons-lang-2.3.jar the string array may looks like
208 * <pre>
209 * Manifest-Version: 1.0
210 * Ant-Version: Apache Ant 1.6.5
211 * Created-By: 1.3.1_09-85 ("Apple Computer, Inc.")
212 * Package: org.apache.commons.lang
213 * Extension-Name: commons-lang
214 * Specification-Version: 2.3
215 * Specification-Vendor: Apache Software Foundation
216 * Specification-Title: Commons Lang
217 * Implementation-Version: 2.3
218 * Implementation-Vendor: Apache Software Foundation
219 * Implementation-Title: Commons Lang
220 * Implementation-Vendor-Id: org.apache
221 * X-Compile-Source-JDK: 1.3
222 * X-Compile-Target-JDK: 1.1
223 * </pre>
224 *
225 * @param classname the name of the class
226 * @return the attribute entries of the Manifest
227 * (or emtpy array if no Manifest or no attributes are found)
228 */
229 @Description("return the manifest entries for the given class")
230 String[] getManifestEntries(String classname);
231
232 /**
233 * Incompatible classes are doublets with different serialVersionUID.
234 *
235 * @return doublet classes with different serialVersionUID
236 */
237 @Description("returns the doublet classes with different serialVersionUIDs")
238 String[] getIncompatibleClasses();
239
240 /**
241 * @return the classpathes where incompatible classes were found
242 */
243 @Description("returns the classpath where incompatible classes were found")
244 String[] getIncompatibleClasspath();
245
246 /**
247 * @return true if it is a known classloader
248 */
249 @Description("returns true for classloader which are known and tested")
250 boolean isClassloaderSupported();
251
252 /**
253 * Returns some information about the classloader. At least the user
254 * should be informed if it is a unknown classloader which is not
255 * supported or not tested.
256 *
257 * @return e.g. "unknown classloader xxx - classpath can be wrong"
258 */
259 @Description("retuns some infos about the found classloader")
260 String getClassloaderInfo();
261
262 /**
263 * Prints the different MBean attributes to the log output.
264 */
265 @Description("logs all attributes to the log output")
266 void logMe();
267
268 /**
269 * This operation dumps the different MBean attributes to a temporary
270 * file with the prefix "cpmon" (for ClasspathMonitor) and the
271 * extension ".txt".
272 */
273 @Description("dumps all attributs to the temporary file 'cpmon...txt'")
274 void dumpMe();
275
276 /**
277 * To be able to register the instance as shutdown hook you can use this
278 * (non static) method.
279 *
280 * @since 1.0
281 */
282 @Description("to register ClasspathMonitor as shutdown hook")
283 void addMeAsShutdownHook();
284
285 /**
286 * If you want to unregister the instance as shutdown hook you can use this
287 * method.
288 *
289 * @since 1.0
290 */
291 @Description("to de-register ClasspathMonitor as shutdown hook")
292 void removeMeAsShutdownHook();
293
294 /**
295 * Here you can ask if the ClasspathMonitor was already registeres ad
296 * shutdown hook.
297 *
298 * @since 1.0
299 * @return true if it is registered as shutdown hook.
300 */
301 @Description("returns true if ClasspathMonitor was registered as shutdown hook")
302 boolean isShutdownHook();
303
304 /**
305 * Is multi threading enabled?
306 * @since 0.9.7
307 * @return true if multi threading is enabled for this class.
308 */
309 boolean isMultiThreadingEnabled();
310
311 /**
312 * Here you can enable or disable the multi threading mode.
313 * @since 0.9.7
314 * @param enabled true, if multithreading should be enabled
315 */
316 @Description("expermimental, don't change it!")
317 void setMultiThreadingEnabled(boolean enabled);
318
319
320 }