001/* ObjectName.java -- Represent the name of a bean, or a pattern for a name.
002   Copyright (C) 2006, 2007 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package javax.management;
039
040import gnu.java.lang.CPStringBuilder;
041
042import java.io.Serializable;
043
044import java.util.Hashtable;
045import java.util.Iterator;
046import java.util.Map;
047import java.util.TreeMap;
048
049import java.io.IOException;
050import java.io.InvalidObjectException;
051import java.io.ObjectInputStream;
052import java.io.ObjectOutputStream;
053
054/**
055 * <p>
056 * An {@link ObjectName} instance represents the name of a management
057 * bean, or a pattern which may match the name of one or more
058 * management beans.  Patterns are distinguished from names by the
059 * presence of the '?' and '*' characters (which match a single
060 * character and a series of zero or more characters, respectively).
061 * </p>
062 * <p>
063 * Each name begins with a domain element, which is terminated by
064 * a ':' character.  The domain may be empty.  If so, it will be
065 * replaced by the default domain of the bean server in certain
066 * contexts.  The domain is a pattern, if it contains either '?'
067 * or '*'.  To avoid collisions, it is usual to use reverse
068 * DNS names for the domain, as in Java package and property names.
069 * </p>
070 * <p>
071 * Following the ':' character is a series of properties.  The list
072 * is separated by commas, and largely consists of unordered key-value
073 * pairs, separated by an equals sign ('=').  At most one element may
074 * be an asterisk ('*'), which turns the {@link ObjectName} instance
075 * into a <emph>property list pattern</emph>.  In this situation, the pattern
076 * matches a name if the name contains at least those key-value pairs
077 * given and has the same domain.
078 * </p>
079 * <p>
080 * A <emph>key</emph> is a string of characters which doesn't include
081 * any of those used as delimiters or in patterns (':', '=', ',', '?'
082 * and '*').  Keys must be unique.
083 * </p>
084 * <p>
085 * A value may be <emph>quoted</emph> or <emph>unquoted</emph>.  Unquoted
086 * values obey the same rules as given for keys above.  Quoted values are
087 * surrounded by quotation marks ("), and use a backslash ('\') character
088 * to include quotes ('\"'), backslashes ('\\'), newlines ('\n'), and
089 * the pattern characters ('\?' and '\*').  The quotes and backslashes
090 * (after expansion) are considered part of the value.
091 * </p>
092 * <p>
093 * Both quoted and unquoted values may contain the wildcard characters
094 * '?' and '*'.  A name with at least one value containing a wildcard
095 * character is known as a <emph>property value pattern</emph>.  A
096 * name is generally a <emph>property pattern</emph> if it is either
097 * a <emph>property list pattern</emph> or <emph>property value pattern</emph>.
098 * </p>
099 * <p>
100 * Spaces are maintained within the different parts of the name.  Thus,
101 * '<code>domain: key1 = value1 </code>' has a key ' key1 ' with value
102 * ' value1 '.  Newlines are disallowed, except where escaped in quoted
103 * values.
104 * </p> 
105 *
106 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
107 * @since 1.5
108 */
109public class ObjectName
110  implements Serializable, QueryExp
111{
112
113  private static final long serialVersionUID = 1081892073854801359L;
114
115  /**
116   * The wildcard {@link ObjectName} {@code "*:*"}
117   *
118   * @since 1.6
119   */
120  public static final ObjectName WILDCARD;
121
122  /**
123   * The domain of the name.
124   */
125  private transient String domain;
126
127  /**
128   * The properties, as key-value pairs.
129   */
130  private transient TreeMap<String,String> properties;
131
132  /**
133   * The properties as a string (stored for ordering).
134   */
135  private transient String propertyListString;
136
137  /**
138   * True if this object name is a property list pattern.
139   */
140  private transient boolean propertyListPattern;
141
142  /**
143   * True if this object name is a property value pattern.
144   */
145  private transient boolean propertyValuePattern;
146
147  /**
148   * The management server associated with this object name.
149   */
150  private transient MBeanServer server;
151
152  /**
153   * Static initializer to set up the wildcard.
154   */
155  static
156  {
157    try
158      {
159        WILDCARD = new ObjectName("");
160      }
161    catch (MalformedObjectNameException e)
162      {
163        throw (InternalError) (new InternalError("A problem occurred " +
164                                                 "initializing the ObjectName " +
165                                                 "wildcard.").initCause(e));
166      }
167  }
168
169  /**
170   * Constructs an {@link ObjectName} instance from the given string,
171   * which should be of the form
172   * &lt;domain&gt;:&lt;properties&gt;&lt;wild&gt;.  &lt;domain&gt;
173   * represents the domain section of the name.  &lt;properties&gt;
174   * represents the key-value pairs, as returned by {@link
175   * #getKeyPropertyListString()}.  &lt;wild&gt; is the optional
176   * asterisk present in the property list.  If the string doesn't
177   * represent a property pattern, it will be empty.  If it does,
178   * it will be either ',*' or '*', depending on whether other
179   * properties are present or not, respectively.
180   *
181   * @param name the string to use to construct this instance.
182   * @throws MalformedObjectNameException if the string is of the
183   *                                      wrong format.
184   * @throws NullPointerException if <code>name</code> is
185   *                              <code>null</code>.
186   */
187  public ObjectName(String name)
188    throws MalformedObjectNameException
189  {
190    if (name.length() == 0)
191      name = "*:*";
192    parse(name);
193  }
194
195  /**
196   * Parse the name in the same form as the constructor.  Used by
197   * readObject().
198   */
199  private void parse(String name)
200    throws MalformedObjectNameException
201  {
202    int domainSep = name.indexOf(':');
203    if (domainSep == -1)
204      throw new MalformedObjectNameException("No domain separator was found.");
205    domain = name.substring(0, domainSep);
206    String rest = name.substring(domainSep + 1);
207    properties = new TreeMap<String,String>();
208    String[] pairs = rest.split(",");
209    if (pairs.length == 0 && !isPattern())
210      throw new MalformedObjectNameException("A name that is not a " +
211                                             "pattern must contain at " +
212                                             "least one key-value pair.");
213    propertyListString = "";
214    for (int a = 0; a < pairs.length; ++a)
215      {
216        if (pairs[a].equals("*"))
217          {
218            if (propertyListPattern)
219              throw new MalformedObjectNameException("Multiple wildcards " +
220                                                     "in properties.");
221            propertyListPattern = true;
222            continue;
223          }
224        int sep = pairs[a].indexOf('=');
225        if (sep == -1)
226          throw new MalformedObjectNameException("A key must be " +
227                                                 "followed by a value.");
228        String key = pairs[a].substring(0, sep);
229        if (properties.containsKey(key))
230          throw new MalformedObjectNameException("The same key occurs " +
231                                                 "more than once.");
232        String value = pairs[a].substring(sep+1);
233        properties.put(key, value);
234        propertyListString += key + "=" + value + ",";
235      }
236    if (propertyListString.length() > 0)
237      propertyListString =
238        propertyListString.substring(0, propertyListString.length() - 1);
239    checkComponents();
240  }
241
242  /**
243   * Constructs an {@link ObjectName} instance using the given
244   * domain and the one specified property.
245   *
246   * @param domain the domain part of the object name.
247   * @param key the key of the property.
248   * @param value the value of the property.
249   * @throws MalformedObjectNameException the domain, key or value
250   *                                      contains an illegal
251   *                                      character or the value
252   *                                      does not follow the quoting
253   *                                      specifications.
254   * @throws NullPointerException if one of the parameters is
255   *                              <code>null</code>.
256   */
257  public ObjectName(String domain, String key, String value)
258    throws MalformedObjectNameException
259  {
260    this.domain = domain;
261    properties = new TreeMap<String,String>();
262    properties.put(key, value);
263    checkComponents();
264  }
265
266  /**
267   * Constructs an {@link ObjectName} instance using the given
268   * domain and properties.
269   *
270   * @param domain the domain part of the object name.
271   * @param properties the key-value property pairs.
272   * @throws MalformedObjectNameException the domain, a key or a value
273   *                                      contains an illegal
274   *                                      character or a value
275   *                                      does not follow the quoting
276   *                                      specifications.
277   * @throws NullPointerException if one of the parameters is
278   *                              <code>null</code>.
279   */
280  public ObjectName(String domain, Hashtable<String,String> properties)
281    throws MalformedObjectNameException
282  {
283    this.domain = domain;
284    this.properties = new TreeMap<String,String>();
285    this.properties.putAll(properties);
286    checkComponents();
287  }
288
289  /**
290   * Checks the legality of the domain and the properties.
291   *
292   * @throws MalformedObjectNameException the domain, a key or a value
293   *                                      contains an illegal
294   *                                      character or a value
295   *                                      does not follow the quoting
296   *                                      specifications.
297   */
298  private void checkComponents()
299    throws MalformedObjectNameException
300  {
301    if (domain.indexOf(':') != -1)
302      throw new MalformedObjectNameException("The domain includes a ':' " +
303                                             "character.");
304    if (domain.indexOf('\n') != -1)
305      throw new MalformedObjectNameException("The domain includes a newline " +
306                                             "character.");
307    char[] keychars = new char[] { '\n', ':', ',', '*', '?', '=' };
308    char[] valchars = new char[] { '\n', ':', ',', '=' };
309    for (Map.Entry<String,String> entry : properties.entrySet())
310      {
311        for (int a = 0; a < keychars.length; ++a)
312          if (entry.getKey().indexOf(keychars[a]) != -1)
313            throw new MalformedObjectNameException("A key contains a '" +
314                                                   keychars[a] + "' " +
315                                                   "character.");
316        String value = entry.getValue();
317        int quote = value.indexOf('"');
318        if (quote == 0)
319          {
320            try
321              {
322                unquote(value);
323              }
324            catch (IllegalArgumentException e)
325              {
326                throw (MalformedObjectNameException)
327                  new MalformedObjectNameException("The quoted value is " +
328                                                   "invalid.").initCause(e);
329              }
330          }
331        else if (quote != -1)
332          throw new MalformedObjectNameException("A value contains " +
333                                                 "a '\"' character.");
334        else
335          {
336            for (int a = 0; a < valchars.length; ++a)
337              if (value.indexOf(valchars[a]) != -1)
338                throw new MalformedObjectNameException("A value contains " +
339                                                       "a '" + valchars[a] + "' " +
340                                                       "character.");
341            
342          }
343        if (value.indexOf('*') != -1 || value.indexOf('?') != -1)
344          propertyValuePattern = true;
345      }
346  }
347
348  /**
349   * <p>
350   * Attempts to find a match between this name and the one supplied.
351   * The following criteria are used:
352   * </p>
353   * <ul>
354   * <li>If the supplied name is a pattern, <code>false</code> is
355   * returned.</li>
356   * <li>If this name is a pattern, this method returns <code>true</code>
357   * if the supplied name matches the pattern.</li>
358   * <li>If this name is not a pattern, the result of
359   * <code>equals(name)</code> is returned.
360   * </ul>
361   *
362   * @param name the name to find a match with.
363   * @return true if the name either matches this pattern or is
364   *         equivalent to this name under the criteria of
365   *         {@link #equals(java.lang.Object)}
366   * @throws NullPointerException if <code>name</code> is <code>null</code>.
367   */
368  public boolean apply(ObjectName name)
369  {
370    if (name.isPattern())
371      return false;
372
373    if (!isPattern())
374      return equals(name);
375
376    if (isDomainPattern())
377      {
378        if (!domainMatches(domain, 0, name.getDomain(), 0))
379          return false;
380      }
381    else
382      {
383        if (!domain.equals(name.getDomain()))
384          return false;
385      }
386
387    if (isPropertyPattern())
388      {
389        Hashtable<String,String> oProps = name.getKeyPropertyList();
390        for (Map.Entry<String,String> entry : properties.entrySet())
391          {
392            String key = entry.getKey();
393            if (!(oProps.containsKey(key)))
394              return false;
395            String val = entry.getValue();
396            if (!(val.equals(oProps.get(key))))
397              return false;
398          }
399      }
400    else
401      {
402        if (!getCanonicalKeyPropertyListString().equals
403            (name.getCanonicalKeyPropertyListString()))
404          return false;
405      }
406    return true;
407  }
408
409  /**
410   * Returns true if the domain matches the pattern.
411   *
412   * @param pattern the pattern to match against.
413   * @param patternindex the index into the pattern to start matching.
414   * @param domain the domain to match.
415   * @param domainindex the index into the domain to start matching.
416   * @return true if the domain matches the pattern.
417   */
418  private static boolean domainMatches(String pattern, int patternindex,
419                                       String domain, int domainindex)
420  {
421    while (patternindex < pattern.length())
422      {
423        char c = pattern.charAt(patternindex++);
424        
425        if (c == '*')
426          {
427            for (int i = domain.length(); i >= domainindex; i--)
428              {
429                if (domainMatches(pattern, patternindex, domain, i))
430                  return true;
431              }
432            return false;
433          }
434
435        if (domainindex >= domain.length())
436          return false;
437        
438        if (c != '?' && c != domain.charAt(domainindex))
439          return false;
440
441        domainindex++;
442      }
443    return true;
444  }
445
446  /**
447   * Compares the specified object with this one.  The two
448   * are judged to be equivalent if the given object is an
449   * instance of {@link ObjectName} and has an equal canonical
450   * form (as returned by {@link #getCanonicalName()}).
451   *
452   * @param obj the object to compare with this.
453   * @return true if the object is also an {@link ObjectName}
454   *         with an equivalent canonical form.
455   */
456  public boolean equals(Object obj)
457  {
458    if (obj instanceof ObjectName)
459      {
460        ObjectName o = (ObjectName) obj;
461        return getCanonicalName().equals(o.getCanonicalName());
462      }
463    return false;
464  }
465
466  /**
467   * Returns the property list in canonical form.  The keys
468   * are ordered using the lexicographic ordering used by
469   * {@link java.lang.String#compareTo(java.lang.Object)}.
470   * 
471   * @return the property list, with the keys in lexicographic
472   *         order.
473   */
474  public String getCanonicalKeyPropertyListString()
475  {
476    CPStringBuilder builder = new CPStringBuilder();
477    Iterator<Map.Entry<String,String>> i = properties.entrySet().iterator();
478    while (i.hasNext())
479      {
480        Map.Entry<String,String> entry = i.next();
481        builder.append(entry.getKey() + "=" + entry.getValue());
482        if (i.hasNext())
483          builder.append(",");
484      }
485    return builder.toString();
486  }
487
488  /**
489   * <p>
490   * Returns the name as a string in canonical form.  More precisely,
491   * this returns a string of the format 
492   * &lt;domain&gt;:&lt;properties&gt;&lt;wild&gt;.  &lt;properties&gt;
493   * is the same value as returned by
494   * {@link #getCanonicalKeyPropertyListString()}.  &lt;wild&gt;
495   * is:
496   * </p>
497   * <ul>
498   * <li>an empty string, if the object name is not a property pattern.</li>
499   * <li>'*' if &lt;properties&gt; is empty.</li>
500   * <li>',*' if there is at least one key-value pair.</li>
501   * </ul>
502   * 
503   * @return the canonical string form of the object name, as specified
504   *         above.
505   */
506  public String getCanonicalName()
507  {
508    return domain + ":" +
509      getCanonicalKeyPropertyListString() +
510      (isPropertyPattern() ? (properties.isEmpty() ? "*" : ",*") : "");
511  }
512
513  /**
514   * Returns the domain part of the object name.
515   *
516   * @return the domain.
517   */
518  public String getDomain()
519  {
520    return domain;
521  }
522
523  /**
524   * Returns an {@link ObjectName} instance that is substitutable for the
525   * one given.  The instance returned may be a subclass of {@link ObjectName},
526   * but is not guaranteed to be of the same type as the given name, if that
527   * should also turn out to be a subclass.  The returned instance may or may
528   * not be equivalent to the one given.  The purpose of this method is to provide
529   * an instance of {@link ObjectName} with a well-defined semantics, such as may
530   * be used in cases where the given name is not trustworthy.
531   *
532   * @param name the {@link ObjectName} to provide a substitute for.
533   * @return a substitute for the given name, which may or may not be a subclass
534   *         of {@link ObjectName}.  In either case, the returned object is
535   *         guaranteed to have the semantics defined here.
536   * @throws NullPointerException if <code>name</code> is <code>null</code>.
537   */
538  public static ObjectName getInstance(ObjectName name)
539  {
540    try
541      {
542        return new ObjectName(name.getCanonicalName());
543      }
544    catch (MalformedObjectNameException e)
545      {
546        throw (InternalError)
547          (new InternalError("The canonical name of " +
548                             "the given name is invalid.").initCause(e));
549      }
550  }
551
552  /**
553   * Returns an {@link ObjectName} instance for the specified name, represented
554   * as a {@link java.lang.String}.  The instance returned may be a subclass of
555   * {@link ObjectName} and may or may not be equivalent to earlier instances
556   * returned by this method for the same string.
557   *
558   * @param name the {@link ObjectName} to provide an instance of.
559   * @return a instance for the given name, which may or may not be a subclass
560   *         of {@link ObjectName}.  
561   * @throws MalformedObjectNameException the domain, a key or a value
562   *                                      contains an illegal
563   *                                      character or a value
564   *                                      does not follow the quoting
565   *                                      specifications.
566   * @throws NullPointerException if <code>name</code> is <code>null</code>.
567   */
568  public static ObjectName getInstance(String name)
569    throws MalformedObjectNameException
570  {
571    return new ObjectName(name);
572  }
573
574  /**
575   * Returns an {@link ObjectName} instance for the specified name, represented
576   * as a series of {@link java.lang.String} objects for the domain and a single
577   * property, as a key-value pair.  The instance returned may be a subclass of
578   * {@link ObjectName} and may or may not be equivalent to earlier instances
579   * returned by this method for the same parameters.
580   *
581   * @param domain the domain part of the object name.
582   * @param key the key of the property.
583   * @param value the value of the property.
584   * @return a instance for the given name, which may or may not be a subclass
585   *         of {@link ObjectName}.  
586   * @throws MalformedObjectNameException the domain, a key or a value
587   *                                      contains an illegal
588   *                                      character or a value
589   *                                      does not follow the quoting
590   *                                      specifications.
591   * @throws NullPointerException if <code>name</code> is <code>null</code>.
592   */
593  public static ObjectName getInstance(String domain, String key, String value)
594    throws MalformedObjectNameException
595  {
596    return new ObjectName(domain, key, value);
597  }
598
599  /**
600   * Returns an {@link ObjectName} instance for the specified name, represented
601   * as a domain {@link java.lang.String} and a table of properties.  The
602   * instance returned may be a subclass of {@link ObjectName} and may or may
603   * not be equivalent to earlier instances returned by this method for the
604   * same string.
605   *
606   * @param domain the domain part of the object name.
607   * @param properties the key-value property pairs.
608   * @return a instance for the given name, which may or may not be a subclass
609   *         of {@link ObjectName}.  
610   * @throws MalformedObjectNameException the domain, a key or a value
611   *                                      contains an illegal
612   *                                      character or a value
613   *                                      does not follow the quoting
614   *                                      specifications.
615   * @throws NullPointerException if <code>name</code> is <code>null</code>.
616   */
617  public static ObjectName getInstance(String domain,
618                                       Hashtable<String,String> properties)
619    throws MalformedObjectNameException
620  {
621    return new ObjectName(domain, properties);
622  }
623
624  /**
625   * Returns the property value corresponding to the given key.
626   *
627   * @param key the key of the property to be obtained.
628   * @return the value of the specified property.
629   * @throws NullPointerException if <code>key</code> is <code>null</code>.
630   */
631  public String getKeyProperty(String key)
632  {
633    if (key == null)
634      throw new NullPointerException("Null key given in request for a value.");
635    return (String) properties.get(key);
636  }
637
638  /**
639   * Returns the properties in a {@link java.util.Hashtable}.  The table
640   * contains each of the properties as keys mapped to their value.  The
641   * returned table is not unmodifiable, but changes made to it will not
642   * be reflected in the object name.
643   *
644   * @return a {@link java.util.Hashtable}, containing each of the object
645   *         name's properties.
646   */
647  public Hashtable<String,String> getKeyPropertyList()
648  {
649    return new Hashtable<String,String>(properties);
650  }
651
652  /**
653   * Returns a {@link java.lang.String} representation of the property
654   * list.  If the object name was created using {@link
655   * ObjectName(String)}, then this string will contain the properties
656   * in the same order they were given in at creation.
657   * 
658   * @return the property list.
659   */
660  public String getKeyPropertyListString()
661  {
662    if (propertyListString != null)
663      return propertyListString;
664    return getCanonicalKeyPropertyListString();
665  }
666
667  /**
668   * Returns a hash code for this object name.  This is calculated as the
669   * summation of the hash codes of the domain and the properties.
670   *
671   * @return a hash code for this object name.
672   */
673  public int hashCode()
674  {
675    return domain.hashCode() + properties.hashCode();
676  }
677
678  /**
679   * Returns true if the domain of this object name is a pattern.
680   * This is the case if it contains one or more wildcard characters
681   * ('*' or '?').
682   *
683   * @return true if the domain is a pattern.
684   */
685  public boolean isDomainPattern()
686  {
687    return domain.contains("?") || domain.contains("*");
688  }
689
690  /**
691   * Returns true if this is an object name pattern.  An object
692   * name pattern has a domain containing a wildcard character
693   * ('*' or '?') and/or a '*' in the list of properties.
694   * This method will return true if either {@link #isDomainPattern()}
695   * or {@link #isPropertyPattern()} does.
696   *
697   * @return true if this is an object name pattern.
698   */
699  public boolean isPattern()
700  {
701    return isDomainPattern() || isPropertyPattern();
702  }
703
704  /**
705   * Returns true if this object name is a property list
706   * pattern, a property value pattern or both.
707   *
708   * @return true if the properties of this name contain a pattern.
709   * @see #isPropertyListPattern
710   * @see #isPropertyValuePattern
711   */
712  public boolean isPropertyPattern()
713  {
714    return propertyListPattern || propertyValuePattern;
715  }
716
717  /**
718   * Returns true if this object name is a property list pattern.  This is
719   * the case if the list of properties contains an '*'.
720   *
721   * @return true if this is a property list pattern.
722   * @since 1.6
723   */
724  public boolean isPropertyListPattern()
725  {
726    return propertyListPattern;
727  }
728
729  /**
730   * Returns true if this object name is a property value pattern.  This is
731   * the case if one of the values contains a wildcard character,
732   * '?' or '*'.
733   *
734   * @return true if this is a property value pattern.
735   * @since 1.6
736   */
737  public boolean isPropertyValuePattern()
738  {
739    return propertyValuePattern;
740  }
741
742  /**
743   * Returns true if the value of the given key is a pattern.  This is
744   * the case if the value contains a wildcard character, '?' or '*'.
745   *
746   * @param key the key whose value should be checked.
747   * @return true if the value of the given key is a pattern.
748   * @since 1.6
749   * @throws NullPointerException if {@code key} is {@code null}.
750   * @throws IllegalArgumentException if {@code key} is not a valid
751   *                                  property.
752   */
753  public boolean isPropertyValuePattern(String key)
754  {
755    String value = getKeyProperty(key);
756    if (value == null)
757      throw new IllegalArgumentException(key + " is not a valid property.");
758    return value.indexOf('?') != -1 || value.indexOf('*') != -1;
759  }
760
761  /**
762   * <p>
763   * Returns a quoted version of the supplied string.  The string may
764   * contain any character.  The resulting quoted version is guaranteed
765   * to be usable as the value of a property, so this method provides
766   * a good way of ensuring that a value is legal.
767   * </p>
768   * <p>
769   * The string is transformed as follows:
770   * </p>
771   * <ul>
772   * <li>The string is prefixed with an opening quote character, '"'.
773   * <li>For each character, s:
774   * <ul>
775   * <li>If s is a quote ('"'), it is replaced by a backslash
776   * followed by a quote.</li>
777   * <li>If s is a star ('*'), it is replaced by a backslash followed
778   * by a star.</li>
779   * <li>If s is a question mark ('?'), it is replaced by a backslash
780   * followed by a question mark.</li>
781   * <li>If s is a backslash ('\'), it is replaced by two backslashes.</li>
782   * <li>If s is a newline character, it is replaced by a backslash followed by
783   * a '\n'.</li>
784   * <li>Otherwise, s is used verbatim.
785   * </ul></li>
786   * <li>The string is terminated with a closing quote character, '"'.</li>
787   * </ul> 
788   * 
789   * @param string the string to quote.
790   * @return a quoted version of the supplied string.
791   * @throws NullPointerException if <code>string</code> is <code>null</code>.
792   */
793  public static String quote(String string)
794  {
795    CPStringBuilder builder = new CPStringBuilder();
796    builder.append('"');
797    for (int a = 0; a < string.length(); ++a)
798      {
799        char s = string.charAt(a);
800        switch (s)
801          {
802          case '"':
803            builder.append("\\\"");
804            break;
805          case '*':
806            builder.append("\\*");
807            break;
808          case '?':
809            builder.append("\\?");
810            break;
811          case '\\':
812            builder.append("\\\\");
813            break;
814          case '\n':
815            builder.append("\\\n");
816            break;
817          default:
818            builder.append(s);
819          }
820      }
821    builder.append('"');
822    return builder.toString();
823  }
824
825  /**
826   * Changes the {@link MBeanServer} on which this query is performed.
827   *
828   * @param server the new server to use.
829   */
830  public void setMBeanServer(MBeanServer server)
831  {
832    this.server = server;
833  }
834
835  /**
836   * Returns a textual representation of the object name.
837   *
838   * <p>The format is unspecified beyond that equivalent object
839   * names will return the same string from this method, but note
840   * that Tomcat depends on the string returned by this method
841   * being a valid textual representation of the object name and
842   * will fail to start if it is not.
843   *
844   * @return a textual representation of the object name.
845   */
846  public String toString()
847  {
848    return getCanonicalName();
849  }
850
851
852  /**
853   * Serialize this {@link ObjectName}.  The serialized
854   * form is the same as the string parsed by the constructor.
855   *
856   * @param out the output stream to write to.
857   * @throws IOException if an I/O error occurs.
858   */
859  private void writeObject(ObjectOutputStream out)
860    throws IOException
861  {
862    out.defaultWriteObject();
863    CPStringBuilder buffer = new CPStringBuilder(getDomain());
864    buffer.append(':');
865    String properties = getKeyPropertyListString();
866    buffer.append(properties);
867    if (isPropertyPattern())
868      {
869       if (properties.length() == 0)
870         buffer.append("*");
871       else
872         buffer.append(",*");
873      }
874    out.writeObject(buffer.toString());
875  }
876
877  /**
878   * Reads the serialized form, which is that used
879   * by the constructor.
880   *
881   * @param in the input stream to read from.
882   * @throws IOException if an I/O error occurs.
883   */
884  private void readObject(ObjectInputStream in) 
885    throws IOException, ClassNotFoundException
886   {
887     in.defaultReadObject();
888     String objectName = (String)in.readObject();
889     try
890       {
891         parse(objectName);
892       }
893     catch (MalformedObjectNameException x)
894       {
895         throw new InvalidObjectException(x.toString());
896       }
897   }
898
899
900  /**
901   * Unquotes the supplied string.  The quotation marks are removed as
902   * are the backslashes preceding the escaped characters ('"', '?',
903   * '*', '\n', '\\').  A one-to-one mapping exists between quoted and
904   * unquoted values.  As a result, a string <code>s</code> should be
905   * equal to <code>unquote(quote(s))</code>.
906   *
907   * @param q the quoted string to unquote.
908   * @return the unquoted string.
909   * @throws NullPointerException if <code>q</code> is <code>null</code>.
910   * @throws IllegalArgumentException if the string is not a valid
911   *                                  quoted string i.e. it is not 
912   *                                  surrounded by quotation marks
913   *                                  and/or characters are not properly
914   *                                  escaped.
915   */
916  public static String unquote(String q)
917  {
918    if (q.charAt(0) != '"')
919      throw new IllegalArgumentException("The string does " +
920                                         "not start with a quote.");
921    if (q.charAt(q.length() - 1) != '"')
922      throw new IllegalArgumentException("The string does " +
923                                         "not end with a quote.");
924    CPStringBuilder builder = new CPStringBuilder();
925    for (int a = 1; a < (q.length() - 1); ++a)
926      {
927        char n = q.charAt(a);
928        if (n == '\\')
929          {
930            n = q.charAt(++a);
931            if (n != '"' && n != '?' && n != '*' &&
932                n != 'n' && n != '\\')
933              throw new IllegalArgumentException("Illegal escaped character: "
934                                                 + n);
935          }
936        else if (n == '"' || n == '\n') 
937          throw new IllegalArgumentException("Illegal character: " + n);
938        builder.append(n);
939      }
940
941    return builder.toString();
942  }
943
944}