javax.management
public class: ObjectName [javadoc |
source]
java.lang.Object
javax.management.ObjectName
All Implemented Interfaces:
QueryExp, Comparable
Represents the object name of an MBean, or a pattern that can
match the names of several MBeans. Instances of this class are
immutable.
An instance of this class can be used to represent:
- An object name
- An object name pattern, within the context of a query
An object name consists of two parts, the domain and the key
properties.
The domain is a string of characters not including
the character colon (:
). It is recommended that the domain
should not contain the string "{@code //}", which is reserved for future use.
If the domain includes at least one occurrence of the wildcard
characters asterisk (*
) or question mark
(?
), 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.
If the domain is empty, it will be replaced in certain contexts
by the default domain of the MBean server in which the
ObjectName is used.
The key properties are an unordered set of keys and
associated values.
Each key is a nonempty string of characters which may
not contain any of the characters comma (,
), equals
(=
), colon, asterisk, or question mark. The same key
may not occur twice in a given ObjectName.
Each value associated with a key is a string of
characters that is either unquoted or quoted.
An unquoted value is a possibly empty string of
characters which may not contain any of the characters comma,
equals, colon, or quote.
If the unquoted value contains at least one occurrence
of the wildcard characters asterisk or question mark, then the object
name is a property value pattern. The asterisk matches any
sequence of zero or more characters, while the question mark matches
any single character.
A quoted value consists of a quote ("
),
followed by a possibly empty string of characters, followed by
another quote. Within the string of characters, the backslash
(\
) has a special meaning. It must be followed by
one of the following characters:
- Another backslash. The second backslash has no special
meaning and the two characters represent a single backslash.
- The character 'n'. The two characters represent a newline
('\n' in Java).
- 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.
- A question mark (?) or asterisk (*). The two characters represent
a question mark or asterisk respectively.
A quote may not appear inside a quoted value except immediately
after an odd number of consecutive backslashes.
The quotes surrounding a quoted value, and any backslashes
within that value, are considered to be part of the value.
If the quoted value contains at least one occurrence of
the characters asterisk or question mark and they are not preceded
by a backslash, then they are considered as wildcard characters and
the object name is a property value pattern. The asterisk
matches any sequence of zero or more characters, while the question
mark matches any single character.
An ObjectName may be a property list pattern. 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.
An ObjectName is a property value pattern when at least
one of its quoted or unquoted key property values
contains the wildcard characters asterisk or question mark as described
above. In this case it has one or more keys and associated values, with
at least one of the values containing wildcard characters. It matches a
nonpattern ObjectName whose domain matches and that contains the same
keys whose values match; if the property value pattern is also a
property list pattern then the nonpattern ObjectName can contain
other keys and values.
An ObjectName is a property pattern if it is either a
property list pattern or a property value pattern
or both.
An ObjectName is a pattern if its domain contains a wildcard or
if the ObjectName is a property pattern.
If an ObjectName is not a pattern, it must contain at least one
key with its associated value.
Examples of ObjectName patterns are:
- {@code *:type=Foo,name=Bar} to match names in any domain whose
exact set of keys is {@code type=Foo,name=Bar}.
- {@code d:type=Foo,name=Bar,*} to match names in the domain
{@code d} that have the keys {@code type=Foo,name=Bar} plus
zero or more other keys.
- {@code *:type=Foo,name=Bar,*} to match names in any domain
that has the keys {@code type=Foo,name=Bar} plus zero or
more other keys.
- {@code d:type=F?o,name=Bar} will match e.g.
{@code d:type=Foo,name=Bar} and {@code d:type=Fro,name=Bar}.
- {@code d:type=F*o,name=Bar} will match e.g.
{@code d:type=Fo,name=Bar} and {@code d:type=Frodo,name=Bar}.
- {@code d:type=Foo,name="B*"} will match e.g.
{@code d:type=Foo,name="Bling"}. Wildcards are recognized even
inside quotes, and like other special characters can be escaped
with {@code \}.
An ObjectName can be written as a String with the following
elements in order:
- The domain.
- A colon (
:
).
- A key property list as defined below.
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
(=
), and the associated value.
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 list pattern.
Spaces have no special significance in a String representing an
ObjectName. For example, the String:
domain: key1 = value1 , key2 = value2
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
" key1 "
also begins and ends with a space.
In addition to the restrictions on characters spelt out above,
no part of an ObjectName may contain a newline character
('\n'
), 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 \n
.
The rules on special characters and quoting apply regardless of
which constructor is used to make an ObjectName.
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
example.com
would have
domains such as com.example.MyDomain
. This is essentially
the same convention as for Java-language package names.
The serialVersionUID of this class is 1081892073854801359L
.
Field Summary |
---|
public static final ObjectName | WILDCARD | Defines the wildcard "*:*" ObjectName. |
Constructor: |
public ObjectName(String name) throws MalformedObjectNameException {
construct(name);
}
Construct an object name from the given string. Parameters:
name - A string representation of the object name.
Throws:
MalformedObjectNameException - The string passed as a
parameter does not have the right format.
NullPointerException - The name parameter
is null.
- exception:
MalformedObjectNameException - The string passed as a
parameter does not have the right format.
- exception:
NullPointerException - The name parameter
is null.
|
public ObjectName(String domain,
Hashtable<String, String> table) throws MalformedObjectNameException {
construct(domain, table);
/* The exception for when a key or value in the table is not a
String is now ClassCastException rather than
MalformedObjectNameException. This was not previously
specified. */
}
Construct an object name with several key properties from a Hashtable. Parameters:
domain - The domain part of the object name.
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.
Throws:
MalformedObjectNameException - The domain
contains an illegal character, or one of the keys or values in
table contains an illegal character, or one of the
values in table does not follow the rules for
quoting.
NullPointerException - One of the parameters is null.
- exception:
MalformedObjectNameException - The domain
contains an illegal character, or one of the keys or values in
table contains an illegal character, or one of the
values in table 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 {
// If key or value are null a NullPointerException
// will be thrown by the put method in Hashtable.
//
Map< String,String > table = Collections.singletonMap(key, value);
construct(domain, table);
}
Construct an object name with exactly one key property. Parameters:
domain - The domain part of the object name.
key - The attribute in the key property of the object name.
value - The value in the key property of the object name.
Throws:
MalformedObjectNameException - The
domain , key , or value
contains an illegal character, or value does not
follow the rules for quoting.
NullPointerException - One of the parameters is null.
- exception:
MalformedObjectNameException - The
domain , key , or value
contains an illegal character, or value does not
follow the rules for quoting.
- exception:
NullPointerException - One of the parameters is null.
|
Method from javax.management.ObjectName Summary: |
---|
apply, compareTo, equals, getCanonicalKeyPropertyListString, getCanonicalName, getDomain, getInstance, getInstance, getInstance, getInstance, getKeyProperty, getKeyPropertyList, getKeyPropertyListString, hashCode, isDomainPattern, isPattern, isPropertyListPattern, isPropertyPattern, isPropertyValuePattern, isPropertyValuePattern, quote, setMBeanServer, toString, unquote |
Methods from java.lang.Object: |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method from javax.management.ObjectName Detail: |
public boolean apply(ObjectName name) {
if (name == null) throw new NullPointerException();
if (name._domain_pattern ||
name._property_list_pattern ||
name._property_value_pattern)
return false;
// No pattern
if (!_domain_pattern &&
!_property_list_pattern &&
!_property_value_pattern)
return _canonicalName.equals(name._canonicalName);
return matchDomains(name) && matchKeys(name);
}
Test whether this ObjectName, which may be a pattern,
matches another ObjectName. If name is a pattern,
the result is false. If this ObjectName is a pattern, the
result is true if and only if name matches the
pattern. If neither this ObjectName nor name is
a pattern, the result is true if and only if the two
ObjectNames are equal as described for the #equals(Object) method.
|
public int compareTo(ObjectName name) {
// Quick optimization:
//
if (name == this) return 0;
// (1) Compare domains
//
int domainValue = this.getDomain().compareTo(name.getDomain());
if (domainValue != 0)
return domainValue;
// (2) Compare "type=" keys
//
// Within a given domain, all names with missing or empty "type="
// come before all names with non-empty type.
//
// When both types are missing or empty, canonical-name ordering
// applies which is a total order.
//
String thisTypeKey = this.getKeyProperty("type");
String anotherTypeKey = name.getKeyProperty("type");
if (thisTypeKey == null)
thisTypeKey = "";
if (anotherTypeKey == null)
anotherTypeKey = "";
int typeKeyValue = thisTypeKey.compareTo(anotherTypeKey);
if (typeKeyValue != 0)
return typeKeyValue;
// (3) Compare canonical names
//
return this.getCanonicalName().compareTo(name.getCanonicalName());
}
Compares two ObjectName instances. The ordering relation between
ObjectNames is not completely specified but is intended to be such
that a sorted list of ObjectNames will appear in an order that is
convenient for a person to read.
In particular, if the two ObjectName instances have different
domains then their order is the lexicographical order of the domains.
The ordering of the key property list remains unspecified.
For example, the ObjectName instances below:
- Shapes:type=Square,name=3
- Colors:type=Red,name=2
- Shapes:type=Triangle,side=isosceles,name=2
- Colors:type=Red,name=1
- Shapes:type=Square,name=1
- Colors:type=Blue,name=1
- Shapes:type=Square,name=2
- JMImplementation:type=MBeanServerDelegate
- Shapes:type=Triangle,side=scalene,name=1
could be ordered as follows:
- Colors:type=Blue,name=1
- Colors:type=Red,name=1
- Colors:type=Red,name=2
- JMImplementation:type=MBeanServerDelegate
- Shapes:type=Square,name=1
- Shapes:type=Square,name=2
- Shapes:type=Square,name=3
- Shapes:type=Triangle,side=scalene,name=1
- Shapes:type=Triangle,side=isosceles,name=2
|
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; // ES: OK
// Because we are sharing canonical form between object names,
// we have finished the comparison at this stage == > unequal
return false;
}
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 #getCanonicalName() . |
public String getCanonicalKeyPropertyListString() {
if (_ca_array.length == 0) return "";
int len = _canonicalName.length();
if (_property_list_pattern) len -= 2;
return _canonicalName.substring(_domain_length +1, len);
}
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 String.compareTo(String) . |
public String getCanonicalName() {
return _canonicalName;
}
Returns the canonical form of the name; that is, a string
representation where the properties are sorted in lexical
order.
More precisely, the canonical form of the name is a String
consisting of the domain part, a colon
(: ), the canonical key property list, and
a pattern indication.
The canonical key property list is the same string
as described for #getCanonicalKeyPropertyListString() .
The pattern indication is:
- empty for an ObjectName
that is not a property list pattern;
- an asterisk for an ObjectName
that is a property list pattern with no keys; or
- a comma and an
asterisk (
,* ) for an ObjectName that is a property
list pattern with at least one key.
|
public String getDomain() {
return _canonicalName.substring(0, _domain_length);
}
|
public static ObjectName getInstance(String name) throws MalformedObjectNameException, NullPointerException {
return new ObjectName(name);
}
Return an instance of ObjectName that can be used anywhere
an object obtained with 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.
|
public static ObjectName getInstance(ObjectName name) {
if (name.getClass().equals(ObjectName.class))
return name;
return Util.newObjectName(name.getSerializedNameString());
}
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 name is of a subclass
of ObjectName, it is not guaranteed that the returned object
will be of the same class.
The returned value may or may not be identical to
name . Calling this method twice with the same
parameters may return the same object or two equal but not
identical objects.
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 behavior to sensitive
code. Such code can call this method to obtain an ObjectName
that is known not to have surprising behavior.
|
public static ObjectName getInstance(String domain,
Hashtable<String, String> table) throws MalformedObjectNameException {
return new ObjectName(domain, table);
}
Return an instance of ObjectName that can be used anywhere
an object obtained with Hashtable)
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.
|
public static ObjectName getInstance(String domain,
String key,
String value) throws MalformedObjectNameException {
return new ObjectName(domain, key, value);
}
Return an instance of ObjectName that can be used anywhere
an object obtained with 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.
|
public String getKeyProperty(String property) {
return _getKeyPropertyList().get(property);
}
Obtains the value associated with a key in a key property. |
public Hashtable<String, String> getKeyPropertyList() {
return new Hashtable< String,String >(_getKeyPropertyList());
}
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.
The returned value may be unmodifiable. If it is
modifiable, changing it has no effect on this ObjectName.
|
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
final int total_size = _canonicalName.length() - _domain_length - 1
- (_property_list_pattern?2:0);
final char[] dest_chars = new char[total_size];
final char[] value = _canonicalName.toCharArray();
writeKeyPropertyListString(value,dest_chars,0);
return new String(dest_chars);
}
Returns a string representation of the list of key
properties specified at creation time. If this ObjectName was
constructed with the constructor #ObjectName(String) ,
the key properties in the returned String will be in the same
order as in the argument to the constructor.
|
public int hashCode() {
return _canonicalName.hashCode();
}
Returns a hash code for this object name. |
public boolean isDomainPattern() {
return _domain_pattern;
}
Checks whether the object name is a pattern on the domain part. |
public boolean isPattern() {
return (_domain_pattern ||
_property_list_pattern ||
_property_value_pattern);
}
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. |
public boolean isPropertyListPattern() {
return _property_list_pattern;
}
Checks whether the object name is a pattern on the key property list.
For example, "d:k=v,*" and "d:k=*,*" are key property list patterns
whereas "d:k=*" is not. |
public boolean isPropertyPattern() {
return _property_list_pattern || _property_value_pattern;
}
Checks whether the object name is a pattern on the key properties.
An object name is a pattern on the key properties if it is a
pattern on the key property list (e.g. "d:k=v,*") or on the
property values (e.g. "d:k=*") or on both (e.g. "d:k=*,*"). |
public boolean isPropertyValuePattern() {
return _property_value_pattern;
}
Checks whether the object name is a pattern on the value part
of at least one of the key properties.
For example, "d:k=*" and "d:k=*,*" are property value patterns
whereas "d:k=v,*" is not. |
public boolean isPropertyValuePattern(String property) {
if (property == null)
throw new NullPointerException("key property can't be null");
for (int i = 0; i < _ca_array.length; i++) {
Property prop = _ca_array[i];
String key = prop.getKeyString(_canonicalName);
if (key.equals(property))
return (prop instanceof PatternProperty);
}
throw new IllegalArgumentException("key property not found");
}
Checks whether the value associated with a key in a key
property is a pattern. |
public static String quote(String s) {
final StringBuilder buf = new StringBuilder("\"");
final int len = s.length();
for (int i = 0; i < len; i++) {
char c = s.charAt(i);
switch (c) {
case '\n':
c = 'n';
buf.append('\\');
break;
case '\\':
case '\"':
case '*':
case '?':
buf.append('\\');
break;
}
buf.append(c);
}
buf.append('"');
return buf.toString();
}
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
s may contain any character. Appropriate quoting
ensures that the returned value is legal in an ObjectName.
The returned value consists of a quote ('"'), a sequence of
characters corresponding to the characters of s ,
and another quote. Characters in s appear
unchanged within the returned value except:
- A quote ('"') is replaced by a backslash (\) followed by a quote.
- An asterisk ('*') is replaced by a backslash (\) followed by an
asterisk.
- A question mark ('?') is replaced by a backslash (\) followed by
a question mark.
- A backslash ('\') is replaced by two backslashes.
- A newline character (the character '\n' in Java) is replaced
by a backslash followed by the character '\n'.
|
public void setMBeanServer(MBeanServer mbs) {
}
|
public String toString() {
return getSerializedNameString();
}
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.
|
public static String unquote(String q) {
final StringBuilder buf = new StringBuilder();
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");
}
}
buf.append(c);
}
return buf.toString();
}
Returns an unquoted form of the given String. If
q is a String returned by quote(s) ,
then unquote(q).equals(s) . If there is no String
s for which quote(s).equals(q) , then
unquote(q) throws an IllegalArgumentException.
These rules imply that there is a one-to-one mapping between
quoted and unquoted forms.
|