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 * <domain>:<properties><wild>. <domain> 173 * represents the domain section of the name. <properties> 174 * represents the key-value pairs, as returned by {@link 175 * #getKeyPropertyListString()}. <wild> 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 * <domain>:<properties><wild>. <properties> 493 * is the same value as returned by 494 * {@link #getCanonicalKeyPropertyListString()}. <wild> 495 * is: 496 * </p> 497 * <ul> 498 * <li>an empty string, if the object name is not a property pattern.</li> 499 * <li>'*' if <properties> 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}