libjava/classpath/javax/management/ObjectName.java

   1 /* ObjectName.java -- Represent the name of a bean, or a pattern for a name.
   2    Copyright (C) 2006, 2007 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   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)
   9 any later version.
  10
  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.
  15
  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
  19 02110-1301 USA.
  20
  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
  24 combination.
  25
  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. */
  37
  38 package javax.management;
  39
  40 import java.io.Serializable;
  41
  42 import java.util.Hashtable;
  43 import java.util.Iterator;
  44 import java.util.Map;
  45 import java.util.TreeMap;
  46
  47 import java.io.IOException;
  48 import java.io.InvalidObjectException;
  49 import java.io.ObjectInputStream;
  50 import java.io.ObjectOutputStream;
  51
  52 /**
  53  * <p>
  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).
  59  * </p>
  60  * <p>
  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.
  67  * </p>
  68  * <p>
  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.
  76  * </p>
  77  * <p>
  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.
  81  * </p>
  82  * <p>
  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.
  89  * </p>
  90  * <p>
  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>.
  96  * </p>
  97  * <p>
  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
 101  * values.
 102  * </p>
 103  *
 104  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
 105  * @since 1.5
 106  */
 107 public class ObjectName
 108   implements Serializable, QueryExp
 109 {
 110
 111   private static final long serialVersionUID = 1081892073854801359L;
 112
 113   /**
 114    * The wildcard {@link ObjectName} {@code "*:*"}
 115    *
 116    * @since 1.6
 117    */
 118   public static final ObjectName WILDCARD;
 119
 120   /**
 121    * The domain of the name.
 122    */
 123   private transient String domain;
 124
 125   /**
 126    * The properties, as key-value pairs.
 127    */
 128   private transient TreeMap<String,String> properties;
 129
 130   /**
 131    * The properties as a string (stored for ordering).
 132    */
 133   private transient String propertyListString;
 134
 135   /**
 136    * True if this object name is a property list pattern.
 137    */
 138   private transient boolean propertyListPattern;
 139
 140   /**
 141    * True if this object name is a property value pattern.
 142    */
 143   private transient boolean propertyValuePattern;
 144
 145   /**
 146    * The management server associated with this object name.
 147    */
 148   private transient MBeanServer server;
 149
 150   /**
 151    * Static initializer to set up the wildcard.
 152    */
 153   static
 154   {
 155     try
 156       {
 157         WILDCARD = new ObjectName("");
 158       }
 159     catch (MalformedObjectNameException e)
 160       {
 161         throw (InternalError) (new InternalError("A problem occurred " +
 162                                                  "initializing the ObjectName " +
 163                                                  "wildcard.").initCause(e));
 164       }
 165   }
 166
 167   /**
 168    * Constructs an {@link ObjectName} instance from the given string,
 169    * which should be of the form
 170    * &lt;domain&gt;:&lt;properties&gt;&lt;wild&gt;.  &lt;domain&gt;
 171    * represents the domain section of the name.  &lt;properties&gt;
 172    * represents the key-value pairs, as returned by {@link
 173    * #getKeyPropertyListString()}.  &lt;wild&gt; 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.
 178    *
 179    * @param name the string to use to construct this instance.
 180    * @throws MalformedObjectNameException if the string is of the
 181    *                                      wrong format.
 182    * @throws NullPointerException if <code>name</code> is
 183    *                              <code>null</code>.
 184    */
 185   public ObjectName(String name)
 186     throws MalformedObjectNameException
 187   {
 188     if (name.length() == 0)
 189       name = "*:*";
 190     parse(name);
 191   }
 192
 193   /**
 194    * Parse the name in the same form as the constructor.  Used by
 195    * readObject().
 196    */
 197   private void parse(String name)
 198     throws MalformedObjectNameException
 199   {
 200     int domainSep = name.indexOf(':');
 201     if (domainSep == -1)
 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)
 213       {
 214         if (pairs[a].equals("*"))
 215           {
 216             if (propertyListPattern)
 217               throw new MalformedObjectNameException("Multiple wildcards " +
 218                                                      "in properties.");
 219             propertyListPattern = true;
 220             continue;
 221           }
 222         int sep = pairs[a].indexOf('=');
 223         if (sep == -1)
 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 " +
 229                                                  "more than once.");
 230         String value = pairs[a].substring(sep+1);
 231         properties.put(key, value);
 232         propertyListString += key + "=" + value + ",";
 233       }
 234     if (propertyListString.length() > 0)
 235       propertyListString =
 236         propertyListString.substring(0, propertyListString.length() - 1);
 237     checkComponents();
 238   }
 239
 240   /**
 241    * Constructs an {@link ObjectName} instance using the given
 242    * domain and the one specified property.
 243    *
 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
 251    *                                      specifications.
 252    * @throws NullPointerException if one of the parameters is
 253    *                              <code>null</code>.
 254    */
 255   public ObjectName(String domain, String key, String value)
 256     throws MalformedObjectNameException
 257   {
 258     this.domain = domain;
 259     properties = new TreeMap<String,String>();
 260     properties.put(key, value);
 261     checkComponents();
 262   }
 263
 264   /**
 265    * Constructs an {@link ObjectName} instance using the given
 266    * domain and properties.
 267    *
 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
 274    *                                      specifications.
 275    * @throws NullPointerException if one of the parameters is
 276    *                              <code>null</code>.
 277    */
 278   public ObjectName(String domain, Hashtable<String,String> properties)
 279     throws MalformedObjectNameException
 280   {
 281     this.domain = domain;
 282     this.properties = new TreeMap<String,String>();
 283     this.properties.putAll(properties);
 284     checkComponents();
 285   }
 286
 287   /**
 288    * Checks the legality of the domain and the properties.
 289    *
 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
 294    *                                      specifications.
 295    */
 296   private void checkComponents()
 297     throws MalformedObjectNameException
 298   {
 299     if (domain.indexOf(':') != -1)
 300       throw new MalformedObjectNameException("The domain includes a ':' " +
 301                                              "character.");
 302     if (domain.indexOf('\n') != -1)
 303       throw new MalformedObjectNameException("The domain includes a newline " +
 304                                              "character.");
 305     char[] keychars = new char[] { '\n', ':', ',', '*', '?', '=' };
 306     char[] valchars = new char[] { '\n', ':', ',', '=' };
 307     Iterator i = properties.entrySet().iterator();
 308     while (i.hasNext())
 309       {
 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 '" +
 315                                                    keychars[a] + "' " +
 316                                                    "character.");
 317         String value = (String) entry.getValue();
 318         int quote = value.indexOf('"');
 319         if (quote == 0)
 320           {
 321             try
 322               {
 323                 unquote(value);
 324               }
 325             catch (IllegalArgumentException e)
 326               {
 327                 throw (MalformedObjectNameException)
 328                   new MalformedObjectNameException("The quoted value is " +
 329                                                    "invalid.").initCause(e);
 330               }
 331           }
 332         else if (quote != -1)
 333           throw new MalformedObjectNameException("A value contains " +
 334                                                  "a '\"' character.");
 335         else
 336           {
 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] + "' " +
 341                                                        "character.");
 342
 343           }
 344         if (value.indexOf('*') != -1 || value.indexOf('?') != -1)
 345           propertyValuePattern = true;
 346       }
 347   }
 348
 349   /**
 350    * <p>
 351    * Attempts to find a match between this name and the one supplied.
 352    * The following criteria are used:
 353    * </p>
 354    * <ul>
 355    * <li>If the supplied name is a pattern, <code>false</code> is
 356    * returned.</li>
 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.
 361    * </ul>
 362    *
 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>.
 368    */
 369   public boolean apply(ObjectName name)
 370   {
 371     if (name.isPattern())
 372       return false;
 373
 374     if (!isPattern())
 375       return equals(name);
 376
 377     if (isDomainPattern())
 378       {
 379         if (!domainMatches(domain, 0, name.getDomain(), 0))
 380           return false;
 381       }
 382     else
 383       {
 384         if (!domain.equals(name.getDomain()))
 385           return false;
 386       }
 387
 388     if (isPropertyPattern())
 389       {
 390         Hashtable oProps = name.getKeyPropertyList();
 391         Iterator i = properties.entrySet().iterator();
 392         while (i.hasNext())
 393           {
 394             Map.Entry entry = (Map.Entry) i.next();
 395             String key = (String) entry.getKey();
 396             if (!(oProps.containsKey(key)))
 397               return false;
 398             String val = (String) entry.getValue();
 399             if (!(val.equals(oProps.get(key))))
 400               return false;
 401           }
 402       }
 403     else
 404       {
 405         if (!getCanonicalKeyPropertyListString().equals
 406             (name.getCanonicalKeyPropertyListString()))
 407           return false;
 408       }
 409     return true;
 410   }
 411
 412   /**
 413    * Returns true if the domain matches the pattern.
 414    *
 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.
 420    */
 421   private static boolean domainMatches(String pattern, int patternindex,
 422                                        String domain, int domainindex)
 423   {
 424     while (patternindex < pattern.length())
 425       {
 426         char c = pattern.charAt(patternindex++);
 427
 428         if (c == '*')
 429           {
 430             for (int i = domain.length(); i >= domainindex; i--)
 431               {
 432                 if (domainMatches(pattern, patternindex, domain, i))
 433                   return true;
 434               }
 435             return false;
 436           }
 437
 438         if (domainindex >= domain.length())
 439           return false;
 440
 441         if (c != '?' && c != domain.charAt(domainindex))
 442           return false;
 443
 444         domainindex++;
 445       }
 446     return true;
 447   }
 448
 449   /**
 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()}).
 454    *
 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.
 458    */
 459   public boolean equals(Object obj)
 460   {
 461     if (obj instanceof ObjectName)
 462       {
 463         ObjectName o = (ObjectName) obj;
 464         return getCanonicalName().equals(o.getCanonicalName());
 465       }
 466     return false;
 467   }
 468
 469   /**
 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)}.
 473    *
 474    * @return the property list, with the keys in lexicographic
 475    *         order.
 476    */
 477   public String getCanonicalKeyPropertyListString()
 478   {
 479     StringBuilder builder = new StringBuilder();
 480     Iterator i = properties.entrySet().iterator();
 481     while (i.hasNext())
 482       {
 483         Map.Entry entry = (Map.Entry) i.next();
 484         builder.append(entry.getKey() + "=" + entry.getValue());
 485         if (i.hasNext())
 486           builder.append(",");
 487       }
 488     return builder.toString();
 489   }
 490
 491   /**
 492    * <p>
 493    * Returns the name as a string in canonical form.  More precisely,
 494    * this returns a string of the format
 495    * &lt;domain&gt;:&lt;properties&gt;&lt;wild&gt;.  &lt;properties&gt;
 496    * is the same value as returned by
 497    * {@link #getCanonicalKeyPropertyListString()}.  &lt;wild&gt;
 498    * is:
 499    * </p>
 500    * <ul>
 501    * <li>an empty string, if the object name is not a property pattern.</li>
 502    * <li>'*' if &lt;properties&gt; is empty.</li>
 503    * <li>',*' if there is at least one key-value pair.</li>
 504    * </ul>
 505    *
 506    * @return the canonical string form of the object name, as specified
 507    *         above.
 508    */
 509   public String getCanonicalName()
 510   {
 511     return domain + ":" +
 512       getCanonicalKeyPropertyListString() +
 513       (isPropertyPattern() ? (properties.isEmpty() ? "*" : ",*") : "");
 514   }
 515
 516   /**
 517    * Returns the domain part of the object name.
 518    *
 519    * @return the domain.
 520    */
 521   public String getDomain()
 522   {
 523     return domain;
 524   }
 525
 526   /**
 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.
 534    *
 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>.
 540    */
 541   public static ObjectName getInstance(ObjectName name)
 542   {
 543     try
 544       {
 545         return new ObjectName(name.getCanonicalName());
 546       }
 547     catch (MalformedObjectNameException e)
 548       {
 549         throw (InternalError)
 550           (new InternalError("The canonical name of " +
 551                              "the given name is invalid.").initCause(e));
 552       }
 553   }
 554
 555   /**
 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.
 560    *
 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
 568    *                                      specifications.
 569    * @throws NullPointerException if <code>name</code> is <code>null</code>.
 570    */
 571   public static ObjectName getInstance(String name)
 572     throws MalformedObjectNameException
 573   {
 574     return new ObjectName(name);
 575   }
 576
 577   /**
 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.
 583    *
 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
 593    *                                      specifications.
 594    * @throws NullPointerException if <code>name</code> is <code>null</code>.
 595    */
 596   public static ObjectName getInstance(String domain, String key, String value)
 597     throws MalformedObjectNameException
 598   {
 599     return new ObjectName(domain, key, value);
 600   }
 601
 602   /**
 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
 607    * same string.
 608    *
 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
 617    *                                      specifications.
 618    * @throws NullPointerException if <code>name</code> is <code>null</code>.
 619    */
 620   public static ObjectName getInstance(String domain,
 621                                        Hashtable<String,String> properties)
 622     throws MalformedObjectNameException
 623   {
 624     return new ObjectName(domain, properties);
 625   }
 626
 627   /**
 628    * Returns the property value corresponding to the given key.
 629    *
 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>.
 633    */
 634   public String getKeyProperty(String key)
 635   {
 636     if (key == null)
 637       throw new NullPointerException("Null key given in request for a value.");
 638     return (String) properties.get(key);
 639   }
 640
 641   /**
 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.
 646    *
 647    * @return a {@link java.util.Hashtable}, containing each of the object
 648    *         name's properties.
 649    */
 650   public Hashtable<String,String> getKeyPropertyList()
 651   {
 652     return new Hashtable<String,String>(properties);
 653   }
 654
 655   /**
 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.
 660    *
 661    * @return the property list.
 662    */
 663   public String getKeyPropertyListString()
 664   {
 665     if (propertyListString != null)
 666       return propertyListString;
 667     return getCanonicalKeyPropertyListString();
 668   }
 669
 670   /**
 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.
 673    *
 674    * @return a hash code for this object name.
 675    */
 676   public int hashCode()
 677   {
 678     return domain.hashCode() + properties.hashCode();
 679   }
 680
 681   /**
 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
 684    * ('*' or '?').
 685    *
 686    * @return true if the domain is a pattern.
 687    */
 688   public boolean isDomainPattern()
 689   {
 690     return domain.contains("?") || domain.contains("*");
 691   }
 692
 693   /**
 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.
 699    *
 700    * @return true if this is an object name pattern.
 701    */
 702   public boolean isPattern()
 703   {
 704     return isDomainPattern() || isPropertyPattern();
 705   }
 706
 707   /**
 708    * Returns true if this object name is a property list
 709    * pattern, a property value pattern or both.
 710    *
 711    * @return true if the properties of this name contain a pattern.
 712    * @see #isPropertyListPattern
 713    * @see #isPropertyValuePattern
 714    */
 715   public boolean isPropertyPattern()
 716   {
 717     return propertyListPattern || propertyValuePattern;
 718   }
 719
 720   /**
 721    * Returns true if this object name is a property list pattern.  This is
 722    * the case if the list of properties contains an '*'.
 723    *
 724    * @return true if this is a property list pattern.
 725    * @since 1.6
 726    */
 727   public boolean isPropertyListPattern()
 728   {
 729     return propertyListPattern;
 730   }
 731
 732   /**
 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,
 735    * '?' or '*'.
 736    *
 737    * @return true if this is a property value pattern.
 738    * @since 1.6
 739    */
 740   public boolean isPropertyValuePattern()
 741   {
 742     return propertyValuePattern;
 743   }
 744
 745   /**
 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 '*'.
 748    *
 749    * @param key the key whose value should be checked.
 750    * @return true if the value of the given key is a pattern.
 751    * @since 1.6
 752    * @throws NullPointerException if {@code key} is {@code null}.
 753    * @throws IllegalArgumentException if {@code key} is not a valid
 754    *                                  property.
 755    */
 756   public boolean isPropertyValuePattern(String key)
 757   {
 758     String value = getKeyProperty(key);
 759     if (value == null)
 760       throw new IllegalArgumentException(key + " is not a valid property.");
 761     return value.indexOf('?') != -1 || value.indexOf('*') != -1;
 762   }
 763
 764   /**
 765    * <p>
 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.
 770    * </p>
 771    * <p>
 772    * The string is transformed as follows:
 773    * </p>
 774    * <ul>
 775    * <li>The string is prefixed with an opening quote character, '"'.
 776    * <li>For each character, s:
 777    * <ul>
 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
 781    * by a star.</li>
 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
 786    * a '\n'.</li>
 787    * <li>Otherwise, s is used verbatim.
 788    * </ul></li>
 789    * <li>The string is terminated with a closing quote character, '"'.</li>
 790    * </ul>
 791    *
 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>.
 795    */
 796   public static String quote(String string)
 797   {
 798     StringBuilder builder = new StringBuilder();
 799     builder.append('"');
 800     for (int a = 0; a < string.length(); ++a)
 801       {
 802         char s = string.charAt(a);
 803         switch (s)
 804           {
 805           case '"':
 806             builder.append("\\\"");
 807             break;
 808           case '*':
 809             builder.append("\\*");
 810             break;
 811           case '?':
 812             builder.append("\\?");
 813             break;
 814           case '\\':
 815             builder.append("\\\\");
 816             break;
 817           case '\n':
 818             builder.append("\\\n");
 819             break;
 820           default:
 821             builder.append(s);
 822           }
 823       }
 824     builder.append('"');
 825     return builder.toString();
 826   }
 827
 828   /**
 829    * Changes the {@link MBeanServer} on which this query is performed.
 830    *
 831    * @param server the new server to use.
 832    */
 833   public void setMBeanServer(MBeanServer server)
 834   {
 835     this.server = server;
 836   }
 837
 838   /**
 839    * Returns a textual representation of the object name.
 840    *
 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.
 846    *
 847    * @return a textual representation of the object name.
 848    */
 849   public String toString()
 850   {
 851     return getCanonicalName();
 852   }
 853
 854
 855   /**
 856    * Serialize this {@link ObjectName}.  The serialized
 857    * form is the same as the string parsed by the constructor.
 858    *
 859    * @param out the output stream to write to.
 860    * @throws IOException if an I/O error occurs.
 861    */
 862   private void writeObject(ObjectOutputStream out)
 863     throws IOException
 864   {
 865     out.defaultWriteObject();
 866     StringBuffer buffer = new StringBuffer(getDomain());
 867     buffer.append(':');
 868     String properties = getKeyPropertyListString();
 869     buffer.append(properties);
 870     if (isPropertyPattern())
 871       {
 872        if (properties.length() == 0)
 873          buffer.append("*");
 874        else
 875          buffer.append(",*");
 876       }
 877     out.writeObject(buffer.toString());
 878   }
 879
 880   /**
 881    * Reads the serialized form, which is that used
 882    * by the constructor.
 883    *
 884    * @param in the input stream to read from.
 885    * @throws IOException if an I/O error occurs.
 886    */
 887   private void readObject(ObjectInputStream in)
 888     throws IOException, ClassNotFoundException
 889    {
 890      in.defaultReadObject();
 891      String objectName = (String)in.readObject();
 892      try
 893        {
 894          parse(objectName);
 895        }
 896      catch (MalformedObjectNameException x)
 897        {
 898          throw new InvalidObjectException(x.toString());
 899        }
 900    }
 901
 902
 903   /**
 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>.
 909    *
 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
 917    *                                  escaped.
 918    */
 919   public static String unquote(String q)
 920   {
 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)
 929       {
 930         char n = q.charAt(a);
 931         if (n == '\\')
 932           {
 933             n = q.charAt(++a);
 934             if (n != '"' && n != '?' && n != '*' &&
 935                 n != 'n' && n != '\\')
 936               throw new IllegalArgumentException("Illegal escaped character: "
 937                                                  + n);
 938           }
 939         else if (n == '"' || n == '\n')
 940           throw new IllegalArgumentException("Illegal character: " + n);
 941         builder.append(n);
 942       }
 943
 944     return builder.toString();
 945   }
 946
 947 }