001: /**
002: * The XMOJO Project 5
003: * Copyright © 2003 XMOJO.org. All rights reserved.
004:
005: * NO WARRANTY
006:
007: * BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
008: * THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
009: * OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
010: * PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
011: * OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
012: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
013: * TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE
014: * LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
015: * REPAIR OR CORRECTION.
016:
017: * IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
018: * ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
019: * THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
020: * GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
021: * USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
022: * DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
023: * PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE),
024: * EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
025: * SUCH DAMAGES.
026: **/package javax.management;
027:
028: import java.io.Serializable;
029:
030: /**
031: * This interface represents the behavioral metadata set for a JMX Element.
032: * For examples, a descriptor is part of the ModelMBeanInfo,
033: * ModelMBeanNotificationInfo, ModelMBeanAttributeInfo,
034: * ModelMBeanConstructorInfo, and ModelMBeanParameterInfo.
035: * <p>
036: * A descriptor consists of a collection of fields. Each field is in
037: * fieldname=fieldvalue format.
038: * <p>
039: * All field names and values are not predefined. New fields can be defined
040: * and added by any program. In the case of ModelMBean some fields have been
041: * predefined for consistency of implementation and support by the
042: * ModelMBeanInfo ModelMBean*Info, and ModelMBean classes.
043: */
044: public interface Descriptor extends Serializable {
045: /**
046: * Returns the value for a specific fieldname.
047: *
048: * @param fieldName The field name in question; if not found, null is returned.
049: *
050: * @return Object Field value.
051: *
052: * @exception RuntimeOperationsException for illegal value for field name.
053: *
054: */
055: public Object getFieldValue(String fieldName)
056: throws RuntimeOperationsException;
057:
058: /**
059: * Sets the value for a specific fieldname. The field value will be
060: * validated before it is set. If it is not valid, then an exception
061: * will be thrown. This will modify an existing field or add a new field.
062: *
063: * @param String fieldName: The field name to be set. Cannot be null or empty.
064: *
065: * @param Object fieldValue: The field value to be set for the field name.
066: * Can be null.
067: *
068: * @exception RuntimeOperationsException for illegal value for field name
069: * or field value.
070: */
071: public void setField(String fieldName, Object fieldValue)
072: throws RuntimeOperationsException;
073:
074: /**
075: * Returns all of the fields contained in this descriptor as a string array.
076: *
077: * @return String array of fields in the format <i>fieldName=fieldValue</i>.
078: * If the value of a field is not a String, then the toString()
079: * method will be called on it and the returned value used as
080: * the value for the field in the returned array. Object values
081: * which are not Strings will be enclosed in parens. If the
082: * descriptor is empty, you will get an empty array.
083: */
084: public String[] getFields();
085:
086: /**
087: * Returns all the fields names in the descriptor.
088: *
089: * @return String array of fields names. If the descriptor is empty,
090: * you will get an empty array.
091: */
092: public String[] getFieldNames();
093:
094: /**
095: * Returns all the field values in the descriptor as an array of
096: * Objects. The retuned values are in the same order as the fieldNames
097: * String array parameter.
098: *
099: * @param fieldNames String array of the names of the fields that the
100: * values should be returned for. If the array is empty
101: * then an empty array will be returned. If the array is
102: * 'null' then all values will be returned. If a field
103: * name in the array does not exist, then null is returned
104: * for the matching array element being returned.
105: *
106: * @return Object array of field values. If the descriptor is empty,
107: * you will get an empty array.
108: */
109: public Object[] getFieldValues(String[] fieldNames);
110:
111: /**
112: * Removes a field from the descriptor.
113: *
114: * @param fieldName String name of the field to be removed. If the field
115: * is not found no exception is thrown.
116: */
117: public void removeField(String fieldName);
118:
119: /**
120: * Sets all Fields in the list to the new value in with the same index in
121: * the fieldValue array. Array sizes must match. The field value will be
122: * validated before it is set. If it is not valid, then an exception will
123: * be thrown. If the arrays are empty, then no change will take effect.
124: *
125: * @param fieldNames String array of field names. The array and array
126: * elements cannot be null.
127: *
128: * @param fieldValues Object array of the corresponding field values.
129: * The array cannot be null. Elements of the array can be null.
130: *
131: * @exception RuntimeOperationsException for illegal value for field Names
132: * or field Values. Neither can be null. The array lengths
133: * must be equal. If the descriptor construction fails for
134: * any reason, this exception will be thrown.
135: */
136: public void setFields(String[] fieldNames, Object[] fieldValues)
137: throws RuntimeOperationsException;
138:
139: /**
140: * Returns a new Descriptor which is a duplicate of the Descriptor.
141: *
142: * @return This returns a duplicate of the Descriptor.
143: *
144: * @exception RuntimeOperationsException for illegal value for field Names
145: * or field Values. If the descriptor construction fails for
146: * any reason, this exception will be thrown.
147: */
148: public Object clone() throws RuntimeOperationsException;
149:
150: /**
151: * Returns true if fieldValues are checked to be sure they are legal for
152: * the fieldNames.
153: *
154: * @return It returns true if the fieldValues checked are legal otherwise false
155: *
156: * @exception RuntimeOperationsException If the validity checking fails
157: * for any reason, this exception will be thrown.
158: */
159: public boolean isValid() throws RuntimeOperationsException;
160: }
|