| ObjectName.java |
package org.jfox.mx;
import java.util.Hashtable;
import java.util.WeakHashMap;
import java.util.HashMap;
import java.util.Enumeration;
import java.util.Arrays;
import java.io.Serializable;
import java.io.InvalidObjectException;
import java.io.ObjectInputStream;
import java.io.IOException;
import java.io.ObjectOutputStream;
import java.lang.ref.WeakReference;
import org.jfox.mx.MalformedObjectNameException;
/**
*
* @author <a href="mailto:young_yy@hotmail.com">Young Yang</a>
*
* <p>Represents the object name of an MBean, or a pattern that can
* match the names of several MBeans. Instances of this class are
* immutable.</p>
*
* <p>An instance of this class can
* be used to represent:
* <ul>
* <li> An object name
* <li> An object name pattern, within the context of a query
* </ul></p>
*
* <p>An object name consists of two parts, the domain and the key
* properties.</p>
*
* <p>The <em>domain</em> is a string of characters not including
* the character colon (<code>:</code>).</p>
*
* <p>If the domain includes at least one occurrence of the wildcard
* characters asterisk (<code>*</code>) or question mark
* (<code>?</code>), then the object name is a pattern. The asterisk
* matches any sequence of zero or more characters, while the question
* mark matches any single character.</p>
*
* <p>If the domain is empty, it will be replaced in certain contexts
* by the <em>default domain</em> of the MBean server in which the
* ObjectName is used.</p>
*
* <p>The <em>key properties</em> are an unordered set of keys and
* associated values.</p>
*
* <p>Each <em>key</em> is a nonempty string of characters which may
* not contain any of the characters comma (<code>,</code>), equals
* (<code>=</code>), colon, asterisk, or question mark. The same key
* may not occur twice in a given ObjectName.</p>
*
* <p>Each <em>value</em> associated with a key is a string of
* characters that is either unquoted or quoted.</p>
*
* <p>An <em>unquoted value</em> is a possibly empty string of
* characters which may not contain any of the characters comma,
* equals, colon, quote, asterisk, or question mark.</p>
*
* <p>A <em>quoted value</em> consists of a quote (<code>"</code>),
* followed by a possibly empty string of characters, followed by
* another quote. Within the string of characters, the backslash
* (<code>\</code>) has a special meaning. It must be followed by
* one of the following characters:</p>
*
* <ul>
* <li>Another backslash. The second backslash has no special
* meaning and the two characters represent a single blackslash.
*
* <li>The character 'n'. The two characters represent a newline
* ('\n' in Java).
*
* <li>A quote. The two characters represent a quote, and that quote
* is not considered to terminate the quoted value. An ending closing
* quote must be present for the quoted value to be valid.
*
* <li>A question mark (?) or star (*). The two characters represent
* a question mark or star respectively.
* </ul>
*
* <p>A quote, question mark, or star may not appear inside a quoted
* value except immediately after an odd number of consecutive
* backslashes.</p>
*
* <p>The quotes surrounding a quoted value, and any backslashes
* within that value, are considered to be part of the value.</p>
*
* <p>An ObjectName may be a <em>property pattern</em>. In this case
* it may have zero or more keys and associated values. It matches a
* nonpattern ObjectName whose domain matches and that contains the
* same keys and associated values, as well as possibly other keys and
* values.</p>
*
* <p>An ObjectName is a pattern if its domain contains a wildcard or
* if the ObjectName is a property pattern.</p>
*
* <p>If an ObjectName is not a pattern, it must contain at least one
* key with its associated value.</p>
*
* <p>An ObjectName can be written as a String with the following
* elements in order:</p>
*
* <ul>
* <li>The domain.
* <li>A colon (<code>:</code>).
* <li>A key property list as defined below.
* </ul>
*
* <p>A key property list written as a String is a comma-separated
* list of elements. Each element is either an asterisk or a key
* property. A key property consists of a key, an equals
* (<code>=</code>), and the associated value.</p>
*
* <p>At most one element of a key property list may be an asterisk.
* If the key property list contains an asterisk element, the
* ObjectName is a property pattern.</p>
*
* <p>Spaces have no special significance in a String representing an
* ObjectName. For example, the String:
* <pre>
* domain: key1 = value1 , key2 = value2
* </pre>
* represents an ObjectName with two keys. The name of each key
* contains six characters, of which the first and last are spaces.
* The value associated with the key <code>" key1 "</code>
* also begins and ends with a space.</p>
*
* <p>In addition to the restrictions on characters spelt out above,
* no part of an ObjectName may contain a newline character
* (<code>'\n'</code>), whether the domain, a key, or a value, whether
* quoted or unquoted. The newline character can be represented in a
* quoted value with the sequence <code>\n</code>.
*
* <p>The rules on special characters and quoting apply regardless of
* which constructor is used to make an ObjectName.</p>
*
* <p>To avoid collisions between MBeans supplied by different
* vendors, a useful convention is to begin the domain name with the
* reverse DNS name of the organization that specifies the MBeans,
* followed by a period and a string whose interpretation is
* determined by that organization. For example, MBeans specified by
* Sun Microsystems Inc., DNS name <code>sun.com</code>, would have
* domains such as <code>com.sun.MyDomain</code>. This is essentially
* the same convention as for Java-language package names.</p>
*/
public class ObjectName implements Serializable {
private final static class PropertyLengthCouple {
int _key_length = 0;
int _value_length = 0;
private PropertyLengthCouple(int key_length, int value_length) {
_key_length = key_length;
_value_length = value_length;
}
public boolean equals(Object obj) {
if (this == obj) return true;
if (!(obj instanceof PropertyLengthCouple)) return false;
PropertyLengthCouple couple = (PropertyLengthCouple) obj;
if ((_key_length != couple._key_length) ||
(_value_length != couple._value_length)) return false;
else return true;
}
public int hashCode() { return (_key_length << 5) ^ _value_length; }
void setLengths(int key_length, int value_length) {
_key_length = key_length;
_value_length = value_length;
}
}
/**
* a structure recording property structure and
* proposing minimal services
*/
private final static class Property {
private static WeakHashMap _PropertyLengthCouples =
new WeakHashMap(89);
int _key_index;
PropertyLengthCouple _lengths;
/**
* Constructor. Every field is initialized once here
*/
Property (int key_index, PropertyLengthCouple couple) {
_key_index = key_index;
WeakReference tmp_ref;
PropertyLengthCouple pl_couple;
if (((tmp_ref = (WeakReference)
_PropertyLengthCouples.get(couple)) != null) &&
((pl_couple = (PropertyLengthCouple) tmp_ref.get()) != null))
_lengths = pl_couple;
else {
_lengths = new PropertyLengthCouple(couple._key_length,
couple._value_length);
// new length couple, record it.
_PropertyLengthCouples.put(_lengths,
new WeakReference(_lengths));
}
}
/**
* assigns the key index of property
*/
void setKeyIndex(int key_index) {
_key_index = key_index;
}
/**
* returns a key string for receiver key
*/
String getKeyString(String name) {
return name.substring(_key_index, _key_index +
_lengths._key_length);
}
/**
* returns a key string for receiver key
*/
String getValueString(String name) {
int in_begin = _key_index + _lengths._key_length + 1;
int out_end = in_begin + _lengths._value_length;
return name.substring(in_begin, out_end);
}
}
/**
* a shared empty array for empty property lists
*/
static final private Property[] _Empty_property_array = new Property[0];
/**
* a shared empty hashtable for empty property lists
*/
static final private Hashtable _EmptyPropertyList = new Hashtable(1);
// Class private fields <==============================
// Instance private fields ----------------------------------->
/**
* a String containing the canonical name
*/
private transient String _canonicalName;
/**
* An array of properties in the same seq order as time creation
*/
private transient Property[] _kp_array;
/**
* An array of properties in the same seq order as canonical order
*/
private transient Property[] _ca_array;
/**
* The length of the domain part of built objectname
*/
private transient int _domain_length = 0;
/**
* The propertyList of built object name. Initialized lazylly.
* Table that contains all the pairs (key,value) for this ObjectName.
*/
private transient Hashtable _propertyList;
/**
* boolean that declares if this ObjectName domain part is a pattern
*/
private transient boolean _domain_pattern = false;
/**
* boolean that declares if this ObjectName contains a pattern on the
* key property list
*/
private transient boolean _property_pattern = false;
// Instance private fields <=======================================
// Private fields <========================================
// Private methods ---------------------------------------->
// Category : Instance construction ------------------------->
/**
* Initializes this {@link org.jfox.mx.ObjectName} from the given string
* representation.
*
* @param name A string representation of the {@link org.jfox.mx.ObjectName}
*/
private void construct(String name) throws MalformedObjectNameException {
// The name cannot be null
if (name == null) throw new
MalformedObjectNameException("ObjectName: name cannot be null");
// Test if the name is empty
if (name.length() == 0) {
// this is equivalent to the whole word query object name.
_canonicalName = "*:*";
_kp_array = _Empty_property_array;
_ca_array = _Empty_property_array;
_domain_length = 1;
_propertyList = null;
_domain_pattern = true;
_property_pattern = true;
return;
}
// initialize parsing of the string
char[] name_chars = name.toCharArray();
int len = name_chars.length;
char[] canonical_chars = new char[len]; // canonical form will be same length at most
int cname_index = 0;
int index = 0;
char c, c1;
// parses domain part
domain_parsing:
while (index < len) {
switch ( c = name_chars[index]) {
case ':' :
_domain_length = index++;
break domain_parsing;
case '=' :
int i = ++index;
while ((i < len) && (name_chars[i++] != ':'))
if (i == len) throw new
MalformedObjectNameException("ObjectName : domain part must be specified");
break;
case '\n' :
throw new MalformedObjectNameException("ObjectName : invalid character '\\n' in domain name");
case '*':
case '?' :
_domain_pattern = true;
default :
index++;
}
}
// check for non-empty properties
if (index == len) throw new
MalformedObjectNameException("ObjectName: Key properties cannot be empty");
// we have got the domain part, begins building of _canonicalName
System.arraycopy(name_chars, 0, canonical_chars, 0, _domain_length);
canonical_chars[_domain_length] = ':';
cname_index = _domain_length + 1;
// parses property list
Property prop;
PropertyLengthCouple prop_len_couple = new PropertyLengthCouple(-1, -1);
HashMap keys_map = new HashMap();
String[] keys;
String key_name;
boolean quoted_value;
int property_index = 0;
int in_index;
int key_index,key_length, value_index, value_length;
keys = new String[10];
_kp_array = new Property[10];
_property_pattern = false;
while (index < len) {
c = name_chars[index];
// case of pattern properties
if (c == '*') {
if (_property_pattern) throw new
MalformedObjectNameException("ObjectName: cannot have several '*' characters in pattern properties");
else {
_property_pattern = true;
if ((++index < len ) && (name_chars[index] != ',')) throw new
MalformedObjectNameException("ObjectName: badly specified pattern property part");
else if (index == len) {
if (property_index == 0) {
// empty properties case
_kp_array = _Empty_property_array;
_ca_array = _Empty_property_array;
_propertyList = _EmptyPropertyList;
}
break;
}
else {
// correct pattern spec in props, continue
index++;
continue;
}
}
}
// standard property case, key part
in_index = index;
key_index = in_index;
while ((in_index < len) && ((c1 = name_chars[in_index++]) != '='))
switch (c1) {
// '=' considered to introduce value part
case '*' :
case '?' :
case ',' :
case ':' :
case '\n' :
throw new
MalformedObjectNameException("ObjectName: invalid character '" + c1 + "' in key part part of property");
default: ;
}
if (in_index == len) throw new
MalformedObjectNameException("ObjectName: unterminated key property part");
if (in_index == index) throw new
MalformedObjectNameException("ObjectName: invalid key (empty)");
value_index = in_index; // in_index pointing after '=' char
key_length = value_index - key_index - 1; // found end of key
// standard property case, value part
if (name_chars[in_index] == '\"') {
quoted_value = true;
// the case of quoted value part
quoted_value_parsing:
while ((++in_index < len) && ((c1 = name_chars[in_index]) != '\"')) {
// the case of an escaped character
if (c1 == '\\') {
if (++in_index == len) throw new
MalformedObjectNameException("ObjectName : unterminated quoted value");
switch (c1 = name_chars[in_index]) {
case '\\' :
case '\"' :
case '?' :
case '*' :
case 'n' :
break; // valid character
default :
throw new
MalformedObjectNameException("ObjectName : invalid escaped character '" + c1 + "' in quoted value");
}
} else if (c1 == '\n') {
throw new
MalformedObjectNameException("ObjectName: newline in quoted value");
} else {
switch (c1) {
case '?' :
case '*' :
throw new
MalformedObjectNameException("ObjectName : invalid unescaped character '" + c1 + "' in quoted value");
default:
break;
}
}
}
if (in_index == len) throw new
MalformedObjectNameException("ObjectName: unterminated quoted value");
else value_length = ++in_index - value_index;
}
else {
// the case of standard value part
quoted_value = false;
while ((in_index < len) && ((c1 = name_chars[in_index]) != ','))
switch (c1) {
// ',' considered to be the value separator
case '*' :
case '?' :
case '=' :
case ':' :
case '"' :
case '\n' :
throw new MalformedObjectNameException("ObjectName: invalid character '" + c1 + "' in value part of property");
default : in_index++;
}
value_length = in_index - value_index;
}
// Parsed property, checks the end of name
if (in_index == len - 1) {
if (quoted_value) throw new
MalformedObjectNameException("ObjectName: invalid ending character `" + name_chars[in_index] + "' ");
else throw new
MalformedObjectNameException("ObjectName: invalid ending comma");
}
else in_index++;
// we got the key and value part, prepare a property for this
prop_len_couple.setLengths(key_length, value_length);
prop = new Property(key_index, prop_len_couple);
key_name = name.substring(key_index, key_index + key_length);
if (property_index == keys.length) {
String[] tmp_string_array = new String[property_index + 10];
System.arraycopy(keys, 0, tmp_string_array, 0, property_index);
keys = tmp_string_array;
}
keys[property_index] = key_name;
addProperty(prop, property_index, keys_map, key_name);
property_index++;
index = in_index;
}
// computes and set canonical name
setCanonicalName(name_chars, canonical_chars, keys, keys_map, cname_index, property_index);
}
/**
* Construct an ObjectName from a domain and a Hashtable.
* @param domain Domain of the ObjectName.
* @param props Hashtable containing couples <i>key</i> -> <i>value</i>.
**/
private void construct(String domain, Hashtable props)
throws MalformedObjectNameException {
// Test if the name is empty
if (domain == null) throw new
MalformedObjectNameException("ObjectName: domain must be specified");
if (props == null) throw new
MalformedObjectNameException("ObjectName: property list cannot be empty");
// checks domain validity
if (!isDomain(domain))
throw new
MalformedObjectNameException("ObjectName: Invalid domain -> " + domain);
// init canonicalname
final StringBuffer sb = new StringBuffer();
sb.append(domain).append(':');
_domain_length = domain.length();
// allocates the property array
int nb_props = props.size();
_kp_array = new Property[nb_props];
PropertyLengthCouple prop_len_couple = new PropertyLengthCouple(-1,-1);
String[] keys = new String[nb_props];
final Enumeration e = props.keys();
final HashMap keys_map = new HashMap();
Property prop;
int key_index;
for (int i=0; e.hasMoreElements(); i++ ) {
if (i > 0) sb.append(",");
String key = "";
try { key = (String)e.nextElement(); } catch (Exception x) {
throw new MalformedObjectNameException("ObjectName: Invalid key `" + key + "'");
}
String value = "";
try { value = (String)props.get(key); } catch (Exception x) {
throw new MalformedObjectNameException("ObjectName: Invalid value `" + value + "'");
}
key_index = sb.length();
checkKey(key);
sb.append(key);
keys[i] = key;
sb.append("=");
checkValue(value);
sb.append(value);
prop_len_couple.setLengths(key.length(), value.length());
prop = new Property(key_index, prop_len_couple);
addProperty(prop, i, keys_map, key);
}
// initialise canonical name and data structure
int len = sb.length();
char[] initial_chars = new char[len];
sb.getChars(0, len, initial_chars, 0);
char[] canonical_chars = new char[len];
System.arraycopy(initial_chars, 0, canonical_chars, 0, _domain_length + 1);
setCanonicalName(initial_chars, canonical_chars, keys, keys_map, _domain_length + 1, _kp_array.length);
}
// Category : Instance construction <==============================
// Category : Internal utilities ------------------------------>
/**
* Add passed property to the list at the given index
* for the passed key name
*/
private void addProperty(Property prop, int index, HashMap keys_map, String key_name)
throws MalformedObjectNameException {
if (keys_map.containsKey(key_name)) throw new
MalformedObjectNameException("ObjectName: key `" +
key_name +"' already defined.");
// if no more space for property arrays, have to increase it
if (index == _kp_array.length) {
Property[] tmp_prop_array = new Property[index + 10];
System.arraycopy(_kp_array, 0, tmp_prop_array, 0, index);
_kp_array = tmp_prop_array;
}
_kp_array[index] = prop;
keys_map.put(key_name, prop);
}
/**
* Sets the canonical name of receiver from input 'specified_chars'
* array, by filling 'canonical_chars' array with found 'nb-props'
* properties starting at position 'prop_index'.
*/
private void setCanonicalName(char[] specified_chars,
char[] canonical_chars,
String[] keys, HashMap keys_map,
int prop_index, int nb_props) {
// Sort the list of found properties
if (_kp_array != _Empty_property_array) {
String[] tmp_keys = new String[nb_props];
Property[] tmp_props = new Property[nb_props];
System.arraycopy(keys, 0, tmp_keys, 0, nb_props);
Arrays.sort(tmp_keys);
keys = tmp_keys;
System.arraycopy(_kp_array, 0, tmp_props, 0 , nb_props);
_kp_array = tmp_props;
_ca_array = new Property[nb_props];
// now assigns _ca_array to the sorted list of keys
// (there cannot be two identical keys in an objectname.
for (int i = 0; i < nb_props; i++)
_ca_array[i] = (Property) keys_map.get(keys[i]);
// now we build the canonical name and set begin indexes of
// properties to reflect canonical form
int last_index = nb_props - 1;
int prop_len;
Property prop;
for (int i = 0; i <= last_index; i++) {
prop = _ca_array[i];
prop_len = prop._lengths._key_length + prop._lengths._value_length + 1; // length of prop including '=' char
System.arraycopy(specified_chars, prop._key_index, canonical_chars, prop_index, prop_len);
prop.setKeyIndex(prop_index);
prop_index += prop_len;
if (i != last_index) {
canonical_chars[prop_index] = ',';
prop_index++;
}
}
}
// terminate canonicalname with '*' in case of pattern
if (_property_pattern) {
if (_kp_array != _Empty_property_array) canonical_chars[prop_index++] = ',';
canonical_chars[prop_index++] = '*';
}
// we now build the canonicalname string
_canonicalName = (new String(canonical_chars, 0, prop_index)).intern();
}
/**
* Parse a key.
* <pre>final int endKey=parseKey(s,startKey);</pre>
* <p>key starts at startKey (included), and ends at endKey (excluded).
* If (startKey == endKey), then the key is empty.
*
* @param s The char array of the original string.
* @param startKey index at which to begin parsing.
* @return The index following the last character of the key.
**/
private final static int parseKey(final char[] s, final int startKey)
throws MalformedObjectNameException {
int next = startKey;
int endKey = startKey;
final int len = s.length;
while (next < len) {
final char k = s[next++];
switch (k) {
case '*':
case '?':
case ',':
case ':':
case '\n':
throw new
MalformedObjectNameException("ObjectName: `" + k +
"'" + " Invalid character in key");
case '=':
// we got the key.
endKey = next-1;
break;
default:
if (next < len) continue;
else endKey=next;
}
break;
}
return endKey;
}
/**
* Parse a value.
* <pre>final int endVal=parseValue(s,startVal);</pre>
* <p>value starts at startVal (included), and ends at endVal (excluded).
* If (startVal == endVal), then the key is empty.
*
* @param s The char array of the original string.
* @param startValue index at which to begin parsing.
* @return The index following the last character of the value.
**/
private final static int parseValue(final char[] s, final int startValue)
throws MalformedObjectNameException {
int next = startValue;
int endValue = startValue;
final int len = s.length;
final char q=s[startValue];
// Quoted value (revisit!!!).
if (q == '"') {
if (++next == len) throw new
MalformedObjectNameException("ObjectName: " +
"Invalid quote.");
while (next < len) {
char last = s[next];
if (last == '\\') {
if (++next == len) throw new
MalformedObjectNameException("ObjectName: " +
"Invalid unterminated quoted character sequence.");
last = s[next];
switch (last) {
case '\\' :
case '\"' :
case '?' :
case '*' :
case 'n' :
break;
default:
throw new
MalformedObjectNameException("ObjectName: " +
"Invalid quoted character '" + last + "' sequence.");
}
} else if (last == '\n') {
throw new MalformedObjectNameException("ObjectName: newline in quoted value");
} else if (last == '\"') {
next++;
break;
} else {
switch (last) {
case '?' :
case '*' :
throw new MalformedObjectNameException("ObjectName: invalid unescaped character '" + last + "' in quoted value");
default:
break;
}
}
next++;
}
endValue = next;
if (next < len) {
if (s[next++] != ',') throw new
MalformedObjectNameException("ObjectName: " +
"Invalid quote.");
}
}
else {
while (next < len) {
final char v=s[next++];
// Non Quoted value (revisit!!!).
switch(v) {
case '*':
case '?':
case '=':
case ':':
case '\n' :
throw new
MalformedObjectNameException("ObjectName: "
+ " Invalid character `" + v +
"' in value");
case ',':
endValue = next-1;
break;
default:
if (next < len) continue;
else endValue=next;
}
break;
}
}
return endValue;
}
/**
* Check if the value given in parameter in the first constructor is a
* valid value
*/
private String checkValue(String val)
throws MalformedObjectNameException {
if (val == null) throw new
MalformedObjectNameException("ObjectName: " +
"Invalid value (null).");
final int len = val.length();
if (len == 0) throw new
MalformedObjectNameException("ObjectName: " +
"Invalid value (empty).");
final char[] s = val.toCharArray();
final int endValue = parseValue(s,0);
if (endValue < len) throw new
MalformedObjectNameException("ObjectName: `" + s[endValue] +
"'" + " Invalid character in value");
return val;
}
/**
* Check if the key given in parameter in the first constructor is a
* valid key.
*/
private String checkKey(String key)
throws MalformedObjectNameException {
if (key == null) throw new
MalformedObjectNameException("ObjectName: " +
"Invalid key (null)");
final int len = key.length();
if (len == 0) throw new
MalformedObjectNameException("ObjectName: " +
"Invalid key (empty)");
final char[] k=key.toCharArray();
final int endKey = parseKey(k,0);
if (endKey < len) throw new
MalformedObjectNameException("ObjectName: `" + k[endKey] +
"'" + " Invalid character in value");
return key;
}
/*
* Tests whether string s is matched by pattern p.
* Supports "?", "*" each of which may be escaped with "\";
* Not yet supported: internationalization; "\" inside brackets.<P>
* Wildcard matching routine by Karl Heuer. Public Domain.<P>
*/
private static boolean wildmatch(char[] s, char[] p, int si, int pi) {
char c;
final int slen = s.length;
final int plen = p.length;
while (pi < plen) { // While still string
c = p[pi++];
if (c == '?') {
if (++si > slen) return false;
} else if (c == '*') { // Wildcard
if (pi >= plen) return true;
do {
if (wildmatch(s,p,si,pi)) return true;
} while (++si < slen);
return false;
} else {
if (si >= slen || c != s[si++]) return false;
}
}
return (si == slen);
}
// Category : Internal utilities <==============================
// Category : Internal accessors ------------------------------>
/**
* Check if domain is a valid domain
*/
private boolean isDomain(String domain) {
if (domain == null) return true;
final char[] d=domain.toCharArray();
final int len = d.length;
int next = 0;
while (next < len) {
final char c = d[next++];
switch (c) {
case ':' :
case '\n' :
return false;
case '*' :
case '?' :
_domain_pattern = true;
default:
continue;
}
}
return true;
}
// Category : Internal accessors <==============================
// Category : Serialization ----------------------------------->
/**
* Deserializes an {@link org.jfox.mx.ObjectName} from an {@link java.io.ObjectInputStream}.
* @serialData <ul>
* <li>In the current serial form (value of property
* <code>jmx.serial.form</code> differs from
* <code>1.0</code>): the string
* "<domain>:<properties><wild>",
* where: <ul>
* <li><domain> represents the domain part
* of the {@link org.jfox.mx.ObjectName}</li>
* <li><properties> represents the list of
* properties, as returned by
* {@link #getKeyPropertyListString}
* <li><wild> is empty if not
* <code>isPropertyPattern</code>, or
* is the character "<code>*</code>" if
* <code>isPropertyPattern</code>
* and <properties> is empty, or
* is "<code>,*</code>" if
* <code>isPropertyPattern</code> and
* <properties> is not empty.
* </li>
* </ul>
* The intent is that this string could be supplied
* to the {@link #ObjectName(String)} constructor to
* produce an equivalent {@link org.jfox.mx.ObjectName}.
* </li>
* <li>In the old serial form (value of property
* <code>jmx.serial.form</code> is
* <code>1.0</code>): <domain> <propertyList>
* <propertyListString> <canonicalName>
* <pattern> <propertyPattern>,
* where: <ul>
* <li><domain> represents the domain part
* of the {@link org.jfox.mx.ObjectName}</li>
* <li><propertyList> is the
* {@link java.util.Hashtable} that contains all the
* pairs (key,value) for this {@link org.jfox.mx.ObjectName}</li>
* <li><propertyListString> is the {@link java.lang.String}
* representation of the list of
* properties in any order (not mandatorily a
* canonical representation)</li>
* <li><canonicalName> is the {@link java.lang.String}
* containing this {@link org.jfox.mx.ObjectName}'s
* canonical name</li>
* <li><pattern> is a boolean which is
* <code>true</code> if this {@link org.jfox.mx.ObjectName}
* contains a pattern</li>
* <li><propertyPattern> is a boolean which is
* <code>true</code> if this {@link org.jfox.mx.ObjectName}
* contains a pattern in the list of properties</li>
* </ul>
* </li>
* </ul>
*/
private void readObject(ObjectInputStream in)
throws IOException, ClassNotFoundException {
// Read an object serialized in the new serial form
//
in.defaultReadObject();
String s = (String)in.readObject();
try
{
construct(s);
}
catch (MalformedObjectNameException e)
{
throw new InvalidObjectException(e.toString());
}
}
/**
* Serializes an {@link org.jfox.mx.ObjectName} to an {@link java.io.ObjectOutputStream}.
* @serialData <ul>
* <li>In the current serial form (value of property
* <code>jmx.serial.form</code> differs from
* <code>1.0</code>): the string
* "<domain>:<properties><wild>",
* where: <ul>
* <li><domain> represents the domain part
* of the {@link org.jfox.mx.ObjectName}</li>
* <li><properties> represents the list of
* properties, as returned by
* {@link #getKeyPropertyListString}
* <li><wild> is empty if not
* <code>isPropertyPattern</code>, or
* is the character "<code>*</code>" if
* this <code>isPropertyPattern</code>
* and <properties> is empty, or
* is "<code>,*</code>" if
* <code>isPropertyPattern</code> and
* <properties> is not empty.
* </li>
* </ul>
* The intent is that this string could be supplied
* to the {@link #ObjectName(String)} constructor to
* produce an equivalent {@link org.jfox.mx.ObjectName}.
* </li>
* <li>In the old serial form (value of property
* <code>jmx.serial.form</code> is
* <code>1.0</code>): <domain> <propertyList>
* <propertyListString> <canonicalName>
* <pattern> <propertyPattern>,
* where: <ul>
* <li><domain> represents the domain part
* of the {@link org.jfox.mx.ObjectName}</li>
* <li><propertyList> is the
* {@link java.util.Hashtable} that contains all the
* pairs (key,value) for this {@link org.jfox.mx.ObjectName}</li>
* <li><propertyListString> is the {@link java.lang.String}
* representation of the list of
* properties in any order (not mandatorily a
* canonical representation)</li>
* <li><canonicalName> is the {@link java.lang.String}
* containing this {@link org.jfox.mx.ObjectName}'s
* canonical name</li>
* <li><pattern> is a boolean which is
* <code>true</code> if this {@link org.jfox.mx.ObjectName}
* contains a pattern</li>
* <li><propertyPattern> is a boolean which is
* <code>true</code> if this {@link org.jfox.mx.ObjectName}
* contains a pattern in the list of properties</li>
* </ul>
* </li>
* </ul>
*/
private void writeObject(ObjectOutputStream out)
throws IOException {
// Serializes this instance in the new serial form
//
out.defaultWriteObject();
out.writeObject(_canonicalName);
}
// Category : Serialization <===================================
// Private methods <========================================
// Public methods ---------------------------------------->
// Category : ObjectName Construction ------------------------------>
/**
* <p>Return an instance of ObjectName that can be used anywhere
* an object obtained with {@link #ObjectName(String) new
* ObjectName(name)} can be used. The returned object may be of
* a subclass of ObjectName. Calling this method twice with the
* same parameters may return the same object or two equal but
* not identical objects.</p>
*
* @param name A string representation of the object name.
*
* @return an ObjectName corresponding to the given String.
*
* @exception MalformedObjectNameException The string passed as a
* parameter does not have the right format.
* @exception NullPointerException The <code>name</code> parameter
* is null.
*
* @since JMX 1.2
*/
public static ObjectName getInstance(String name)
throws MalformedObjectNameException, NullPointerException {
return new ObjectName(name);
}
/**
* <p>Return an instance of ObjectName that can be used anywhere
* an object obtained with {@link #ObjectName(String, String,
* String) new ObjectName(domain, key, value)} can be used. The
* returned object may be of a subclass of ObjectName. Calling
* this method twice with the same parameters may return the same
* object or two equal but not identical objects.</p>
*
* @param domain The domain part of the object name.
* @param key The attribute in the key property of the object name.
* @param value The value in the key property of the object name.
*
* @return an ObjectName corresponding to the given domain,
* key, and value.
*
* @exception org.jfox.mx.MalformedObjectNameException The
* <code>domain</code>, <code>key</code>, or <code>value</code>
* contains an illegal character, or <code>value</code> does not
* follow the rules for quoting.
* @exception NullPointerException One of the parameters is null.
*
* @since JMX 1.2
*/
public static ObjectName getInstance(String domain, String key,
String value)
throws MalformedObjectNameException, NullPointerException {
return new ObjectName(domain, key, value);
}
/**
* <p>Return an instance of ObjectName that can be used anywhere
* an object obtained with {@link #ObjectName(String, Hashtable)
* new ObjectName(domain, table)} can be used. The returned
* object may be of a subclass of ObjectName. Calling this method
* twice with the same parameters may return the same object or
* two equal but not identical objects.</p>
*
* @param domain The domain part of the object name.
* @param table A hash table containing one or more key
* properties. The key of each entry in the table is the key of a
* key property in the object name. The associated value in the
* table is the associated value in the object name.
*
* @return an ObjectName corresponding to the given domain and
* key mappings.
*
* @exception MalformedObjectNameException The <code>domain</code>
* contains an illegal character, or one of the keys or values in
* <code>table</code> contains an illegal character, or one of the
* values in <code>table</code> does not follow the rules for
* quoting.
* @exception NullPointerException One of the parameters is null.
*
* @since JMX 1.2
*/
public static ObjectName getInstance(String domain, Hashtable table)
throws MalformedObjectNameException, NullPointerException {
return new ObjectName(domain, table);
}
/**
* <p>Return an instance of ObjectName that can be used anywhere
* the given object can be used. The returned object may be of a
* subclass of ObjectName. If <code>name</code> is of a subclass
* of ObjectName, it is not guaranteed that the returned object
* will be of the same class.</p>
*
* <p>The returned value may or may not be identical to
* <code>name</code>. Calling this method twice with the same
* parameters may return the same object or two equal but not
* identical objects.</p>
*
* <p>Since ObjectName is immutable, it is not usually useful to
* make a copy of an ObjectName. The principal use of this method
* is to guard against a malicious caller who might pass an
* instance of a subclass with surprising behaviour to sensitive
* code. Such code can call this method to obtain an ObjectName
* that is known not to have surprising behaviour.</p>
*
* @param name an instance of the ObjectName class or of a subclass
*
* @return an instance of ObjectName or a subclass that is known to
* have the same semantics. If <code>name</code> respects the
* semantics of ObjectName, then the returned object is equal
* (though not necessarily identical) to <code>name</code>.
*
* @exception NullPointerException The <code>name</code> is null.
*
* @since JMX 1.2
*/
public static ObjectName getInstance(ObjectName name)
throws NullPointerException {
if (name.getClass().equals(ObjectName.class))
return name;
try {
return new ObjectName(name.getCanonicalName());
} catch (MalformedObjectNameException e) {
throw new IllegalArgumentException("Unexpected: " + e);
// can't happen
}
}
/**
* Construct an object name from the given string.
*
* @param name A string representation of the object name.
*
* @exception MalformedObjectNameException The string passed as a
* parameter does not have the right format.
* @exception NullPointerException The <code>name</code> parameter
* is null.
*/
public ObjectName(String name) throws MalformedObjectNameException, NullPointerException {
construct(name);
}
/**
* Construct an object name with exactly one key property.
*
* @param domain The domain part of the object name.
* @param key The attribute in the key property of the object name.
* @param value The value in the key property of the object name.
*
* @exception MalformedObjectNameException The
* <code>domain</code>, <code>key</code>, or <code>value</code>
* contains an illegal character, or <code>value</code> does not
* follow the rules for quoting.
* @exception NullPointerException One of the parameters is null.
*/
public ObjectName(String domain, String key, String value)
throws MalformedObjectNameException, NullPointerException {
Hashtable table = new Hashtable(1);
if ( key == null || value == null) throw new
MalformedObjectNameException("ObjectName: " +
"Neither the key nor the value can be null");
table.put(key, value);
construct(domain, table);
}
/**
* Construct an object name with several key properties from a Hashtable.
*
* @param domain The domain part of the object name.
* @param table A hash table containing one or more key
* properties. The key of each entry in the table is the key of a
* key property in the object name. The associated value in the
* table is the associated value in the object name.
*
* @exception MalformedObjectNameException The <code>domain</code>
* contains an illegal character, or one of the keys or values in
* <code>table</code> contains an illegal character, or one of the
* values in <code>table</code> does not follow the rules for
* quoting.
* @exception NullPointerException One of the parameters is null.
*/
public ObjectName(String domain, Hashtable table)
throws MalformedObjectNameException, NullPointerException {
if (table == null) throw new
MalformedObjectNameException("ObjectName: Hashtable is null");
if (table.isEmpty()) throw new
MalformedObjectNameException("ObjectName: Empty Hashtable");
construct(domain, table);
}
// Category : ObjectName Construction <==============================
// Category : Getter methods ------------------------------>
/**
* Checks whether the object name is a pattern. An object name is
* a pattern if its domain contains a wildcard or if the object
* name is a property pattern.
*
* @return True if the name is a pattern, otherwise false.
*/
public boolean isPattern() {
return (_domain_pattern || _property_pattern);
}
/**
* Checks whether the object name is a pattern on the domain part.
*
* @return True if the name is a domain pattern, otherwise false.
*
* @since JMX 1.2
*/
public boolean isDomainPattern() {
return _domain_pattern;
}
/**
* Checks whether the object name is a pattern on the key properties.
*
* @return True if the name is a pattern, otherwise false.
*/
public boolean isPropertyPattern() {
return _property_pattern;
}
/**
* <p>Returns the canonical form of the name; that is, a string
* representation where the properties are sorted in lexical
* order.</p>
*
* <p>More precisely, the canonical form of the name is a String
* consisting of the <em>domain part</em>, a colon
* (<code>:</code>), the <em>canonical key property list</em>, and
* a <em>pattern indication</em>.</p>
*
* <p>The <em>canonical key property list</em> is the same string
* as described for {@link #getCanonicalKeyPropertyListString()}.</p>
*
* <p>The <em>pattern indication</em> is:
* <ul>
* <li>empty for an ObjectName
* that is not a property pattern;
* <li>an asterisk for an ObjectName
* that is a property pattern with no keys; or
* <li>a comma and an
* asterisk (<code>,*</code>) for an ObjectName that is a property
* pattern with at least one key.
* </ul></p>
*
* @return The canonical form of the name.
*/
public String getCanonicalName() {
return _canonicalName;
}
/**
* Returns the domain part.
*
* @return the domain.
*/
public String getDomain() {
return _canonicalName.substring(0, _domain_length);
}
/**
* Obtains the value associated with a key in a key property.
*
* @param property The property whose value is to be obtained.
*
* @return The value of the property, or null if there is no such
* property in this ObjectName.
*
* @exception NullPointerException If <code>property</code> is null.
*/
public String getKeyProperty(String property) throws NullPointerException {
return (String) _getKeyPropertyList().get(property);
}
/**
* <p>Returns the key properties as a Hashtable. The returned
* value is a Hashtable in which each key is a key in the
* ObjectName's key property list and each value is the associated
* value.</p>
*
* <p>The returned value must not be modidied.</p>
*
* @return The table of key properties.
*/
private final Hashtable _getKeyPropertyList() {
synchronized (this) {
if (_propertyList == null) {
// build (lazy eval) the property list from the canonical properties array
_propertyList = new Hashtable();
int len = _ca_array.length;
Property prop;
for (int i = len - 1; i >= 0; i--) {
prop = _ca_array[i];
_propertyList.put(prop.getKeyString(_canonicalName),
prop.getValueString(_canonicalName));
}
}
}
return _propertyList;
}
/**
* <p>Returns the key properties as a Hashtable. The returned
* value is a Hashtable in which each key is a key in the
* ObjectName's key property list and each value is the associated
* value.</p>
*
* <p>The returned value may be unmodifiable. If it is
* modifiable, changing it has no effect on this ObjectName.</p>
*
* @return The table of key properties.
*/
public Hashtable getKeyPropertyList() {
return (Hashtable)_getKeyPropertyList().clone();
}
/**
* <p>Returns a string representation of the list of key
* properties specified at creation time. If this ObjectName was
* constructed with the constructor {@link #ObjectName(String)},
* the key properties in the returned String will be in the same
* order as in the argument to the constructor.</p>
*
* @return The key property list string. This string is
* independent of whether the ObjectName is a pattern.
*/
public String getKeyPropertyListString() {
// BEWARE : we rebuild the propertyliststring at each call !!
if (_kp_array.length == 0) return "";
// the size of the string is the canonical one minus domain part and pattern part
int total_size = _canonicalName.length() - _domain_length - 1;
if (_property_pattern) total_size -= 2;
char[] dest_chars = new char[total_size];
char[] value = _canonicalName.toCharArray();
Property prop;
int prop_len;
int index = 0;
int len = _kp_array.length;
for (int i = 0; i < len; i++) {
prop = _kp_array[i];
prop_len = prop._lengths._key_length + prop._lengths._value_length +1;
System.arraycopy(value, prop._key_index, dest_chars, index, prop_len);
index += prop_len;
if (index < total_size) dest_chars[index++] = ',';
}
return new String(dest_chars);
}
/**
* Returns a string representation of the list of key properties,
* in which the key properties are sorted in lexical order. This
* is used in lexicographic comparisons performed in order to
* select MBeans based on their key property list. Lexical order
* is the order implied by {@link String#compareTo(String)
* String.compareTo(String)}.
*
* @return The canonical key property list string. This string is
* independent of whether the ObjectName is a pattern.
*/
public String getCanonicalKeyPropertyListString() {
if (_ca_array.length == 0) return "";
int len = _canonicalName.length();
if (_property_pattern) len -= 2;
return _canonicalName.substring(_domain_length +1, len);
}
// Category : Getter methods <===================================
// Category : Utilities ---------------------------------------->
/**
* <p>Returns a string representation of the object name. The
* format of this string is not specified, but users can expect
* that two ObjectNames return the same string if and only if they
* are equal.</p>
*
* @return a string representation of this object name.
*/
public String toString() {
final String pls = getKeyPropertyListString();
StringBuffer sb = new StringBuffer(_canonicalName.length());
sb.append(_canonicalName.substring(0, _domain_length + 1));
sb.append(pls);
if (_property_pattern) {
if (pls.length() == 0) sb.append('*');
else sb.append(",*");
}
return sb.toString();
}
/**
* Compares the current object name with another object name. Two
* ObjectName instances are equal if and only if their canonical
* forms are equal. The canonical form is the string described
* for {@link #getCanonicalName()}.
*
* @param object The object name that the current object name is to be
* compared with.
*
* @return True if <code>object</code> is an ObjectName whose
* canonical form is equal to that of this ObjectName.
*/
public boolean equals(Object object) {
// same object case
if (this == object) return true;
// object is not an object name case
if (!(object instanceof ObjectName)) return false;
// equality when canonical names are the same
// (because usage of intern())
ObjectName on = (ObjectName) object;
String on_string = on._canonicalName;
if (_canonicalName == on_string) return true;
// Because we are sharing canonical form between object names,
// we have finished the comparison at this stage ==> unequal
return false;
}
/**
* Returns a hash code for this object name.
*
*/
public int hashCode() {
return _canonicalName.hashCode();
}
/**
* <p>Returns a quoted form of the given String, suitable for
* inclusion in an ObjectName. The returned value can be used as
* the value associated with a key in an ObjectName. The String
* <code>s</code> may contain any character. Appropriate quoting
* ensures that the returned value is legal in an ObjectName.</p>
*
* <p>The returned value consists of a quote ('"'), a sequence of
* characters corresponding to the characters of <code>s</code>,
* and another quote. Characters in <code>s</code> appear
* unchanged within the returned value except:</p>
*
* <ul>
* <li>A quote ('"')is replaced by a backslash (\) followed by a quote.
* <li>A star ('*') is replaced by a backslash (\) followed by a star.
* <li>A question mark ('?') is replaced by a backslash (\) followed by
* a question mark.
* <li>A backslash ('\') is replaced by two backslashes.
* <li>A newline character (the character '\n' in Java) is replaced
* by a backslash followed by the character '\n'.
* </ul>
*
* @param s the String to be quoted.
*
* @return the quoted String.
*
* @exception NullPointerException if <code>s</code> is null.
*
* @since JMX 1.2
*/
public static String quote(String s)
throws NullPointerException {
final StringBuffer buf = new StringBuffer("\"");
final int len = s.length();
for (int i = 0; i < len; i++) {
char c = s.charAt(i);
switch (c) {
case '\n':
c = 'n';
// fall in...
case '\\':
case '\"':
case '*':
case '?':
buf.append('\\');
break;
}
buf.append(c);
}
buf.append('"');
return buf.toString();
}
/**
* <p>Returns an unquoted form of the given String. If
* <code>q</code> is a String returned by {@link #quote quote(s)},
* then <code>unquote(q).equals(s)</code>. If there is no String
* <code>s</code> for which <code>quote(s).equals(q)</code>, then
* unquote(q) throws an IllegalArgumentException.</p>
*
* <p>These rules imply that there is a one-to-one mapping between
* quoted and unquoted forms.</p>
*
* @param q the String to be unquoted.
*
* @return the unquoted String.
*
* @exception IllegalArgumentException if <code>q</code> could not
* have been returned by the {@link #quote} method, for instance
* if it does not begin and end with a quote (").
*
* @exception NullPointerException if <code>q</code> is null.
*
* @since JMX 1.2
*/
public static String unquote(String q)
throws IllegalArgumentException, NullPointerException {
final StringBuffer buf = new StringBuffer();
final int len = q.length();
if (len < 2 || q.charAt(0) != '"' || q.charAt(len - 1) != '"')
throw new IllegalArgumentException("Argument not quoted");
for (int i = 1; i < len - 1; i++) {
char c = q.charAt(i);
if (c == '\\') {
if (i == len - 2)
throw new IllegalArgumentException("Trailing backslash");
c = q.charAt(++i);
switch (c) {
case 'n':
c = '\n';
break;
case '\\':
case '\"':
case '*':
case '?':
break;
default:
throw new IllegalArgumentException("Bad character '" + c + "' after backslash");
}
}
else {
switch (c) {
case '*' :
case '?' :
case '\"':
case '\n':
throw new IllegalArgumentException("Invalid unescaped character '" + c +
"' in the string to unquote");
default : ;
}
}
buf.append(c);
}
return buf.toString();
}
// Category : Utilities <===================================
// Category : QueryExp Interface ---------------------------------------->
/**
* <p>Test whether this ObjectName, which may be a pattern,
* matches another ObjectName. If <code>name</code> is a pattern,
* the result is false. If this ObjectName is a pattern, the
* result is true if and only if <code>name</code> matches the
* pattern. If neither this ObjectName nor <code>name</code> is
* a pattern, the result is true if and only if the two
* ObjectNames are equal as described for the {@link
* #equals(Object)} method.</p>
*
* @param name The name of the MBean to compare to.
*
* @return True if <code>name</code> matches this ObjectName.
*
* @exception NullPointerException if <code>name</code> is null.
*
* @since JMX 1.2
*/
public boolean apply(ObjectName name) throws NullPointerException {
if (name == null) throw new NullPointerException();
if (name._domain_pattern || name._property_pattern)
return false;
// No pattern
if (!_domain_pattern && !_property_pattern)
return _canonicalName.equals(name._canonicalName);
return matchDomains(name) && matchKeys(name);
}
private final boolean matchDomains(ObjectName name) {
if (_domain_pattern) {
// wildmatch domains
final char[] dom_pattern = getDomain().toCharArray();
final char[] dom_string = name.getDomain().toCharArray();
return wildmatch(dom_string,dom_pattern,0,0);
}
return getDomain().equals(name.getDomain());
}
private final boolean matchKeys(ObjectName name) {
if (_property_pattern) {
// Every property inside pattern should exist in name
final Hashtable nameProps = name._getKeyPropertyList();
final Property[] props=_ca_array;
final String cn=_canonicalName;
for (int i= props.length -1; i >= 0 ; i--) {
// find value in given object name for key at current
// index in receiver
<