FileDocCategorySizeDatePackage
DescriptorSupport.javaAPI DocJava SE 5 API46328Fri Aug 26 14:57:34 BST 2005javax.management.modelmbean

DescriptorSupport

public class DescriptorSupport extends Object implements Descriptor
This class represents the metadata set for a ModelMBean element. A descriptor is part of the ModelMBeanInfo, ModelMBeanNotificationInfo, ModelMBeanAttributeInfo, ModelMBeanConstructorInfo, and ModelMBeanParameterInfo.

A descriptor consists of a collection of fields. Each field is in fieldname=fieldvalue format. Field names are not case sensitive, case will be preserved on field values.

All field names and values are not predefined. New fields can be defined and added by any program. Some fields have been predefined for consistency of implementation and support by the ModelMBeanInfo, ModelMBeanAttributeInfo, ModelMBeanConstructorInfo, ModelMBeanNotificationInfo, ModelMBeanOperationInfo and ModelMBean classes.

since
1.5

Fields Summary
private static final long
oldSerialVersionUID
private static final long
newSerialVersionUID
private static final ObjectStreamField[]
oldSerialPersistentFields
private static final ObjectStreamField[]
newSerialPersistentFields
private static final long
serialVersionUID
private static final ObjectStreamField[]
serialPersistentFields
private static final String
serialForm
private transient Map
descriptorMap
private static final int
DEFAULT_SIZE
private static final String
currClass
private static final String[]
entities
private static final Map
entityToCharMap
private static final String[]
charToEntityMap
Constructors Summary
public DescriptorSupport()
Descriptor default constructor. Default initial descriptor size is 20. It will grow as needed.
Note that the created empty descriptor is not a valid descriptor (the method {@link #isValid isValid} returns false)



                                          
     
    
	if (tracing())
	    {
		trace("Descriptor()","Constructor");
	    }
	descriptorMap = new HashMap(DEFAULT_SIZE);
public DescriptorSupport(int initNumFields)
Descriptor constructor. Takes as parameter the initial capacity of the Map that stores the descriptor fields. Capacity will grow as needed.
Note that the created empty descriptor is not a valid descriptor (the method {@link #isValid isValid} returns false).

param
initNumFields The initial capacity of the Map that stores the descriptor fields.
exception
RuntimeOperationsException for illegal value for initNumFields (<= 0)
exception
MBeanException Wraps a distributed communication Exception.

	if (tracing()) {
	    trace("Descriptor(maxNumFields = " + initNumFields + ")",
		  "Constructor");
	}
	if (initNumFields <= 0) {
	    if (tracing()) {
		trace("Descriptor(maxNumFields)",
		      "Illegal arguments: initNumFields <= 0");
	    }
	    final String msg =
		"Descriptor field limit invalid: " + initNumFields;
	    final RuntimeException iae = new IllegalArgumentException(msg);
	    throw new RuntimeOperationsException(iae, msg);
	}
	descriptorMap = new HashMap(initNumFields);
public DescriptorSupport(DescriptorSupport inDescr)
Descriptor constructor taking a Descriptor as parameter. Creates a new descriptor initialized to the values of the descriptor passed in parameter.

param
inDescr the descriptor to be used to initialize the constructed descriptor. If it is null or contains no descriptor fields, an empty Descriptor will be created.

	if (tracing()) {
	    trace("Descriptor(Descriptor)","Constructor");
	}
	if (inDescr == null) {
	    descriptorMap = new HashMap(DEFAULT_SIZE);
	} else {
	    descriptorMap = new HashMap(inDescr.descriptorMap);
	}
public DescriptorSupport(String inStr)

Descriptor constructor taking an XML String.

The format of the XML string is not defined, but an implementation must ensure that the string returned by {@link #toXMLString() toXMLString()} on an existing descriptor can be used to instantiate an equivalent descriptor using this constructor.

In this implementation, all field values will be created as Strings. If the field values are not Strings, the programmer will have to reset or convert these fields correctly.

param
inStr An XML-formatted string used to populate this Descriptor. The format is not defined, but any implementation must ensure that the string returned by method {@link #toXMLString toXMLString} on an existing descriptor can be used to instantiate an equivalent descriptor when instantiated using this constructor.
exception
RuntimeOperationsException If the String inStr passed in parameter is null
exception
XMLParseException XML parsing problem while parsing the input String
exception
MBeanException Wraps a distributed communication Exception.

	/* parse an XML-formatted string and populate internal
	 * structure with it */
	if (tracing()) {
	    trace("Descriptor(String ='" + inStr + "')","Constructor");
	}
	if (inStr == null) {
	    if (tracing()) {
		trace("Descriptor(String = null)","Illegal arguments");
	    }
	    final String msg = "String in parameter is null";
	    final RuntimeException iae = new IllegalArgumentException(msg);
	    throw new RuntimeOperationsException(iae, msg);
	}

	final String lowerInStr = inStr.toLowerCase();
	if (!lowerInStr.startsWith("<descriptor>")
	    || !lowerInStr.endsWith("</descriptor>")) {
	    throw new XMLParseException("No <descriptor>, </descriptor> pair");
	}

	// parse xmlstring into structures
	descriptorMap = new HashMap(DEFAULT_SIZE);
	// create dummy descriptor: should have same size
	// as number of fields in xmlstring
	// loop through structures and put them in descriptor

	StringTokenizer st = new StringTokenizer(inStr, "<> \t\n\r\f");

	boolean inFld = false;
	boolean inDesc = false;
	String fieldName = null;
	String fieldValue = null;


	while (st.hasMoreTokens()) {  // loop through tokens
	    String tok = st.nextToken();

	    if (tok.equalsIgnoreCase("FIELD")) {
		inFld = true;
	    } else if (tok.equalsIgnoreCase("/FIELD")) {
		if ((fieldName != null) && (fieldValue != null)) {
		    fieldName =
			fieldName.substring(fieldName.indexOf('"") + 1,
					    fieldName.lastIndexOf('""));
		    final Object fieldValueObject =
			parseQuotedFieldValue(fieldValue);
		    setField(fieldName, fieldValueObject);
		}
		fieldName = null;
		fieldValue = null;
		inFld = false;
	    } else if (tok.equalsIgnoreCase("DESCRIPTOR")) {
		inDesc = true;
	    } else if (tok.equalsIgnoreCase("/DESCRIPTOR")) {
		inDesc = false;
		fieldName = null;
		fieldValue = null;
		inFld = false;
	    } else if (inFld && inDesc) {
		// want kw=value, eg, name="myname" value="myvalue"
		int eq_separator = tok.indexOf("=");
		if (eq_separator > 0) {
		    String kwPart = tok.substring(0,eq_separator);
		    String valPart = tok.substring(eq_separator+1);
		    if (kwPart.equalsIgnoreCase("NAME"))
			fieldName = valPart;
		    else if (kwPart.equalsIgnoreCase("VALUE"))
			fieldValue = valPart;
		    else {  // xml parse exception
			final String msg =
			    "Expected `name' or `value', got `" + tok + "'";
			throw new XMLParseException(msg);
		    }
		} else { // xml parse exception
		    final String msg =
			"Expected `keyword=value', got `" + tok + "'";
		    throw new XMLParseException(msg);
		}
	    }
	}  // while tokens

	if (tracing()) {
	    trace("Descriptor(XMLString)","Exit");
	}
public DescriptorSupport(String[] fieldNames, Object[] fieldValues)
Constructor taking field names and field values. The array and array elements cannot be null.

param
fieldNames String array of field names. No elements of this array can be null.
param
fieldValues Object array of the corresponding field values. Elements of the array can be null. The fieldValue must be valid for the fieldName (as defined in method {@link #isValid isValid})

Note: array sizes of parameters should match. If both arrays are null or empty, then an empty descriptor is created.

exception
RuntimeOperationsException for illegal value for field Names or field Values. The array lengths must be equal. If the descriptor construction fails for any reason, this exception will be thrown.

	if (tracing()) {
	    trace("Descriptor(fieldNames, fieldObjects)","Constructor");
	}

	if ((fieldNames == null) || (fieldValues == null) ||
	    (fieldNames.length != fieldValues.length)) {
	    if (tracing()) {
		trace("Descriptor(String[],Object[])","Illegal arguments");
	    }

	    final String msg =
		"Null or invalid fieldNames or fieldValues";
	    final RuntimeException iae = new IllegalArgumentException(msg);
	    throw new RuntimeOperationsException(iae, msg);
	}

	/* populate internal structure with fields */
	descriptorMap = new HashMap(fieldNames.length);
	// a field value can be "null"

	for (int i=0; i < fieldNames.length; i++) {
	    // setField will throw an exception if a fieldName is be null.
	    // the fieldName and fieldValue will be validated in setField.
	    setField(fieldNames[i], fieldValues[i]);
	}
	if (tracing()) {
	    trace("Descriptor(fieldNames, fieldObjects)","Exit");
	}
public DescriptorSupport(String[] fields)
Constructor taking fields in the fieldName=fieldValue format.

param
fields String array with each element containing a field name and value. If this array is null or empty, then the default constructor will be executed. Null strings or empty strings will be ignored.

All field values should be Strings. If the field values are not Strings, the programmer will have to reset or convert these fields correctly.

Note: Each string should be of the form fieldName=fieldValue.

exception
RuntimeOperationsException for illegal value for field Names or field Values. The field must contain an "=". "=fieldValue", "fieldName", and "fieldValue" are illegal. FieldName cannot be null. "fieldName=" will cause the value to be null. If the descriptor construction fails for any reason, this exception will be thrown.

	if (tracing()) {
	    trace("Descriptor(fields)","Constructor");
	}
	if (( fields == null ) || ( fields.length == 0)) {
	    descriptorMap = new HashMap(DEFAULT_SIZE);
	    return;
	}

	descriptorMap = new HashMap(fields.length);

	for (int i=0; i < fields.length; i++) {
	    if ((fields[i] == null) || (fields[i].equals(""))) {
		continue;
	    }
	    int eq_separator = fields[i].indexOf("=");
	    if (eq_separator < 0) {
		// illegal if no = or is first character
		if (tracing()) {
		    trace("Descriptor(String[])",
			  "Illegal arguments: field does not have '=' " +
			  "as a name and value separator");
		}
		final String msg = "Field in invalid format: no equals sign";
		final RuntimeException iae = new IllegalArgumentException(msg);
		throw new RuntimeOperationsException(iae, msg);
	    }

	    String fieldName = fields[i].substring(0,eq_separator);
	    String fieldValue = null;
	    if (eq_separator < fields[i].length()) {
		// = is not in last character
		fieldValue = fields[i].substring(eq_separator+1);
	    }

	    if (fieldName.equals("")) {
		if (tracing()) {
		    trace("Descriptor(String[])",
			  "Illegal arguments: fieldName is empty");
		}

		final String msg = "Field in invalid format: no fieldName";
		final RuntimeException iae = new IllegalArgumentException(msg);
		throw new RuntimeOperationsException(iae, msg);
	    }

	    setField(fieldName,fieldValue);
	}
	if (tracing()) {
	    trace("Descriptor(fields)","Exit");
	}
Methods Summary
public synchronized java.lang.Objectclone()
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.

	if (tracing()) {
	    trace("Descriptor.clone()","Executed");
	}
	return(new DescriptorSupport(this));
public synchronized java.lang.String[]getFieldNames()
Returns all the fields names in the descriptor. The order is not the order in which the fields were set.

return
String array of fields names. If the descriptor is empty, you will get an empty array.

	if (tracing()) {
	    trace("getFieldNames()","Entry");
	}
	int numberOfEntries = descriptorMap.size();

	String[] responseFields = new String[numberOfEntries];
	Set returnedSet = descriptorMap.entrySet();

	int i = 0;

	if (tracing()) {
	    trace("getFieldNames()","Returning " + numberOfEntries + " fields");
	}

	for (Iterator iter = returnedSet.iterator(); iter.hasNext(); i++) {
	    Map.Entry currElement = (Map.Entry) iter.next();

	    if (( currElement == null ) || (currElement.getKey() == null)) {
		if (tracing()) {
		    trace("getFieldNames()","Field is null");
		}
	    } else {
		responseFields[i] = currElement.getKey().toString();
	    }
	}

	if (tracing()) {
	    trace("getFieldNames()","Exit");
	}

	return responseFields;
public synchronized java.lang.ObjectgetFieldValue(java.lang.String inFieldName)
Returns the value for a specific fieldname.

param
inFieldName The field name in question; if not found, null is returned.
return
An Object representing the field value
exception
RuntimeOperationsException for illegal value (null or empty string) for field Names.


	if ((inFieldName == null) || (inFieldName.equals(""))) {
	    if (tracing()) {
		trace("getField()","Illegal arguments: null field name.");
	    }
	    final String msg = "Fieldname requested is null";
	    final RuntimeException iae = new IllegalArgumentException(msg);
	    throw new RuntimeOperationsException(iae, msg);
	}
	Object retValue = descriptorMap.get(new CaseIgnoreString(inFieldName));
	if (tracing()) {
	    trace("getField(" + inFieldName + ")",
		  "Returns '" + retValue + "'");
	}
	return(retValue);
public synchronized java.lang.Object[]getFieldValues(java.lang.String[] fieldNames)
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. The order is not the order in which the fields were set.
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.

	if (tracing()) {
	    trace("getFieldValues(fieldNames)","Entry");
	}
	// if fieldNames == null return all values
	// if fieldNames is String[0] return no values

	int numberOfEntries = descriptorMap.size();

	/* Following test is somewhat inconsistent but is called for
	   by the @return clause above. */
	if (numberOfEntries == 0)
	    return new Object[0];

	Object[] responseFields;
	if (fieldNames != null) {
	    responseFields = new Object[fieldNames.length];
	    // room for selected
	} else {
	    responseFields = new Object[numberOfEntries];
	    // room for all
	}

	int i = 0;

	if (tracing()) {
	    trace("getFieldValues()",
		  "Returning " + numberOfEntries + " fields");
	}

	if (fieldNames == null) {
	    for (Iterator iter = descriptorMap.values().iterator();
		 iter.hasNext(); i++)
		responseFields[i] = iter.next();
	} else {
	    for (i=0; i < fieldNames.length; i++) {
		if ((fieldNames[i] == null) || (fieldNames[i].equals(""))) {
		    responseFields[i] = null;
		} else {
		    responseFields[i] = getFieldValue(fieldNames[i]);
		}
	    }
	}


	if (tracing()) {
	    trace("getFieldValues()","Exit");
	}

	return responseFields;
public synchronized java.lang.String[]getFields()
Returns all the fields in the descriptor. The order is not the order in which the fields were set.

return
String array of fields in the format fieldName=fieldValue. If there are no fields in the descriptor, then an empty String array is returned. If a fieldValue is not a String then the toString() method is called on it and its returned value is used as the value for the field enclosed in parenthesis.
see
#setFields

	if (tracing()) {
	    trace("getFields()","Entry");
	}
	int numberOfEntries = descriptorMap.size();

	String[] responseFields = new String[numberOfEntries];
	Set returnedSet = descriptorMap.entrySet();

	int i = 0;
	Object currValue = null;
	Map.Entry currElement = null;

	if (tracing()) {
	    trace("getFields()","Returning " + numberOfEntries + " fields");
	}
	for (Iterator iter = returnedSet.iterator(); iter.hasNext(); i++) {
	    currElement = (Map.Entry) iter.next();

	    if (currElement == null) {
		if (tracing()) {
		    trace("getFields()","Element is null");
		}
	    } else {
		currValue = currElement.getValue();
		if (currValue == null) {
		    responseFields[i] = currElement.getKey() + "=";
		} else {
		    if (currValue instanceof java.lang.String) {
			responseFields[i] =
			    currElement.getKey() + "=" + currValue.toString();
		    } else {
			responseFields[i] =
			    currElement.getKey() + "=(" +
			    currValue.toString() + ")";
		    }
		}
	    }
	}

	if (tracing()) {
	    trace("getFields()","Exit");
	}

	return responseFields;
private static booleanisMagic(char c)


     
	char maxChar = 0;
	for (int i = 0; i < entities.length; i++) {
	    final char c = entities[i].charAt(0);
	    if (c > maxChar)
		maxChar = c;
	}
	charToEntityMap = new String[maxChar + 1];
	for (int i = 0; i < entities.length; i++) {
	    final char c = entities[i].charAt(0);
	    final String entity = entities[i].substring(1);
	    charToEntityMap[c] = entity;
	    entityToCharMap.put(entity, new Character(c));
	}
    
	return (c < charToEntityMap.length && charToEntityMap[c] != null);
public synchronized booleanisValid()
Returns true if all of the fields have legal values given their names.

This implementation does not support interoperating with a directory or lookup service. Thus, conforming to the specification, no checking is done on the "export" field.

Otherwise this implementation returns false if:

  • name and descriptorType fieldNames are not defined, or null, or empty, or not String
  • class, role, getMethod, setMethod fieldNames, if defined, are null or not String
  • persistPeriod, currencyTimeLimit, lastUpdatedTimeStamp, lastReturnedTimeStamp if defined, are null, or not a Numeric String or not a Numeric Value >= -1
  • log fieldName, if defined, is null, or not a Boolean or not a String with value "t", "f", "true", "false". These String values must not be case sensitive.
  • visibility fieldName, if defined, is null, or not a Numeric String or a not Numeric Value >= 1 and <= 4
  • severity fieldName, if defined, is null, or not a Numeric String or not a Numeric Value >= 0 and <= 6
  • persistPolicy fieldName, if defined, is null, or not a following String :
    "OnUpdate", "OnTimer", "NoMoreOftenThan", "Always", "Never". These String values must not be case sensitive.

exception
RuntimeOperationsException If the validity checking fails for any reason, this exception will be thrown.

	if (tracing()) {
	    trace("Descriptor.isValid()","Executed");
	}
	// verify that the descriptor is valid, by iterating over each field...

	Set returnedSet = descriptorMap.entrySet();

	if (returnedSet == null) {   // null descriptor, not valid
	    if (tracing()) {
		trace("Descriptor.isValid()","returns false (null set)");
	    }
	    return false;
	}
	// must have a name and descriptor type field
	String thisName = (String)(this.getFieldValue("name"));
	String thisDescType = (String)(getFieldValue("descriptorType"));

	if ((thisName == null) || (thisDescType == null) ||
	    (thisName.equals("")) || (thisDescType.equals(""))) {
	    return false;
	}

	// According to the descriptor type we validate the fields contained

	for (Iterator iter = returnedSet.iterator(); iter.hasNext();) {
	    Map.Entry currElement = (Map.Entry) iter.next();

	    if (currElement != null) {
		if (currElement.getValue() != null) {
		    // validate the field valued...
		    if (validateField((currElement.getKey()).toString(),
				      (currElement.getValue()).toString())) {
			continue;
		    } else {
			if (tracing()) {
			    trace("isValid()",
				  "Field " + currElement.getKey() + "=" +
				  currElement.getValue() + " is not valid");
			}
			return false;
		    }
		}
	    }
	}

	// fell through, all fields OK

	if (tracing()) {
	    trace("Descriptor.isValid()","returns true");
	}

	return true;
private static java.lang.StringmakeFieldValue(java.lang.Object value)
Make the string that will go inside "..." for a value that is not a plain String.

throws
RuntimeOperationsException if the value cannot be encoded.

	if (value == null)
	    return "(null)";

	Class valueClass = value.getClass();
	try {
	    valueClass.getConstructor(new Class[] {String.class});
	} catch (NoSuchMethodException e) {
	    final String msg =
		"Class " + valueClass + " does not have a public " +
		"constructor with a single string arg";
	    final RuntimeException iae = new IllegalArgumentException(msg);
	    throw new RuntimeOperationsException(iae,
						 "Cannot make XML descriptor");
	} catch (SecurityException e) {
	    // OK: we'll pretend the constructor is there
	    // too bad if it's not: we'll find out when we try to
	    // reconstruct the DescriptorSupport
	}

	final String quotedValueString = quote(value.toString());
	
	return "(" + valueClass.getName() + "/" + quotedValueString + ")";
private static java.lang.ObjectparseQuotedFieldValue(java.lang.String s)

	s = unquote(s);
	if (s.equalsIgnoreCase("(null)"))
	    return null;
	if (!s.startsWith("(") || !s.endsWith(")"))
	    return s;
	final int slash = s.indexOf('/");
	if (slash < 0) {
	    // compatibility: old code didn't include class name
	    return s.substring(1, s.length() - 1);
	}
	final String className = s.substring(1, slash);
	final Constructor constr;
	try {
	    final ClassLoader contextClassLoader =
		Thread.currentThread().getContextClassLoader();
            if (contextClassLoader == null) {
                SecurityManager sm = System.getSecurityManager();
                if (sm != null) {
                    sm.checkPackageAccess(className);
                }
            }
	    final Class c =
		Class.forName(className, false, contextClassLoader);
	    constr = c.getConstructor(new Class[] {String.class});
	} catch (Exception e) {
	    throw new XMLParseException(e,
					"Cannot parse value: <" + s + ">");
	}
	final String arg = s.substring(slash + 1, s.length() - 1);
	try {
	    return constr.newInstance(new Object[] {arg});
	} catch (Exception e) {
	    final String msg =
		"Cannot construct instance of " + className +
		" with arg: <" + s + ">";
	    throw new XMLParseException(e, msg);
	}
private static java.lang.Stringquote(java.lang.String s)

	boolean found = false;
	for (int i = 0; i < s.length(); i++) {
	    if (isMagic(s.charAt(i))) {
		found = true;
		break;
	    }
	}
	if (!found)
	    return s;
	StringBuffer buf = new StringBuffer();
	for (int i = 0; i < s.length(); i++) {
	    char c = s.charAt(i);
	    if (isMagic(c))
		buf.append(charToEntityMap[c]);
	    else
		buf.append(c);
	}
	return buf.toString();
private voidreadObject(java.io.ObjectInputStream in)
Deserializes a {@link DescriptorSupport} from an {@link ObjectInputStream}.

	ObjectInputStream.GetField fields = in.readFields();
	Map descriptor = (Map) fields.get("descriptor", null);
	descriptorMap = new HashMap();
	for (Iterator it = descriptor.entrySet().iterator(); it.hasNext(); ) {
	    Map.Entry entry = (Map.Entry) it.next();
	    setField((String) entry.getKey(), entry.getValue());
	}
public synchronized voidremoveField(java.lang.String fieldName)
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.

	if ((fieldName == null) || (fieldName.equals(""))) {
	    return;
	}

	descriptorMap.remove(new CaseIgnoreString(fieldName));
public synchronized voidsetField(java.lang.String inFieldName, java.lang.Object fieldValue)
Sets the string value for a specific fieldname. The value must be valid for the field (as defined in method {@link #isValid isValid}). If the field does not exist, it is added at the end of the Descriptor. If it does exist, the value is replaced.

param
inFieldName The field name to be set. Must not be null or empty string.
param
fieldValue The field value to be set for the field name. Can be null or empty string.
exception
RuntimeOperationsException for illegal value for field Names.


	// field name cannot be null or empty
	if ((inFieldName == null) || (inFieldName.equals(""))) {
	    if (tracing()) {
		trace("setField(String,String)",
		      "Illegal arguments: null or empty field name");
	    }

	    final String msg = "Fieldname to be set is null or empty";
	    final RuntimeException iae = new IllegalArgumentException(msg);
	    throw new RuntimeOperationsException(iae, msg);
	}

	if (!validateField(inFieldName, fieldValue)) {
	    if (tracing()) {
		trace("setField(fieldName,FieldValue)","Illegal arguments");
	    }

	    final String msg =
		"Field value invalid: " + inFieldName + "=" + fieldValue;
	    final RuntimeException iae = new IllegalArgumentException(msg);
	    throw new RuntimeOperationsException(iae, msg);
	}

	if (tracing()) {
	    if (fieldValue != null) {
		trace("setField(fieldName, fieldValue)",
		      "Entry: setting '" + inFieldName + "' to '" +
		      fieldValue + "'.");
	    }
	}

	descriptorMap.put(new CaseIgnoreString(inFieldName), fieldValue);
public synchronized voidsetFields(java.lang.String[] fieldNames, java.lang.Object[] fieldValues)
Sets all Fields in the list to the new value with the same index in the fieldValue array. Array sizes must match. The field value will be validated before it is set (by calling the method {@link #isValid isValid}). 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.
see
#getFields


	if (tracing()) {
	    trace("setFields(fieldNames, ObjectValues)","Entry");
	}


	if ((fieldNames == null) || (fieldValues == null) ||
	    (fieldNames.length != fieldValues.length)) {
	    if (tracing()) {
		trace("Descriptor.setFields(String[],Object[])",
		      "Illegal arguments");
	    }

	    final String msg = "FieldNames and FieldValues are null or invalid";
	    final RuntimeException iae = new IllegalArgumentException(msg);
	    throw new RuntimeOperationsException(iae, msg);
	}

	for (int i=0; i < fieldNames.length; i++) {
	    if (( fieldNames[i] == null) || (fieldNames[i].equals(""))) {
		if (tracing()) {
		    trace("Descriptor.setFields(String[],Object[])",
			  "Null field name encountered at " + i + " element");
		}

		final String msg = "FieldNames is null or invalid";
		final RuntimeException iae = new IllegalArgumentException(msg);
		throw new RuntimeOperationsException(iae, msg);
	    }
	    setField(fieldNames[i], fieldValues[i]);
	}
	if (tracing()) {
	    trace("Descriptor.setFields(fieldNames, fieldObjects)","Exit");
	}
private longtoNumeric(java.lang.String inStr)

	long result = -2;
	try {
	    result = java.lang.Long.parseLong(inStr);
	} catch (Exception e) {
	    return -2;
	}
	return result;
public synchronized java.lang.StringtoString()
Returns a human readable string representing the descriptor. The string will be in the format of "fieldName=fieldValue,fieldName2=fieldValue2,..."
If there are no fields in the descriptor, then an empty String is returned.
If a fieldValue is an object then the toString() method is called on it and its returned value is used as the value for the field enclosed in parenthesis.

exception
RuntimeOperationsException for illegal value for field Names or field Values. If the descriptor string fails for any reason, this exception will be thrown.

	if (tracing()) {
	    trace("Descriptor.toString()","Entry");
	}

	String respStr = "";
	String[] fields = getFields();

	if (tracing()) {
	    trace("Descriptor.toString()",
		  "Printing " + fields.length + " fields");
	}

	if ((fields == null) || (fields.length == 0)) {
	    if (tracing()) {
		trace("Descriptor.toString()","Empty Descriptor");
	    }
	    return respStr;
	}

	for (int i=0; i < fields.length; i++) {
	    if (i == (fields.length - 1)) {
		respStr = respStr.concat(fields[i]);
	    } else {
		respStr = respStr.concat(fields[i] + ", ");
	    }
	}

	if (tracing()) {
	    trace("Descriptor.toString()","Exit returning " + respStr);
	}

	return respStr;
public synchronized java.lang.StringtoXMLString()

Returns an XML String representing the descriptor.

The format is not defined, but an implementation must ensure that the string returned by this method can be used to build an equivalent descriptor when instantiated using the constructor {@link #DescriptorSupport(String) DescriptorSupport(String inStr)}.

Fields which are not String objects will have toString() called on them to create the value. The value will be enclosed in parentheses. It is not guaranteed that you can reconstruct these objects unless they have been specifically set up to support toString() in a meaningful format and have a matching constructor that accepts a String in the same format.

If the descriptor is empty the following String is returned: <Descriptor></Descriptor>

return
the XML string.
exception
RuntimeOperationsException for illegal value for field Names or field Values. If the XML formated string construction fails for any reason, this exception will be thrown.

	StringBuffer buf = new StringBuffer("<Descriptor>");
	Set returnedSet = descriptorMap.entrySet();
	for (Iterator iter = returnedSet.iterator(); iter.hasNext(); ) {
	    final Map.Entry currElement = (Map.Entry) iter.next();
	    final String name = currElement.getKey().toString();
	    Object value = currElement.getValue();
	    String valueString = null;
	    /* Set valueString to non-null iff this is a string that
	       cannot be confused with the encoding of an object.  If it
	       could be so confused (surrounded by parentheses) then we
	       call makeFieldValue as for any non-String object and end
	       up with an encoding like "(java.lang.String/(thing))".  */
	    if (value instanceof String) {
		final String svalue = (String) value;
		if (!svalue.startsWith("(") || !svalue.endsWith(")"))
		    valueString = quote(svalue);
	    }
	    if (valueString == null)
		valueString = makeFieldValue(value);
	    buf.append("<field name=\"").append(name).append("\" value=\"")
		.append(valueString).append("\"></field>");
	}
	buf.append("</Descriptor>");
	return buf.toString();
private voidtrace(java.lang.String inClass, java.lang.String inMethod, java.lang.String inText)

	Trace.send(Trace.LEVEL_TRACE, Trace.INFO_MODELMBEAN, inClass,
		   inMethod,
		   Integer.toHexString(this.hashCode()) + " " + inText);
private voidtrace(java.lang.String inMethod, java.lang.String inText)

	trace(currClass, inMethod, inText);
private booleantracing()

	return Trace.isSelected(Trace.LEVEL_TRACE, Trace.INFO_MODELMBEAN);
private static java.lang.Stringunquote(java.lang.String s)

	if (!s.startsWith("\"") || !s.endsWith("\""))
	    throw new XMLParseException("Value must be quoted: <" + s + ">");
	StringBuffer buf = new StringBuffer();
	final int len = s.length() - 1;
	for (int i = 1; i < len; i++) {
	    final char c = s.charAt(i);
	    final int semi;
	    final Character quoted;
	    if (c == '&"
		&& (semi = s.indexOf(';", i + 1)) >= 0
		&& ((quoted =
		    (Character) entityToCharMap.get(s.substring(i, semi+1)))
		    != null)) {
		buf.append(quoted);
		i = semi;
	    } else
		buf.append(c);
	}
	return buf.toString();
private booleanvalidateField(java.lang.String fldName, java.lang.Object fldValue)

	if ((fldName == null) || (fldName.equals("")))
	    return false;
	String SfldValue = "";
	boolean isAString = false;
	if ((fldValue != null) && (fldValue instanceof java.lang.String)) {
	    SfldValue = (String) fldValue;
	    isAString = true;
	}

	boolean nameOrDescriptorType =
	    (fldName.equalsIgnoreCase("Name") ||
	     fldName.equalsIgnoreCase("DescriptorType"));
	if (nameOrDescriptorType ||
	    fldName.equalsIgnoreCase("SetMethod") ||
	    fldName.equalsIgnoreCase("GetMethod") ||
	    fldName.equalsIgnoreCase("Role") ||
	    fldName.equalsIgnoreCase("Class")) {
	    if (fldValue == null || !isAString)
		return false;
	    if (nameOrDescriptorType && SfldValue.equals(""))
		return false;
	    return true;
	} else if (fldName.equalsIgnoreCase("visibility")) {
	    long v;
	    if ((fldValue != null) && (isAString)) {
		v = toNumeric(SfldValue);
	    } else if (fldValue instanceof java.lang.Integer) {
		v = ((Integer)fldValue).intValue();
	    } else return false;

	    if (v >= 1 &&  v <= 4)
		return true;
	    else
		return false;
	} else if (fldName.equalsIgnoreCase("severity")) {

	    long v;
	    if ((fldValue != null) && (isAString)) {
		v = toNumeric(SfldValue);
	    } else if (fldValue instanceof java.lang.Integer) {
		v = ((Integer)fldValue).intValue();
	    } else return false;

	    return (v >= 0 && v <= 6);
	} else if (fldName.equalsIgnoreCase("PersistPolicy")) {
	    return (((fldValue != null) && (isAString)) &&
		    ( SfldValue.equalsIgnoreCase("OnUpdate") ||
		      SfldValue.equalsIgnoreCase("OnTimer") ||
		      SfldValue.equalsIgnoreCase("NoMoreOftenThan") ||
		      SfldValue.equalsIgnoreCase("Always") ||
		      SfldValue.equalsIgnoreCase("Never") ));
	} else if (fldName.equalsIgnoreCase("PersistPeriod") ||
		   fldName.equalsIgnoreCase("CurrencyTimeLimit") ||
		   fldName.equalsIgnoreCase("LastUpdatedTimeStamp") ||
		   fldName.equalsIgnoreCase("LastReturnedTimeStamp")) {

	    long v;
	    if ((fldValue != null) && (isAString)) {
		v = toNumeric(SfldValue);
	    } else if (fldValue instanceof java.lang.Number) {
		v = ((Number)fldValue).longValue();
	    } else return false;

	    return (v >= -1);
	} else if (fldName.equalsIgnoreCase("log")) {
	    return ((fldValue instanceof java.lang.Boolean) ||
		    (isAString &&
		     (SfldValue.equalsIgnoreCase("T") ||
		      SfldValue.equalsIgnoreCase("true") ||
		      SfldValue.equalsIgnoreCase("F") ||
		      SfldValue.equalsIgnoreCase("false") )));
	}

	// default to true, it is a field we aren't validating (user etc.)
	return true;
private voidwriteObject(java.io.ObjectOutputStream out)
Serializes a {@link DescriptorSupport} to an {@link ObjectOutputStream}.

	ObjectOutputStream.PutField fields = out.putFields();
	boolean compat = "1.0".equals(serialForm);
	if (compat)
	    fields.put("currClass", currClass);
	boolean forceLowerCase = (compat || "1.2.0".equals(serialForm) ||
				  "1.2.1".equals(serialForm));
	Map descriptor = new HashMap();
	for (Iterator it = descriptorMap.entrySet().iterator();
	     it.hasNext(); ) {
	    Map.Entry entry = (Map.Entry) it.next();
	    String fieldName = entry.getKey().toString();
	    if (forceLowerCase)
		fieldName = fieldName.toLowerCase();
	    descriptor.put(fieldName, entry.getValue());
	}
	fields.put("descriptor", descriptor);
	out.writeFields();