javax.management
Class ObjectName

java.lang.Object
  extended by javax.management.ObjectName
All Implemented Interfaces:
Serializable, QueryExp

public class ObjectName
extends Object
implements Serializable, QueryExp

An ObjectName instance represents the name of a management bean, or a pattern which may match the name of one or more management beans. Patterns are distinguished from names by the presence of the '?' and '*' characters (which match a single character and a series of zero or more characters, respectively).

Each name begins with a domain element, which is terminated by a ':' character. The domain may be empty. If so, it will be replaced by the default domain of the bean server in certain contexts. The domain is a pattern, if it contains either '?' or '*'. To avoid collisions, it is usual to use reverse DNS names for the domain, as in Java package and property names.

Following the ':' character is a series of properties. The list is separated by commas, and largely consists of unordered key-value pairs, separated by an equals sign ('='). At most one element may be an asterisk ('*'), which turns the ObjectName instance into a property list pattern. In this situation, the pattern matches a name if the name contains at least those key-value pairs given and has the same domain.

A key is a string of characters which doesn't include any of those used as delimiters or in patterns (':', '=', ',', '?' and '*'). Keys must be unique.

A value may be quoted or unquoted. Unquoted values obey the same rules as given for keys above. Quoted values are surrounded by quotation marks ("), and use a backslash ('\') character to include quotes ('\"'), backslashes ('\\'), newlines ('\n'), and the pattern characters ('\?' and '\*'). The quotes and backslashes (after expansion) are considered part of the value.

Both quoted and unquoted values may contain the wildcard characters '?' and '*'. A name with at least one value containing a wildcard character is known as a property value pattern. A name is generally a property pattern if it is either a property list pattern or property value pattern.

Spaces are maintained within the different parts of the name. Thus, 'domain: key1 = value1 ' has a key ' key1 ' with value ' value1 '. Newlines are disallowed, except where escaped in quoted values.

Since:
1.5
See Also:
Serialized Form

Field Summary
static ObjectName WILDCARD
          The wildcard ObjectName "*:*"
 
Constructor Summary
ObjectName(String name)
          Constructs an ObjectName instance from the given string, which should be of the form <domain>:<properties><wild>.
ObjectName(String domain, Hashtable<String,String> properties)
          Constructs an ObjectName instance using the given domain and properties.
ObjectName(String domain, String key, String value)
          Constructs an ObjectName instance using the given domain and the one specified property.
 
Method Summary
 boolean apply(ObjectName name)
           Attempts to find a match between this name and the one supplied.
 boolean equals(Object obj)
          Compares the specified object with this one.
 String getCanonicalKeyPropertyListString()
          Returns the property list in canonical form.
 String getCanonicalName()
           Returns the name as a string in canonical form.
 String getDomain()
          Returns the domain part of the object name.
static ObjectName getInstance(ObjectName name)
          Returns an ObjectName instance that is substitutable for the one given.
static ObjectName getInstance(String name)
          Returns an ObjectName instance for the specified name, represented as a String.
static ObjectName getInstance(String domain, Hashtable<String,String> properties)
          Returns an ObjectName instance for the specified name, represented as a domain String and a table of properties.
static ObjectName getInstance(String domain, String key, String value)
          Returns an ObjectName instance for the specified name, represented as a series of String objects for the domain and a single property, as a key-value pair.
 String getKeyProperty(String key)
          Returns the property value corresponding to the given key.
 Hashtable<String,String> getKeyPropertyList()
          Returns the properties in a Hashtable.
 String getKeyPropertyListString()
          Returns a String representation of the property list.
 int hashCode()
          Returns a hash code for this object name.
 boolean isDomainPattern()
          Returns true if the domain of this object name is a pattern.
 boolean isPattern()
          Returns true if this is an object name pattern.
 boolean isPropertyListPattern()
          Returns true if this object name is a property list pattern.
 boolean isPropertyPattern()
          Returns true if this object name is a property list pattern, a property value pattern or both.
 boolean isPropertyValuePattern()
          Returns true if this object name is a property value pattern.
 boolean isPropertyValuePattern(String key)
          Returns true if the value of the given key is a pattern.
static String quote(String string)
           Returns a quoted version of the supplied string.
 void setMBeanServer(MBeanServer server)
          Changes the MBeanServer on which this query is performed.
 String toString()
          Returns a textual representation of the object name.
static String unquote(String q)
          Unquotes the supplied string.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

WILDCARD

public static final ObjectName WILDCARD
The wildcard ObjectName "*:*"

Since:
1.6
Constructor Detail

ObjectName

public ObjectName(String name)
           throws MalformedObjectNameException
Constructs an ObjectName instance from the given string, which should be of the form <domain>:<properties><wild>. <domain> represents the domain section of the name. <properties> represents the key-value pairs, as returned by getKeyPropertyListString(). <wild> is the optional asterisk present in the property list. If the string doesn't represent a property pattern, it will be empty. If it does, it will be either ',*' or '*', depending on whether other properties are present or not, respectively.

Parameters:
name - the string to use to construct this instance.
Throws:
MalformedObjectNameException - if the string is of the wrong format.
NullPointerException - if name is null.

ObjectName

public ObjectName(String domain,
                  String key,
                  String value)
           throws MalformedObjectNameException
Constructs an ObjectName instance using the given domain and the one specified property.

Parameters:
domain - the domain part of the object name.
key - the key of the property.
value - the value of the property.
Throws:
MalformedObjectNameException - the domain, key or value contains an illegal character or the value does not follow the quoting specifications.
NullPointerException - if one of the parameters is null.

ObjectName

public ObjectName(String domain,
                  Hashtable<String,String> properties)
           throws MalformedObjectNameException
Constructs an ObjectName instance using the given domain and properties.

Parameters:
domain - the domain part of the object name.
properties - the key-value property pairs.
Throws:
MalformedObjectNameException - the domain, a key or a value contains an illegal character or a value does not follow the quoting specifications.
NullPointerException - if one of the parameters is null.
Method Detail

apply

public boolean apply(ObjectName name)

Attempts to find a match between this name and the one supplied. The following criteria are used:

Specified by:
apply in interface QueryExp
Parameters:
name - the name to find a match with.
Returns:
true if the name either matches this pattern or is equivalent to this name under the criteria of equals(java.lang.Object)
Throws:
NullPointerException - if name is null.

equals

public boolean equals(Object obj)
Compares the specified object with this one. The two are judged to be equivalent if the given object is an instance of ObjectName and has an equal canonical form (as returned by getCanonicalName()).

Overrides:
equals in class Object
Parameters:
obj - the object to compare with this.
Returns:
true if the object is also an ObjectName with an equivalent canonical form.
See Also:
Object.hashCode()

getCanonicalKeyPropertyListString

public String getCanonicalKeyPropertyListString()
Returns the property list in canonical form. The keys are ordered using the lexicographic ordering used by Comparable.compareTo(java.lang.Object).

Returns:
the property list, with the keys in lexicographic order.

getCanonicalName

public String getCanonicalName()

Returns the name as a string in canonical form. More precisely, this returns a string of the format <domain>:<properties><wild>. <properties> is the same value as returned by getCanonicalKeyPropertyListString(). <wild> is:

Returns:
the canonical string form of the object name, as specified above.

getDomain

public String getDomain()
Returns the domain part of the object name.

Returns:
the domain.

getInstance

public static ObjectName getInstance(ObjectName name)
Returns an ObjectName instance that is substitutable for the one given. The instance returned may be a subclass of ObjectName, but is not guaranteed to be of the same type as the given name, if that should also turn out to be a subclass. The returned instance may or may not be equivalent to the one given. The purpose of this method is to provide an instance of ObjectName with a well-defined semantics, such as may be used in cases where the given name is not trustworthy.

Parameters:
name - the ObjectName to provide a substitute for.
Returns:
a substitute for the given name, which may or may not be a subclass of ObjectName. In either case, the returned object is guaranteed to have the semantics defined here.
Throws:
NullPointerException - if name is null.

getInstance

public static ObjectName getInstance(String name)
                              throws MalformedObjectNameException
Returns an ObjectName instance for the specified name, represented as a String. The instance returned may be a subclass of ObjectName and may or may not be equivalent to earlier instances returned by this method for the same string.

Parameters:
name - the ObjectName to provide an instance of.
Returns:
a instance for the given name, which may or may not be a subclass of ObjectName.
Throws:
MalformedObjectNameException - the domain, a key or a value contains an illegal character or a value does not follow the quoting specifications.
NullPointerException - if name is null.

getInstance

public static ObjectName getInstance(String domain,
                                     String key,
                                     String value)
                              throws MalformedObjectNameException
Returns an ObjectName instance for the specified name, represented as a series of String objects for the domain and a single property, as a key-value pair. The instance returned may be a subclass of ObjectName and may or may not be equivalent to earlier instances returned by this method for the same parameters.

Parameters:
domain - the domain part of the object name.
key - the key of the property.
value - the value of the property.
Returns:
a instance for the given name, which may or may not be a subclass of ObjectName.
Throws:
MalformedObjectNameException - the domain, a key or a value contains an illegal character or a value does not follow the quoting specifications.
NullPointerException - if name is null.

getInstance

public static ObjectName getInstance(String domain,
                                     Hashtable<String,String> properties)
                              throws MalformedObjectNameException
Returns an ObjectName instance for the specified name, represented as a domain String and a table of properties. The instance returned may be a subclass of ObjectName and may or may not be equivalent to earlier instances returned by this method for the same string.

Parameters:
domain - the domain part of the object name.
properties - the key-value property pairs.
Returns:
a instance for the given name, which may or may not be a subclass of ObjectName.
Throws:
MalformedObjectNameException - the domain, a key or a value contains an illegal character or a value does not follow the quoting specifications.
NullPointerException - if name is null.

getKeyProperty

public String getKeyProperty(String key)
Returns the property value corresponding to the given key.

Parameters:
key - the key of the property to be obtained.
Returns:
the value of the specified property.
Throws:
NullPointerException - if key is null.

getKeyPropertyList

public Hashtable<String,String> getKeyPropertyList()
Returns the properties in a Hashtable. The table contains each of the properties as keys mapped to their value. The returned table is not unmodifiable, but changes made to it will not be reflected in the object name.

Returns:
a Hashtable, containing each of the object name's properties.

getKeyPropertyListString

public String getKeyPropertyListString()
Returns a String representation of the property list. If the object name was created using ObjectName(String), then this string will contain the properties in the same order they were given in at creation.

Returns:
the property list.

hashCode

public int hashCode()
Returns a hash code for this object name. This is calculated as the summation of the hash codes of the domain and the properties.

Overrides:
hashCode in class Object
Returns:
a hash code for this object name.
See Also:
Object.equals(Object), System.identityHashCode(Object)

isDomainPattern

public boolean isDomainPattern()
Returns true if the domain of this object name is a pattern. This is the case if it contains one or more wildcard characters ('*' or '?').

Returns:
true if the domain is a pattern.

isPattern

public boolean isPattern()
Returns true if this is an object name pattern. An object name pattern has a domain containing a wildcard character ('*' or '?') and/or a '*' in the list of properties. This method will return true if either isDomainPattern() or isPropertyPattern() does.

Returns:
true if this is an object name pattern.

isPropertyPattern

public boolean isPropertyPattern()
Returns true if this object name is a property list pattern, a property value pattern or both.

Returns:
true if the properties of this name contain a pattern.
See Also:
isPropertyListPattern(), isPropertyValuePattern()

isPropertyListPattern

public boolean isPropertyListPattern()
Returns true if this object name is a property list pattern. This is the case if the list of properties contains an '*'.

Returns:
true if this is a property list pattern.
Since:
1.6

isPropertyValuePattern

public boolean isPropertyValuePattern()
Returns true if this object name is a property value pattern. This is the case if one of the values contains a wildcard character, '?' or '*'.

Returns:
true if this is a property value pattern.
Since:
1.6

isPropertyValuePattern

public boolean isPropertyValuePattern(String key)
Returns true if the value of the given key is a pattern. This is the case if the value contains a wildcard character, '?' or '*'.

Parameters:
key - the key whose value should be checked.
Returns:
true if the value of the given key is a pattern.
Throws:
NullPointerException - if key is null.
IllegalArgumentException - if key is not a valid property.
Since:
1.6

quote

public static String quote(String string)

Returns a quoted version of the supplied string. The string may contain any character. The resulting quoted version is guaranteed to be usable as the value of a property, so this method provides a good way of ensuring that a value is legal.

The string is transformed as follows:

Parameters:
string - the string to quote.
Returns:
a quoted version of the supplied string.
Throws:
NullPointerException - if string is null.

setMBeanServer

public void setMBeanServer(MBeanServer server)
Changes the MBeanServer on which this query is performed.

Specified by:
setMBeanServer in interface QueryExp
Parameters:
server - the new server to use.

toString

public String toString()
Returns a textual representation of the object name.

The format is unspecified beyond that equivalent object names will return the same string from this method, but note that Tomcat depends on the string returned by this method being a valid textual representation of the object name and will fail to start if it is not.

Overrides:
toString in class Object
Returns:
a textual representation of the object name.
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

unquote

public static String unquote(String q)
Unquotes the supplied string. The quotation marks are removed as are the backslashes preceding the escaped characters ('"', '?', '*', '\n', '\\'). A one-to-one mapping exists between quoted and unquoted values. As a result, a string s should be equal to unquote(quote(s)).

Parameters:
q - the quoted string to unquote.
Returns:
the unquoted string.
Throws:
NullPointerException - if q is null.
IllegalArgumentException - if the string is not a valid quoted string i.e. it is not surrounded by quotation marks and/or characters are not properly escaped.