01: /*
02: * Copyright (C) The MX4J Contributors.
03: * All rights reserved.
04: *
05: * This software is distributed under the terms of the MX4J License version 1.0.
06: * See the terms of the MX4J License in the documentation provided with this software.
07: */
08:
09: package javax.management;
10:
11: import java.io.Serializable;
12:
13: /**
14: * A set of name-value pairs that allow ModelMBean metadata to have additional information attached to.
15: * Descriptor is cloneable since represent a snapshot of what the client passed in to the ModelMBean.
16: * This ensures that if the client nulls out some value, the descriptor is still valid, since it has been cloned
17: * prior the client modification. The client can always re-set the descriptor on the model mbean.
18: *
19: * @version $Revision: 1.6 $
20: */
21: public interface Descriptor extends Cloneable, Serializable {
22: /**
23: * Returns the value of a given field name.
24: *
25: * @param fieldName The field name
26: * @return Object The value for the given field name. Returns null if not found.
27: * @throws RuntimeOperationsException if the value for field name is illegal
28: */
29: public Object getFieldValue(String fieldName)
30: throws RuntimeOperationsException;
31:
32: /**
33: * Sets a value for the given field name. The field value will be checked
34: * before being set. This will either add a new field or update it if it
35: * already exists.
36: *
37: * @param fieldName The name of the field
38: * @param fieldValue The value for the given field name
39: * @throws RuntimeOperationsException If values for fieldName or fieldValue
40: * are illegal or the description construction fails
41: */
42: public void setField(String fieldName, Object fieldValue)
43: throws RuntimeOperationsException;
44:
45: /**
46: * Removes the named field. If the field is not present, does nothing.
47: *
48: * @param fieldName The field to be removed.
49: */
50: public void removeField(String fieldName);
51:
52: /**
53: * Returns the names of all existing fields. If no fields are present, an empty array is returned.
54: */
55: public String[] getFieldNames();
56:
57: /**
58: * Return the values of the specified fields, in order.
59: *
60: * @param fieldNames The names of the fields
61: * @return Object[] The values of the fields
62: */
63: public Object[] getFieldValues(String[] fieldNames);
64:
65: /**
66: * Returns the names and values of all existing fields.
67: *
68: * @return String[] The String array in the format fieldName=fieldValue.
69: * An empty descriptor will result in an empty array returned.
70: */
71: public String[] getFields();
72:
73: /**
74: * Sets the given fieldValues for the given fieldNames.
75: * The size of both given array should match.
76: *
77: * @param fieldNames The names of the fields.
78: * @param fieldValues The values of the fields.
79: * @throws RuntimeOperationsException if fieldNames or fieldValues contains illegal values.
80: */
81: public void setFields(String[] fieldNames, Object[] fieldValues)
82: throws RuntimeOperationsException;
83:
84: /**
85: * Returns a copy of this Descriptor
86: */
87: public Object clone() throws RuntimeOperationsException;
88:
89: /**
90: * Returns true when the values for the fields of this Descriptor are valid values, false otherwise.
91: *
92: * @throws RuntimeOperationsException If the field names or values are illegal
93: */
94: public boolean isValid() throws RuntimeOperationsException;
95: }
|