OSDN Git Service

604205437f31d450d3fd23446a63347e84d32934
[pf3gnuchains/gcc-fork.git] / 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.Collections;
43 import java.util.Hashtable;
44 import java.util.Iterator;
45 import java.util.Map;
46 import java.util.TreeMap;
47
48 /**
49  * <p>
50  * An {@link ObjectName} instance represents the name of a management
51  * bean, or a pattern which may match the name of one or more
52  * management beans.  Patterns are distinguished from names by the
53  * presence of the '?' and '*' characters (which match a single
54  * character and a series of zero or more characters, respectively).
55  * </p>
56  * <p>
57  * Each name begins with a domain element, which is terminated by
58  * a ':' character.  The domain may be empty.  If so, it will be
59  * replaced by the default domain of the bean server in certain
60  * contexts.  The domain is a pattern, if it contains either '?'
61  * or '*'.  To avoid collisions, it is usual to use reverse
62  * DNS names for the domain, as in Java package and property names.
63  * </p>
64  * <p>
65  * Following the ':' character is a series of properties.  The list
66  * is separated by commas, and largely consists of unordered key-value
67  * pairs, separated by an equals sign ('=').  At most one element may
68  * be an asterisk ('*'), which turns the {@link ObjectName} instance
69  * into a <emph>property pattern</emph>.  In this situation, the pattern
70  * matches a name if the name contains at least those key-value pairs
71  * given and has the same domain.
72  * </p>
73  * <p>
74  * A <emph>key</emph> is a string of characters which doesn't include
75  * any of those used as delimiters or in patterns (':', '=', ',', '?'
76  * and '*').  Keys must be unique.
77  * </p>
78  * <p>
79  * A value may be <emph>quoted</emph> or <emph>unquoted</emph>.  Unquoted
80  * values obey the same rules as given for keys above.  Quoted values are
81  * surrounded by quotation marks ("), and use a backslash ('\') character
82  * to include quotes ('\"'), backslashes ('\\'), newlines ('\n'), and
83  * the pattern characters ('\?' and '\*').  The quotes and backslashes
84  * (after expansion) are considered part of the value.
85  * </p>
86  * <p>
87  * Spaces are maintained within the different parts of the name.  Thus,
88  * '<code>domain: key1 = value1 </code>' has a key ' key1 ' with value
89  * ' value1 '.  Newlines are disallowed, except where escaped in quoted
90  * values.
91  * </p> 
92  *
93  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
94  * @since 1.5
95  */
96 public class ObjectName
97   implements Serializable, QueryExp
98 {
99
100   /**
101    * The domain of the name.
102    */
103   private String domain;
104
105   /**
106    * The properties, as key-value pairs.
107    */
108   private TreeMap<String,String> properties = new TreeMap<String,String>();
109
110   /**
111    * The properties as a string (stored for ordering).
112    */
113   private String propertyListString;
114
115   /**
116    * True if this object name is a property pattern.
117    */
118   private boolean propertyPattern;
119
120   /**
121    * The management server associated with this object name.
122    */
123   private MBeanServer server;
124
125   /**
126    * Constructs an {@link ObjectName} instance from the given string,
127    * which should be of the form
128    * &lt;domain&gt;:&lt;properties&gt;&lt;wild&gt;.  &lt;domain&gt;
129    * represents the domain section of the name.  &lt;properties&gt;
130    * represents the key-value pairs, as returned by {@link
131    * #getKeyPropertyListString()}.  &lt;wild&gt; is the optional
132    * asterisk present in the property list.  If the string doesn't
133    * represent a property pattern, it will be empty.  If it does,
134    * it will be either ',*' or '*', depending on whether other
135    * properties are present or not, respectively.
136    *
137    * @param name the string to use to construct this instance.
138    * @throws MalformedObjectNameException if the string is of the
139    *                                      wrong format.
140    * @throws NullPointerException if <code>name</code> is
141    *                              <code>null</code>.
142    */
143   public ObjectName(String name)
144     throws MalformedObjectNameException
145   {
146     if (name.length() == 0)
147       name = "*:*";
148
149     int domainSep = name.indexOf(':');
150     if (domainSep == -1)
151       throw new MalformedObjectNameException("No domain separator was found.");
152     domain = name.substring(0, domainSep);
153     String rest = name.substring(domainSep + 1);
154     if (rest.equals("*"))
155       propertyPattern = true;
156     else
157       {
158         if (rest.endsWith(",*"))
159           {
160             propertyPattern = true;
161             propertyListString = rest.substring(0, rest.length() - 2);
162           }
163         else
164           propertyListString = rest;
165         String[] pairs = propertyListString.split(",");
166         if (pairs.length == 0 && !isPattern())
167           throw new MalformedObjectNameException("A name that is not a " +
168                                                  "pattern must contain at " +
169                                                  "least one key-value pair.");
170         for (int a = 0; a < pairs.length; ++a)
171           {
172             int sep = pairs[a].indexOf('=');
173             String key = pairs[a].substring(0, sep);
174             if (properties.containsKey(key))
175               throw new MalformedObjectNameException("The same key occurs " +
176                                                      "more than once.");
177             properties.put(key, pairs[a].substring(sep + 1));
178           }     
179       }
180     checkComponents();
181   }
182
183   /**
184    * Constructs an {@link ObjectName} instance using the given
185    * domain and the one specified property.
186    *
187    * @param domain the domain part of the object name.
188    * @param key the key of the property.
189    * @param value the value of the property.
190    * @throws MalformedObjectNameException the domain, key or value
191    *                                      contains an illegal
192    *                                      character or the value
193    *                                      does not follow the quoting
194    *                                      specifications.
195    * @throws NullPointerException if one of the parameters is
196    *                              <code>null</code>.
197    */
198   public ObjectName(String domain, String key, String value)
199     throws MalformedObjectNameException
200   {
201     this.domain = domain;
202     properties.put(key, value);
203     checkComponents();
204   }
205
206   /**
207    * Constructs an {@link ObjectName} instance using the given
208    * domain and properties.
209    *
210    * @param domain the domain part of the object name.
211    * @param properties the key-value property pairs.
212    * @throws MalformedObjectNameException the domain, a key or a value
213    *                                      contains an illegal
214    *                                      character or a value
215    *                                      does not follow the quoting
216    *                                      specifications.
217    * @throws NullPointerException if one of the parameters is
218    *                              <code>null</code>.
219    */
220   public ObjectName(String domain, Hashtable<String,String> properties)
221     throws MalformedObjectNameException
222   {
223     this.domain = domain;
224     this.properties.putAll(properties);
225     checkComponents();
226   }
227
228   /**
229    * Checks the legality of the domain and the properties.
230    *
231    * @throws MalformedObjectNameException the domain, a key or a value
232    *                                      contains an illegal
233    *                                      character or a value
234    *                                      does not follow the quoting
235    *                                      specifications.
236    */
237   private void checkComponents()
238     throws MalformedObjectNameException
239   {
240     if (domain.indexOf(':') != -1)
241       throw new MalformedObjectNameException("The domain includes a ':' " +
242                                              "character.");
243     if (domain.indexOf('\n') != -1)
244       throw new MalformedObjectNameException("The domain includes a newline " +
245                                              "character.");
246     char[] chars = new char[] { ':', ',', '*', '?', '=' };
247     Iterator i = properties.entrySet().iterator();
248     while (i.hasNext())
249       {
250         Map.Entry entry = (Map.Entry) i.next();
251         String key = (String) entry.getKey();
252         for (int a = 0; a < chars.length; ++a)
253           if (key.indexOf(chars[a]) != -1)
254             throw new MalformedObjectNameException("A key contains a '" +
255                                                    chars[a] + "' " +
256                                                    "character.");
257         String value = (String) entry.getValue();
258         int quote = value.indexOf('"');
259         if (quote == 0)
260           {
261             try
262               {
263                 unquote(value);
264               }
265             catch (IllegalArgumentException e)
266               {
267                 throw new MalformedObjectNameException("The quoted value is " +
268                                                        "invalid.");
269               }
270           }
271         else if (quote != -1)
272           throw new MalformedObjectNameException("A value contains " +
273                                                  "a '\"' character.");
274         else
275           {
276             for (int a = 0; a < chars.length; ++a)
277               if (value.indexOf(chars[a]) != -1)
278                 throw new MalformedObjectNameException("A value contains " +
279                                                        "a '" + chars[a] + "' " +
280                                                        "character.");
281           }
282       }
283   }
284
285   /**
286    * <p>
287    * Attempts to find a match between this name and the one supplied.
288    * The following criteria are used:
289    * </p>
290    * <ul>
291    * <li>If the supplied name is a pattern, <code>false</code> is
292    * returned.</li>
293    * <li>If this name is a pattern, this method returns <code>true</code>
294    * if the supplied name matches the pattern.</li>
295    * <li>If this name is not a pattern, the result of
296    * <code>equals(name)</code> is returned.
297    * </ul>
298    *
299    * @param name the name to find a match with.
300    * @return true if the name either matches this pattern or is
301    *         equivalent to this name under the criteria of
302    *         {@link #equals(java.lang.Object)}
303    * @throws NullPointerException if <code>name</code> is <code>null</code>.
304    */
305   public boolean apply(ObjectName name)
306   {
307     if (name.isPattern())
308       return false;
309
310     if (!isPattern())
311       return equals(name);
312
313     if (isDomainPattern())
314       {
315         if (!domainMatches(domain, 0, name.getDomain(), 0))
316           return false;
317       }
318     else
319       {
320         if (!domain.equals(name.getDomain()))
321           return false;
322       }
323
324     if (isPropertyPattern())
325       {
326         Hashtable oProps = name.getKeyPropertyList();
327         Iterator i = properties.entrySet().iterator();
328         while (i.hasNext())
329           {
330             Map.Entry entry = (Map.Entry) i.next();
331             String key = (String) entry.getKey();
332             if (!(oProps.containsKey(key)))
333               return false;
334             String val = (String) entry.getValue();
335             if (!(val.equals(oProps.get(key))))
336               return false;
337           }
338       }
339     else
340       {
341         if (!getCanonicalKeyPropertyListString().equals
342             (name.getCanonicalKeyPropertyListString()))
343           return false;
344       }
345     return true;
346   }
347
348   /**
349    * Returns true if the domain matches the pattern.
350    *
351    * @param pattern the pattern to match against.
352    * @param patternindex the index into the pattern to start matching.
353    * @param domain the domain to match.
354    * @param domainindex the index into the domain to start matching.
355    * @return true if the domain matches the pattern.
356    */
357   private static boolean domainMatches(String pattern, int patternindex,
358                                        String domain, int domainindex)
359   {
360     while (patternindex < pattern.length())
361       {
362         char c = pattern.charAt(patternindex++);
363         
364         if (c == '*')
365           {
366             for (int i = domain.length(); i >= domainindex; i--)
367               {
368                 if (domainMatches(pattern, patternindex, domain, i))
369                   return true;
370               }
371             return false;
372           }
373
374         if (domainindex >= domain.length())
375           return false;
376         
377         if (c != '?' && c != domain.charAt(domainindex))
378           return false;
379
380         domainindex++;
381       }
382     return true;
383   }
384
385   /**
386    * Compares the specified object with this one.  The two
387    * are judged to be equivalent if the given object is an
388    * instance of {@link ObjectName} and has an equal canonical
389    * form (as returned by {@link #getCanonicalName()}).
390    *
391    * @param obj the object to compare with this.
392    * @return true if the object is also an {@link ObjectName}
393    *         with an equivalent canonical form.
394    */
395   public boolean equals(Object obj)
396   {
397     if (obj instanceof ObjectName)
398       {
399         ObjectName o = (ObjectName) obj;
400         return getCanonicalName().equals(o.getCanonicalName());
401       }
402     return false;
403   }
404
405   /**
406    * Returns the property list in canonical form.  The keys
407    * are ordered using the lexicographic ordering used by
408    * {@link java.lang.String#compareTo(java.lang.Object)}.
409    * 
410    * @return the property list, with the keys in lexicographic
411    *         order.
412    */
413   public String getCanonicalKeyPropertyListString()
414   {
415     StringBuilder builder = new StringBuilder();
416     Iterator i = properties.entrySet().iterator();
417     while (i.hasNext())
418       {
419         Map.Entry entry = (Map.Entry) i.next();
420         builder.append(entry.getKey() + "=" + entry.getValue());
421         if (i.hasNext())
422           builder.append(",");
423       }
424     return builder.toString();
425   }
426
427   /**
428    * <p>
429    * Returns the name as a string in canonical form.  More precisely,
430    * this returns a string of the format 
431    * &lt;domain&gt;:&lt;properties&gt;&lt;wild&gt;.  &lt;properties&gt;
432    * is the same value as returned by
433    * {@link #getCanonicalKeyPropertyListString()}.  &lt;wild&gt;
434    * is:
435    * </p>
436    * <ul>
437    * <li>an empty string, if the object name is not a property pattern.</li>
438    * <li>'*' if &lt;properties&gt; is empty.</li>
439    * <li>',*' if there is at least one key-value pair.</li>
440    * </ul>
441    * 
442    * @return the canonical string form of the object name, as specified
443    *         above.
444    */
445   public String getCanonicalName()
446   {
447     return domain + ":" +
448       getCanonicalKeyPropertyListString() +
449       (isPropertyPattern() ? (properties.isEmpty() ? "*" : ",*") : "");
450   }
451
452   /**
453    * Returns the domain part of the object name.
454    *
455    * @return the domain.
456    */
457   public String getDomain()
458   {
459     return domain;
460   }
461
462   /**
463    * Returns an {@link ObjectName} instance that is substitutable for the
464    * one given.  The instance returned may be a subclass of {@link ObjectName},
465    * but is not guaranteed to be of the same type as the given name, if that
466    * should also turn out to be a subclass.  The returned instance may or may
467    * not be equivalent to the one given.  The purpose of this method is to provide
468    * an instance of {@link ObjectName} with a well-defined semantics, such as may
469    * be used in cases where the given name is not trustworthy.
470    *
471    * @param name the {@link ObjectName} to provide a substitute for.
472    * @return a substitute for the given name, which may or may not be a subclass
473    *         of {@link ObjectName}.  In either case, the returned object is
474    *         guaranteed to have the semantics defined here.
475    * @throws NullPointerException if <code>name</code> is <code>null</code>.
476    */
477   public static ObjectName getInstance(ObjectName name)
478   {
479     try
480       {
481         return new ObjectName(name.getCanonicalName());
482       }
483     catch (MalformedObjectNameException e)
484       {
485         throw (InternalError)
486           (new InternalError("The canonical name of " +
487                              "the given name is invalid.").initCause(e));
488       }
489   }
490
491   /**
492    * Returns an {@link ObjectName} instance for the specified name, represented
493    * as a {@link java.lang.String}.  The instance returned may be a subclass of
494    * {@link ObjectName} and may or may not be equivalent to earlier instances
495    * returned by this method for the same string.
496    *
497    * @param name the {@link ObjectName} to provide an instance of.
498    * @return a instance for the given name, which may or may not be a subclass
499    *         of {@link ObjectName}.  
500    * @throws MalformedObjectNameException the domain, a key or a value
501    *                                      contains an illegal
502    *                                      character or a value
503    *                                      does not follow the quoting
504    *                                      specifications.
505    * @throws NullPointerException if <code>name</code> is <code>null</code>.
506    */
507   public static ObjectName getInstance(String name)
508     throws MalformedObjectNameException
509   {
510     return new ObjectName(name);
511   }
512
513   /**
514    * Returns an {@link ObjectName} instance for the specified name, represented
515    * as a series of {@link java.lang.String} objects for the domain and a single
516    * property, as a key-value pair.  The instance returned may be a subclass of
517    * {@link ObjectName} and may or may not be equivalent to earlier instances
518    * returned by this method for the same parameters.
519    *
520    * @param domain the domain part of the object name.
521    * @param key the key of the property.
522    * @param value the value of the property.
523    * @return a instance for the given name, which may or may not be a subclass
524    *         of {@link ObjectName}.  
525    * @throws MalformedObjectNameException the domain, a key or a value
526    *                                      contains an illegal
527    *                                      character or a value
528    *                                      does not follow the quoting
529    *                                      specifications.
530    * @throws NullPointerException if <code>name</code> is <code>null</code>.
531    */
532   public static ObjectName getInstance(String domain, String key, String value)
533     throws MalformedObjectNameException
534   {
535     return new ObjectName(domain, key, value);
536   }
537
538   /**
539    * Returns an {@link ObjectName} instance for the specified name, represented
540    * as a domain {@link java.lang.String} and a table of properties.  The
541    * instance returned may be a subclass of {@link ObjectName} and may or may
542    * not be equivalent to earlier instances returned by this method for the
543    * same string.
544    *
545    * @param domain the domain part of the object name.
546    * @param properties the key-value property pairs.
547    * @return a instance for the given name, which may or may not be a subclass
548    *         of {@link ObjectName}.  
549    * @throws MalformedObjectNameException the domain, a key or a value
550    *                                      contains an illegal
551    *                                      character or a value
552    *                                      does not follow the quoting
553    *                                      specifications.
554    * @throws NullPointerException if <code>name</code> is <code>null</code>.
555    */
556   public static ObjectName getInstance(String domain,
557                                        Hashtable<String,String> properties)
558     throws MalformedObjectNameException
559   {
560     return new ObjectName(domain, properties);
561   }
562
563   /**
564    * Returns the property value corresponding to the given key.
565    *
566    * @param key the key of the property to be obtained.
567    * @return the value of the specified property.
568    * @throws NullPointerException if <code>key</code> is <code>null</code>.
569    */
570   public String getKeyProperty(String key)
571   {
572     if (key == null)
573       throw new NullPointerException("Null key given in request for a value.");
574     return (String) properties.get(key);
575   }
576
577   /**
578    * Returns the properties in a {@link java.util.Hashtable}.  The table
579    * contains each of the properties as keys mapped to their value.  The
580    * returned table is not unmodifiable, but changes made to it will not
581    * be reflected in the object name.
582    *
583    * @return a {@link java.util.Hashtable}, containing each of the object
584    *         name's properties.
585    */
586   public Hashtable<String,String> getKeyPropertyList()
587   {
588     return new Hashtable<String,String>(properties);
589   }
590
591   /**
592    * Returns a {@link java.lang.String} representation of the property
593    * list.  If the object name was created using {@link
594    * ObjectName(String)}, then this string will contain the properties
595    * in the same order they were given in at creation.
596    * 
597    * @return the property list.
598    */
599   public String getKeyPropertyListString()
600   {
601     if (propertyListString != null)
602       return propertyListString;
603     return getCanonicalKeyPropertyListString();
604   }
605
606   /**
607    * Returns a hash code for this object name.  This is calculated as the
608    * summation of the hash codes of the domain and the properties.
609    *
610    * @return a hash code for this object name.
611    */
612   public int hashCode()
613   {
614     return domain.hashCode() + properties.hashCode();
615   }
616
617   /**
618    * Returns true if the domain of this object name is a pattern.
619    * This is the case if it contains one or more wildcard characters
620    * ('*' or '?').
621    *
622    * @return true if the domain is a pattern.
623    */
624   public boolean isDomainPattern()
625   {
626     return domain.contains("?") || domain.contains("*");
627   }
628
629   /**
630    * Returns true if this is an object name pattern.  An object
631    * name pattern has a domain containing a wildcard character
632    * ('*' or '?') and/or a '*' in the list of properties.
633    * This method will return true if either {@link #isDomainPattern()}
634    * or {@link #isPropertyPattern()} does.
635    *
636    * @return true if this is an object name pattern.
637    */
638   public boolean isPattern()
639   {
640     return isDomainPattern() || isPropertyPattern();
641   }
642
643   /**
644    * Returns true if this object name is a property pattern.  This is
645    * the case if the list of properties contains an '*'.
646    *
647    * @return true if this is a property pattern.
648    */
649   public boolean isPropertyPattern()
650   {
651     return propertyPattern;
652   }
653
654   /**
655    * <p>
656    * Returns a quoted version of the supplied string.  The string may
657    * contain any character.  The resulting quoted version is guaranteed
658    * to be usable as the value of a property, so this method provides
659    * a good way of ensuring that a value is legal.
660    * </p>
661    * <p>
662    * The string is transformed as follows:
663    * </p>
664    * <ul>
665    * <li>The string is prefixed with an opening quote character, '"'.
666    * <li>For each character, s:
667    * <ul>
668    * <li>If s is a quote ('"'), it is replaced by a backslash
669    * followed by a quote.</li>
670    * <li>If s is a star ('*'), it is replaced by a backslash followed
671    * by a star.</li>
672    * <li>If s is a question mark ('?'), it is replaced by a backslash
673    * followed by a question mark.</li>
674    * <li>If s is a backslash ('\'), it is replaced by two backslashes.</li>
675    * <li>If s is a newline character, it is replaced by a backslash followed by
676    * a '\n'.</li>
677    * <li>Otherwise, s is used verbatim.
678    * </ul></li>
679    * <li>The string is terminated with a closing quote character, '"'.</li>
680    * </ul> 
681    * 
682    * @param string the string to quote.
683    * @return a quoted version of the supplied string.
684    * @throws NullPointerException if <code>string</code> is <code>null</code>.
685    */
686   public static String quote(String string)
687   {
688     StringBuilder builder = new StringBuilder();
689     builder.append('"');
690     for (int a = 0; a < string.length(); ++a)
691       {
692         char s = string.charAt(a);
693         switch (s)
694           {
695           case '"':
696             builder.append("\\\"");
697             break;
698           case '*':
699             builder.append("\\*");
700             break;
701           case '?':
702             builder.append("\\?");
703             break;
704           case '\\':
705             builder.append("\\\\");
706             break;
707           case '\n':
708             builder.append("\\\n");
709             break;
710           default:
711             builder.append(s);
712           }
713       }
714     builder.append('"');
715     return builder.toString();
716   }
717
718   /**
719    * Changes the {@link MBeanServer} on which this query is performed.
720    *
721    * @param server the new server to use.
722    */
723   public void setMBeanServer(MBeanServer server)
724   {
725     this.server = server;
726   }
727
728   /**
729    * Returns a textual representation of the object name.
730    *
731    * <p>The format is unspecified beyond that equivalent object
732    * names will return the same string from this method, but note
733    * that Tomcat depends on the string returned by this method
734    * being a valid textual representation of the object name and
735    * will fail to start if it is not.
736    *
737    * @return a textual representation of the object name.
738    */
739   public String toString()
740   {
741     return getCanonicalName();
742   }
743
744   /**
745    * Unquotes the supplied string.  The quotation marks are removed as
746    * are the backslashes preceding the escaped characters ('"', '?',
747    * '*', '\n', '\\').  A one-to-one mapping exists between quoted and
748    * unquoted values.  As a result, a string <code>s</code> should be
749    * equal to <code>unquote(quote(s))</code>.
750    *
751    * @param q the quoted string to unquote.
752    * @return the unquoted string.
753    * @throws NullPointerException if <code>q</code> is <code>null</code>.
754    * @throws IllegalArgumentException if the string is not a valid
755    *                                  quoted string i.e. it is not 
756    *                                  surrounded by quotation marks
757    *                                  and/or characters are not properly
758    *                                  escaped.
759    */
760   public static String unquote(String q)
761   {
762     if (q.charAt(0) != '"')
763       throw new IllegalArgumentException("The string does " +
764                                          "not start with a quote.");
765     if (q.charAt(q.length() - 1) != '"')
766       throw new IllegalArgumentException("The string does " +
767                                          "not end with a quote.");
768     StringBuilder builder = new StringBuilder();
769     for (int a = 1; a < (q.length() - 1); ++a)
770       {
771         char n = q.charAt(a);
772         if (n == '\\')
773           {
774             n = q.charAt(++a);
775             if (n != '"' && n != '?' && n != '*' &&
776                 n != '\n' && n != '\\')
777               throw new IllegalArgumentException("Illegal escaped character: "
778                                                  + n);
779           }
780         builder.append(n);
781       }
782
783     return builder.toString();
784   }
785
786 }