Overview Package Class Use Source Tree Index Deprecated About
Prev Class | Next ClassFrames | No Frames
Summary: Nested | Field | Method | ConstrDetail: Nested | Field | Method | Constr

javax.management

Class ObjectName

Implemented Interfaces:
QueryExp, Serializable
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 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(String name)
Returns an ObjectName instance for the specified name, represented as a String.
static ObjectName
getInstance(String domain, Hashtable 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.
static ObjectName
getInstance(ObjectName name)
Returns an ObjectName instance that is substitutable for the one given.
String
getKeyProperty(String key)
Returns the property value corresponding to the given key.
Hashtable
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, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

WILDCARD

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

Constructor Details

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,
                  Hashtable 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.

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.

Method Details

apply

public boolean apply(ObjectName name)
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.
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(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 interface Object
Parameters:
obj - the object to compare with this.
Returns:
true if the object is also an ObjectName with an equivalent canonical form.

getCanonicalKeyPropertyListString

public String getCanonicalKeyPropertyListString()
Returns the property list in canonical form. The keys are ordered using the lexicographic ordering used by java.lang.String.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:
  • 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

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

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,
                                     Hashtable 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.

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(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.

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 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 interface Object
Returns:
a hash code for this object name.

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.

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

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

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:

  • 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

    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 interface Object
    Returns:
    a textual representation of the object name.

    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.
    ObjectName.java -- Represent the name of a bean, or a pattern for a name. Copyright (C) 2006, 2007 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

    Overview Package Class Use Source Tree Index Deprecated About