annotate src/share/classes/javax/management/openmbean/package.html @ 0:37a05a11f281

Initial load
author duke
date Sat, 01 Dec 2007 00:00:00 +0000
children 00cd9dc3c2b5
rev   line source
duke@0 1 <html>
duke@0 2 <head>
duke@0 3 <title> package</title>
duke@0 4 <!--
duke@0 5 Copyright 2001-2007 Sun Microsystems, Inc. All Rights Reserved.
duke@0 7
duke@0 8 This code is free software; you can redistribute it and/or modify it
duke@0 9 under the terms of the GNU General Public License version 2 only, as
duke@0 10 published by the Free Software Foundation. Sun designates this
duke@0 11 particular file as subject to the "Classpath" exception as provided
duke@0 12 by Sun in the LICENSE file that accompanied this code.
duke@0 13
duke@0 14 This code is distributed in the hope that it will be useful, but WITHOUT
duke@0 15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@0 16 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@0 17 version 2 for more details (a copy is included in the LICENSE file that
duke@0 18 accompanied this code).
duke@0 19
duke@0 20 You should have received a copy of the GNU General Public License version
duke@0 21 2 along with this work; if not, write to the Free Software Foundation,
duke@0 22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@0 23
duke@0 24 Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
duke@0 25 CA 95054 USA or visit if you need additional information or
duke@0 26 have any questions.
duke@0 27 -->
duke@0 28 </head>
duke@0 29 <body bgcolor="white">
duke@0 30
duke@0 31 <p>Provides the open data types and Open MBean descriptor classes.
duke@0 32 An <em>Open MBean</em> is an MBean where the types of attributes
duke@0 33 and of operation parameters and return values are built using a
duke@0 34 small set of predefined Java classes. Open MBeans facilitate
duke@0 35 operation with remote management programs that do not necessarily
duke@0 36 have access to application-specific types, including non-Java
duke@0 37 programs.</p>
duke@0 38
duke@0 39 <p>Every MBean has an {@link
duke@0 40 MBeanInfo} with information about the MBean itself, and its
duke@0 41 attributes, operations, constructors, and notifications. In an
duke@0 42 Open MBean, this <code>MBeanInfo</code> implements the {@link
duke@0 43 OpenMBeanInfo}
duke@0 44 interface, usually by being an instance of {@link
duke@0 45
duke@0 46 OpenMBeanInfoSupport}.</p>
duke@0 47
duke@0 48 <p>The attribute information returned by {@link
duke@0 49
duke@0 50 MBeanInfo.getAttributes} for an Open MBean is an array of
duke@0 51 objects implementing {@link
duke@0 52
duke@0 53 OpenMBeanAttributeInfo}, usually instances of {@link
duke@0 54
duke@0 55 OpenMBeanAttributeInfoSupport}. In addition to the usual
duke@0 56 information about attributes, an
duke@0 57 <code>OpenMBeanAttributeInfo</code> specifies the {@link
duke@0 58 OpenType} of the attribute.
duke@0 59 The possible <code>OpenType</code> values are predefined, which
duke@0 60 is what ensures that remote managers will understand them.</p>
duke@0 61
duke@0 62 <p>Similar remarks apply to the parameter types of operations and
duke@0 63 constructors, and to the return types of operations.</p>
duke@0 64
duke@0 65 <p>There is a distinction between an attribute's Java language
duke@0 66 type, as returned by {@link
duke@0 67 getType()}, and
duke@0 68 its <code>OpenType</code>, as returned by {@link
duke@0 69
duke@0 70 getOpenType()}. For example, if the Java language type is
duke@0 71 <code>java.lang.String</code>, the <code>OpenType</code> will be
duke@0 72 {@link
duke@0 73 SimpleType.String}. If the Java language type is {@link
duke@0 74}, the
duke@0 75 <code>OpenType</code> will be a {@link
duke@0 76 CompositeType} that
duke@0 77 describes the items in the <code>CompositeData</code> instances
duke@0 78 for the attribute.</p>
duke@0 79
duke@0 80 <h2><a name="constraints">Default values and constraints</a></h2>
duke@0 81
duke@0 82 <p>In Open MBeans, attributes and parameters can have default values
duke@0 83 and/or constraints associated with them in the {@code
duke@0 84 OpenMBeanAttributeInfo} or {@code OpenMBeanParameterInfo}.
duke@0 85 There are two ways to specify these constraints. Either the
duke@0 86 values are directly specified as parameters to one of the
duke@0 87 constructors of {@code OpenMBeanAttributeInfoSupport} or
duke@0 88 {@code OpenMBeanParameterInfoSupport}, for example
duke@0 89 {@link
duke@0 90
duke@0 91 String, String, OpenType, Object, Object[])}; or the values are
duke@0 92 specified in a {@link Descriptor} given
duke@0 93 as a parameter to one of the constructors.</p>
duke@0 94
duke@0 95 <p>When a {@code Descriptor} is used, the fields of interest are
duke@0 96 these:</p>
duke@0 97
duke@0 98 <ul>
duke@0 99
duke@0 100 <li>{@code defaultValue} defines the value returned by
duke@0 101 {@link
duke@0 102 getDefaultValue()};
duke@0 103
duke@0 104 <li>{@code minValue} defines the value returned by {@link
duke@0 105 getMinValue()};
duke@0 106
duke@0 107 <li>{@code maxValue} defines the value returned by {@link
duke@0 108 getMaxValue()};
duke@0 109
duke@0 110 <li>{@code legalValues} defines the values returned by {@link
duke@0 111 getLegalValues()}.
duke@0 112
duke@0 113 </ul>
duke@0 114
duke@0 115 <p>For {@code defaultValue}, {@code minValue}, and {@code
duke@0 116 maxValue}, the associated value must either be of the Java type
duke@0 117 corresponding to {@code openType}, or be a string that can be
duke@0 118 converted into that type. The conversion uses the static method
duke@0 119 {@code valueOf(String)} if it finds one; otherwise a constructor
duke@0 120 with a single {@code String} parameter if it finds one; otherwise
duke@0 121 it fails.</p>
duke@0 122
duke@0 123 <p>For {@code legalValues}, the associated value must be either
duke@0 124 an array or a {@code Set}, and the elements of the array or set
duke@0 125 must be convertible as described for {@code defaultValue} etc.</p>
duke@0 126
duke@0 127 <p>The following conditions must be met for these fields:</p>
duke@0 128
duke@0 129 <ul>
duke@0 130 <li>the values must be of the appropriate type, or be strings
duke@0 131 that can be converted to the appropriate type as explained
duke@0 132 above;
duke@0 133
duke@0 134 <li>if {@code legalValues} is present then neither {@code
duke@0 135 minValue} nor {@code maxValue} must be present;
duke@0 136
duke@0 137 <li>if {@code defaultValue} is present then it must satisfy the
duke@0 138 constraints defined by {@code legalValues}, {@code minValue}, or
duke@0 139 {@code maxValue} when any of these is also present;
duke@0 140
duke@0 141 <li>if {@code minValue} and {@code maxValue} are both present
duke@0 142 then {@code minValue} must not be greater than {@code maxValue}.
duke@0 143 </ul>
duke@0 144
duke@0 145 @see <a href="{@docRoot}/../technotes/guides/jmx/">
duke@0 146 Java SE 6 Platform documentation on JMX technology</a>,
duke@0 147 in particular the
duke@0 148 <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
duke@0 149 JMX Specification, version 1.4</a>
duke@0 150
duke@0 151 @since 1.5
duke@0 152
duke@0 153 </BODY>
duke@0 154 </HTML>