src/java.management/share/classes/javax/management/openmbean/package-info.java - master - githubmirror/panama-vector

src/java.management/share/classes/javax/management/openmbean/package-info.java
146 строк7 KB
Nizar Benalla
8332070: Convert package.html files in `java.management` to package-info.java
06 июн 2024, 10:27
06 июн 2024, 10:27c7d2841
/*
 * Copyright (c) 2001, 2024, 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.
 */

/**
 * <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 id="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="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
 *   JMX Specification, version 1.4</a>
 *
 * @since 1.5
 */
package javax.management.openmbean;