/*
* @(#)file Descriptor.java
* @(#)author IBM Corp.
* @(#)version 1.23
* @(#)lastedit 04/02/10
*/
/*
* Copyright IBM Corp. 1999-2000. All rights reserved.
*
* The program is provided "as is" without any warranty express or implied,
* including the warranty of non-infringement and the implied warranties of
* merchantibility and fitness for a particular purpose. IBM will not be
* liable for any damages suffered by you or any third party claim against
* you regarding the Program.
*
* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
* This software is the proprietary information of Sun Microsystems, Inc.
* Use is subject to license terms.
*
* Copyright 2004 Sun Microsystems, Inc. Tous droits reserves.
* Ce logiciel est propriete de Sun Microsystems, Inc.
* Distribue par des licences qui en restreignent l'utilisation.
*
*/
package javax.management;
import javax.management.RuntimeOperationsException;
import javax.management.MBeanException;
import com.sun.jmx.trace.Trace;
/**
* This interface represents the behavioral metadata set for a JMX Element.
* For examples, a descriptor is part of the ModelMBeanInfo, ModelMBeanNotificationInfo, ModelMBeanAttributeInfo,
* ModelMBeanConstructorInfo, and ModelMBeanParameterInfo.
* <P>
* A descriptor consists of a collection of fields. Each field is in fieldname=fieldvalue format.
* <P>
* All field names and values are not predefined. New fields can be defined and added by any program.
* In the case of ModelMBean some fields have been predefined for consistency of implementation and support by the ModelMBeanInfo
* ModelMBean*Info, and ModelMBean classes.
*<P>
*
* @since 1.5
*/
public interface Descriptor extends java.io.Serializable, Cloneable
{
/**
* Returns the value for a specific fieldname.
*
* @param fieldName The field name in question; if not found, null is returned.
*
* @return Object Field value.
*
* @exception RuntimeOperationsException for illegal value for field name.
*
*/
public Object getFieldValue(String fieldName)
throws RuntimeOperationsException;
/**
* Sets the value for a specific fieldname. The field value will be validated before
* it is set. If it is not valid, then an exception will be thrown. This will modify
* an existing field or add a new field.
*
* @param fieldName The field name to be set. Cannot be null or empty.
* @param fieldValue The field value to be set for the field
* name. Can be null.
*
* @exception RuntimeOperationsException for illegal value for field name or field value.
*
*/
public void setField(String fieldName, Object fieldValue)
throws RuntimeOperationsException;
/**
* Returns all of the fields contained in this descriptor as a string array.
*
* @return String array of fields in the format <i>fieldName=fieldValue</i>
* If the value of a field is not a String, then the toString() method
* will be called on it and the returned value used as the value for
* the field in the returned array. Object values which are not Strings
* will be enclosed in parentheses. If the descriptor is empty, you will get
* an empty array.
*
* @see #setFields
*/
public String[] getFields() ;
/**
* Returns all the fields names in the descriptor.
*
* @return String array of fields names. If the descriptor is empty, you will get
* an empty array.
*
*/
public String[] getFieldNames() ;
/**
* Returns all the field values in the descriptor as an array of Objects. The
* returned values are in the same order as the fieldNames String array parameter.
*
* @param fieldNames String array of the names of the fields that the values
* should be returned for. If the array is empty then an empty array will be
* returned. If the array is 'null' then all values will be returned. If a field
* name in the array does not exist, then null is returned for the matching array
* element being returned.
*
* @return Object array of field values. If the descriptor is empty, you will get
* an empty array.
*
*/
public Object[] getFieldValues(String[] fieldNames) ;
/**
* Removes a field from the descriptor.
*
* @param fieldName String name of the field to be removed.
* If the field is not found no exception is thrown.
*/
public void removeField(String fieldName) ;
/**
* Sets all Fields in the list to the new value in with the same index
* in the fieldValue array. Array sizes must match.
* The field value will be validated before it is set.
* If it is not valid, then an exception will be thrown.
* If the arrays are empty, then no change will take effect.
*
* @param fieldNames String array of field names. The array and array elements cannot be null.
* @param fieldValues Object array of the corresponding field values. The array cannot be null.
* Elements of the array can be null.
*
* @exception RuntimeOperationsException for illegal value for field Names or field Values.
* Neither can be null. The array lengths must be equal.
* If the descriptor construction fails for any reason, this exception will be thrown.
*
* @see #getFields
*/
public void setFields(String[] fieldNames, Object[] fieldValues)
throws RuntimeOperationsException;
/**
* Returns a new Descriptor which is a duplicate of the Descriptor.
*
* @exception RuntimeOperationsException for illegal value for field Names or field Values.
* If the descriptor construction fails for any reason, this exception will be thrown.
*/
public Object clone() throws RuntimeOperationsException;
/**
* Returns true if all of the fields have legal values given their
* names.
*
* @return true if the values are legal.
*
* @exception RuntimeOperationsException If the validity checking fails for any reason, this exception will be thrown.
*/
public boolean isValid() throws RuntimeOperationsException;
}
|