001: /*
002: * Copyright (C) The MX4J Contributors.
003: * All rights reserved.
004: *
005: * This software is distributed under the terms of the MX4J License version 1.0.
006: * See the terms of the MX4J License in the documentation provided with this software.
007: */
008:
009: package javax.management;
010:
011: import java.io.IOException;
012: import java.util.Set;
013:
014: /**
015: * This interface allows clients (local or remote) to create, register, unregister and access registered MBeans.
016: *
017: * @version $Revision: 1.4 $
018: * @see MBeanServer
019: * @since JMX 1.2
020: */
021: public interface MBeanServerConnection {
022: /**
023: * Adds a NotificationListener to a registered MBean.
024: * A notification emitted by the specified source MBean will be forwarded by the MBeanServer to the given listener,
025: * if the given NotificationFilter allows so. If the filter is null, every notification will be sent to the
026: * listener.
027: * The handback object is transparently passed to the listener by the MBeanServer.
028: * The source of the notification is the source MBean ObjectName.
029: *
030: * @param observed The ObjectName of the source MBean on which the listener should be added.
031: * @param listener The listener which will handle the notifications emitted by the source MBean.
032: * @param filter The filter which will allow the notification to be forwarded to the listener.
033: * @param handback The context to be sent to the listener when a notification is emitted.
034: * @throws InstanceNotFoundException If the source MBean is not registered in the MBeanServer.
035: * @throws IOException If a communication problem occurred.
036: * @see #removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)
037: */
038: public void addNotificationListener(ObjectName observed,
039: NotificationListener listener, NotificationFilter filter,
040: Object handback) throws InstanceNotFoundException,
041: IOException;
042:
043: /**
044: * Adds a NotificationListener to a registered MBean.
045: * A notification emitted by the specified source MBean will be forwarded by the MBeanServer to the given listener MBean,
046: * if the given NotificationFilter allows so. If the filter is null, every notification will be sent to the
047: * listener.
048: * The handback object is transparently passed to the listener by the MBeanServer.
049: * The source of the notification is the source MBean ObjectName.
050: * If the listener MBean is unregistered, it will continue to receive notifications.
051: *
052: * @param observed The ObjectName of the source MBean on which the listener should be added.
053: * @param listener The ObjectName of the listener MBean which will handle the notifications emitted by the source MBean.
054: * @param filter The filter which will allow the notification to be forwarded to the listener.
055: * @param handback The context to be sent to the listener when a notification is emitted.
056: * @throws InstanceNotFoundException If the source or listener MBean are not registered in the MBeanServer.
057: * @throws IOException If a communication problem occurred.
058: * @see #removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)
059: */
060: public void addNotificationListener(ObjectName observed,
061: ObjectName listener, NotificationFilter filter,
062: Object handback) throws InstanceNotFoundException,
063: IOException;
064:
065: /**
066: * Removes the specified listener from the named source MBean.
067: * If the listener is registered more than once, for example with different filters or handbacks,
068: * this method will remove all those registrations.
069: *
070: * @param observed The ObjectName of the source MBean on which the listener should be removed.
071: * @param listener The listener to be removed.
072: * @throws InstanceNotFoundException If the source MBean is not registered in the MBeanServer.
073: * @throws ListenerNotFoundException If the listener is not registered in the MBean.
074: * @throws IOException If a communication problem occurred.
075: * @see #addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)
076: */
077: public void removeNotificationListener(ObjectName observed,
078: NotificationListener listener)
079: throws InstanceNotFoundException,
080: ListenerNotFoundException, IOException;
081:
082: /**
083: * Removes the specified listener MBean from the named source MBean.
084: * If the listener is registered more than once, for example with different filters or handbacks,
085: * this method will remove all those registrations.
086: *
087: * @param observed The ObjectName of the source MBean on which the listener should be removed.
088: * @param listener The ObjectName of the listener MBean to be removed.
089: * @throws InstanceNotFoundException If the source or listener MBean are not registered in the MBeanServer.
090: * @throws ListenerNotFoundException The listener is not registered in the MBean.
091: * @throws IOException If a communication problem occurred.
092: * @see #addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)
093: */
094: public void removeNotificationListener(ObjectName observed,
095: ObjectName listener) throws InstanceNotFoundException,
096: ListenerNotFoundException, IOException;
097:
098: /**
099: * Removes the specified listener from the named source MBean.
100: * The MBean must have a listener that exactly matches the given listener, filter, and handback parameters.
101: *
102: * @param observed The ObjectName of the source MBean on which the listener should be removed.
103: * @param listener The listener to be removed.
104: * @param filter The filter that was specified when the listener was added.
105: * @param handback The handback that was specified when the listener was added.
106: * @throws InstanceNotFoundException If the source MBean is not registered in the MBeanServer.
107: * @throws ListenerNotFoundException If the listener (along with filter and handback) is not registered in the MBean.
108: * @throws IOException If a communication problem occurred.
109: * @see #addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)
110: * @since JMX 1.2
111: */
112: public void removeNotificationListener(ObjectName observed,
113: NotificationListener listener, NotificationFilter filter,
114: Object handback) throws InstanceNotFoundException,
115: ListenerNotFoundException, IOException;
116:
117: /**
118: * Removes the specified listener MBean from the named source MBean.
119: * The MBean must have a listener that exactly matches the given listener, filter, and handback parameters.
120: *
121: * @param observed The ObjectName of the source MBean on which the listener should be removed.
122: * @param listener The ObjectName of the listener MBean to be removed.
123: * @param filter The filter that was specified when the listener was added.
124: * @param handback The handback that was specified when the listener was added.
125: * @throws InstanceNotFoundException If the source MBean is not registered in the MBeanServer.
126: * @throws ListenerNotFoundException If the listener (along with filter and handback) is not registered in the MBean.
127: * @throws IOException If a communication problem occurred.
128: * @see #addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)
129: * @since JMX 1.2
130: */
131: public void removeNotificationListener(ObjectName observed,
132: ObjectName listener, NotificationFilter filter,
133: Object handback) throws InstanceNotFoundException,
134: ListenerNotFoundException, IOException;
135:
136: /**
137: * Returns the metadata information exposed for management about the named MBean.
138: *
139: * @param objectName The name of the MBean for which retrieve the metadata.
140: * @return An instance of MBeanInfo allowing the retrieval of constructors, attributes, operations and notifications of this MBean.
141: * @throws IntrospectionException If an exception occured during introspection of the MBean.
142: * @throws InstanceNotFoundException If the named MBean is not registered in the MBeanServer.
143: * @throws ReflectionException If a reflection-type exception occurred
144: * @throws IOException If a communication problem occurred.
145: */
146: public MBeanInfo getMBeanInfo(ObjectName objectName)
147: throws InstanceNotFoundException, IntrospectionException,
148: ReflectionException, IOException;
149:
150: /**
151: * Returns whether the MBean specified is an instance of the specified class.
152: *
153: * @param objectName The ObjectName of the MBean.
154: * @param className The name of the class.
155: * @return True if the MBean specified is an instance of the specified class.
156: * @throws InstanceNotFoundException If the named MBean is not registered in the MBeanServer.
157: * @throws IOException If a communication problem occurred.
158: */
159: public boolean isInstanceOf(ObjectName objectName, String className)
160: throws InstanceNotFoundException, IOException;
161:
162: /**
163: * Returns the list of different ObjectName domains under which the MBeans in this MBeanServer are registered.
164: *
165: * @return The array of different ObjectName domains present in this MBeanServer.
166: * @throws IOException If a communication problem occurred.
167: * @since JMX 1.2
168: */
169: public String[] getDomains() throws IOException;
170:
171: /**
172: * Returns the default domain for this MBeanServer used in case ObjectName domain are not specified.
173: *
174: * @return The default domain of this MBeanServer.
175: * @throws IOException If a communication problem occurred.
176: */
177: public String getDefaultDomain() throws IOException;
178:
179: /**
180: * A facility method for <code>createMBean(className, objectName, null, null)</code>.
181: *
182: * @see #createMBean(String, ObjectName, Object[], String[])
183: */
184: public ObjectInstance createMBean(String className,
185: ObjectName objectName) throws ReflectionException,
186: InstanceAlreadyExistsException, MBeanRegistrationException,
187: MBeanException, NotCompliantMBeanException, IOException;
188:
189: /**
190: * Instantiates and registers an MBean of the specified class with the given ObjectName in the MBeanServer.
191: * The MBeanServer will use its ClassLoaderRepository to load the class of the MBean and the specified
192: * constructor's parameter classes, and creates the instance passing the specified arguments.
193: * The ObjectName may be null if the MBean implements {@link MBeanRegistration}
194: *
195: * @param className The class name of the MBean to be instantiated.
196: * @param objectName The ObjectName of the MBean, may be null.
197: * @param args An array containing the arguments to pass to the constructor.
198: * @param parameters An array containing the signature of the constructor.
199: * @return An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean.
200: * @throws ReflectionException If a reflection exception is thrown.
201: * @throws InstanceAlreadyExistsException If another MBean with the same ObjectName is already registered in the MBeanServer.
202: * @throws MBeanRegistrationException If an exception is thrown during MBean's registration.
203: * @throws MBeanException If the constructor of the MBean has thrown an exception
204: * @throws NotCompliantMBeanException If the MBean is not a JMX compliant MBean
205: * @throws IOException If a communication problem occurred.
206: */
207: public ObjectInstance createMBean(String className,
208: ObjectName objectName, Object[] args, String[] parameters)
209: throws ReflectionException, InstanceAlreadyExistsException,
210: MBeanRegistrationException, MBeanException,
211: NotCompliantMBeanException, IOException;
212:
213: /**
214: * A facility method for <code>createMBean(className, objectName, loaderName, null, null)</code>.
215: *
216: * @see #createMBean(String, ObjectName, ObjectName, Object[], String[])
217: */
218: public ObjectInstance createMBean(String className,
219: ObjectName objectName, ObjectName loaderName)
220: throws ReflectionException, InstanceAlreadyExistsException,
221: MBeanRegistrationException, MBeanException,
222: NotCompliantMBeanException, InstanceNotFoundException,
223: IOException;
224:
225: /**
226: * Instantiates and registers an MBean of the specified class with the given ObjectName in the MBeanServer.
227: * The MBeanServer will use the specified classloader MBean to load the class of the MBean and the specified
228: * constructor's parameter classes, and creates the instance passing the specified arguments, or the classloader
229: * of the MBeanServer if the classloader ObjectName is null.
230: * The ObjectName may be null if the MBean implements {@link MBeanRegistration}
231: *
232: * @param className The class name of the MBean to be instantiated.
233: * @param objectName The ObjectName of the MBean, may be null.
234: * @param loaderName The ObjectName of the classloader MBean to be used.
235: * @param args An array containing the arguments to pass to the constructor.
236: * @param parameters An array containing the signature of the constructor.
237: * @return An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean.
238: * @throws ReflectionException If a reflection exception is thrown.
239: * @throws InstanceAlreadyExistsException If another MBean with the same ObjectName is already registered in the MBeanServer.
240: * @throws MBeanRegistrationException If an exception is thrown during MBean's registration.
241: * @throws MBeanException If the constructor of the MBean has thrown an exception
242: * @throws NotCompliantMBeanException If the MBean is not a JMX compliant MBean
243: * @throws InstanceNotFoundException If the specified classloader MBean is not registered in the MBeanServer.
244: * @throws IOException If a communication problem occurred.
245: */
246: public ObjectInstance createMBean(String className,
247: ObjectName objectName, ObjectName loaderName,
248: Object[] args, String[] parameters)
249: throws ReflectionException, InstanceAlreadyExistsException,
250: MBeanRegistrationException, MBeanException,
251: NotCompliantMBeanException, InstanceNotFoundException,
252: IOException;
253:
254: /**
255: * Unregisters the MBean with the specified ObjectName from this MBeanServer.
256: *
257: * @param objectName The ObjectName of the MBean to be unregistered.
258: * @throws InstanceNotFoundException If the specified MBean is not registered in the MBeanServer.
259: * @throws MBeanRegistrationException If an exception is thrown during MBean's unregistration.
260: * @throws IOException If a communication problem occurred.
261: */
262: public void unregisterMBean(ObjectName objectName)
263: throws InstanceNotFoundException,
264: MBeanRegistrationException, IOException;
265:
266: /**
267: * Gets the value of the specified attribute of the named MBean.
268: *
269: * @param objectName The ObjectName of the MBean from which the attribute is to be retrieved.
270: * @param attribute The attribute name.
271: * @return The value of the specified attribute.
272: * @throws AttributeNotFoundException If the specified attribute does not belong to the management interface of the MBean.
273: * @throws MBeanException If the MBean's getter method throws an exception.
274: * @throws InstanceNotFoundException If the specified MBean is not registered in the MBeanServer.
275: * @throws ReflectionException If a reflection exception is thrown.
276: * @throws IOException If a communication problem occurred.
277: * @see #setAttribute
278: */
279: public Object getAttribute(ObjectName objectName, String attribute)
280: throws MBeanException, AttributeNotFoundException,
281: InstanceNotFoundException, ReflectionException, IOException;
282:
283: /**
284: * Sets the value of the specified attribute of the named MBean.
285: *
286: * @param objectName The name of the MBean within which the attribute is to be set.
287: * @param attribute The Attribute to be set.
288: * @throws InstanceNotFoundException If the specified MBean is not registered in the MBeanServer.
289: * @throws AttributeNotFoundException If the specified attribute does not belong to the management interface of the MBean.
290: * @throws InvalidAttributeValueException If the value specified for the attribute does not match the attribute's type
291: * @throws MBeanException If the MBean's setter method throws an exception.
292: * @throws ReflectionException If a reflection exception is thrown.
293: * @throws IOException If a communication problem occurred.
294: * @see #getAttribute
295: */
296: public void setAttribute(ObjectName objectName, Attribute attribute)
297: throws InstanceNotFoundException,
298: AttributeNotFoundException, InvalidAttributeValueException,
299: MBeanException, ReflectionException, IOException;
300:
301: /**
302: * Gets the values of several attributes of the named MBean.
303: *
304: * @param objectName The ObjectName of the MBean from which the attributes are to be retrieved.
305: * @param attributes The attribute names.
306: * @return An AttributeList containing the values of the attributes that it has been possible to retrieve.
307: * @throws InstanceNotFoundException If the specified MBean is not registered in the MBeanServer.
308: * @throws ReflectionException If a reflection exception is thrown.
309: * @throws IOException If a communication problem occurred.
310: * @see #setAttributes
311: */
312: public AttributeList getAttributes(ObjectName objectName,
313: String[] attributes) throws InstanceNotFoundException,
314: ReflectionException, IOException;
315:
316: /**
317: * Sets the values of several attributes of the named MBean.
318: *
319: * @param objectName The name of the MBean within which the attribute is to be set.
320: * @param attributes The AttributeList containing the Attributes to be set.
321: * @return The AttributeList containing the attributes that it has been possible to set.
322: * @throws InstanceNotFoundException If the specified MBean is not registered in the MBeanServer.
323: * @throws ReflectionException If a reflection exception is thrown.
324: * @throws IOException If a communication problem occurred.
325: * @see #getAttributes
326: */
327: public AttributeList setAttributes(ObjectName objectName,
328: AttributeList attributes) throws InstanceNotFoundException,
329: ReflectionException, IOException;
330:
331: /**
332: * Invokes the specified operation on the named MBean.
333: *
334: * @param objectName The ObjectName of the MBean on which the method is to be invoked.
335: * @param methodName The name of the operation to be invoked.
336: * @param args An array containing the arguments to pass to the operation.
337: * @param parameters An array containing the signature of the operation.
338: * @return The return value of the operation, or null if the operation returns void.
339: * @throws InstanceNotFoundException If the specified MBean is not registered in the MBeanServer.
340: * @throws MBeanException If the MBean's operation method throws an exception.
341: * @throws ReflectionException If a reflection exception is thrown.
342: * @throws IOException If a communication problem occurred.
343: */
344: public Object invoke(ObjectName objectName, String methodName,
345: Object[] args, String[] parameters)
346: throws InstanceNotFoundException, MBeanException,
347: ReflectionException, IOException;
348:
349: /**
350: * Returns the number of MBeans registered in this MBeanServer.
351: *
352: * @throws IOException If a communication problem occurred.
353: */
354: public Integer getMBeanCount() throws IOException;
355:
356: /**
357: * Checks whether the given ObjectName identifies an MBean registered in this MBeanServer.
358: *
359: * @param objectName The ObjectName to be checked.
360: * @return True if an MBean with the specified ObjectName is already registered in the MBeanServer.
361: * @throws IOException If a communication problem occurred.
362: */
363: public boolean isRegistered(ObjectName objectName)
364: throws IOException;
365:
366: /**
367: * Gets the ObjectInstance for the named MBean registered with the MBeanServer.
368: *
369: * @param objectName The ObjectName of the MBean.
370: * @return The ObjectInstance associated with the named MBean.
371: * @throws InstanceNotFoundException If the specified MBean is not registered in the MBeanServer.
372: * @throws IOException If a communication problem occurred.
373: */
374: public ObjectInstance getObjectInstance(ObjectName objectName)
375: throws InstanceNotFoundException, IOException;
376:
377: /**
378: * Gets a subset of the ObjectInstances belonging to MBeans registered in this MBeanServer.
379: * It is possible to filter the set of MBeans by specifying a pattern for MBean's ObjectNames, and a query expression
380: * to be evaluated to further filter the set of MBeans.
381: * The set can be further restricted if any exception is thrown during retrieval of MBean (for example for
382: * security reasons): the failing MBean will not be included.
383: *
384: * @param patternName The ObjectName pattern identifying the MBeans to be retrieved, or null to retrieve all MBeans.
385: * @param filter The query expression to be evaluated for selecting MBeans, or null.
386: * @return A set containing the ObjectInstance objects for the selected MBeans.
387: * @throws IOException If a communication problem occurred.
388: */
389: public Set queryMBeans(ObjectName patternName, QueryExp filter)
390: throws IOException;
391:
392: /**
393: * Gets a subset of the ObjectNames belonging to MBeans registered in this MBeanServer.
394: * It is possible to filter the set of MBeans by specifying a pattern for MBean's ObjectNames, and a query expression
395: * to be evaluated to further filter the set of MBeans.
396: * The set can be further restricted if any exception is thrown during retrieval of MBean (for example for
397: * security reasons): the failing MBean will not be included.
398: *
399: * @param patternName The ObjectName pattern identifying the MBeans to be retrieved, or null to retrieve all MBeans.
400: * @param filter The query expression to be evaluated for selecting MBeans, or null.
401: * @return A set containing the ObjectNames for the selected MBeans.
402: * @throws IOException If a communication problem occurred.
403: */
404: public Set queryNames(ObjectName patternName, QueryExp filter)
405: throws IOException;
406: }
|