ojluni/src/main/java/javax/management/openmbean/package.html - platform/libcore - Git at Google

 <html>
 <head>
 <title>javax.management.openmbean package</title>
 <!--
 Copyright (c) 2001, 2011, Oracle and/or its affiliates. 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.  Oracle designates this
 particular file as subject to the "Classpath" exception as provided
 by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 or visit www.oracle.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 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>
	<html>
	<head>
	<title>javax.management.openmbean package</title>
	<!--
	Copyright (c) 2001, 2011, Oracle and/or its affiliates. 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. Oracle designates this
	particular file as subject to the "Classpath" exception as provided
	by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	or visit www.oracle.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 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>