001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.management;
023:
024: import java.io.ObjectInputStream;
025: import java.util.Set;
026:
027: import javax.management.loading.ClassLoaderRepository;
028:
029: /**
030: * The interface used to access the MBean server instances.
031: *
032: * @see javax.management.MBeanServerFactory
033: * @see javax.management.loading.ClassLoaderRepository
034: *
035: * @author <a href="mailto:juha@jboss.org">Juha Lindfors</a>.
036: * @author <a href="mailto:Adrian.Brock@HappeningTimes.com">Adrian Brock</a>.
037: * @version $Revision: 57200 $
038: */
039: public interface MBeanServer extends MBeanServerConnection {
040:
041: /**
042: * Create an MBean registered using the given object name.<p>
043: *
044: * Uses the default contructor.
045: *
046: * @param className the class name of the mbean
047: * @param name the object name for registration, can be null
048: * @return an ObjectInstance describing the registration
049: * @exception ReflectionException for class not found or an exception
050: * invoking the contructor
051: * @exception InstanceAlreadyExistsException for an MBean already registered
052: * with the passed or generated ObjectName
053: * @exception MBeanRegistrationException for any exception thrown by the
054: * MBean's preRegister
055: * @exception MBeanException for any exception thrown by the MBean's constructor
056: * @exception NotCompliantMBeanException if the class name does not correspond to
057: * a valid MBean
058: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
059: * null class name, the ObjectName could not be determined or it is a pattern
060: */
061: public ObjectInstance createMBean(String className, ObjectName name)
062: throws ReflectionException, InstanceAlreadyExistsException,
063: MBeanRegistrationException, MBeanException,
064: NotCompliantMBeanException;
065:
066: /**
067: * Create an MBean registered using the given object name.<p>
068: *
069: * The MBean is loaded using the passed classloader. Uses the default contructor.
070: *
071: * @param className the class name of the mbean
072: * @param loaderName an MBean that implements a classloader
073: * @param name the object name for registration, can be null
074: * @return an ObjectInstance describing the registration
075: * @exception ReflectionException for class not found or an exception
076: * invoking the contructor
077: * @exception InstanceAlreadyExistsException for an MBean already registered
078: * with the passed or generated ObjectName
079: * @exception MBeanRegistrationException for any exception thrown by the
080: * MBean's preRegister
081: * @exception MBeanException for any exception thrown by the MBean's constructor
082: * @exception InstanceNotFoundException if the loaderName is not a classloader registered
083: * in the MBeanServer
084: * @exception NotCompliantMBeanException if the class name does not correspond to
085: * a valid MBean
086: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
087: * null class name, the ObjectName could not be determined or it is a pattern
088: */
089: public ObjectInstance createMBean(String className,
090: ObjectName name, ObjectName loaderName)
091: throws ReflectionException, InstanceAlreadyExistsException,
092: MBeanRegistrationException, MBeanException,
093: NotCompliantMBeanException, InstanceNotFoundException;
094:
095: /**
096: * Create an MBean registered using the given object name.<p>
097: *
098: * Uses the specified constructor.
099: *
100: * @param className the class name of the mbean
101: * @param loaderName an MBean that implements a classloader
102: * @param params the parameters for the constructor
103: * @param signature the signature of the constructor
104: * @return an ObjectInstance describing the registration
105: * @exception ReflectionException for class not found or an exception
106: * invoking the contructor
107: * @exception InstanceAlreadyExistsException for an MBean already registered
108: * with the passed or generated ObjectName
109: * @exception MBeanRegistrationException for any exception thrown by the
110: * MBean's preRegister
111: * @exception MBeanException for any exception thrown by the MBean's constructor
112: * @exception NotCompliantMBeanException if the class name does not correspond to
113: * a valid MBean
114: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
115: * null class name, the ObjectName could not be determined or it is a pattern
116: */
117: public ObjectInstance createMBean(String className,
118: ObjectName name, Object[] params, String[] signature)
119: throws ReflectionException, InstanceAlreadyExistsException,
120: MBeanRegistrationException, MBeanException,
121: NotCompliantMBeanException;
122:
123: /**
124: * Create an MBean registered using the given object name.<p>
125: *
126: * The MBean is loaded using the passed classloader. Uses the specified constructor.
127: *
128: * @param className the class name of the mbean
129: * @param loaderName an MBean that implements a classloader
130: * @param name the object name for registration, can be null
131: * @param params the parameters for the constructor
132: * @param signature the signature of the constructor
133: * @return an ObjectInstance describing the registration
134: * @exception ReflectionException for class not found or an exception
135: * invoking the contructor
136: * @exception InstanceAlreadyExistsException for an MBean already registered
137: * with the passed or generated ObjectName
138: * @exception MBeanRegistrationException for any exception thrown by the
139: * MBean's preRegister
140: * @exception MBeanException for any exception thrown by the MBean's constructor
141: * @exception InstanceNotFoundException if the loaderName is not a classloader registered
142: * in the MBeanServer
143: * @exception NotCompliantMBeanException if the class name does not correspond to
144: * a valid MBean
145: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
146: * null class name, the ObjectName could not be determined or it is a pattern
147: */
148: public ObjectInstance createMBean(String className,
149: ObjectName name, ObjectName loaderName, Object[] params,
150: String[] signature) throws ReflectionException,
151: InstanceAlreadyExistsException, MBeanRegistrationException,
152: MBeanException, NotCompliantMBeanException,
153: InstanceNotFoundException;
154:
155: /**
156: * Registers an mbean.
157: *
158: * @param object the mbean implementation to register
159: * @param name the object name of the mbean to register
160: * @exception InstanceAlreadyExistsException if the object name is already registered
161: * in the MBeanServer
162: * @exception MBeanRegistrationException for any exception thrown by the
163: * MBean's preDeregister
164: * @exception NotCompliantMBeanException if the class name does not correspond to
165: * a valid MBean
166: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
167: * null name, or trying to register a JMX implementation MBean
168: */
169: public ObjectInstance registerMBean(Object object, ObjectName name)
170: throws InstanceAlreadyExistsException,
171: MBeanRegistrationException, NotCompliantMBeanException;
172:
173: /**
174: * Unregisters an mbean.
175: *
176: * @param name the object name of the mbean to unregister
177: * @exception InstanceNotFoundException if the mbean is not registered
178: * in the MBeanServer
179: * @exception MBeanRegistrationException for any exception thrown by the
180: * MBean's preDeregister
181: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
182: * null name, or trying to unregister a JMX implementation MBean
183: */
184: public void unregisterMBean(ObjectName name)
185: throws InstanceNotFoundException,
186: MBeanRegistrationException;
187:
188: /**
189: * Retrieve an MBean's registration information.
190: *
191: * @param name the object name of the mbean
192: * @exception InstanceNotFoundException if the mbean is not registered
193: * in the MBeanServer
194: */
195: public ObjectInstance getObjectInstance(ObjectName name)
196: throws InstanceNotFoundException;
197:
198: /**
199: * Retrieve a set of Object instances
200: *
201: * @param name an ObjectName pattern, can be null for all mbeans
202: * @param query a query expression to further filter the mbeans, can be null
203: * for no query
204: */
205: public Set queryMBeans(ObjectName name, QueryExp query);
206:
207: /**
208: * Retrieve a set of Object names
209: *
210: * @param name an ObjectName pattern, can be null for all mbeans
211: * @param query a query expression to further filter the mbeans, can be null
212: * for no query
213: */
214: public Set queryNames(ObjectName name, QueryExp query);
215:
216: /**
217: * Test whether an mbean is registered.
218: *
219: * @param name the object name of the mbean
220: * @return true when the mbean is registered, false otherwise
221: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
222: * null name
223: */
224: public boolean isRegistered(ObjectName name);
225:
226: /**
227: * Retrieve the number of mbeans registered in the server.
228: *
229: * @return true the number of registered mbeans
230: */
231: public Integer getMBeanCount();
232:
233: /**
234: * Retrieve a value from an MBean.
235: *
236: * @param name the object name of the mbean
237: * @param attribute the attribute name of the value to retrieve
238: * @return the value
239: * @exception ReflectionException for an exception invoking the mbean
240: * @exception MBeanException for any exception thrown by the mbean
241: * @exception InstanceNotFoundException if the mbean is not registered
242: * @exception AttributeNotFoundException if the mbean has no such attribute
243: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
244: * null name or attribute
245: */
246: public Object getAttribute(ObjectName name, String attribute)
247: throws MBeanException, AttributeNotFoundException,
248: InstanceNotFoundException, ReflectionException;
249:
250: /**
251: * Retrieve a list of values from an MBean.
252: *
253: * @param name the object name of the mbean
254: * @param attributes the attribute names of the values to retrieve
255: * @return the list of values, attributes with errors are ignored
256: * @exception ReflectionException for an exception invoking the mbean
257: * @exception InstanceNotFoundException if the mbean is not registered
258: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
259: * null name or attributes
260: */
261: public AttributeList getAttributes(ObjectName name,
262: String[] attributes) throws InstanceNotFoundException,
263: ReflectionException;
264:
265: /**
266: * Set a value for an MBean.
267: *
268: * @param name the object name of the mbean
269: * @param attribute the attribute name and value to set
270: * @exception ReflectionException for an exception invoking the mbean
271: * @exception MBeanException for any exception thrown by the mbean
272: * @exception InstanceNotFoundException if the mbean is not registered
273: * @exception AttributeNotFoundException if the mbean has no such attribute
274: * @exception InvalidAttributeValueException if the new value has an incorrect type
275: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
276: * null name or attribute
277: */
278: public void setAttribute(ObjectName name, Attribute attribute)
279: throws InstanceNotFoundException,
280: AttributeNotFoundException, InvalidAttributeValueException,
281: MBeanException, ReflectionException;
282:
283: /**
284: * Set a list of values for an MBean.
285: *
286: * @param name the object name of the mbean
287: * @param attributes the attribute names and values to set
288: * @return the list of values, attributes with errors are ignored
289: * @exception ReflectionException for an exception invoking the mbean
290: * @exception InstanceNotFoundException if the mbean is not registered
291: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
292: * null name or attributes
293: */
294: public AttributeList setAttributes(ObjectName name,
295: AttributeList attributes) throws InstanceNotFoundException,
296: ReflectionException;
297:
298: /**
299: * Invokes an operation on an mbean.
300: *
301: * @param name the object name of the mbean
302: * @param operationName the operation to perform
303: * @param params the parameters
304: * @param signature the signature of the operation
305: * @return any result of the operation
306: * @exception ReflectionException for an exception invoking the mbean
307: * @exception MBeanException for any exception thrown by the mbean
308: * @exception InstanceNotFoundException if the mbean is not registered
309: */
310: public Object invoke(ObjectName name, String operationName,
311: Object[] params, String[] signature)
312: throws InstanceNotFoundException, MBeanException,
313: ReflectionException;
314:
315: /**
316: * Retrieve the default domain of the mbeanserver.
317: *
318: * @return the default domain
319: */
320: public String getDefaultDomain();
321:
322: /**
323: * Retrieve the domains of the mbeanserver.
324: *
325: * @return the domains
326: */
327: public String[] getDomains();
328:
329: /**
330: * Add a notification listener to an MBean.
331: *
332: * @param name the name of the MBean broadcasting notifications
333: * @param listener the listener to add
334: * @param filter a filter to preprocess notifications
335: * @param handback a object to add to any notifications
336: * @exception InstanceNotFoundException if the broadcaster is not registered
337: */
338: public void addNotificationListener(ObjectName name,
339: NotificationListener listener, NotificationFilter filter,
340: Object handback) throws InstanceNotFoundException;
341:
342: /**
343: * Add a notification listener to an MBean.
344: *
345: * @param name the name of the MBean broadcasting notifications
346: * @param listener the object name listener to add
347: * @param filter a filter to preprocess notifications
348: * @param handback a object to add to any notifications
349: * @exception InstanceNotFoundException if the broadcaster or listener is not registered
350: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
351: * null listener or the listener does not implement the Notification Listener interface
352: */
353: public void addNotificationListener(ObjectName name,
354: ObjectName listener, NotificationFilter filter,
355: Object handback) throws InstanceNotFoundException;
356:
357: /**
358: * Removes a listener from an mbean.<p>
359: *
360: * All registrations of the listener are removed.
361: *
362: * @param name the name of the MBean broadcasting notifications
363: * @param listener the object name of the listener to remove
364: * @exception InstanceNotFoundException if the broadcaster or listener is not registered
365: * @exception ListenerNotFoundException if the listener is not registered against the broadcaster
366: */
367: public void removeNotificationListener(ObjectName name,
368: ObjectName listener) throws InstanceNotFoundException,
369: ListenerNotFoundException;
370:
371: /**
372: * Removes a listener from an mbean.<p>
373: *
374: * Only the listener that was registered with the same filter and handback is removed.
375: *
376: * @param name the name of the MBean broadcasting notifications
377: * @param listener the object name of listener to remove
378: * @param filter the filter of the listener to remove
379: * @exception InstanceNotFoundException if the broadcaster or listener is not registered
380: * @exception ListenerNotFoundException if the listener, filter, handback
381: * is not registered against the broadcaster
382: */
383: public void removeNotificationListener(ObjectName name,
384: ObjectName listener, NotificationFilter filter,
385: Object handback) throws InstanceNotFoundException,
386: ListenerNotFoundException;
387:
388: /**
389: * Removes a listener from an mbean.<p>
390: *
391: * All registrations of the listener are removed.
392: *
393: * @param name the name of the MBean broadcasting notifications
394: * @param listener the listener to remove
395: * @exception InstanceNotFoundException if the broadcaster is not registered
396: * @exception ListenerNotFoundException if the listener is not registered against the broadcaster
397: */
398: public void removeNotificationListener(ObjectName name,
399: NotificationListener listener)
400: throws InstanceNotFoundException, ListenerNotFoundException;
401:
402: /**
403: * Removes a listener from an mbean.<p>
404: *
405: * Only the listener that was registered with the same filter and handback is removed.
406: *
407: * @param name the name of the MBean broadcasting notifications
408: * @param listener the listener to remove
409: * @param filter the filter of the listener to remove
410: * @exception InstanceNotFoundException if the broadcaster is not registered
411: * @exception ListenerNotFoundException if the listener, filter, handback
412: * is not registered against the broadcaster
413: */
414: public void removeNotificationListener(ObjectName name,
415: NotificationListener listener, NotificationFilter filter,
416: Object handback) throws InstanceNotFoundException,
417: ListenerNotFoundException;
418:
419: /**
420: * Retrieves the jmx metadata for an mbean
421: *
422: * @param name the name of the mbean
423: * @return the metadata
424: * @exception IntrospectionException for any error during instrospection
425: * @exception InstanceNotFoundException if the mbean is not registered
426: * @exception ReflectionException for any error trying to invoke the operation on the mbean
427: */
428: public MBeanInfo getMBeanInfo(ObjectName name)
429: throws InstanceNotFoundException, IntrospectionException,
430: ReflectionException;
431:
432: /**
433: * Tests whether an mbean can be cast to the given type
434: *
435: * @param name the name of the mbean
436: * @param className the class name to check
437: * @return true when it is of that type, false otherwise
438: * @exception InstanceNotFoundException if the mbean is not registered
439: */
440: public boolean isInstanceOf(ObjectName name, String className)
441: throws InstanceNotFoundException;
442:
443: /**
444: * Instantiates an object using the default loader repository and default
445: * no-args constructor.
446: *
447: * @see javax.management.loading.DefaultLoaderRepository
448: *
449: * @param className Class to instantiate. Must have a public no-args
450: * constructor. Cannot contain a <tt>null</tt> reference.
451: *
452: * @return instantiated object
453: *
454: * @throws ReflectionException If there was an error while trying to invoke
455: * the class's constructor or the given class was not found. This
456: * exception wraps the actual exception thrown.
457: * @throws MBeanException If the object constructor threw a checked exception
458: * during the initialization. This exception wraps the actual
459: * exception thrown.
460: * @throws RuntimeMBeanException If the class constructor threw a runtime
461: * exception. This exception wraps the actual exception thrown.
462: * @throws RuntimeErrorException If the class constructor threw an error.
463: * This exception wraps the actual error thrown.
464: * @throws RuntimeOperationsException If the <tt>className</tt> is <tt>null</tt>.
465: * Wraps an <tt>IllegalArgumentException</tt> instance.
466: */
467: public Object instantiate(String className)
468: throws ReflectionException, MBeanException;
469:
470: /**
471: * Instantiates an object using the given class loader. If the loader name contains
472: * a <tt>null</tt> reference, the class loader of the MBean server implementation
473: * will be used. The object must have a default, no-args constructor.
474: *
475: * @param className Class to instantiate. Must have a public no args constructor.
476: * Cannot contain a <tt>null</tt> reference.
477: * @param loaderName Object name of a class loader that has been registered to the server.
478: * If <tt>null</tt>, the class loader of the MBean server is used.
479: * @return instantiated object
480: *
481: * @throws ReflectionException If there was an error while trying to invoke
482: * the class's constructor or the given class was not found. This
483: * exception wraps the actual exception thrown.
484: * @throws MBeanException If the object constructor threw a checked exception
485: * during the initialization. This exception wraps the actual exception
486: * thrown.
487: * @throws InstanceNotFoundException if the specified class loader was not
488: * registered to the agent
489: * @throws RuntimeMBeanException If the class constructor raised a runtime
490: * exception. This exception wraps the actual exception thrown.
491: * @throws RuntimeErrorException If the class constructor raised an error.
492: * This exception wraps the actual error thrown.
493: * @throws RuntimeOperationsException if the <tt>className</tt> is <tt>null</tt>.
494: * Wraps an <tt>IllegalArgumentException</tt> instance.
495: */
496: public Object instantiate(String className, ObjectName loaderName)
497: throws ReflectionException, MBeanException,
498: InstanceNotFoundException;
499:
500: /**
501: * Instantiates an object using the default loader repository and a given constructor.
502: * The class being instantiated must contain a constructor that matches the
503: * signature given as an argument to this method call.
504: *
505: * @see javax.management.loading.DefaultLoaderRepository
506: *
507: * @param className class to instantiate
508: * @param params argument values for the constructor call
509: * @param signature signature of the constructor as fully qualified class names
510: *
511: * @return instantiated object
512: *
513: * @throws ReflectionException If there was an error while trying to invoke
514: * the class's constructor or the given class was not found. This
515: * exception wraps the actual exception thrown.
516: * @throws MBeanException If the object constructor raised a checked exception
517: * during the initialization. This exception wraps the actual exception
518: * thrown.
519: * @throws RuntimeMBeanException If the class constructor raised a runtime
520: * exception. This exception wraps the actual exception thrown.
521: * @throws RuntimeErrorException If the class constructor raised an error.
522: * This exception wraps the actual error thrown.
523: * @throws RuntimeOperationsException if the <tt>className</tt> is <tt>null</tt>.
524: * Wraps an <tt>IllegalArgumentException</tt> instance.
525: */
526: public Object instantiate(String className, Object[] params,
527: String[] signature) throws ReflectionException,
528: MBeanException;
529:
530: /**
531: * Instantiates an object using the given class loader. If the loader name contains
532: * a <tt>null</tt> reference, the class loader of the MBean server implementation
533: * will be used. The object must contain a constructor with a matching signature
534: * given as a parameter to this call.
535: *
536: * @param className class to instantiate
537: * @param loaderName object name of a registered class loader in the agent.
538: * @param params argument values for the constructor call
539: * @param signature signature of the constructor as fully qualified class name strings
540: *
541: * @return instantiated object
542: *
543: * @throws ReflectionException If there was an error while trying to invoke the
544: * class's constructor or the given class was not found. this exception
545: * wraps the actual exception thrown.
546: * @throws MBeanException If the object constructor raised a checked exception
547: * during the initialization. This exception wraps the actual exception thrown.
548: * @throws InstanceNotFoundException if the specified class loader was not
549: * registered to the agent.
550: * @throws RuntimeMBeanException If the class constructor raised a runtime
551: * exception. This exception wraps the actual exception thrown.
552: * @throws RuntimeErrorException If the class constructor raised an error.
553: * This exception wraps the actual error thrown.
554: * @throws RuntimeOperationsException if the <tt>className</tt> argument is <tt>null</tt>.
555: * Wraps an <tt>IllegalArgumentException</tt> instance.
556: */
557: public Object instantiate(String className, ObjectName loaderName,
558: Object[] params, String[] signature)
559: throws ReflectionException, MBeanException,
560: InstanceNotFoundException;
561:
562: /**
563: * @deprecated use {@link #getClassLoaderFor(ObjectName)} to obtain the
564: * appropriate classloader for deserialization
565: */
566: public ObjectInputStream deserialize(ObjectName name, byte[] data)
567: throws InstanceNotFoundException, OperationsException;
568:
569: /**
570: * @deprecated use {@link #getClassLoaderFor(ObjectName)} to obtain the
571: * appropriate classloader for deserialization
572: */
573: public ObjectInputStream deserialize(String className, byte[] data)
574: throws OperationsException, ReflectionException;
575:
576: /**
577: * @deprecated use {@link #getClassLoaderFor(ObjectName)} to obtain the
578: * appropriate classloader for deserialization
579: */
580: public ObjectInputStream deserialize(String className,
581: ObjectName loaderName, byte[] data)
582: throws InstanceNotFoundException, OperationsException,
583: ReflectionException;
584:
585: /**
586: * Retrieve the classloader for an mbean
587: *
588: * @param name the object name of the mbean
589: * @return the classloader
590: * @exception InstanceNotFoundException when the mbean is not registered
591: */
592: public ClassLoader getClassLoaderFor(ObjectName name)
593: throws InstanceNotFoundException;
594:
595: /**
596: * Retrieve the classloader registered as an MBean
597: *
598: * @param name the object name of the classloader
599: * @return the classloader
600: * @exception InstanceNotFoundException when the mbean is not registered
601: */
602: public ClassLoader getClassLoader(ObjectName name)
603: throws InstanceNotFoundException;
604:
605: /**
606: * Retrieve the classloader repository for this mbean server
607: *
608: * @return the classloader repository
609: */
610: public ClassLoaderRepository getClassLoaderRepository();
611: }
|