1. /*
  2. * @(#)CompoundName.java 1.5 00/02/02
  3. *
  4. * Copyright 1999, 2000 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package javax.naming;
  11. import java.util.Enumeration;
  12. import java.util.Properties;
  13. /**
  14. * This class represents a compound name -- a name from
  15. * a hierarchical name space.
  16. * Each component in a compound name is an atomic name.
  17. * <p>
  18. * The components of a compound name are numbered. The indexes of a
  19. * compound name with N components range from 0 up to, but not including, N.
  20. * This range may be written as [0,N).
  21. * The most significant component is at index 0.
  22. * An empty compound name has no components.
  23. *<p>
  24. * <h4>Compound Name Syntax</h4>
  25. * The syntax of a compound name is specified using a set of properties:
  26. *<dl>
  27. * <dt>jndi.syntax.direction
  28. * <dd>Direction for parsing ("right_to_left", "left_to_right", "flat").
  29. * If unspecified, defaults to "flat", which means the namespace is flat
  30. * with no hierarchical structure.
  31. *
  32. * <dt>jndi.syntax.separator
  33. * <dd>Separator between atomic name components.
  34. * Required unless direction is "flat".
  35. *
  36. * <dt>jndi.syntax.ignorecase
  37. * <dd>If present, "true" means ignore the case when comparing name
  38. * components. If its value is not "true", or if the property is not
  39. * present, case is considered when comparing name components.
  40. *
  41. * <dt>jndi.syntax.escape
  42. * <dd>If present, specifies the escape string for overriding separator,
  43. * escapes and quotes.
  44. *
  45. * <dt>jndi.syntax.beginquote
  46. * <dd>If present, specifies the string delimiting start of a quoted string.
  47. *
  48. * <dt>jndi.syntax.endquote
  49. * <dd>String delimiting end of quoted string.
  50. * If present, specifies the string delimiting the end of a quoted string.
  51. * If not present, use syntax.beginquote as end quote.
  52. * <dt>jndi.syntax.beginquote2
  53. * <dd>Alternative set of begin/end quotes.
  54. *
  55. * <dt>jndi.syntax.endquote2
  56. * <dd>Alternative set of begin/end quotes.
  57. *
  58. * <dt>jndi.syntax.trimblanks
  59. * <dd>If present, "true" means trim any leading and trailing whitespaces
  60. * in a name component for comparison purposes. If its value is not
  61. * "true", or if the property is not present, blanks are significant.
  62. * <dt>jndi.syntax.separator.ava
  63. * <dd>If present, specifies the string that separates
  64. * attribute-value-assertions when specifying multiple attribute/value
  65. * pairs. (e.g. "," in age=65,gender=male).
  66. * <dt>jndi.syntax.separator.typeval
  67. * <dd>If present, specifies the string that separators attribute
  68. * from value (e.g. "=" in "age=65")
  69. *</dl>
  70. * These properties are interpreted according to the following rules:
  71. *<ol>
  72. *<li>
  73. * In a string without quotes or escapes, any instance of the
  74. * separator delimits two atomic names. Each atomic name is referred
  75. * to as a <em>component</em>.
  76. *<li>
  77. * A separator, quote or escape is escaped if preceded immediately
  78. * (on the left) by the escape.
  79. *<li>
  80. * If there are two sets of quotes, a specific begin-quote must be matched
  81. * by its corresponding end-quote.
  82. *<li>
  83. * A non-escaped begin-quote which precedes a component must be
  84. * matched by a non-escaped end-quote at the end of the component.
  85. * A component thus quoted is referred to as a
  86. * <em>quoted component</em>. It is parsed by
  87. * removing the being- and end- quotes, and by treating the intervening
  88. * characters as ordinary characters unless one of the rules involving
  89. * quoted components listed below applies.
  90. *<li>
  91. * Quotes embedded in non-quoted components are treated as ordinary strings
  92. * and need not be matched.
  93. *<li>
  94. * A separator that is escaped or appears between non-escaped
  95. * quotes is treated as an ordinary string and not a separator.
  96. *<li>
  97. * An escape string within a quoted component acts as an escape only when
  98. * followed by the corresponding end-quote string.
  99. * This can be used to embed an escaped quote within a quoted component.
  100. *<li>
  101. * An escaped escape string is not treated as an escape string.
  102. *<li>
  103. * An escape string that does not precede a meta string (quotes or separator)
  104. * and is not at the end of a component is treated as an ordinary string.
  105. *<li>
  106. * A leading separator (the compound name string begins with
  107. * a separator) denotes a leading empty atomic component (consisting
  108. * of an empty string).
  109. * A trailing separator (the compound name string ends with
  110. * a separator) denotes a trailing empty atomic component.
  111. * Adjacent separators denote an empty atomic component.
  112. *</ol>
  113. * <p>
  114. * The string form of the compound name follows the syntax described above.
  115. * When the components of the compound name are turned into their
  116. * string representation, the reserved syntax rules described above are
  117. * applied (e.g. embedded separators are escaped or quoted)
  118. * so that when the same string is parsed, it will yield the same components
  119. * of the original compound name.
  120. *<p>
  121. *<h4>Multithreaded Access</h4>
  122. * A <tt>CompoundName</tt> instance is not synchronized against concurrent
  123. * multithreaded access. Multiple threads trying to access and modify a
  124. * <tt>CompoundName</tt> should lock the object.
  125. *
  126. * @author Rosanna Lee
  127. * @author Scott Seligman
  128. * @version 1.5 00/02/02
  129. * @since 1.3
  130. */
  131. public class CompoundName implements Name {
  132. /**
  133. * Implementation of this compound name.
  134. * This field is initialized by the constructors and cannot be null.
  135. * It should be treated as a read-only variable by subclasses.
  136. */
  137. protected transient NameImpl impl;
  138. /**
  139. * Syntax properties for this compound name.
  140. * This field is initialized by the constructors and cannot be null.
  141. * It should be treated as a read-only variable by subclasses.
  142. * Any necessary changes to mySyntax should be made within constructors
  143. * and not after the compound name has been instantiated.
  144. */
  145. protected transient Properties mySyntax;
  146. /**
  147. * Constructs a new compound name instance using the components
  148. * specified in comps and syntax. This protected method is intended to be
  149. * to be used by subclasses of CompoundName when they override
  150. * methods such as clone(), getPrefix(), getSuffix().
  151. *
  152. * @param comps A non-null enumeration of the components to add.
  153. * Each element of the enumeration is of class String.
  154. * The enumeration will be consumed to extract its
  155. * elements.
  156. * @param syntax A non-null properties that specify the syntax of
  157. * this compound name. See class description for
  158. * contents of properties.
  159. */
  160. protected CompoundName(Enumeration comps, Properties syntax) {
  161. mySyntax = syntax;
  162. impl = new NameImpl(syntax, comps);
  163. }
  164. /**
  165. * Constructs a new compound name instance by parsing the string n
  166. * using the syntax specified by the syntax properties supplied.
  167. *
  168. * @param n The non-null string to parse.
  169. * @param syntax A non-null list of properties that specify the syntax of
  170. * this compound name. See class description for
  171. * contents of properties.
  172. * @exception InvalidNameException If 'n' violates the syntax specified
  173. * by <code>syntax</code>.
  174. */
  175. public CompoundName(String n, Properties syntax) throws InvalidNameException {
  176. mySyntax = syntax;
  177. impl = new NameImpl(syntax, n);
  178. }
  179. /**
  180. * Generates the string representation of this compound name, using
  181. * the syntax rules of the compound name. The syntax rules
  182. * are described in the class description.
  183. * An empty component is represented by an empty string.
  184. *
  185. * The string representation thus generated can be passed to
  186. * the CompoundName constructor with the same syntax properties
  187. * to create a new equivalent compound name.
  188. *
  189. * @return A non-null string representation of this compound name.
  190. */
  191. public String toString() {
  192. return (impl.toString());
  193. }
  194. /**
  195. * Determines whether obj is syntactically equal to this compound name.
  196. * If obj is null or not a CompoundName, false is returned.
  197. * Two compound names are equal if each component in one is "equal"
  198. * to the corresponding component in the other.
  199. *<p>
  200. * Equality is also defined in terms of the syntax of this compound name.
  201. * The default implementation of CompoundName uses the syntax properties
  202. * jndi.syntax.ignorecase and jndi.syntax.trimblanks when comparing
  203. * two components for equality. If case is ignored, two strings
  204. * with the same sequence of characters but with different cases
  205. * are considered equal. If blanks are being trimmed, leading and trailing
  206. * blanks are ignored for the purpose of the comparison.
  207. *<p>
  208. * Both compound names must have the same number of components.
  209. *<p>
  210. * Implementation note: Currently the syntax properties of the two compound
  211. * names are not compared for equality. They might be in the future.
  212. *
  213. * @param obj The possibly null object to compare against.
  214. * @return true if obj is equal to this compound name, false otherwise.
  215. * @see #compareTo(java.lang.Object obj)
  216. */
  217. public boolean equals(Object obj) {
  218. // %%% check syntax too?
  219. return (obj != null &&
  220. obj instanceof CompoundName &&
  221. impl.equals(((CompoundName)obj).impl));
  222. }
  223. /**
  224. * Computes the hash code of this compound name.
  225. * The hash code is the sum of the hash codes of the "canonicalized"
  226. * forms of individual components of this compound name.
  227. * Each component is "canonicalized" according to the
  228. * compound name's syntax before its hash code is computed.
  229. * For a case-insensitive name, for example, the uppercased form of
  230. * a name has the same hash code as its lowercased equivalent.
  231. *
  232. * @return An int representing the hash code of this name.
  233. */
  234. public int hashCode() {
  235. return impl.hashCode();
  236. }
  237. /**
  238. * Creates a copy of this compound name.
  239. * Changes to the components of this compound name won't
  240. * affect the new copy and vice versa.
  241. * The clone and this compound name share the same syntax.
  242. *
  243. * @return A non-null copy of this compound name.
  244. */
  245. public Object clone() {
  246. return (new CompoundName(getAll(), mySyntax));
  247. }
  248. /**
  249. * Compares this CompoundName with the specified Object for order.
  250. * Returns a
  251. * negative integer, zero, or a positive integer as this Name is less
  252. * than, equal to, or greater than the given Object.
  253. * <p>
  254. * If obj is null or not an instance of CompoundName, ClassCastException
  255. * is thrown.
  256. * <p>
  257. * See equals() for what it means for two compound names to be equal.
  258. * If two compound names are equal, 0 is returned.
  259. *<p>
  260. * Ordering of compound names depend on the syntax of the compound name.
  261. * By default, they follow lexicographical rules for string comparison
  262. * with the extension that this applies to all the components in the
  263. * compound name and that comparison of individual components is
  264. * affected by the jndi.syntax.ignorecase and jndi.syntax.trimblanks
  265. * properties, identical to how they affect equals().
  266. * If this compound name is "lexicographically" lesser than obj,
  267. * a negative number is returned.
  268. * If this compound name is "lexicographically" greater than obj,
  269. * a positive number is returned.
  270. *<p>
  271. * Implementation note: Currently the syntax properties of the two compound
  272. * names are not compared when checking order. They might be in the future.
  273. * @param obj The non-null object to compare against.
  274. * @return a negative integer, zero, or a positive integer as this Name
  275. * is less than, equal to, or greater than the given Object.
  276. * @exception ClassCastException if obj is not a CompoundName.
  277. * @see #equals(java.lang.Object)
  278. */
  279. public int compareTo(Object obj) {
  280. if (!(obj instanceof CompoundName)) {
  281. throw new ClassCastException("Not a CompoundName");
  282. }
  283. return impl.compareTo(((CompoundName)obj).impl);
  284. }
  285. /**
  286. * Retrieves the number of components in this compound name.
  287. *
  288. * @return The nonnegative number of components in this compound name.
  289. */
  290. public int size() {
  291. return (impl.size());
  292. }
  293. /**
  294. * Determines whether this compound name is empty.
  295. * A compound name is empty if it has zero components.
  296. *
  297. * @return true if this compound name is empty, false otherwise.
  298. */
  299. public boolean isEmpty() {
  300. return (impl.isEmpty());
  301. }
  302. /**
  303. * Retrieves the components of this compound name as an enumeration
  304. * of strings.
  305. * The effects of updates to this compound name on this enumeration
  306. * is undefined.
  307. *
  308. * @return A non-null enumeration of the components of this
  309. * compound name. Each element of the enumeration is of class String.
  310. */
  311. public Enumeration getAll() {
  312. return (impl.getAll());
  313. }
  314. /**
  315. * Retrieves a component of this compound name.
  316. *
  317. * @param posn The 0-based index of the component to retrieve.
  318. * Must be in the range [0,size()).
  319. * @return The component at index posn.
  320. * @exception ArrayIndexOutOfBoundsException if posn is outside the
  321. * specified range.
  322. */
  323. public String get(int posn) {
  324. return (impl.get(posn));
  325. }
  326. /**
  327. * Creates a compound name whose components consist of a prefix of the
  328. * components in this compound name.
  329. * The result and this compound name share the same syntax.
  330. * Subsequent changes to
  331. * this compound name does not affect the name that is returned and
  332. * vice versa.
  333. *
  334. * @param posn The 0-based index of the component at which to stop.
  335. * Must be in the range [0,size()].
  336. * @return A compound name consisting of the components at indexes in
  337. * the range [0,posn).
  338. * @exception ArrayIndexOutOfBoundsException
  339. * If posn is outside the specified range.
  340. */
  341. public Name getPrefix(int posn) {
  342. Enumeration comps = impl.getPrefix(posn);
  343. return (new CompoundName(comps, mySyntax));
  344. }
  345. /**
  346. * Creates a compound name whose components consist of a suffix of the
  347. * components in this compound name.
  348. * The result and this compound name share the same syntax.
  349. * Subsequent changes to
  350. * this compound name does not affect the name that is returned.
  351. *
  352. * @param posn The 0-based index of the component at which to start.
  353. * Must be in the range [0,size()].
  354. * @return A compound name consisting of the components at indexes in
  355. * the range [posn,size()). If posn is equal to
  356. * size(), an empty compound name is returned.
  357. * @exception ArrayIndexOutOfBoundsException
  358. * If posn is outside the specified range.
  359. */
  360. public Name getSuffix(int posn) {
  361. Enumeration comps = impl.getSuffix(posn);
  362. return (new CompoundName(comps, mySyntax));
  363. }
  364. /**
  365. * Determines whether a compound name is a prefix of this compound name.
  366. * A compound name 'n' is a prefix if it is equal to
  367. * getPrefix(n.size())--in other words, this compound name
  368. * starts with 'n'.
  369. * If n is null or not a compound name, false is returned.
  370. *<p>
  371. * Implementation note: Currently the syntax properties of n
  372. * are not used when doing the comparison. They might be in the future.
  373. * @param n The possibly null compound name to check.
  374. * @return true if n is a CompoundName and
  375. * is a prefix of this compound name, false otherwise.
  376. */
  377. public boolean startsWith(Name n) {
  378. if (n instanceof CompoundName) {
  379. return (impl.startsWith(n.size(), n.getAll()));
  380. } else {
  381. return false;
  382. }
  383. }
  384. /**
  385. * Determines whether a compound name is a suffix of this compound name.
  386. * A compound name 'n' is a suffix if it it is equal to
  387. * getSuffix(size()-n.size())--in other words, this
  388. * compound name ends with 'n'.
  389. * If n is null or not a compound name, false is returned.
  390. *<p>
  391. * Implementation note: Currently the syntax properties of n
  392. * are not used when doing the comparison. They might be in the future.
  393. * @param n The possibly null compound name to check.
  394. * @return true if n is a CompoundName and
  395. * is a suffix of this compound name, false otherwise.
  396. */
  397. public boolean endsWith(Name n) {
  398. if (n instanceof CompoundName) {
  399. return (impl.endsWith(n.size(), n.getAll()));
  400. } else {
  401. return false;
  402. }
  403. }
  404. /**
  405. * Adds the components of a compound name -- in order -- to the end of
  406. * this compound name.
  407. *<p>
  408. * Implementation note: Currently the syntax properties of suffix
  409. * is not used or checked. They might be in the future.
  410. * @param suffix The non-null components to add.
  411. * @return The updated CompoundName, not a new one. Cannot be null.
  412. * @exception InvalidNameException If suffix is not a compound name,
  413. * or if the addition of the components violates the syntax
  414. * of this compound name (e.g. exceeding number of components).
  415. */
  416. public Name addAll(Name suffix) throws InvalidNameException {
  417. if (suffix instanceof CompoundName) {
  418. impl.addAll(suffix.getAll());
  419. return this;
  420. } else {
  421. throw new InvalidNameException("Not a compound name: " +
  422. suffix.toString());
  423. }
  424. }
  425. /**
  426. * Adds the components of a compound name -- in order -- at a specified
  427. * position within this compound name.
  428. * Components of this compound name at or after the index of the first
  429. * new component are shifted up (away from index 0)
  430. * to accommodate the new components.
  431. *<p>
  432. * Implementation note: Currently the syntax properties of suffix
  433. * is not used or checked. They might be in the future.
  434. *
  435. * @param n The non-null components to add.
  436. * @param posn The index in this name at which to add the new
  437. * components. Must be in the range [0,size()].
  438. * @return The updated CompoundName, not a new one. Cannot be null.
  439. * @exception ArrayIndexOutOfBoundsException
  440. * If posn is outside the specified range.
  441. * @exception InvalidNameException If n is not a compound name,
  442. * or if the addition of the components violates the syntax
  443. * of this compound name (e.g. exceeding number of components).
  444. */
  445. public Name addAll(int posn, Name n) throws InvalidNameException {
  446. if (n instanceof CompoundName) {
  447. impl.addAll(posn, n.getAll());
  448. return this;
  449. } else {
  450. throw new InvalidNameException("Not a compound name: " +
  451. n.toString());
  452. }
  453. }
  454. /**
  455. * Adds a single component to the end of this compound name.
  456. *
  457. * @param comp The non-null component to add.
  458. * @return The updated CompoundName, not a new one. Cannot be null.
  459. * @exception InvalidNameException If adding comp at end of the name
  460. * would violate the compound name's syntax.
  461. */
  462. public Name add(String comp) throws InvalidNameException{
  463. impl.add(comp);
  464. return this;
  465. }
  466. /**
  467. * Adds a single component at a specified position within this
  468. * compound name.
  469. * Components of this compound name at or after the index of the new
  470. * component are shifted up by one (away from index 0)
  471. * to accommodate the new component.
  472. *
  473. * @param comp The non-null component to add.
  474. * @param posn The index at which to add the new component.
  475. * Must be in the range [0,size()].
  476. * @exception ArrayIndexOutOfBoundsException
  477. * If posn is outside the specified range.
  478. * @return The updated CompoundName, not a new one. Cannot be null.
  479. * @exception InvalidNameException If adding comp at the specified position
  480. * would violate the compound name's syntax.
  481. */
  482. public Name add(int posn, String comp) throws InvalidNameException{
  483. impl.add(posn, comp);
  484. return this;
  485. }
  486. /**
  487. * Deletes a component from this compound name.
  488. * The component of this compound name at position 'posn' is removed,
  489. * and components at indices greater than 'posn'
  490. * are shifted down (towards index 0) by one.
  491. *
  492. * @param posn The index of the component to delete.
  493. * Must be in the range [0,size()).
  494. * @return The component removed (a String).
  495. * @exception ArrayIndexOutOfBoundsException
  496. * If posn is outside the specified range (includes case where
  497. * compound name is empty).
  498. * @exception InvalidNameException If deleting the component
  499. * would violate the compound name's syntax.
  500. */
  501. public Object remove(int posn) throws InvalidNameException {
  502. return impl.remove(posn);
  503. }
  504. /**
  505. * Overriden to avoid implementation dependency.
  506. * @serialData The syntax <tt>Properties</tt>, followed by
  507. * the number of components (an <tt>int</tt>), and the individual
  508. * components (each a <tt>String</tt>).
  509. */
  510. private void writeObject(java.io.ObjectOutputStream s)
  511. throws java.io.IOException {
  512. s.writeObject(mySyntax);
  513. s.writeInt(size());
  514. Enumeration comps = getAll();
  515. while (comps.hasMoreElements()) {
  516. s.writeObject(comps.nextElement());
  517. }
  518. }
  519. /**
  520. * Overriden to avoid implementation dependency.
  521. */
  522. private void readObject(java.io.ObjectInputStream s)
  523. throws java.io.IOException, ClassNotFoundException {
  524. mySyntax = (Properties)s.readObject();
  525. impl = new NameImpl(mySyntax);
  526. int n = s.readInt(); // number of components
  527. try {
  528. while (--n >= 0) {
  529. add((String)s.readObject());
  530. }
  531. } catch (InvalidNameException e) {
  532. throw (new java.io.StreamCorruptedException("Invalid name"));
  533. }
  534. }
  535. /**
  536. * Use serialVersionUID from JNDI 1.1.1 for interoperability
  537. */
  538. private static final long serialVersionUID = 3513100557083972036L;
  539. /*
  540. // For testing
  541. public static void main(String[] args) {
  542. Properties dotSyntax = new Properties();
  543. dotSyntax.put("jndi.syntax.direction", "right_to_left");
  544. dotSyntax.put("jndi.syntax.separator", ".");
  545. dotSyntax.put("jndi.syntax.ignorecase", "true");
  546. dotSyntax.put("jndi.syntax.escape", "\\");
  547. // dotSyntax.put("jndi.syntax.beginquote", "\"");
  548. // dotSyntax.put("jndi.syntax.beginquote2", "'");
  549. Name first = null;
  550. try {
  551. for (int i = 0; i < args.length; i++) {
  552. Name name;
  553. Enumeration e;
  554. System.out.println("Given name: " + args[i]);
  555. name = new CompoundName(args[i], dotSyntax);
  556. if (first == null) {
  557. first = name;
  558. }
  559. e = name.getComponents();
  560. while (e.hasMoreElements()) {
  561. System.out.println("Element: " + e.nextElement());
  562. }
  563. System.out.println("Constructed name: " + name.toString());
  564. System.out.println("Compare " + first.toString() + " with "
  565. + name.toString() + " = " + first.compareTo(name));
  566. }
  567. } catch (Exception ne) {
  568. ne.printStackTrace();
  569. }
  570. }
  571. */
  572. }