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
A
A value may be
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
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.
Modifier and Type | Field and Description |
---|---|
static ObjectName |
WILDCARD
The wildcard
ObjectName "*:*" |
Constructor and Description |
---|
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. |
Modifier and Type | Method and Description |
---|---|
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.
|
public static final ObjectName WILDCARD
ObjectName
"*:*"
public ObjectName(String name) throws MalformedObjectNameException
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.name
- the string to use to construct this instance.MalformedObjectNameException
- if the string is of the
wrong format.NullPointerException
- if name
is
null
.public ObjectName(String domain, String key, String value) throws MalformedObjectNameException
ObjectName
instance using the given
domain and the one specified property.domain
- the domain part of the object name.key
- the key of the property.value
- the value of the property.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
.public ObjectName(String domain, Hashtable<String,String> properties) throws MalformedObjectNameException
ObjectName
instance using the given
domain and properties.domain
- the domain part of the object name.properties
- the key-value property pairs.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
.public boolean apply(ObjectName name)
Attempts to find a match between this name and the one supplied. The following criteria are used:
false
is
returned.true
if the supplied name matches the pattern.equals(name)
is returned.
apply
in interface QueryExp
name
- the name to find a match with.equals(java.lang.Object)
NullPointerException
- if name
is null
.public boolean equals(Object obj)
ObjectName
and has an equal canonical
form (as returned by getCanonicalName()
).equals
in class Object
obj
- the object to compare with this.ObjectName
with an equivalent canonical form.Object.hashCode()
public String getCanonicalKeyPropertyListString()
Comparable.compareTo(java.lang.Object)
.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:
public static ObjectName getInstance(ObjectName name)
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.name
- the ObjectName
to provide a substitute for.ObjectName
. In either case, the returned object is
guaranteed to have the semantics defined here.NullPointerException
- if name
is null
.public static ObjectName getInstance(String name) throws MalformedObjectNameException
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.name
- the ObjectName
to provide an instance of.ObjectName
.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
.public static ObjectName getInstance(String domain, String key, String value) throws MalformedObjectNameException
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.domain
- the domain part of the object name.key
- the key of the property.value
- the value of the property.ObjectName
.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
.public static ObjectName getInstance(String domain, Hashtable<String,String> properties) throws MalformedObjectNameException
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.domain
- the domain part of the object name.properties
- the key-value property pairs.ObjectName
.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
.public String getKeyProperty(String key)
key
- the key of the property to be obtained.NullPointerException
- if key
is null
.public Hashtable<String,String> getKeyPropertyList()
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.Hashtable
, containing each of the object
name's properties.public String getKeyPropertyListString()
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.public int hashCode()
hashCode
in class Object
Object.equals(Object)
,
System.identityHashCode(Object)
public boolean isDomainPattern()
public boolean isPattern()
isDomainPattern()
or isPropertyPattern()
does.public boolean isPropertyPattern()
isPropertyListPattern()
,
isPropertyValuePattern()
public boolean isPropertyListPattern()
public boolean isPropertyValuePattern()
public boolean isPropertyValuePattern(String key)
key
- the key whose value should be checked.NullPointerException
- if key
is null
.IllegalArgumentException
- if key
is not a valid
property.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:
string
- the string to quote.NullPointerException
- if string
is null
.public void setMBeanServer(MBeanServer server)
MBeanServer
on which this query is performed.setMBeanServer
in interface QueryExp
server
- the new server to use.public String toString()
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.
toString
in class Object
Object.getClass()
,
Object.hashCode()
,
Class.getName()
,
Integer.toHexString(int)
public static String unquote(String q)
s
should be
equal to unquote(quote(s))
.q
- the quoted string to unquote.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.