1 /* ObjectName.java -- Represent the name of a bean, or a pattern for a name.
2 Copyright (C) 2006, 2007 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
38 package javax.management;
40 import java.io.Serializable;
42 import java.util.Hashtable;
43 import java.util.Iterator;
45 import java.util.TreeMap;
47 import java.io.IOException;
48 import java.io.InvalidObjectException;
49 import java.io.ObjectInputStream;
50 import java.io.ObjectOutputStream;
54 * An {@link ObjectName} instance represents the name of a management
55 * bean, or a pattern which may match the name of one or more
56 * management beans. Patterns are distinguished from names by the
57 * presence of the '?' and '*' characters (which match a single
58 * character and a series of zero or more characters, respectively).
61 * Each name begins with a domain element, which is terminated by
62 * a ':' character. The domain may be empty. If so, it will be
63 * replaced by the default domain of the bean server in certain
64 * contexts. The domain is a pattern, if it contains either '?'
65 * or '*'. To avoid collisions, it is usual to use reverse
66 * DNS names for the domain, as in Java package and property names.
69 * Following the ':' character is a series of properties. The list
70 * is separated by commas, and largely consists of unordered key-value
71 * pairs, separated by an equals sign ('='). At most one element may
72 * be an asterisk ('*'), which turns the {@link ObjectName} instance
73 * into a <emph>property list pattern</emph>. In this situation, the pattern
74 * matches a name if the name contains at least those key-value pairs
75 * given and has the same domain.
78 * A <emph>key</emph> is a string of characters which doesn't include
79 * any of those used as delimiters or in patterns (':', '=', ',', '?'
80 * and '*'). Keys must be unique.
83 * A value may be <emph>quoted</emph> or <emph>unquoted</emph>. Unquoted
84 * values obey the same rules as given for keys above. Quoted values are
85 * surrounded by quotation marks ("), and use a backslash ('\') character
86 * to include quotes ('\"'), backslashes ('\\'), newlines ('\n'), and
87 * the pattern characters ('\?' and '\*'). The quotes and backslashes
88 * (after expansion) are considered part of the value.
91 * Both quoted and unquoted values may contain the wildcard characters
92 * '?' and '*'. A name with at least one value containing a wildcard
93 * character is known as a <emph>property value pattern</emph>. A
94 * name is generally a <emph>property pattern</emph> if it is either
95 * a <emph>property list pattern</emph> or <emph>property value pattern</emph>.
98 * Spaces are maintained within the different parts of the name. Thus,
99 * '<code>domain: key1 = value1 </code>' has a key ' key1 ' with value
100 * ' value1 '. Newlines are disallowed, except where escaped in quoted
104 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
107 public class ObjectName
108 implements Serializable, QueryExp
111 private static final long serialVersionUID = 1081892073854801359L;
114 * The wildcard {@link ObjectName} {@code "*:*"}
118 public static final ObjectName WILDCARD;
121 * The domain of the name.
123 private transient String domain;
126 * The properties, as key-value pairs.
128 private transient TreeMap<String,String> properties;
131 * The properties as a string (stored for ordering).
133 private transient String propertyListString;
136 * True if this object name is a property list pattern.
138 private transient boolean propertyListPattern;
141 * True if this object name is a property value pattern.
143 private transient boolean propertyValuePattern;
146 * The management server associated with this object name.
148 private transient MBeanServer server;
151 * Static initializer to set up the wildcard.
157 WILDCARD = new ObjectName("");
159 catch (MalformedObjectNameException e)
161 throw (InternalError) (new InternalError("A problem occurred " +
162 "initializing the ObjectName " +
163 "wildcard.").initCause(e));
168 * Constructs an {@link ObjectName} instance from the given string,
169 * which should be of the form
170 * <domain>:<properties><wild>. <domain>
171 * represents the domain section of the name. <properties>
172 * represents the key-value pairs, as returned by {@link
173 * #getKeyPropertyListString()}. <wild> is the optional
174 * asterisk present in the property list. If the string doesn't
175 * represent a property pattern, it will be empty. If it does,
176 * it will be either ',*' or '*', depending on whether other
177 * properties are present or not, respectively.
179 * @param name the string to use to construct this instance.
180 * @throws MalformedObjectNameException if the string is of the
182 * @throws NullPointerException if <code>name</code> is
185 public ObjectName(String name)
186 throws MalformedObjectNameException
188 if (name.length() == 0)
194 * Parse the name in the same form as the constructor. Used by
197 private void parse(String name)
198 throws MalformedObjectNameException
200 int domainSep = name.indexOf(':');
202 throw new MalformedObjectNameException("No domain separator was found.");
203 domain = name.substring(0, domainSep);
204 String rest = name.substring(domainSep + 1);
205 properties = new TreeMap<String,String>();
206 String[] pairs = rest.split(",");
207 if (pairs.length == 0 && !isPattern())
208 throw new MalformedObjectNameException("A name that is not a " +
209 "pattern must contain at " +
210 "least one key-value pair.");
211 propertyListString = "";
212 for (int a = 0; a < pairs.length; ++a)
214 if (pairs[a].equals("*"))
216 if (propertyListPattern)
217 throw new MalformedObjectNameException("Multiple wildcards " +
219 propertyListPattern = true;
222 int sep = pairs[a].indexOf('=');
224 throw new MalformedObjectNameException("A key must be " +
225 "followed by a value.");
226 String key = pairs[a].substring(0, sep);
227 if (properties.containsKey(key))
228 throw new MalformedObjectNameException("The same key occurs " +
230 String value = pairs[a].substring(sep+1);
231 properties.put(key, value);
232 propertyListString += key + "=" + value + ",";
234 if (propertyListString.length() > 0)
236 propertyListString.substring(0, propertyListString.length() - 1);
241 * Constructs an {@link ObjectName} instance using the given
242 * domain and the one specified property.
244 * @param domain the domain part of the object name.
245 * @param key the key of the property.
246 * @param value the value of the property.
247 * @throws MalformedObjectNameException the domain, key or value
248 * contains an illegal
249 * character or the value
250 * does not follow the quoting
252 * @throws NullPointerException if one of the parameters is
255 public ObjectName(String domain, String key, String value)
256 throws MalformedObjectNameException
258 this.domain = domain;
259 properties = new TreeMap<String,String>();
260 properties.put(key, value);
265 * Constructs an {@link ObjectName} instance using the given
266 * domain and properties.
268 * @param domain the domain part of the object name.
269 * @param properties the key-value property pairs.
270 * @throws MalformedObjectNameException the domain, a key or a value
271 * contains an illegal
272 * character or a value
273 * does not follow the quoting
275 * @throws NullPointerException if one of the parameters is
278 public ObjectName(String domain, Hashtable<String,String> properties)
279 throws MalformedObjectNameException
281 this.domain = domain;
282 this.properties = new TreeMap<String,String>();
283 this.properties.putAll(properties);
288 * Checks the legality of the domain and the properties.
290 * @throws MalformedObjectNameException the domain, a key or a value
291 * contains an illegal
292 * character or a value
293 * does not follow the quoting
296 private void checkComponents()
297 throws MalformedObjectNameException
299 if (domain.indexOf(':') != -1)
300 throw new MalformedObjectNameException("The domain includes a ':' " +
302 if (domain.indexOf('\n') != -1)
303 throw new MalformedObjectNameException("The domain includes a newline " +
305 char[] keychars = new char[] { '\n', ':', ',', '*', '?', '=' };
306 char[] valchars = new char[] { '\n', ':', ',', '=' };
307 Iterator i = properties.entrySet().iterator();
310 Map.Entry entry = (Map.Entry) i.next();
311 String key = (String) entry.getKey();
312 for (int a = 0; a < keychars.length; ++a)
313 if (key.indexOf(keychars[a]) != -1)
314 throw new MalformedObjectNameException("A key contains a '" +
317 String value = (String) entry.getValue();
318 int quote = value.indexOf('"');
325 catch (IllegalArgumentException e)
327 throw (MalformedObjectNameException)
328 new MalformedObjectNameException("The quoted value is " +
329 "invalid.").initCause(e);
332 else if (quote != -1)
333 throw new MalformedObjectNameException("A value contains " +
334 "a '\"' character.");
337 for (int a = 0; a < valchars.length; ++a)
338 if (value.indexOf(valchars[a]) != -1)
339 throw new MalformedObjectNameException("A value contains " +
340 "a '" + valchars[a] + "' " +
344 if (value.indexOf('*') != -1 || value.indexOf('?') != -1)
345 propertyValuePattern = true;
351 * Attempts to find a match between this name and the one supplied.
352 * The following criteria are used:
355 * <li>If the supplied name is a pattern, <code>false</code> is
357 * <li>If this name is a pattern, this method returns <code>true</code>
358 * if the supplied name matches the pattern.</li>
359 * <li>If this name is not a pattern, the result of
360 * <code>equals(name)</code> is returned.
363 * @param name the name to find a match with.
364 * @return true if the name either matches this pattern or is
365 * equivalent to this name under the criteria of
366 * {@link #equals(java.lang.Object)}
367 * @throws NullPointerException if <code>name</code> is <code>null</code>.
369 public boolean apply(ObjectName name)
371 if (name.isPattern())
377 if (isDomainPattern())
379 if (!domainMatches(domain, 0, name.getDomain(), 0))
384 if (!domain.equals(name.getDomain()))
388 if (isPropertyPattern())
390 Hashtable oProps = name.getKeyPropertyList();
391 Iterator i = properties.entrySet().iterator();
394 Map.Entry entry = (Map.Entry) i.next();
395 String key = (String) entry.getKey();
396 if (!(oProps.containsKey(key)))
398 String val = (String) entry.getValue();
399 if (!(val.equals(oProps.get(key))))
405 if (!getCanonicalKeyPropertyListString().equals
406 (name.getCanonicalKeyPropertyListString()))
413 * Returns true if the domain matches the pattern.
415 * @param pattern the pattern to match against.
416 * @param patternindex the index into the pattern to start matching.
417 * @param domain the domain to match.
418 * @param domainindex the index into the domain to start matching.
419 * @return true if the domain matches the pattern.
421 private static boolean domainMatches(String pattern, int patternindex,
422 String domain, int domainindex)
424 while (patternindex < pattern.length())
426 char c = pattern.charAt(patternindex++);
430 for (int i = domain.length(); i >= domainindex; i--)
432 if (domainMatches(pattern, patternindex, domain, i))
438 if (domainindex >= domain.length())
441 if (c != '?' && c != domain.charAt(domainindex))
450 * Compares the specified object with this one. The two
451 * are judged to be equivalent if the given object is an
452 * instance of {@link ObjectName} and has an equal canonical
453 * form (as returned by {@link #getCanonicalName()}).
455 * @param obj the object to compare with this.
456 * @return true if the object is also an {@link ObjectName}
457 * with an equivalent canonical form.
459 public boolean equals(Object obj)
461 if (obj instanceof ObjectName)
463 ObjectName o = (ObjectName) obj;
464 return getCanonicalName().equals(o.getCanonicalName());
470 * Returns the property list in canonical form. The keys
471 * are ordered using the lexicographic ordering used by
472 * {@link java.lang.String#compareTo(java.lang.Object)}.
474 * @return the property list, with the keys in lexicographic
477 public String getCanonicalKeyPropertyListString()
479 StringBuilder builder = new StringBuilder();
480 Iterator i = properties.entrySet().iterator();
483 Map.Entry entry = (Map.Entry) i.next();
484 builder.append(entry.getKey() + "=" + entry.getValue());
488 return builder.toString();
493 * Returns the name as a string in canonical form. More precisely,
494 * this returns a string of the format
495 * <domain>:<properties><wild>. <properties>
496 * is the same value as returned by
497 * {@link #getCanonicalKeyPropertyListString()}. <wild>
501 * <li>an empty string, if the object name is not a property pattern.</li>
502 * <li>'*' if <properties> is empty.</li>
503 * <li>',*' if there is at least one key-value pair.</li>
506 * @return the canonical string form of the object name, as specified
509 public String getCanonicalName()
511 return domain + ":" +
512 getCanonicalKeyPropertyListString() +
513 (isPropertyPattern() ? (properties.isEmpty() ? "*" : ",*") : "");
517 * Returns the domain part of the object name.
519 * @return the domain.
521 public String getDomain()
527 * Returns an {@link ObjectName} instance that is substitutable for the
528 * one given. The instance returned may be a subclass of {@link ObjectName},
529 * but is not guaranteed to be of the same type as the given name, if that
530 * should also turn out to be a subclass. The returned instance may or may
531 * not be equivalent to the one given. The purpose of this method is to provide
532 * an instance of {@link ObjectName} with a well-defined semantics, such as may
533 * be used in cases where the given name is not trustworthy.
535 * @param name the {@link ObjectName} to provide a substitute for.
536 * @return a substitute for the given name, which may or may not be a subclass
537 * of {@link ObjectName}. In either case, the returned object is
538 * guaranteed to have the semantics defined here.
539 * @throws NullPointerException if <code>name</code> is <code>null</code>.
541 public static ObjectName getInstance(ObjectName name)
545 return new ObjectName(name.getCanonicalName());
547 catch (MalformedObjectNameException e)
549 throw (InternalError)
550 (new InternalError("The canonical name of " +
551 "the given name is invalid.").initCause(e));
556 * Returns an {@link ObjectName} instance for the specified name, represented
557 * as a {@link java.lang.String}. The instance returned may be a subclass of
558 * {@link ObjectName} and may or may not be equivalent to earlier instances
559 * returned by this method for the same string.
561 * @param name the {@link ObjectName} to provide an instance of.
562 * @return a instance for the given name, which may or may not be a subclass
563 * of {@link ObjectName}.
564 * @throws MalformedObjectNameException the domain, a key or a value
565 * contains an illegal
566 * character or a value
567 * does not follow the quoting
569 * @throws NullPointerException if <code>name</code> is <code>null</code>.
571 public static ObjectName getInstance(String name)
572 throws MalformedObjectNameException
574 return new ObjectName(name);
578 * Returns an {@link ObjectName} instance for the specified name, represented
579 * as a series of {@link java.lang.String} objects for the domain and a single
580 * property, as a key-value pair. The instance returned may be a subclass of
581 * {@link ObjectName} and may or may not be equivalent to earlier instances
582 * returned by this method for the same parameters.
584 * @param domain the domain part of the object name.
585 * @param key the key of the property.
586 * @param value the value of the property.
587 * @return a instance for the given name, which may or may not be a subclass
588 * of {@link ObjectName}.
589 * @throws MalformedObjectNameException the domain, a key or a value
590 * contains an illegal
591 * character or a value
592 * does not follow the quoting
594 * @throws NullPointerException if <code>name</code> is <code>null</code>.
596 public static ObjectName getInstance(String domain, String key, String value)
597 throws MalformedObjectNameException
599 return new ObjectName(domain, key, value);
603 * Returns an {@link ObjectName} instance for the specified name, represented
604 * as a domain {@link java.lang.String} and a table of properties. The
605 * instance returned may be a subclass of {@link ObjectName} and may or may
606 * not be equivalent to earlier instances returned by this method for the
609 * @param domain the domain part of the object name.
610 * @param properties the key-value property pairs.
611 * @return a instance for the given name, which may or may not be a subclass
612 * of {@link ObjectName}.
613 * @throws MalformedObjectNameException the domain, a key or a value
614 * contains an illegal
615 * character or a value
616 * does not follow the quoting
618 * @throws NullPointerException if <code>name</code> is <code>null</code>.
620 public static ObjectName getInstance(String domain,
621 Hashtable<String,String> properties)
622 throws MalformedObjectNameException
624 return new ObjectName(domain, properties);
628 * Returns the property value corresponding to the given key.
630 * @param key the key of the property to be obtained.
631 * @return the value of the specified property.
632 * @throws NullPointerException if <code>key</code> is <code>null</code>.
634 public String getKeyProperty(String key)
637 throw new NullPointerException("Null key given in request for a value.");
638 return (String) properties.get(key);
642 * Returns the properties in a {@link java.util.Hashtable}. The table
643 * contains each of the properties as keys mapped to their value. The
644 * returned table is not unmodifiable, but changes made to it will not
645 * be reflected in the object name.
647 * @return a {@link java.util.Hashtable}, containing each of the object
650 public Hashtable<String,String> getKeyPropertyList()
652 return new Hashtable<String,String>(properties);
656 * Returns a {@link java.lang.String} representation of the property
657 * list. If the object name was created using {@link
658 * ObjectName(String)}, then this string will contain the properties
659 * in the same order they were given in at creation.
661 * @return the property list.
663 public String getKeyPropertyListString()
665 if (propertyListString != null)
666 return propertyListString;
667 return getCanonicalKeyPropertyListString();
671 * Returns a hash code for this object name. This is calculated as the
672 * summation of the hash codes of the domain and the properties.
674 * @return a hash code for this object name.
676 public int hashCode()
678 return domain.hashCode() + properties.hashCode();
682 * Returns true if the domain of this object name is a pattern.
683 * This is the case if it contains one or more wildcard characters
686 * @return true if the domain is a pattern.
688 public boolean isDomainPattern()
690 return domain.contains("?") || domain.contains("*");
694 * Returns true if this is an object name pattern. An object
695 * name pattern has a domain containing a wildcard character
696 * ('*' or '?') and/or a '*' in the list of properties.
697 * This method will return true if either {@link #isDomainPattern()}
698 * or {@link #isPropertyPattern()} does.
700 * @return true if this is an object name pattern.
702 public boolean isPattern()
704 return isDomainPattern() || isPropertyPattern();
708 * Returns true if this object name is a property list
709 * pattern, a property value pattern or both.
711 * @return true if the properties of this name contain a pattern.
712 * @see #isPropertyListPattern
713 * @see #isPropertyValuePattern
715 public boolean isPropertyPattern()
717 return propertyListPattern || propertyValuePattern;
721 * Returns true if this object name is a property list pattern. This is
722 * the case if the list of properties contains an '*'.
724 * @return true if this is a property list pattern.
727 public boolean isPropertyListPattern()
729 return propertyListPattern;
733 * Returns true if this object name is a property value pattern. This is
734 * the case if one of the values contains a wildcard character,
737 * @return true if this is a property value pattern.
740 public boolean isPropertyValuePattern()
742 return propertyValuePattern;
746 * Returns true if the value of the given key is a pattern. This is
747 * the case if the value contains a wildcard character, '?' or '*'.
749 * @param key the key whose value should be checked.
750 * @return true if the value of the given key is a pattern.
752 * @throws NullPointerException if {@code key} is {@code null}.
753 * @throws IllegalArgumentException if {@code key} is not a valid
756 public boolean isPropertyValuePattern(String key)
758 String value = getKeyProperty(key);
760 throw new IllegalArgumentException(key + " is not a valid property.");
761 return value.indexOf('?') != -1 || value.indexOf('*') != -1;
766 * Returns a quoted version of the supplied string. The string may
767 * contain any character. The resulting quoted version is guaranteed
768 * to be usable as the value of a property, so this method provides
769 * a good way of ensuring that a value is legal.
772 * The string is transformed as follows:
775 * <li>The string is prefixed with an opening quote character, '"'.
776 * <li>For each character, s:
778 * <li>If s is a quote ('"'), it is replaced by a backslash
779 * followed by a quote.</li>
780 * <li>If s is a star ('*'), it is replaced by a backslash followed
782 * <li>If s is a question mark ('?'), it is replaced by a backslash
783 * followed by a question mark.</li>
784 * <li>If s is a backslash ('\'), it is replaced by two backslashes.</li>
785 * <li>If s is a newline character, it is replaced by a backslash followed by
787 * <li>Otherwise, s is used verbatim.
789 * <li>The string is terminated with a closing quote character, '"'.</li>
792 * @param string the string to quote.
793 * @return a quoted version of the supplied string.
794 * @throws NullPointerException if <code>string</code> is <code>null</code>.
796 public static String quote(String string)
798 StringBuilder builder = new StringBuilder();
800 for (int a = 0; a < string.length(); ++a)
802 char s = string.charAt(a);
806 builder.append("\\\"");
809 builder.append("\\*");
812 builder.append("\\?");
815 builder.append("\\\\");
818 builder.append("\\\n");
825 return builder.toString();
829 * Changes the {@link MBeanServer} on which this query is performed.
831 * @param server the new server to use.
833 public void setMBeanServer(MBeanServer server)
835 this.server = server;
839 * Returns a textual representation of the object name.
841 * <p>The format is unspecified beyond that equivalent object
842 * names will return the same string from this method, but note
843 * that Tomcat depends on the string returned by this method
844 * being a valid textual representation of the object name and
845 * will fail to start if it is not.
847 * @return a textual representation of the object name.
849 public String toString()
851 return getCanonicalName();
856 * Serialize this {@link ObjectName}. The serialized
857 * form is the same as the string parsed by the constructor.
859 * @param out the output stream to write to.
860 * @throws IOException if an I/O error occurs.
862 private void writeObject(ObjectOutputStream out)
865 out.defaultWriteObject();
866 StringBuffer buffer = new StringBuffer(getDomain());
868 String properties = getKeyPropertyListString();
869 buffer.append(properties);
870 if (isPropertyPattern())
872 if (properties.length() == 0)
877 out.writeObject(buffer.toString());
881 * Reads the serialized form, which is that used
882 * by the constructor.
884 * @param in the input stream to read from.
885 * @throws IOException if an I/O error occurs.
887 private void readObject(ObjectInputStream in)
888 throws IOException, ClassNotFoundException
890 in.defaultReadObject();
891 String objectName = (String)in.readObject();
896 catch (MalformedObjectNameException x)
898 throw new InvalidObjectException(x.toString());
904 * Unquotes the supplied string. The quotation marks are removed as
905 * are the backslashes preceding the escaped characters ('"', '?',
906 * '*', '\n', '\\'). A one-to-one mapping exists between quoted and
907 * unquoted values. As a result, a string <code>s</code> should be
908 * equal to <code>unquote(quote(s))</code>.
910 * @param q the quoted string to unquote.
911 * @return the unquoted string.
912 * @throws NullPointerException if <code>q</code> is <code>null</code>.
913 * @throws IllegalArgumentException if the string is not a valid
914 * quoted string i.e. it is not
915 * surrounded by quotation marks
916 * and/or characters are not properly
919 public static String unquote(String q)
921 if (q.charAt(0) != '"')
922 throw new IllegalArgumentException("The string does " +
923 "not start with a quote.");
924 if (q.charAt(q.length() - 1) != '"')
925 throw new IllegalArgumentException("The string does " +
926 "not end with a quote.");
927 StringBuilder builder = new StringBuilder();
928 for (int a = 1; a < (q.length() - 1); ++a)
930 char n = q.charAt(a);
934 if (n != '"' && n != '?' && n != '*' &&
935 n != 'n' && n != '\\')
936 throw new IllegalArgumentException("Illegal escaped character: "
939 else if (n == '"' || n == '\n')
940 throw new IllegalArgumentException("Illegal character: " + n);
944 return builder.toString();