ObjectName.java revision 528
381N/A * Copyright 1999-2008 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * <p>Represents the object name of an MBean, or a pattern that can 0N/A * match the names of several MBeans. Instances of this class are 0N/A * <p>An instance of this class can be used to represent:</p> 0N/A * <li>An object name</li> 0N/A * <li>An object name pattern, within the context of a query</li> 0N/A * <p>An object name consists of two parts, the domain and the key 0N/A * <p>The <em>domain</em> is a string of characters not including 0N/A * the character colon (<code>:</code>). It is recommended that the domain 0N/A * should not contain the string "{@code //}", which is reserved for future use. 0N/A * <p>If the domain includes at least one occurrence of the wildcard 0N/A * characters asterisk (<code>*</code>) or question mark 0N/A * (<code>?</code>), then the object name is a pattern. The asterisk 0N/A * matches any sequence of zero or more characters, while the question 0N/A * mark matches any single character.</p> 0N/A * <p>If the domain is empty, it will be replaced in certain contexts 0N/A * by the <em>default domain</em> of the MBean server in which the 0N/A * ObjectName is used.</p> 0N/A * <p>The <em>key properties</em> are an unordered set of keys and 0N/A * associated values.</p> 0N/A * <p>Each <em>key</em> is a nonempty string of characters which may 0N/A * not contain any of the characters comma (<code>,</code>), equals 0N/A * (<code>=</code>), colon, asterisk, or question mark. The same key 0N/A * may not occur twice in a given ObjectName.</p> 0N/A * <p>Each <em>value</em> associated with a key is a string of 0N/A * characters that is either unquoted or quoted.</p> 0N/A * <p>An <em>unquoted value</em> is a possibly empty string of 0N/A * characters which may not contain any of the characters comma, 0N/A * equals, colon, or quote.</p> 0N/A * <p>If the <em>unquoted value</em> contains at least one occurrence 0N/A * of the wildcard characters asterisk or question mark, then the object 0N/A * name is a <em>property value pattern</em>. The asterisk matches any 0N/A * sequence of zero or more characters, while the question mark matches 0N/A * any single character.</p> 0N/A * <p>A <em>quoted value</em> consists of a quote (<code>"</code>), 0N/A * followed by a possibly empty string of characters, followed by 0N/A * another quote. Within the string of characters, the backslash 0N/A * (<code>\</code>) has a special meaning. It must be followed by 0N/A * one of the following characters:</p> 0N/A * <li>Another backslash. The second backslash has no special 0N/A * meaning and the two characters represent a single backslash.</li> 0N/A * <li>The character 'n'. The two characters represent a newline 0N/A * ('\n' in Java).</li> 0N/A * <li>A quote. The two characters represent a quote, and that quote 0N/A * is not considered to terminate the quoted value. An ending closing 0N/A * quote must be present for the quoted value to be valid.</li> 0N/A * <li>A question mark (?) or asterisk (*). The two characters represent 0N/A * a question mark or asterisk respectively.</li> 0N/A * <p>A quote may not appear inside a quoted value except immediately 0N/A * after an odd number of consecutive backslashes.</p> 0N/A * <p>The quotes surrounding a quoted value, and any backslashes 0N/A * within that value, are considered to be part of the value.</p> 0N/A * <p>If the <em>quoted value</em> contains at least one occurrence of 0N/A * the characters asterisk or question mark and they are not preceded 0N/A * by a backslash, then they are considered as wildcard characters and 0N/A * the object name is a <em>property value pattern</em>. The asterisk 0N/A * matches any sequence of zero or more characters, while the question 0N/A * mark matches any single character.</p> 0N/A * <p>An ObjectName may be a <em>property list pattern</em>. In this 0N/A * case it may have zero or more keys and associated values. It matches 0N/A * a nonpattern ObjectName whose domain matches and that contains the 0N/A * same keys and associated values, as well as possibly other keys and 0N/A * <p>An ObjectName is a <em>property value pattern</em> when at least 0N/A * one of its <em>quoted</em> or <em>unquoted</em> key property values 0N/A * contains the wildcard characters asterisk or question mark as described 0N/A * above. In this case it has one or more keys and associated values, with 0N/A * at least one of the values containing wildcard characters. It matches a 0N/A * nonpattern ObjectName whose domain matches and that contains the same 0N/A * keys whose values match; if the property value pattern is also a 0N/A * property list pattern then the nonpattern ObjectName can contain 0N/A * other keys and values.</p> 0N/A * <p>An ObjectName is a <em>property pattern</em> if it is either a 0N/A * <em>property list pattern</em> or a <em>property value pattern</em> 0N/A * <p>An ObjectName is a pattern if its domain contains a wildcard or 0N/A * if the ObjectName is a property pattern.</p> 0N/A * <p>If an ObjectName is not a pattern, it must contain at least one 0N/A * key with its associated value.</p> 0N/A * <p>Examples of ObjectName patterns are:</p> 0N/A * <li>{@code *:type=Foo,name=Bar} to match names in any domain whose 0N/A * exact set of keys is {@code type=Foo,name=Bar}.</li> 0N/A * <li>{@code d:type=Foo,name=Bar,*} to match names in the domain 0N/A * {@code d} that have the keys {@code type=Foo,name=Bar} plus 0N/A * zero or more other keys.</li> 0N/A * <li>{@code *:type=Foo,name=Bar,*} to match names in any domain 0N/A * that has the keys {@code type=Foo,name=Bar} plus zero or 0N/A * more other keys.</li> 0N/A * <li>{@code d:type=F?o,name=Bar} will match e.g. 0N/A * {@code d:type=Foo,name=Bar} and {@code d:type=Fro,name=Bar}.</li> 0N/A * <li>{@code d:type=F*o,name=Bar} will match e.g. 0N/A * {@code d:type=Fo,name=Bar} and {@code d:type=Frodo,name=Bar}.</li> 0N/A * <li>{@code d:type=Foo,name="B*"} will match e.g. 0N/A * {@code d:type=Foo,name="Bling"}. Wildcards are recognized even 0N/A * inside quotes, and like other special characters can be escaped 0N/A * with {@code \}.</li> 0N/A * <p>An ObjectName can be written as a String with the following 0N/A * elements in order:</p> 0N/A * <li>A colon (<code>:</code>). 0N/A * <li>A key property list as defined below. 0N/A * <p>A key property list written as a String is a comma-separated 0N/A * list of elements. Each element is either an asterisk or a key 0N/A * property. A key property consists of a key, an equals 0N/A * (<code>=</code>), and the associated value.</p> 0N/A * <p>At most one element of a key property list may be an asterisk. 0N/A * If the key property list contains an asterisk element, the 0N/A * ObjectName is a property list pattern.</p> 0N/A * <p>Spaces have no special significance in a String representing an 0N/A * ObjectName. For example, the String: 0N/A * domain: key1 = value1 , key2 = value2 0N/A * represents an ObjectName with two keys. The name of each key 0N/A * contains six characters, of which the first and last are spaces. 0N/A * The value associated with the key <code>" key1 "</code> 0N/A * also begins and ends with a space.</p> 0N/A * <p>In addition to the restrictions on characters spelt out above, 0N/A * no part of an ObjectName may contain a newline character 0N/A * (<code>'\n'</code>), whether the domain, a key, or a value, whether 0N/A * quoted or unquoted. The newline character can be represented in a 0N/A * quoted value with the sequence <code>\n</code>. 0N/A * <p>The rules on special characters and quoting apply regardless of 0N/A * which constructor is used to make an ObjectName.</p> 0N/A * <p>To avoid collisions between MBeans supplied by different 0N/A * vendors, a useful convention is to begin the domain name with the 0N/A * reverse DNS name of the organization that specifies the MBeans, 0N/A * followed by a period and a string whose interpretation is 0N/A * determined by that organization. For example, MBeans specified by 0N/A * Sun Microsystems Inc., DNS name <code>sun.com</code>, would have 0N/A * domains such as <code>com.sun.MyDomain</code>. This is essentially 0N/A * the same convention as for Java-language package names.</p> 0N/A * <p>The <b>serialVersionUID</b> of this class is <code>1081892073854801359L</code>. 528N/A * The sequence of characters used to separate name spaces in a name space 528N/A * @see javax.management.namespace 0N/A * A structure recording property structure and 0N/A * proposing minimal services 0N/A * Assigns the key index of property 0N/A * Returns a key string for receiver key 0N/A * Returns a value string for receiver key 0N/A * Marker class for value pattern property. 0N/A // Inner classes <======================================== 0N/A // Private fields ----------------------------------------> 0N/A // Serialization compatibility stuff --------------------> 0N/A // Two serial forms are supported in this class. The selected form depends 0N/A // on system property "jmx.serial.form": 0N/A // - "1.0" for JMX 1.0 0N/A // - any other value for JMX 1.1 and higher 0N/A // Serial version for old serial form 0N/A // Serial version for new serial form 0N/A // Serializable fields in old serial form 0N/A // Serializable fields in new serial form 0N/A // Actual serial version and serial form 0N/A // OK: exception means no compat with 1.0, too bad 0N/A // Serialization compatibility stuff <============================== 0N/A // Class private fields -----------------------------------> 0N/A * a shared empty array for empty property lists 0N/A // Class private fields <============================== 0N/A // Instance private fields -----------------------------------> 0N/A * a String containing the canonical name 0N/A * An array of properties in the same seq order as time creation 0N/A * An array of properties in the same seq order as canonical order 0N/A * The length of the domain part of built objectname 0N/A * The propertyList of built object name. Initialized lazily. 0N/A * Table that contains all the pairs (key,value) for this ObjectName. 0N/A * boolean that declares if this ObjectName domain part is a pattern 0N/A * boolean that declares if this ObjectName contains a pattern on the 0N/A * boolean that declares if this ObjectName contains a pattern on the 0N/A * value of at least one key property 528N/A // The domain cannot be null 528N/A // The key property list cannot be null 528N/A "key property list cannot be empty");
528N/A // checks domain validity. A side effect of this method is also to 528N/A // set the _domain_pattern flag. 528N/A // TODO remove this hack 528N/A // if (toString().endsWith("//javax.management.service:type1=event_client_delegeate_mbean,type2=default")) { 528N/A // Thread.currentThread().dumpStack(); 528N/A // throw new Error("************************ Gotcha!"); 0N/A // Instance private fields <======================================= 0N/A // Private fields <======================================== 0N/A // Private methods ----------------------------------------> 0N/A // Category : Instance construction -------------------------> 0N/A * Initializes this {@link ObjectName} from the given string 0N/A * @param name A string representation of the {@link ObjectName} 0N/A * @exception MalformedObjectNameException The string passed as a 0N/A * parameter does not have the right format. 0N/A * @exception NullPointerException The <code>name</code> parameter 0N/A // The name cannot be null 0N/A // Test if the name is empty 0N/A // this is equivalent to the whole word query object name. 0N/A // initialize parsing of the string 528N/A // be same length at most 0N/A // parses domain part 0N/A // ":" omission check. 0N/A // Although "=" is a valid character in the domain part 0N/A // it is true that it is rarely used in the real world. 0N/A // So check straight away if the ":" has been omitted 0N/A // from the ObjectName. This allows us to provide a more 0N/A // accurate exception message. 0N/A "Domain part must be specified");
0N/A "Invalid character '\\n' in domain name");
0N/A // check for non-empty properties 0N/A "Key properties cannot be empty");
0N/A // we have got the domain part, begins building of _canonicalName 0N/A // parses property list 0N/A // case of pattern properties 0N/A "Cannot have several '*' characters in pattern " +
0N/A "Invalid character found after '*': end of " +
0N/A "name or ',' expected");
0N/A // empty properties case 0N/A // correct pattern spec in props, continue 0N/A // standard property case, key part 0N/A // '=' considered to introduce value part 0N/A "' in key part of property");
0N/A "Unterminated key property part");
0N/A // standard property case, value part 0N/A // the case of quoted value part 0N/A // the case of an escaped character 0N/A "Unterminated quoted value");
0N/A break;
// valid character 0N/A "Invalid escape sequence '\\" +
0N/A c1 +
"' in quoted value");
0N/A "Newline in quoted value");
0N/A "Unterminated quoted value");
0N/A // the case of standard value part 0N/A // ',' considered to be the value separator 0N/A "' in value part of property");
0N/A // Parsed property, checks the end of name 0N/A "Invalid ending character `" +
0N/A "Invalid ending comma");
0N/A // we got the key and value part, prepare a property for this 0N/A // computes and set canonical name 0N/A * Construct an ObjectName from a domain and a Hashtable. 0N/A * @param domain Domain of the ObjectName. 0N/A * @param props Map containing couples <i>key</i> -> <i>value</i>. 0N/A * @exception MalformedObjectNameException The <code>domain</code> 0N/A * contains an illegal character, or one of the keys or values in 0N/A * <code>table</code> contains an illegal character, or one of the 0N/A * values in <code>table</code> does not follow the rules for quoting. 0N/A * @exception NullPointerException One of the parameters is null. 0N/A // The domain cannot be null 0N/A // The key property list cannot be null 0N/A // The key property list cannot be empty 0N/A "key property list cannot be empty");
0N/A // checks domain validity 0N/A // init canonicalname 0N/A // allocates the property array 0N/A // initialize canonical name and data structure 0N/A // Category : Instance construction <============================== 0N/A // Category : Internal utilities ------------------------------> 0N/A * Add passed property to the list at the given index 0N/A * for the passed key name 0N/A // if no more space for property arrays, have to increase it 0N/A * Sets the canonical name of receiver from input 'specified_chars' 0N/A * array, by filling 'canonical_chars' array with found 'nb-props' 0N/A * properties starting at position 'prop_index'. 0N/A // Sort the list of found properties 0N/A // now assigns _ca_array to the sorted list of keys 0N/A // (there cannot be two identical keys in an objectname. 0N/A // now we build the canonical name and set begin indexes of 0N/A // properties to reflect canonical form 0N/A // length of prop including '=' char 0N/A // terminate canonicalname with '*' in case of pattern 0N/A // we now build the canonicalname string 0N/A * <pre>final int endKey=parseKey(s,startKey);</pre> 0N/A * <p>key starts at startKey (included), and ends at endKey (excluded). 0N/A * If (startKey == endKey), then the key is empty. 0N/A * @param s The char array of the original string. 0N/A * @param startKey index at which to begin parsing. 0N/A * @return The index following the last character of the key. 0N/A * <pre>final int endVal=parseValue(s,startVal);</pre> 0N/A * <p>value starts at startVal (included), and ends at endVal (excluded). 0N/A * If (startVal == endVal), then the key is empty. 0N/A * @param s The char array of the original string. 0N/A * @param startValue index at which to begin parsing. 0N/A * @return The first element of the int array indicates the index 0N/A * following the last character of the value. The second 0N/A * element of the int array indicates that the value is 0N/A * a pattern when its value equals 1. 0N/A "Invalid unterminated quoted character sequence");
0N/A // We have an escaped quote. If this escaped 0N/A // quote is the last character, it does not 0N/A // qualify as a valid termination quote. 0N/A "Missing termination quote");
0N/A "Invalid quoted character sequence '\\" +
0N/A "Newline in quoted value");
0N/A // Check that last character is a termination quote. 0N/A // We have already handled the case were the last 0N/A // character is an escaped quote earlier. 0N/A // Non quoted value. 0N/A * Check if the supplied value is a valid value. 0N/A * @return true if the value is a pattern, otherwise false. 0N/A * Check if the supplied key is a valid key. 0N/A // Category : Internal utilities <============================== 0N/A // Category : Internal accessors ------------------------------> 0N/A * Check if domain is a valid domain. Set _domain_pattern if appropriate. 0N/A // Category : Internal accessors <============================== 0N/A // Category : Serialization -----------------------------------> 0N/A * Deserializes an {@link ObjectName} from an {@link ObjectInputStream}. 0N/A * <li>In the current serial form (value of property 0N/A * <code>jmx.serial.form</code> differs from 0N/A * <code>1.0</code>): the string 0N/A * "<domain>:<properties><wild>", 0N/A * <li><domain> represents the domain part 0N/A * of the {@link ObjectName}</li> 0N/A * <li><properties> represents the list of 0N/A * properties, as returned by 0N/A * {@link #getKeyPropertyListString} 0N/A * <li><wild> is empty if not 0N/A * <code>isPropertyPattern</code>, or 0N/A * is the character "<code>*</code>" if 0N/A * <code>isPropertyPattern</code> 0N/A * and <properties> is empty, or 0N/A * is "<code>,*</code>" if 0N/A * <code>isPropertyPattern</code> and 0N/A * <properties> is not empty. 0N/A * The intent is that this string could be supplied 0N/A * to the {@link #ObjectName(String)} constructor to 0N/A * produce an equivalent {@link ObjectName}. 0N/A * <li>In the old serial form (value of property 0N/A * <code>jmx.serial.form</code> is 0N/A * <code>1.0</code>): <domain> <propertyList> 0N/A * <propertyListString> <canonicalName> 0N/A * <pattern> <propertyPattern>, 0N/A * <li><domain> represents the domain part 0N/A * of the {@link ObjectName}</li> 0N/A * <li><propertyList> is the 0N/A * {@link Hashtable} that contains all the 0N/A * pairs (key,value) for this 0N/A * {@link ObjectName}</li> 0N/A * <li><propertyListString> is the 0N/A * {@link String} representation of the 0N/A * list of properties in any order (not 0N/A * mandatorily a canonical representation) 0N/A * <li><canonicalName> is the 0N/A * {@link String} containing this 0N/A * {@link ObjectName}'s canonical name</li> 0N/A * <li><pattern> is a boolean which is 0N/A * <code>true</code> if this 0N/A * {@link ObjectName} contains a pattern</li> 0N/A * <li><propertyPattern> is a boolean which 0N/A * is <code>true</code> if this 0N/A * {@link ObjectName} contains a pattern in 0N/A * the list of properties</li> 0N/A // Read an object serialized in the old serial form 0N/A //in.defaultReadObject(); 470N/A // 6616825: take care of property patterns 0N/A // Read an object serialized in the new serial form 528N/A "Serialized ObjectName does not start with " +
old +
528N/A // TODO remove this hack 528N/A // if (nameString.endsWith("//javax.management.service:type1=event_client_delegeate_mbean,type2=default")) { 528N/A // System.err.println("old="+old+", nw="+nw); 528N/A // Thread.currentThread().dumpStack(); 528N/A // throw new Error("************************ Gotcha!"); 0N/A * Serializes an {@link ObjectName} to an {@link ObjectOutputStream}. 0N/A * <li>In the current serial form (value of property 0N/A * <code>jmx.serial.form</code> differs from 0N/A * <code>1.0</code>): the string 0N/A * "<domain>:<properties><wild>", 0N/A * <li><domain> represents the domain part 0N/A * of the {@link ObjectName}</li> 0N/A * <li><properties> represents the list of 0N/A * properties, as returned by 0N/A * {@link #getKeyPropertyListString} 0N/A * <li><wild> is empty if not 0N/A * <code>isPropertyPattern</code>, or 0N/A * is the character "<code>*</code>" if 0N/A * this <code>isPropertyPattern</code> 0N/A * and <properties> is empty, or 0N/A * is "<code>,*</code>" if 0N/A * <code>isPropertyPattern</code> and 0N/A * <properties> is not empty. 0N/A * The intent is that this string could be supplied 0N/A * to the {@link #ObjectName(String)} constructor to 0N/A * produce an equivalent {@link ObjectName}. 0N/A * <li>In the old serial form (value of property 0N/A * <code>jmx.serial.form</code> is 0N/A * <code>1.0</code>): <domain> <propertyList> 0N/A * <propertyListString> <canonicalName> 0N/A * <pattern> <propertyPattern>, 0N/A * <li><domain> represents the domain part 0N/A * of the {@link ObjectName}</li> 0N/A * <li><propertyList> is the 0N/A * {@link Hashtable} that contains all the 0N/A * pairs (key,value) for this 0N/A * {@link ObjectName}</li> 0N/A * <li><propertyListString> is the 0N/A * {@link String} representation of the 0N/A * list of properties in any order (not 0N/A * mandatorily a canonical representation) 0N/A * <li><canonicalName> is the 0N/A * {@link String} containing this 0N/A * {@link ObjectName}'s canonical name</li> 0N/A * <li><pattern> is a boolean which is 0N/A * <code>true</code> if this 0N/A * {@link ObjectName} contains a pattern</li> 0N/A * <li><propertyPattern> is a boolean which 0N/A * is <code>true</code> if this 0N/A * {@link ObjectName} contains a pattern in 0N/A * the list of properties</li> 0N/A // Serializes this instance in the old serial form 0N/A // Read CR 6441274 before making any changes to this code 0N/A // Serializes this instance in the new serial form 0N/A // Category : Serialization <=================================== 0N/A // Private methods <======================================== 0N/A // Public methods ----------------------------------------> 0N/A // Category : ObjectName Construction ------------------------------> 0N/A * <p>Return an instance of ObjectName that can be used anywhere 0N/A * an object obtained with {@link #ObjectName(String) new 0N/A * ObjectName(name)} can be used. The returned object may be of 0N/A * a subclass of ObjectName. Calling this method twice with the 0N/A * same parameters may return the same object or two equal but 0N/A * not identical objects.</p> 0N/A * @param name A string representation of the object name. 0N/A * @return an ObjectName corresponding to the given String. 0N/A * @exception MalformedObjectNameException The string passed as a 0N/A * parameter does not have the right format. 0N/A * @exception NullPointerException The <code>name</code> parameter 0N/A * <p>Return an instance of ObjectName that can be used anywhere 0N/A * an object obtained with {@link #ObjectName(String, String, 0N/A * String) new ObjectName(domain, key, value)} can be used. The 0N/A * returned object may be of a subclass of ObjectName. Calling 0N/A * this method twice with the same parameters may return the same 0N/A * object or two equal but not identical objects.</p> 0N/A * @param domain The domain part of the object name. 0N/A * @param key The attribute in the key property of the object name. 0N/A * @param value The value in the key property of the object name. 0N/A * @return an ObjectName corresponding to the given domain, 0N/A * @exception MalformedObjectNameException The 0N/A * <code>domain</code>, <code>key</code>, or <code>value</code> 0N/A * contains an illegal character, or <code>value</code> does not 0N/A * follow the rules for quoting. 0N/A * @exception NullPointerException One of the parameters is null. 0N/A * <p>Return an instance of ObjectName that can be used anywhere 0N/A * an object obtained with {@link #ObjectName(String, Hashtable) 0N/A * new ObjectName(domain, table)} can be used. The returned 0N/A * object may be of a subclass of ObjectName. Calling this method 0N/A * twice with the same parameters may return the same object or 0N/A * two equal but not identical objects.</p> 0N/A * @param domain The domain part of the object name. 0N/A * @param table A hash table containing one or more key 0N/A * properties. The key of each entry in the table is the key of a 0N/A * key property in the object name. The associated value in the 0N/A * table is the associated value in the object name. 0N/A * @return an ObjectName corresponding to the given domain and 0N/A * @exception MalformedObjectNameException The <code>domain</code> 0N/A * contains an illegal character, or one of the keys or values in 0N/A * <code>table</code> contains an illegal character, or one of the 0N/A * values in <code>table</code> does not follow the rules for 0N/A * @exception NullPointerException One of the parameters is null. 0N/A * <p>Return an instance of ObjectName that can be used anywhere 0N/A * the given object can be used. The returned object may be of a 0N/A * subclass of ObjectName. If <code>name</code> is of a subclass 0N/A * of ObjectName, it is not guaranteed that the returned object 0N/A * will be of the same class.</p> 0N/A * <p>The returned value may or may not be identical to 0N/A * <code>name</code>. Calling this method twice with the same 0N/A * parameters may return the same object or two equal but not 0N/A * identical objects.</p> 0N/A * <p>Since ObjectName is immutable, it is not usually useful to 0N/A * make a copy of an ObjectName. The principal use of this method 0N/A * is to guard against a malicious caller who might pass an 0N/A * instance of a subclass with surprising behavior to sensitive 0N/A * code. Such code can call this method to obtain an ObjectName 0N/A * that is known not to have surprising behavior.</p> 0N/A * @param name an instance of the ObjectName class or of a subclass 0N/A * @return an instance of ObjectName or a subclass that is known to 0N/A * have the same semantics. If <code>name</code> respects the 0N/A * semantics of ObjectName, then the returned object is equal 0N/A * (though not necessarily identical) to <code>name</code>. 0N/A * @exception NullPointerException The <code>name</code> is null. 528N/A * Returns an {@code ObjectName} that is the same as this one but 528N/A * with the specified domain. 528N/A * This method preserves the original key order in the new instance. 528N/A * If the provided name has a key property pattern, it will also be 528N/A * preserved in the returned instance. 528N/A * @param newDomain The new domain for the returned instance; 528N/A * @return A new {@code ObjectName} that is the same as {@code this} 528N/A * except the domain is {@code newDomain}. 528N/A * @throws NullPointerException if {@code newDomain} is null. 528N/A * @throws MalformedObjectNameException if the new domain is syntactically 0N/A * Construct an object name from the given string. 0N/A * @param name A string representation of the object name. 0N/A * @exception MalformedObjectNameException The string passed as a 0N/A * parameter does not have the right format. 0N/A * @exception NullPointerException The <code>name</code> parameter 0N/A * Construct an object name with exactly one key property. 0N/A * @param domain The domain part of the object name. 0N/A * @param key The attribute in the key property of the object name. 0N/A * @param value The value in the key property of the object name. 0N/A * @exception MalformedObjectNameException The 0N/A * <code>domain</code>, <code>key</code>, or <code>value</code> 0N/A * contains an illegal character, or <code>value</code> does not 0N/A * follow the rules for quoting. 0N/A * @exception NullPointerException One of the parameters is null. 0N/A // If key or value are null a NullPointerException 0N/A // will be thrown by the put method in Hashtable. 0N/A * Construct an object name with several key properties from a Hashtable. 0N/A * @param domain The domain part of the object name. 0N/A * @param table A hash table containing one or more key 0N/A * properties. The key of each entry in the table is the key of a 0N/A * key property in the object name. The associated value in the 0N/A * table is the associated value in the object name. 0N/A * @exception MalformedObjectNameException The <code>domain</code> 0N/A * contains an illegal character, or one of the keys or values in 0N/A * <code>table</code> contains an illegal character, or one of the 0N/A * values in <code>table</code> does not follow the rules for 0N/A * @exception NullPointerException One of the parameters is null. 0N/A /* The exception for when a key or value in the table is not a 0N/A String is now ClassCastException rather than 0N/A MalformedObjectNameException. This was not previously 0N/A // Category : ObjectName Construction <============================== 0N/A // Category : Getter methods ------------------------------> 0N/A * Checks whether the object name is a pattern. 0N/A * An object name is a pattern if its domain contains a 0N/A * wildcard or if the object name is a property pattern. 0N/A * @return True if the name is a pattern, otherwise false. 0N/A * Checks whether the object name is a pattern on the domain part. 0N/A * @return True if the name is a domain pattern, otherwise false. 0N/A * Checks whether the object name is a pattern on the key properties. 0N/A * An object name is a pattern on the key properties if it is a 0N/A * pattern on the key property list (e.g. "d:k=v,*") or on the 0N/A * property values (e.g. "d:k=*") or on both (e.g. "d:k=*,*"). 0N/A * @return True if the name is a property pattern, otherwise false. 0N/A * Checks whether the object name is a pattern on the key property list. 0N/A * For example, "d:k=v,*" and "d:k=*,*" are key property list patterns 0N/A * whereas "d:k=*" is not. 0N/A * @return True if the name is a property list pattern, otherwise false. 0N/A * Checks whether the object name is a pattern on the value part 0N/A * of at least one of the key properties. 0N/A * For example, "d:k=*" and "d:k=*,*" are property value patterns 0N/A * whereas "d:k=v,*" is not. 0N/A * @return True if the name is a property value pattern, otherwise false. 0N/A * Checks whether the value associated with a key in a key 0N/A * property is a pattern. 0N/A * @param property The property whose value is to be checked. 0N/A * @return True if the value associated with the given key property 0N/A * is a pattern, otherwise false. 0N/A * @exception NullPointerException If <code>property</code> is null. 0N/A * @exception IllegalArgumentException If <code>property</code> is not 0N/A * a valid key property for this ObjectName. 0N/A * <p>Returns the canonical form of the name; that is, a string 0N/A * representation where the properties are sorted in lexical 0N/A * <p>More precisely, the canonical form of the name is a String 0N/A * consisting of the <em>domain part</em>, a colon 0N/A * (<code>:</code>), the <em>canonical key property list</em>, and 0N/A * a <em>pattern indication</em>.</p> 0N/A * <p>The <em>canonical key property list</em> is the same string 0N/A * as described for {@link #getCanonicalKeyPropertyListString()}.</p> 0N/A * <p>The <em>pattern indication</em> is: 0N/A * <li>empty for an ObjectName 0N/A * that is not a property list pattern; 0N/A * <li>an asterisk for an ObjectName 0N/A * that is a property list pattern with no keys; or 0N/A * <li>a comma and an 0N/A * asterisk (<code>,*</code>) for an ObjectName that is a property 0N/A * list pattern with at least one key. 0N/A * @return The canonical form of the name. 0N/A * Returns the domain part. 0N/A * @return The domain. 0N/A * Obtains the value associated with a key in a key property. 0N/A * @param property The property whose value is to be obtained. 0N/A * @return The value of the property, or null if there is no such 0N/A * property in this ObjectName. 0N/A * @exception NullPointerException If <code>property</code> is null. 0N/A * <p>Returns the key properties as a Map. The returned 0N/A * value is a Map in which each key is a key in the 0N/A * ObjectName's key property list and each value is the associated 0N/A * <p>The returned value must not be modified.</p> 0N/A * @return The table of key properties. 0N/A synchronized (
this) {
0N/A // build (lazy eval) the property list from the canonical 0N/A for (
int i =
len -
1; i >=
0; i--) {
0N/A * <p>Returns the key properties as a Hashtable. The returned 0N/A * value is a Hashtable in which each key is a key in the 0N/A * ObjectName's key property list and each value is the associated 0N/A * <p>The returned value may be unmodifiable. If it is 0N/A * modifiable, changing it has no effect on this ObjectName.</p> 0N/A * @return The table of key properties. 0N/A // CR 6441274 depends on the modification property defined above 0N/A * <p>Returns a string representation of the list of key 0N/A * properties specified at creation time. If this ObjectName was 0N/A * constructed with the constructor {@link #ObjectName(String)}, 0N/A * the key properties in the returned String will be in the same 0N/A * order as in the argument to the constructor.</p> 0N/A * @return The key property list string. This string is 0N/A * independent of whether the ObjectName is a pattern. 0N/A // BEWARE : we rebuild the propertyliststring at each call !! 0N/A // the size of the string is the canonical one minus domain 0N/A // part and pattern part 0N/A * <p>Returns the serialized string of the ObjectName. 0N/A * properties specified at creation time. If this ObjectName was 0N/A * constructed with the constructor {@link #ObjectName(String)}, 0N/A * the key properties in the returned String will be in the same 0N/A * order as in the argument to the constructor.</p> 0N/A * @return The key property list string. This string is 0N/A * independent of whether the ObjectName is a pattern. 0N/A // the size of the string is the canonical one 0N/A // copy "domain:" into dest_chars 0N/A // Add property list string 0N/A // Add ",*" if necessary 0N/A // Property list string is empty. 0N/A // Property list string is not empty. 0N/A * <p>Write a string representation of the list of key 0N/A * properties specified at creation time in the given array, starting 0N/A * at the specified offset. If this ObjectName was 0N/A * constructed with the constructor {@link #ObjectName(String)}, 0N/A * the key properties in the returned String will be in the same 0N/A * order as in the argument to the constructor.</p> 0N/A * @return offset + #of chars written 0N/A for (
int i =
0; i <
len; i++) {
0N/A * Returns a string representation of the list of key properties, 0N/A * in which the key properties are sorted in lexical order. This 0N/A * is used in lexicographic comparisons performed in order to 0N/A * select MBeans based on their key property list. Lexical order 0N/A * is the order implied by {@link String#compareTo(String) 0N/A * String.compareTo(String)}. 0N/A * @return The canonical key property list string. This string is 0N/A * independent of whether the ObjectName is a pattern. 0N/A // Category : Getter methods <=================================== 0N/A // Category : Utilities ----------------------------------------> 0N/A * <p>Returns a string representation of the object name. The 0N/A * format of this string is not specified, but users can expect 0N/A * that two ObjectNames return the same string if and only if they 0N/A * @return a string representation of this object name. 0N/A * Compares the current object name with another object name. Two 0N/A * ObjectName instances are equal if and only if their canonical 0N/A * forms are equal. The canonical form is the string described 0N/A * for {@link #getCanonicalName()}. 0N/A * @param object The object name that the current object name is to be 0N/A * @return True if <code>object</code> is an ObjectName whose 0N/A * canonical form is equal to that of this ObjectName. 0N/A // object is not an object name case 0N/A // equality when canonical names are the same 0N/A // (because usage of intern()) 0N/A // Because we are sharing canonical form between object names, 0N/A // we have finished the comparison at this stage ==> unequal 0N/A * Returns a hash code for this object name. 0N/A * <p>Returns a quoted form of the given String, suitable for 0N/A * inclusion in an ObjectName. The returned value can be used as 0N/A * the value associated with a key in an ObjectName. The String 0N/A * <code>s</code> may contain any character. Appropriate quoting 0N/A * ensures that the returned value is legal in an ObjectName.</p> 0N/A * <p>The returned value consists of a quote ('"'), a sequence of 0N/A * characters corresponding to the characters of <code>s</code>, 0N/A * and another quote. Characters in <code>s</code> appear 0N/A * unchanged within the returned value except:</p> 0N/A * <li>A quote ('"') is replaced by a backslash (\) followed by a quote.</li> 0N/A * <li>An asterisk ('*') is replaced by a backslash (\) followed by an 0N/A * <li>A question mark ('?') is replaced by a backslash (\) followed by 0N/A * a question mark.</li> 0N/A * <li>A backslash ('\') is replaced by two backslashes.</li> 0N/A * <li>A newline character (the character '\n' in Java) is replaced 0N/A * by a backslash followed by the character '\n'.</li> 0N/A * @param s the String to be quoted. 0N/A * @return the quoted String. 0N/A * @exception NullPointerException if <code>s</code> is null. 0N/A for (
int i =
0; i <
len; i++) {
0N/A * <p>Returns an unquoted form of the given String. If 0N/A * <code>q</code> is a String returned by {@link #quote quote(s)}, 0N/A * then <code>unquote(q).equals(s)</code>. If there is no String 0N/A * <code>s</code> for which <code>quote(s).equals(q)</code>, then 0N/A * unquote(q) throws an IllegalArgumentException.</p> 0N/A * <p>These rules imply that there is a one-to-one mapping between 0N/A * quoted and unquoted forms.</p> 0N/A * @param q the String to be unquoted. 0N/A * @return the unquoted String. 0N/A * @exception IllegalArgumentException if <code>q</code> could not 0N/A * have been returned by the {@link #quote} method, for instance 0N/A * if it does not begin and end with a quote ("). 0N/A * @exception NullPointerException if <code>q</code> is null. 0N/A for (
int i =
1; i <
len -
1; i++) {
0N/A "Bad character '" + c +
"' after backslash");
0N/A "Invalid unescaped character '" + c +
0N/A "' in the string to unquote");
0N/A * Defines the wildcard "*:*" ObjectName. 0N/A // Category : Utilities <=================================== 0N/A // Category : QueryExp Interface ----------------------------------------> 0N/A * <p>Test whether this ObjectName, which may be a pattern, 0N/A * matches another ObjectName. If <code>name</code> is a pattern, 0N/A * the result is false. If this ObjectName is a pattern, the 0N/A * result is true if and only if <code>name</code> matches the 0N/A * pattern. If neither this ObjectName nor <code>name</code> is 0N/A * a pattern, the result is true if and only if the two 0N/A * ObjectNames are equal as described for the {@link 0N/A * #equals(Object)} method.</p> 0N/A * @param name The name of the MBean to compare to. 0N/A * @return True if <code>name</code> matches this ObjectName. 0N/A * @exception NullPointerException if <code>name</code> is null. 0N/A // wildmatch domains 528N/A // This ObjectName is the pattern 528N/A // The other ObjectName is the string. 0N/A // If key property value pattern but not key property list 0N/A // pattern, then the number of key properties must be equal 0N/A // If key property value pattern or key property list pattern, 0N/A // then every property inside pattern should exist in name 0N/A // Find value in given object name for key at current 0N/A // index in receiver 0N/A // Did we find a value for this key ? 0N/A // If this property is ok (same key, same value), go to next 0N/A // wildmatch key property values 528N/A // p is the property pattern, v is the string 0N/A // If no pattern, then canonical names must be equal 0N/A /* Method inherited from QueryExp, no implementation needed here 0N/A because ObjectName is not relative to an MBeanServer and does 0N/A not contain a subquery. 0N/A // Category : QueryExp Interface <========================= 0N/A // Category : Comparable Interface ----------------------------------------> 0N/A * <p>Compares two ObjectName instances. The ordering relation between 0N/A * ObjectNames is not completely specified but is intended to be such 0N/A * that a sorted list of ObjectNames will appear in an order that is 0N/A * convenient for a person to read.</p> 0N/A * <p>In particular, if the two ObjectName instances have different 0N/A * domains then their order is the lexicographical order of the domains. 0N/A * The ordering of the key property list remains unspecified.</p> 0N/A * <p>For example, the ObjectName instances below:</p> 0N/A * <li>Shapes:type=Square,name=3</li> 0N/A * <li>Colors:type=Red,name=2</li> 0N/A * <li>Shapes:type=Triangle,side=isosceles,name=2</li> 0N/A * <li>Colors:type=Red,name=1</li> 0N/A * <li>Shapes:type=Square,name=1</li> 0N/A * <li>Colors:type=Blue,name=1</li> 0N/A * <li>Shapes:type=Square,name=2</li> 0N/A * <li>JMImplementation:type=MBeanServerDelegate</li> 0N/A * <li>Shapes:type=Triangle,side=scalene,name=1</li> 0N/A * <p>could be ordered as follows:</p> 0N/A * <li>Colors:type=Blue,name=1</li> 0N/A * <li>Colors:type=Red,name=1</li> 0N/A * <li>Colors:type=Red,name=2</li> 0N/A * <li>JMImplementation:type=MBeanServerDelegate</li> 0N/A * <li>Shapes:type=Square,name=1</li> 0N/A * <li>Shapes:type=Square,name=2</li> 0N/A * <li>Shapes:type=Square,name=3</li> 0N/A * <li>Shapes:type=Triangle,side=scalene,name=1</li> 0N/A * <li>Shapes:type=Triangle,side=isosceles,name=2</li> 0N/A * @param name the ObjectName to be compared. 0N/A * @return a negative integer, zero, or a positive integer as this 0N/A * ObjectName is less than, equal to, or greater than the 0N/A * specified ObjectName. 0N/A // (1) Compare domains 0N/A // (2) Compare "type=" keys 0N/A // Within a given domain, all names with missing or empty "type=" 0N/A // come before all names with non-empty type. 0N/A // When both types are missing or empty, canonical-name ordering 0N/A // applies which is a total order. 0N/A // (3) Compare canonical names 0N/A // Category : Comparable Interface <========================= 0N/A // Public methods <========================================