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.IOException;
025: import java.util.Set;
026:
027: /**
028: * An interface used to talk to an MBeanServer that is either remote or
029: * local. The local interface MBeanServer extends this one.
030: *
031: * @see javax.management.MBeanServer
032: *
033: * @author <a href="mailto:Adrian.Brock@HappeningTimes.com">Adrian Brock</a>.
034: * @version $Revision: 57200 $
035: */
036: public interface MBeanServerConnection {
037: /**
038: * Create an MBean registered using the given object name.<p>
039: *
040: * Uses the default contructor.
041: *
042: * @param className the class name of the mbean
043: * @param name the object name for registration, can be null
044: * @return an ObjectInstance describing the registration
045: * @exception ReflectionException for class not found or an exception
046: * invoking the contructor
047: * @exception InstanceAlreadyExistsException for an MBean already registered
048: * with the passed or generated ObjectName
049: * @exception MBeanRegistrationException for any exception thrown by the
050: * MBean's preRegister
051: * @exception MBeanException for any exception thrown by the MBean's constructor
052: * @exception NotCompliantMBeanException if the class name does not correspond to
053: * a valid MBean
054: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
055: * null class name, the ObjectName could not be determined or it is a pattern
056: * @exception IOException for a communication problem during this operation
057: */
058: public ObjectInstance createMBean(String className, ObjectName name)
059: throws ReflectionException, InstanceAlreadyExistsException,
060: MBeanRegistrationException, MBeanException,
061: NotCompliantMBeanException, IOException;
062:
063: /**
064: * Create an MBean registered using the given object name.<p>
065: *
066: * The MBean is loaded using the passed classloader. Uses the default contructor.
067: *
068: * @param className the class name of the mbean
069: * @param loaderName an MBean that implements a classloader
070: * @param name the object name for registration, can be null
071: * @return an ObjectInstance describing the registration
072: * @exception ReflectionException for class not found or an exception
073: * invoking the contructor
074: * @exception InstanceAlreadyExistsException for an MBean already registered
075: * with the passed or generated ObjectName
076: * @exception MBeanRegistrationException for any exception thrown by the
077: * MBean's preRegister
078: * @exception MBeanException for any exception thrown by the MBean's constructor
079: * @exception InstanceNotFoundException if the loaderName is not a classloader registered
080: * in the MBeanServer
081: * @exception NotCompliantMBeanException if the class name does not correspond to
082: * a valid MBean
083: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
084: * null class name, the ObjectName could not be determined or it is a pattern
085: * @exception IOException for a communication problem during this operation
086: */
087: public ObjectInstance createMBean(String className,
088: ObjectName name, ObjectName loaderName)
089: throws ReflectionException, InstanceAlreadyExistsException,
090: MBeanRegistrationException, MBeanException,
091: NotCompliantMBeanException, InstanceNotFoundException,
092: IOException;
093:
094: /**
095: * Create an MBean registered using the given object name.<p>
096: *
097: * Uses the specified constructor.
098: *
099: * @param className the class name of the mbean
100: * @param name the object name for registration, can be null
101: * @param params the parameters for the constructor
102: * @param signature the signature of the constructor
103: * @return an ObjectInstance describing the registration
104: * @exception ReflectionException for class not found or an exception
105: * invoking the contructor
106: * @exception InstanceAlreadyExistsException for an MBean already registered
107: * with the passed or generated ObjectName
108: * @exception MBeanRegistrationException for any exception thrown by the
109: * MBean's preRegister
110: * @exception MBeanException for any exception thrown by the MBean's constructor
111: * @exception NotCompliantMBeanException if the class name does not correspond to
112: * a valid MBean
113: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
114: * null class name, the ObjectName could not be determined or it is a pattern
115: * @exception IOException for a communication problem during this operation
116: */
117: public ObjectInstance createMBean(String className,
118: ObjectName name, Object[] params, String[] signature)
119: throws ReflectionException, InstanceAlreadyExistsException,
120: MBeanRegistrationException, MBeanException,
121: NotCompliantMBeanException, IOException;
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: * @exception IOException for a communication problem during this operation
148: */
149: public ObjectInstance createMBean(String className,
150: ObjectName name, ObjectName loaderName, Object[] params,
151: String[] signature) throws ReflectionException,
152: InstanceAlreadyExistsException, MBeanRegistrationException,
153: MBeanException, NotCompliantMBeanException,
154: InstanceNotFoundException, IOException;
155:
156: /**
157: * Unregisters an mbean.
158: *
159: * @param name the object name of the mbean to unregister
160: * @exception InstanceNotFoundException if the mbean is not registered
161: * in the MBeanServer
162: * @exception MBeanRegistrationException for any exception thrown by the
163: * MBean's preDeregister
164: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
165: * null name, or trying to unregister a JMX implementation MBean
166: * @exception IOException for a communication problem during this operation
167: */
168: public void unregisterMBean(ObjectName name)
169: throws InstanceNotFoundException,
170: MBeanRegistrationException, IOException;
171:
172: /**
173: * Retrieve an MBean's registration information.
174: *
175: * @param name the object name of the mbean
176: * @exception InstanceNotFoundException if the mbean is not registered
177: * in the MBeanServer
178: * @exception IOException for a communication problem during this operation
179: */
180: public ObjectInstance getObjectInstance(ObjectName name)
181: throws InstanceNotFoundException, IOException;
182:
183: /**
184: * Retrieve a set of Object instances
185: *
186: * @param name an ObjectName pattern, can be null for all mbeans
187: * @param query a query expression to further filter the mbeans, can be null
188: * for no query
189: * @exception IOException for a communication problem during this operation
190: */
191: public Set queryMBeans(ObjectName name, QueryExp query)
192: throws IOException;
193:
194: /**
195: * Retrieve a set of Object names
196: *
197: * @param name an ObjectName pattern, can be null for all mbeans
198: * @param query a query expression to further filter the mbeans, can be null
199: * for no query
200: * @exception IOException for a communication problem during this operation
201: */
202: public Set queryNames(ObjectName name, QueryExp query)
203: throws IOException;
204:
205: /**
206: * Test whether an mbean is registered.
207: *
208: * @param name the object name of the mbean
209: * @return true when the mbean is registered, false otherwise
210: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
211: * null name
212: * @exception IOException for a communication problem during this operation
213: */
214: public boolean isRegistered(ObjectName name) throws IOException;
215:
216: /**
217: * Retrieve the number of mbeans registered in the server.
218: *
219: * @return true the number of registered mbeans
220: * @exception IOException for a communication problem during this operation
221: */
222: public Integer getMBeanCount() throws IOException;
223:
224: /**
225: * Retrieve a value from an MBean.
226: *
227: * @param name the object name of the mbean
228: * @param attribute the attribute name of the value to retrieve
229: * @return the value
230: * @exception ReflectionException for an exception invoking the mbean
231: * @exception MBeanException for any exception thrown by the mbean
232: * @exception InstanceNotFoundException if the mbean is not registered
233: * @exception AttributeNotFoundException if the mbean has no such attribute
234: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
235: * null name or attribute
236: * @exception IOException for a communication problem during this operation
237: */
238: public Object getAttribute(ObjectName name, String attribute)
239: throws MBeanException, AttributeNotFoundException,
240: InstanceNotFoundException, ReflectionException, IOException;
241:
242: /**
243: * Retrieve a list of values from an MBean.
244: *
245: * @param name the object name of the mbean
246: * @param attributes the attribute names of the values to retrieve
247: * @return the list of values, attributes with errors are ignored
248: * @exception ReflectionException for an exception invoking the mbean
249: * @exception InstanceNotFoundException if the mbean is not registered
250: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
251: * null name or attributes
252: * @exception IOException for a communication problem during this operation
253: */
254: public AttributeList getAttributes(ObjectName name,
255: String[] attributes) throws InstanceNotFoundException,
256: ReflectionException, IOException;
257:
258: /**
259: * Set a value for an MBean.
260: *
261: * @param name the object name of the mbean
262: * @param attribute the attribute name and value to set
263: * @exception ReflectionException for an exception invoking the mbean
264: * @exception MBeanException for any exception thrown by the mbean
265: * @exception InstanceNotFoundException if the mbean is not registered
266: * @exception AttributeNotFoundException if the mbean has no such attribute
267: * @exception InvalidAttributeValueException if the new value has an incorrect type
268: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
269: * null name or attribute
270: * @exception IOException for a communication problem during this operation
271: */
272: public void setAttribute(ObjectName name, Attribute attribute)
273: throws InstanceNotFoundException,
274: AttributeNotFoundException, InvalidAttributeValueException,
275: MBeanException, ReflectionException, IOException;
276:
277: /**
278: * Set a list of values for an MBean.
279: *
280: * @param name the object name of the mbean
281: * @param attributes the attribute names and values to set
282: * @return the list of values, attributes with errors are ignored
283: * @exception ReflectionException for an exception invoking the mbean
284: * @exception InstanceNotFoundException if the mbean is not registered
285: * @exception RuntimeOperationsException wrapping an IllegalArgumentException for a
286: * null name or attributes
287: * @exception IOException for a communication problem during this operation
288: */
289: public AttributeList setAttributes(ObjectName name,
290: AttributeList attributes) throws InstanceNotFoundException,
291: ReflectionException, IOException;
292:
293: /**
294: * Invokes an operation on an mbean.
295: *
296: * @param name the object name of the mbean
297: * @param operationName the operation to perform
298: * @param params the parameters
299: * @param signature the signature of the operation
300: * @return any result of the operation
301: * @exception ReflectionException for an exception invoking the mbean
302: * @exception MBeanException for any exception thrown by the mbean
303: * @exception InstanceNotFoundException if the mbean is not registered
304: * @exception IOException for a communication problem during this operation
305: */
306: public Object invoke(ObjectName name, String operationName,
307: Object[] params, String[] signature)
308: throws InstanceNotFoundException, MBeanException,
309: ReflectionException, IOException;
310:
311: /**
312: * Retrieve the default domain of the mbeanserver.
313: *
314: * @return the default domain
315: * @exception IOException for a communication problem during this operation
316: */
317: public String getDefaultDomain() throws IOException;
318:
319: /**
320: * Retrieve the domains of the mbeanserver.
321: *
322: * @return the domains
323: * @exception IOException for a communication problem during this operation
324: */
325: public String[] getDomains() throws IOException;
326:
327: /**
328: * Add a notification listener to an MBean.
329: *
330: * @param name the name of the MBean broadcasting notifications
331: * @param listener the listener to add
332: * @param filter a filter to preprocess notifications
333: * @param handback a object to add to any notifications
334: * @exception InstanceNotFoundException if the broadcaster is not registered
335: * @exception IOException for a communication problem during this operation
336: */
337: public void addNotificationListener(ObjectName name,
338: NotificationListener listener, NotificationFilter filter,
339: Object handback) throws InstanceNotFoundException,
340: IOException;
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: * @exception IOException for a communication problem during this operation
353: */
354: public void addNotificationListener(ObjectName name,
355: ObjectName listener, NotificationFilter filter,
356: Object handback) throws InstanceNotFoundException,
357: IOException;
358:
359: /**
360: * Removes a listener from an mbean.<p>
361: *
362: * All registrations of the listener are removed.
363: *
364: * @param name the name of the MBean broadcasting notifications
365: * @param listener the object name of the listener to remove
366: * @exception InstanceNotFoundException if the broadcaster or listener is not registered
367: * @exception ListenerNotFoundException if the listener is not registered against the broadcaster
368: * @exception IOException for a communication problem during this operation
369: */
370: public void removeNotificationListener(ObjectName name,
371: ObjectName listener) throws InstanceNotFoundException,
372: ListenerNotFoundException, IOException;
373:
374: /**
375: * Removes a listener from an mbean.<p>
376: *
377: * Only the listener that was registered with the same filter and handback is removed.
378: *
379: * @param name the name of the MBean broadcasting notifications
380: * @param listener the object name of listener to remove
381: * @param filter the filter of the listener to remove
382: * @exception InstanceNotFoundException if the broadcaster or listener is not registered
383: * @exception ListenerNotFoundException if the listener, filter, handback
384: * is not registered against the broadcaster
385: * @exception IOException for a communication problem during this operation
386: */
387: public void removeNotificationListener(ObjectName name,
388: ObjectName listener, NotificationFilter filter,
389: Object handback) throws InstanceNotFoundException,
390: ListenerNotFoundException, IOException;
391:
392: /**
393: * Removes a listener from an mbean.<p>
394: *
395: * All registrations of the listener are removed.
396: *
397: * @param name the name of the MBean broadcasting notifications
398: * @param listener the listener to remove
399: * @exception InstanceNotFoundException if the broadcaster is not registered
400: * @exception ListenerNotFoundException if the listener is not registered against the broadcaster
401: * @exception IOException for a communication problem during this operation
402: */
403: public void removeNotificationListener(ObjectName name,
404: NotificationListener listener)
405: throws InstanceNotFoundException,
406: ListenerNotFoundException, IOException;
407:
408: /**
409: * Removes a listener from an mbean.<p>
410: *
411: * Only the listener that was registered with the same filter and handback is removed.
412: *
413: * @param name the name of the MBean broadcasting notifications
414: * @param listener the listener to remove
415: * @param filter the filter of the listener to remove
416: * @exception InstanceNotFoundException if the broadcaster is not registered
417: * @exception ListenerNotFoundException if the listener, filter, handback
418: * is not registered against the broadcaster
419: * @exception IOException for a communication problem during this operation
420: */
421: public void removeNotificationListener(ObjectName name,
422: NotificationListener listener, NotificationFilter filter,
423: Object handback) throws InstanceNotFoundException,
424: ListenerNotFoundException, IOException;
425:
426: /**
427: * Retrieves the jmx metadata for an mbean
428: *
429: * @param name the name of the mbean
430: * @return the metadata
431: * @exception IntrospectionException for any error during instrospection
432: * @exception InstanceNotFoundException if the mbean is not registered
433: * @exception ReflectionException for any error trying to invoke the operation on the mbean
434: * @exception IOException for a communication problem during this operation
435: */
436: public MBeanInfo getMBeanInfo(ObjectName name)
437: throws InstanceNotFoundException, IntrospectionException,
438: ReflectionException, IOException;
439:
440: /**
441: * Tests whether an mbean can be cast to the given type
442: *
443: * @param name the name of the mbean
444: * @param className the class name to check
445: * @return true when it is of that type, false otherwise
446: * @exception InstanceNotFoundException if the mbean is not registered
447: * @exception IOException for a communication problem during this operation
448: */
449: public boolean isInstanceOf(ObjectName name, String className)
450: throws InstanceNotFoundException, IOException;
451: }
|