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    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.management;
039    
040    import gnu.java.lang.CPStringBuilder;
041    
042    import java.io.Serializable;
043    
044    import java.util.Hashtable;
045    import java.util.Iterator;
046    import java.util.Map;
047    import java.util.TreeMap;
048    
049    import java.io.IOException;
050    import java.io.InvalidObjectException;
051    import java.io.ObjectInputStream;
052    import 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     */
109    public 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    }