1 /*
2 * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 /*
26 * @author IBM Corp.
27 *
28 * Copyright IBM Corp. 1999-2000. All rights reserved.
29 */
30
31 package javax.management.modelmbean;
32
33 import javax.management.DynamicMBean;
34 import javax.management.InstanceNotFoundException;
35 import javax.management.MBeanException;
36 import javax.management.PersistentMBean;
37 import javax.management.RuntimeOperationsException;
38
39 /**
40 * This interface must be implemented by the ModelMBeans. An implementation of this interface
41 * must be shipped with every JMX Agent.
42 * <P>
43 * Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's
44 * createMBean method. The resource then sets the ModelMBeanInfo (with Descriptors) for the ModelMBean
45 * instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible
46 * from MBeans, connectors/adaptors like other MBeans. Through the ModelMBeanInfo Descriptors, values and methods in
47 * the managed application can be defined and mapped to attributes and operations of the ModelMBean.
48 * This mapping can be defined during development in an XML formatted file or dynamically and
49 * programmatically at runtime.
50 * <P>
51 * Every ModelMBean which is instantiated in the MBeanServer becomes manageable:
52 * its attributes and operations
53 * become remotely accessible through the connectors/adaptors connected to that MBeanServer.
54 * A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean.
55 * By instantiating a ModelMBean, resources are guaranteed that the MBean is valid.
56 * <P>
57 * MBeanException and RuntimeOperationsException must be thrown on every public method. This allows
58 * for wrapping exceptions from distributed communications (RMI, EJB, etc.). These exceptions do
59 * not have to be thrown by the implementation except in the scenarios described in the specification
60 * and javadoc.
61 *
62 * @since 1.5
63 */
64
65 public interface ModelMBean extends
66 DynamicMBean,
67 PersistentMBean,
68 ModelMBeanNotificationBroadcaster
69 {
70
71 /**
72 * Initializes a ModelMBean object using ModelMBeanInfo passed in.
73 * This method makes it possible to set a customized ModelMBeanInfo on
74 * the ModelMBean as long as it is not registered with the MBeanServer.
75 * <br>
76 * Once the ModelMBean's ModelMBeanInfo (with Descriptors) are
77 * customized and set on the ModelMBean, the ModelMBean can be
78 * registered with the MBeanServer.
79 * <P>
80 * If the ModelMBean is currently registered, this method throws
81 * a {@link javax.management.RuntimeOperationsException} wrapping an
82 * {@link IllegalStateException}
83 *
84 * @param inModelMBeanInfo The ModelMBeanInfo object to be used
85 * by the ModelMBean.
86 *
87 * @exception MBeanException Wraps a distributed communication
88 * Exception.
89 * @exception RuntimeOperationsException
90 * <ul><li>Wraps an {@link IllegalArgumentException} if
91 * the MBeanInfo passed in parameter is null.</li>
92 * <li>Wraps an {@link IllegalStateException} if the ModelMBean
93 * is currently registered in the MBeanServer.</li>
94 * </ul>
95 *
96 **/
97 public void setModelMBeanInfo(ModelMBeanInfo inModelMBeanInfo)
98 throws MBeanException, RuntimeOperationsException;
99
100 /**
101 * Sets the instance handle of the object against which to
102 * execute all methods in this ModelMBean management interface
103 * (MBeanInfo and Descriptors).
104 *
105 * @param mr Object that is the managed resource
106 * @param mr_type The type of reference for the managed resource. Can be: ObjectReference,
107 * Handle, IOR, EJBHandle, RMIReference.
108 * If the MBeanServer cannot process the mr_type passed in, an InvalidTargetTypeException
109 * will be thrown.
110 *
111 *
112 * @exception MBeanException The initializer of the object has thrown an exception.
113 * @exception RuntimeOperationsException Wraps an IllegalArgumentException:
114 * The managed resource type passed in parameter is null.
115 * @exception InstanceNotFoundException The managed resource object could not be found
116 * @exception InvalidTargetObjectTypeException The managed resource type cannot be processed by the
117 * ModelMBean or JMX Agent.
118 */
119 public void setManagedResource(Object mr, String mr_type)
120 throws MBeanException, RuntimeOperationsException,
121 InstanceNotFoundException, InvalidTargetObjectTypeException ;
122
123 }