001: /* JFox, the OpenSource J2EE Application Server
002: *
003: * Copyright (C) 2002 huihoo.org
004: * Distributable under GNU LGPL license
005: * See the GNU Lesser General Public License for more details.
006: */
007:
008: package javax.management;
009:
010: import java.io.Serializable;
011:
012: /**
013: * This interface represents the behavioral metadata set for a JMX Element.
014: * For examples, a descriptor is part of the ModelMBeanInfo, ModelMBeanNotificationInfo, ModelMBeanAttributeInfo,
015: * ModelMBeanConstructorInfo, and ModelMBeanParameterInfo.
016: * <P>
017: * A descriptor consists of a collection of fields. Each field is in fieldname=fieldvalue format.
018: * <P>
019: * All field names and values are not predefined. New fields can be defined and added by any program.
020: * In the case odf ModelMBean some fields have been predefined for consistency of implementation and support by the ModelMBeanInfo
021: * ModelMBean*Info, and ModelMBean classes.
022: *<P>
023: *
024: * @author <a href="mailto:young_yy@hotmail.org">Young Yang</a>
025: */
026:
027: public interface Descriptor extends Serializable {
028: /**
029: * Returns the value for a specific fieldname.
030: *
031: * @param fieldName The field name in question; if not found, null is returned.
032: *
033: * @return Object Field value.
034: *
035: * @exception RuntimeOperationsException for illegal value for field name.
036: *
037: */
038: public Object getFieldValue(String fieldName)
039: throws RuntimeOperationsException;
040:
041: /**
042: * Sets the value for a specific fieldname. The field value will be validated before
043: * it is set. If it is not valid, then an exception will be thrown. This will modify
044: * an existing field or add a new field.
045: *
046: * @param fieldName: The field name to be set. Cannot be null or empty.
047: * @param fieldValue: The field value to be set for the field name. Can be null.
048: *
049: * @exception RuntimeOperationsException for illegal value for field name or field value.
050: *
051: */
052: public void setField(String fieldName, Object fieldValue)
053: throws RuntimeOperationsException;
054:
055: /**
056: * Returns all of the fields contained in this descriptor as a string array.
057: *
058: * @return String array of fields in the format <i>fieldName=fieldValue</i>
059: * If the value of a field is not a String, then the toString() method
060: * will be called on it and the returned value used as the value for
061: * the field in the returned array. Object values which are not Strings
062: * will be enclosed in parens. If the descriptor is empty, you will get
063: * an empty array.
064: */
065: public String[] getFields();
066:
067: /**
068: * Returns all the fields names in the descriptor.
069: *
070: * @return String array of fields names. If the descriptor is empty, you will get
071: * an empty array.
072: *
073: */
074: public String[] getFieldNames();
075:
076: /**
077: * Returns all the field values in the descriptor as an array of Objects. The
078: * retuned values are in the same order as the fieldNames String array parameter.
079: *
080: * @param fieldNames String array of the names of the fields that the values
081: * should be returned for. If the array is empty then an empty array will be
082: * returned. If the array is 'null' then all values will be returned. If a field
083: * name in the array does not exist, then null is returned for the matching array
084: * element being returned.
085: *
086: * @return Object array of field values. If the descriptor is empty, you will get
087: * an empty array.
088: *
089: */
090: public Object[] getFieldValues(String[] fieldNames);
091:
092: /**
093: * Removes a field from the descriptor
094: *
095: * @param fieldName String name of the field to be removed.
096: * If the field is not found no exception is thrown.
097: */
098: public void removeField(String fieldName);
099:
100: /**
101: * Sets all Fields in the list to the new value in with the same index
102: * in the fieldValue array. Array sizes must match.
103: * The field value will be validated before it is set.
104: * If it is not valid, then an exception will be thrown.
105: * If the arrays are empty, then no change will take effect.
106: *
107: * @param fieldNames String array of field names. The array and array elements cannot be null.
108: * @param fieldValues Object array of the corresponding field values. The array cannot be null.
109: * Elements of the array can be null.
110: *
111: * @exception RuntimeOperationsException for illegal value for field URLName or field Values.
112: * Niether can be null. The array lengths must be equal.
113: * If the descriptor construction fails for any reason, this exception will be thrown.
114: *
115: */
116: public void setFields(String[] fieldNames, Object[] fieldValues)
117: throws RuntimeOperationsException;
118:
119: /**
120: * Returns a new Descriptor which is a duplicate of the Descriptor.
121: *
122: * @exception RuntimeOperationsException for illegal value for field URLName or field Values.
123: * If the descriptor construction fails for any reason, this exception will be thrown.
124: */
125: public Object clone() throws RuntimeOperationsException;
126:
127: /**
128: * Returns true if fieldValues are checked to be sure they are legal for the fieldNames.
129: *
130: * @exception RuntimeOperationsException If the validity checking fails for any reason, this exception will be thrown.
131: */
132: public boolean isValid() throws RuntimeOperationsException;
133:
134: }
|