--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/management/openmbean/package.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,154 @@
+<html>
+<head>
+<title>javax.management.openmbean package</title>
+<!--
+Copyright 2001-2007 Sun Microsystems, Inc. All Rights Reserved.
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This code is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License version 2 only, as
+published by the Free Software Foundation. Sun designates this
+particular file as subject to the "Classpath" exception as provided
+by Sun in the LICENSE file that accompanied this code.
+
+This code is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+version 2 for more details (a copy is included in the LICENSE file that
+accompanied this code).
+
+You should have received a copy of the GNU General Public License version
+2 along with this work; if not, write to the Free Software Foundation,
+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+CA 95054 USA or visit www.sun.com if you need additional information or
+have any questions.
+-->
+</head>
+<body bgcolor="white">
+
+ <p>Provides the open data types and Open MBean descriptor classes.
+ An <em>Open MBean</em> is an MBean where the types of attributes
+ and of operation parameters and return values are built using a
+ small set of predefined Java classes. Open MBeans facilitate
+ operation with remote management programs that do not necessarily
+ have access to application-specific types, including non-Java
+ programs.</p>
+
+ <p>Every MBean has an {@link javax.management.MBeanInfo
+ MBeanInfo} with information about the MBean itself, and its
+ attributes, operations, constructors, and notifications. In an
+ Open MBean, this <code>MBeanInfo</code> implements the {@link
+ javax.management.openmbean.OpenMBeanInfo OpenMBeanInfo}
+ interface, usually by being an instance of {@link
+ javax.management.openmbean.OpenMBeanInfoSupport
+ OpenMBeanInfoSupport}.</p>
+
+ <p>The attribute information returned by {@link
+ javax.management.MBeanInfo#getAttributes()
+ MBeanInfo.getAttributes} for an Open MBean is an array of
+ objects implementing {@link
+ javax.management.openmbean.OpenMBeanAttributeInfo
+ OpenMBeanAttributeInfo}, usually instances of {@link
+ javax.management.openmbean.OpenMBeanAttributeInfoSupport
+ OpenMBeanAttributeInfoSupport}. In addition to the usual
+ information about attributes, an
+ <code>OpenMBeanAttributeInfo</code> specifies the {@link
+ javax.management.openmbean.OpenType OpenType} of the attribute.
+ The possible <code>OpenType</code> values are predefined, which
+ is what ensures that remote managers will understand them.</p>
+
+ <p>Similar remarks apply to the parameter types of operations and
+ constructors, and to the return types of operations.</p>
+
+ <p>There is a distinction between an attribute's Java language
+ type, as returned by {@link
+ javax.management.MBeanAttributeInfo#getType() getType()}, and
+ its <code>OpenType</code>, as returned by {@link
+ javax.management.openmbean.OpenMBeanAttributeInfo#getOpenType()
+ getOpenType()}. For example, if the Java language type is
+ <code>java.lang.String</code>, the <code>OpenType</code> will be
+ {@link javax.management.openmbean.SimpleType#STRING
+ SimpleType.String}. If the Java language type is {@link
+ javax.management.openmbean.CompositeData}, the
+ <code>OpenType</code> will be a {@link
+ javax.management.openmbean.CompositeType CompositeType} that
+ describes the items in the <code>CompositeData</code> instances
+ for the attribute.</p>
+
+ <h2><a name="constraints">Default values and constraints</a></h2>
+
+ <p>In Open MBeans, attributes and parameters can have default values
+ and/or constraints associated with them in the {@code
+ OpenMBeanAttributeInfo} or {@code OpenMBeanParameterInfo}.
+ There are two ways to specify these constraints. Either the
+ values are directly specified as parameters to one of the
+ constructors of {@code OpenMBeanAttributeInfoSupport} or
+ {@code OpenMBeanParameterInfoSupport}, for example
+ {@link
+ javax.management.openmbean.OpenMBeanParameterInfoSupport#OpenMBeanParameterInfoSupport(
+ String, String, OpenType, Object, Object[])}; or the values are
+ specified in a {@link javax.management.Descriptor Descriptor} given
+ as a parameter to one of the constructors.</p>
+
+ <p>When a {@code Descriptor} is used, the fields of interest are
+ these:</p>
+
+ <ul>
+
+ <li>{@code defaultValue} defines the value returned by
+ {@link javax.management.openmbean.OpenMBeanParameterInfo#getDefaultValue()
+ getDefaultValue()};
+
+ <li>{@code minValue} defines the value returned by {@link
+ javax.management.openmbean.OpenMBeanParameterInfo#getMinValue() getMinValue()};
+
+ <li>{@code maxValue} defines the value returned by {@link
+ javax.management.openmbean.OpenMBeanParameterInfo#getMaxValue() getMaxValue()};
+
+ <li>{@code legalValues} defines the values returned by {@link
+ javax.management.openmbean.OpenMBeanParameterInfo#getLegalValues() getLegalValues()}.
+
+ </ul>
+
+ <p>For {@code defaultValue}, {@code minValue}, and {@code
+ maxValue}, the associated value must either be of the Java type
+ corresponding to {@code openType}, or be a string that can be
+ converted into that type. The conversion uses the static method
+ {@code valueOf(String)} if it finds one; otherwise a constructor
+ with a single {@code String} parameter if it finds one; otherwise
+ it fails.</p>
+
+ <p>For {@code legalValues}, the associated value must be either
+ an array or a {@code Set}, and the elements of the array or set
+ must be convertible as described for {@code defaultValue} etc.</p>
+
+ <p>The following conditions must be met for these fields:</p>
+
+ <ul>
+ <li>the values must be of the appropriate type, or be strings
+ that can be converted to the appropriate type as explained
+ above;
+
+ <li>if {@code legalValues} is present then neither {@code
+ minValue} nor {@code maxValue} must be present;
+
+ <li>if {@code defaultValue} is present then it must satisfy the
+ constraints defined by {@code legalValues}, {@code minValue}, or
+ {@code maxValue} when any of these is also present;
+
+ <li>if {@code minValue} and {@code maxValue} are both present
+ then {@code minValue} must not be greater than {@code maxValue}.
+ </ul>
+
+ @see <a href="{@docRoot}/../technotes/guides/jmx/">
+ Java SE 6 Platform documentation on JMX technology</a>,
+ in particular the
+ <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
+ JMX Specification, version 1.4</a>
+
+ @since 1.5
+
+</BODY>
+</HTML>