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