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 consists of two parts, the domain and the key properties.
The domain is a string of characters not including
the character colon (:).
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, quote, asterisk, or question mark.
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:
A quote, question mark, or star 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.
An ObjectName may be a property 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 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.
An ObjectName can be written as a String with the following elements in order:
:).
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 pattern.
Spaces have no special significance in a String representing an ObjectName. For example, the String:
domain: key1 = value1 , key2 = value2represents 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
Sun Microsystems Inc., DNS name sun.com, would have
domains such as com.sun.MyDomain. This is essentially
the same convention as for Java-language package names.
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 .
The pattern indication is:
,*) for an ObjectName that is a property
pattern with at least one key.
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.
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.
Return an instance of ObjectName that can be used anywhere an object obtained with 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.
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.
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.
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized statement
that synchronizes on the object.
Class, by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
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:
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.
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify method
or the notifyAll method.
timeout
milliseconds plus nanos nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.