ObjectName (GNU Classpath 0.94-pre Documentation)

An {@link 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 {@link ObjectName} instance into a property 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.

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

Constructor Summary
	ObjectName(String name) Constructs an {@link ObjectName} instance from the given string, which should be of the form <domain>:<properties><wild>.
	ObjectName(String domain, String key, String value) Constructs an {@link ObjectName} instance using the given domain and the one specified property.
	ObjectName(String domain, Hashtable<String,String> properties) Constructs an {@link ObjectName} instance using the given domain and properties.

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 {@link ObjectName} instance that is substitutable for the one given.
static ObjectName	getInstance(String name) Returns an {@link ObjectName} instance for the specified name, represented as a {@link java.lang.String}.
static ObjectName	getInstance(String domain, String key, String value) Returns an {@link ObjectName} instance for the specified name, represented as a series of {@link java.lang.String} objects for the domain and a single property, as a key-value pair.
static ObjectName	getInstance(String domain, Hashtable<String,String> properties) Returns an {@link ObjectName} instance for the specified name, represented as a domain {@link java.lang.String} and a table of properties.
String	getKeyProperty(String key) Returns the property value corresponding to the given key.
Hashtable<String,String>	getKeyPropertyList() Returns the properties in a {@link java.util.Hashtable}.
String	getKeyPropertyListString() Returns a {@link java.lang.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	isPropertyPattern() Returns true if this object name is a property pattern.
static String	quote(String string) Returns a quoted version of the supplied string.
void	setMBeanServer(MBeanServer server) Changes the {@link 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.

Constructor Detail

ObjectName

Constructs an {@link 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 {@link #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

Constructs an {@link 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

Constructs an {@link 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

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

If the supplied name is a pattern, false is returned.
If this name is a pattern, this method returns true if the supplied name matches the pattern.
If this name is not a pattern, the result of equals(name) is returned.

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 {@link #equals(java.lang.Object)}

Throws: NullPointerException if name is null.

equals

Compares the specified object with this one. The two are judged to be equivalent if the given object is an instance of {@link ObjectName} and has an equal canonical form (as returned by {@link #getCanonicalName()}).

Parameters: obj the object to compare with this.

Returns: true if the object is also an {@link ObjectName} with an equivalent canonical form.

getCanonicalKeyPropertyListString

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 {@link #getCanonicalKeyPropertyListString()}. <wild> is:

an empty string, if the object name is not a property pattern.
'*' if <properties> is empty.
',*' if there is at least one key-value pair.

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

getDomain

getInstance

Returns an {@link ObjectName} instance that is substitutable for the one given. The instance returned may be a subclass of {@link 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 {@link ObjectName} with a well-defined semantics, such as may be used in cases where the given name is not trustworthy.

Parameters: name the {@link ObjectName} to provide a substitute for.

Returns: a substitute for the given name, which may or may not be a subclass of {@link ObjectName}. In either case, the returned object is guaranteed to have the semantics defined here.

Throws: NullPointerException if name is null.

getInstance

Returns an {@link ObjectName} instance for the specified name, represented as a {@link java.lang.String}. The instance returned may be a subclass of {@link ObjectName} and may or may not be equivalent to earlier instances returned by this method for the same string.

Parameters: name the {@link ObjectName} to provide an instance of.

Returns: a instance for the given name, which may or may not be a subclass of {@link 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

Returns an {@link ObjectName} instance for the specified name, represented as a series of {@link java.lang.String} objects for the domain and a single property, as a key-value pair. The instance returned may be a subclass of {@link 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 {@link 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

Returns an {@link ObjectName} instance for the specified name, represented as a domain {@link java.lang.String} and a table of properties. The instance returned may be a subclass of {@link 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 {@link 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

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

getKeyPropertyListString

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:

The string is prefixed with an opening quote character, '"'.
For each character, s:
- If s is a quote ('"'), it is replaced by a backslash followed by a quote.
- If s is a star ('*'), it is replaced by a backslash followed by a star.
- If s is a question mark ('?'), it is replaced by a backslash followed by a question mark.
- If s is a backslash ('\'), it is replaced by two backslashes.
- If s is a newline character, it is replaced by a backslash followed by a '\n'.
- Otherwise, s is used verbatim.
The string is terminated with a closing quote character, '"'.

Parameters: string the string to quote.

Returns: a quoted version of the supplied string.

Throws: NullPointerException if string is null.

setMBeanServer

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.

Returns: a textual representation of the object name.

unquote

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.

Class ObjectName