CompoundName


1   /*
2    * @(#)CompoundName.java    1.11 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.naming;
9   
10  import java.util.Enumeration  ;
11  import java.util.Properties  ;
12  
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.11 04/05/05
129  * @since 1.3
130  */
131 
132 public class CompoundName implements Name   {
133 
134     /**
135       * Implementation of this compound name.
136       * This field is initialized by the constructors and cannot be null.
137       * It should be treated as a read-only variable by subclasses.
138       */
139     protected transient NameImpl   impl;
140     /**
141       * Syntax properties for this compound name.
142       * This field is initialized by the constructors and cannot be null.
143       * It should be treated as a read-only variable by subclasses.
144       * Any necessary changes to mySyntax should be made within constructors
145       * and not after the compound name has been instantiated.
146       */
147     protected transient Properties   mySyntax;
148 
149     /**
150       * Constructs a new compound name instance using the components
151       * specified in comps and syntax. This protected method is intended to be
152       * to be used by subclasses of CompoundName when they override
153       * methods such as clone(), getPrefix(), getSuffix().
154       *
155       * @param comps  A non-null enumeration of the components to add.
156       *   Each element of the enumeration is of class String.
157       *               The enumeration will be consumed to extract its
158       *               elements. 
159       * @param syntax   A non-null properties that specify the syntax of
160       *         this compound name. See class description for
161       *         contents of properties.
162       */
163     protected CompoundName(Enumeration  <String  > comps, Properties   syntax) {
164     if (syntax == null) {
165         throw new NullPointerException  ();
166     }
167     mySyntax = syntax;
168     impl = new NameImpl  (syntax, comps);
169     }
170 
171     /**
172       * Constructs a new compound name instance by parsing the string n
173       * using the syntax specified by the syntax properties supplied.
174       *
175       * @param  n   The non-null string to parse.
176       * @param syntax   A non-null list of properties that specify the syntax of
177       *         this compound name.  See class description for
178       *         contents of properties.
179       * @exception  InvalidNameException If 'n' violates the syntax specified
180       *         by <code>syntax</code>.
181       */
182     public CompoundName(String   n, Properties   syntax) throws InvalidNameException   {
183     if (syntax == null) {
184         throw new NullPointerException  ();
185     }
186     mySyntax = syntax;
187     impl = new NameImpl  (syntax, n);
188     }
189 
190     /**
191       * Generates the string representation of this compound name, using
192       * the syntax rules of the compound name. The syntax rules
193       * are described in the class description.
194       * An empty component is represented by an empty string.
195       *
196       * The string representation thus generated can be passed to
197       * the CompoundName constructor with the same syntax properties
198       * to create a new equivalent compound name.
199       *
200       * @return A non-null string representation of this compound name.
201       */
202     public String   toString() {
203     return (impl.toString());
204     }
205 
206     /**
207       * Determines whether obj is syntactically equal to this compound name.
208       * If obj is null or not a CompoundName, false is returned.
209       * Two compound names are equal if each component in one is "equal"
210       * to the corresponding component in the other. 
211       *<p>
212       * Equality is also defined in terms of the syntax of this compound name.
213       * The default implementation of CompoundName uses the syntax properties
214       * jndi.syntax.ignorecase and jndi.syntax.trimblanks when comparing
215       * two components for equality.  If case is ignored, two strings
216       * with the same sequence of characters but with different cases
217       * are considered equal. If blanks are being trimmed, leading and trailing
218       * blanks are ignored for the purpose of the comparison.
219       *<p>
220       * Both compound names must have the same number of components.
221       *<p>
222       * Implementation note: Currently the syntax properties of the two compound
223       * names are not compared for equality. They might be in the future.
224       *
225       * @param  obj The possibly null object to compare against.
226       * @return true if obj is equal to this compound name, false otherwise.
227       * @see #compareTo(java.lang.Object obj)
228       */
229     public boolean equals(Object   obj) {
230     // %%% check syntax too?
231     return (obj != null &&
232         obj instanceof CompoundName   &&
233         impl.equals(((CompoundName  )obj).impl));
234     }
235 
236     /**
237       * Computes the hash code of this compound name.
238       * The hash code is the sum of the hash codes of the "canonicalized" 
239       * forms of individual components of this compound name.
240       * Each component is "canonicalized" according to the 
241       * compound name's syntax before its hash code is computed.
242       * For a case-insensitive name, for example, the uppercased form of 
243       * a name has the same hash code as its lowercased equivalent.
244       * 
245       * @return An int representing the hash code of this name.
246       */
247     public int hashCode() {
248     return impl.hashCode();
249     }
250 
251     /**
252       * Creates a copy of this compound name.
253       * Changes to the components of this compound name won't
254       * affect the new copy and vice versa.
255       * The clone and this compound name share the same syntax.
256       *
257       * @return A non-null copy of this compound name.
258       */
259     public Object   clone() {
260     return (new CompoundName  (getAll(), mySyntax));
261     }
262 
263     /**
264      * Compares this CompoundName with the specified Object for order.  
265      * Returns a
266      * negative integer, zero, or a positive integer as this Name is less
267      * than, equal to, or greater than the given Object. 
268      * <p>
269      * If obj is null or not an instance of CompoundName, ClassCastException
270      * is thrown.
271      * <p>
272      * See equals() for what it means for two compound names to be equal.
273      * If two compound names are equal, 0 is returned.
274      *<p>
275      * Ordering of compound names depend on the syntax of the compound name.
276      * By default, they follow lexicographical rules for string comparison
277      * with the extension that this applies to all the components in the
278      * compound name and that comparison of individual components is
279      * affected by the jndi.syntax.ignorecase and jndi.syntax.trimblanks
280      * properties, identical to how they affect equals().
281      * If this compound name is "lexicographically" lesser than obj,
282      * a negative number is returned.
283      * If this compound name is "lexicographically" greater than obj,
284      * a positive number is returned.
285      *<p>
286      * Implementation note: Currently the syntax properties of the two compound
287      * names are not compared when checking order. They might be in the future.
288      * @param   obj The non-null object to compare against.
289      * @return  a negative integer, zero, or a positive integer as this Name
290      *      is less than, equal to, or greater than the given Object.
291      * @exception ClassCastException if obj is not a CompoundName.
292      * @see #equals(java.lang.Object)
293      */
294     public int compareTo(Object   obj) {
295     if (!(obj instanceof CompoundName  )) {
296         throw new ClassCastException  ("Not a CompoundName");
297     }
298     return impl.compareTo(((CompoundName  )obj).impl);
299     }
300 
301     /**
302       * Retrieves the number of components in this compound name.
303       *
304       * @return The nonnegative number of components in this compound name.
305       */
306     public int size() {
307     return (impl.size());
308     }
309 
310     /**
311       * Determines whether this compound name is empty.
312       * A compound name is empty if it has zero components.
313       *
314       * @return true if this compound name is empty, false otherwise.
315       */
316     public boolean isEmpty() {
317     return (impl.isEmpty());
318     }
319 
320     /**
321       * Retrieves the components of this compound name as an enumeration
322       * of strings.
323       * The effects of updates to this compound name on this enumeration
324       * is undefined.
325       *
326       * @return A non-null enumeration of the components of this
327       * compound name. Each element of the enumeration is of class String.
328       */
329     public Enumeration  <String  > getAll() {
330     return (impl.getAll());
331     }
332 
333     /**
334       * Retrieves a component of this compound name.
335       *
336       * @param  posn    The 0-based index of the component to retrieve.
337       *         Must be in the range [0,size()).
338       * @return The component at index posn.
339       * @exception ArrayIndexOutOfBoundsException if posn is outside the
340       *     specified range.
341       */
342     public String   get(int posn) {
343     return (impl.get(posn));
344     }
345 
346     /**
347       * Creates a compound name whose components consist of a prefix of the
348       * components in this compound name.
349       * The result and this compound name share the same syntax.
350       * Subsequent changes to
351       * this compound name does not affect the name that is returned and
352       * vice versa.
353       *
354       * @param  posn    The 0-based index of the component at which to stop.
355       *         Must be in the range [0,size()].
356       * @return A compound name consisting of the components at indexes in
357       *     the range [0,posn).
358       * @exception ArrayIndexOutOfBoundsException
359       *     If posn is outside the specified range.
360       */
361     public Name   getPrefix(int posn) {
362     Enumeration   comps = impl.getPrefix(posn);
363     return (new CompoundName  (comps, mySyntax));
364     }
365 
366     /**
367       * Creates a compound name whose components consist of a suffix of the
368       * components in this compound name.
369       * The result and this compound name share the same syntax.
370       * Subsequent changes to
371       * this compound name does not affect the name that is returned.
372       *
373       * @param  posn    The 0-based index of the component at which to start.
374       *         Must be in the range [0,size()].
375       * @return A compound name consisting of the components at indexes in
376       *     the range [posn,size()).  If posn is equal to 
377       *     size(), an empty compound name is returned.
378       * @exception ArrayIndexOutOfBoundsException
379       *     If posn is outside the specified range.
380       */
381     public Name   getSuffix(int posn) {
382     Enumeration   comps = impl.getSuffix(posn);
383     return (new CompoundName  (comps, mySyntax));
384     }
385 
386     /**
387       * Determines whether a compound name is a prefix of this compound name.
388       * A compound name 'n' is a prefix if it is equal to 
389       * getPrefix(n.size())--in other words, this compound name
390       * starts with 'n'.
391       * If n is null or not a compound name, false is returned.
392       *<p>
393       * Implementation note: Currently the syntax properties of n
394       *  are not used when doing the comparison. They might be in the future.
395       * @param  n   The possibly null compound name to check.
396       * @return true if n is a CompoundName and
397       *         is a prefix of this compound name, false otherwise.
398       */
399     public boolean startsWith(Name   n) {
400     if (n instanceof CompoundName  ) {
401         return (impl.startsWith(n.size(), n.getAll()));
402     } else {
403         return false;
404     }
405     }
406 
407     /**
408       * Determines whether a compound name is a suffix of this compound name.
409       * A compound name 'n' is a suffix if it it is equal to
410       * getSuffix(size()-n.size())--in other words, this
411       * compound name ends with 'n'.
412       * If n is null or not a compound name, false is returned.
413       *<p>
414       * Implementation note: Currently the syntax properties of n
415       *  are not used when doing the comparison. They might be in the future.
416       * @param  n   The possibly null compound name to check.
417       * @return true if n is a CompoundName and
418       *     is a suffix of this compound name, false otherwise.
419       */
420     public boolean endsWith(Name   n) {
421     if (n instanceof CompoundName  ) {
422         return (impl.endsWith(n.size(), n.getAll()));
423     } else {
424         return false;
425     }
426     }
427 
428     /**
429       * Adds the components of a compound name -- in order -- to the end of
430       * this compound name.
431       *<p>
432       * Implementation note: Currently the syntax properties of suffix
433       *  is not used or checked. They might be in the future.
434       * @param suffix   The non-null components to add.
435       * @return The updated CompoundName, not a new one. Cannot be null.
436       * @exception InvalidNameException If suffix is not a compound name,
437       *        or if the addition of the components violates the syntax
438       *        of this compound name (e.g. exceeding number of components).
439       */
440     public Name   addAll(Name   suffix) throws InvalidNameException   {
441     if (suffix instanceof CompoundName  ) {
442         impl.addAll(suffix.getAll());
443         return this;
444     } else {
445         throw new InvalidNameException  ("Not a compound name: " +
446         suffix.toString());
447     }
448     }
449 
450     /**
451       * Adds the components of a compound name -- in order -- at a specified
452       * position within this compound name.
453       * Components of this compound name at or after the index of the first
454       * new component are shifted up (away from index 0)
455       * to accommodate the new components.
456       *<p>
457       * Implementation note: Currently the syntax properties of suffix
458       *  is not used or checked. They might be in the future.
459       *
460       * @param n    The non-null components to add.
461       * @param posn The index in this name at which to add the new
462       *         components.  Must be in the range [0,size()].
463       * @return The updated CompoundName, not a new one. Cannot be null.
464       * @exception ArrayIndexOutOfBoundsException
465       *     If posn is outside the specified range.
466       * @exception InvalidNameException If n is not a compound name,
467       *        or if the addition of the components violates the syntax
468       *        of this compound name (e.g. exceeding number of components).
469       */
470     public Name   addAll(int posn, Name   n) throws InvalidNameException   {
471     if (n instanceof CompoundName  ) {
472         impl.addAll(posn, n.getAll());
473         return this;
474     } else {
475         throw new InvalidNameException  ("Not a compound name: " +
476         n.toString());
477     }
478     }
479 
480     /**
481       * Adds a single component to the end of this compound name.
482       *
483       * @param comp The non-null component to add.
484       * @return The updated CompoundName, not a new one. Cannot be null.
485       * @exception InvalidNameException If adding comp at end of the name
486       *             would violate the compound name's syntax.
487       */
488     public Name   add(String   comp) throws InvalidNameException  {
489     impl.add(comp);
490     return this;
491     }
492 
493     /**
494       * Adds a single component at a specified position within this
495       * compound name.
496       * Components of this compound name at or after the index of the new
497       * component are shifted up by one (away from index 0)
498       * to accommodate the new component.
499       *
500       * @param  comp    The non-null component to add.
501       * @param  posn    The index at which to add the new component.
502       *         Must be in the range [0,size()].
503       * @exception ArrayIndexOutOfBoundsException
504       *     If posn is outside the specified range.
505       * @return The updated CompoundName, not a new one. Cannot be null.
506       * @exception InvalidNameException If adding comp at the specified position
507       *             would violate the compound name's syntax.
508       */
509     public Name   add(int posn, String   comp) throws InvalidNameException  {
510     impl.add(posn, comp);
511     return this;
512     }
513 
514     /**
515       * Deletes a component from this compound name.
516       * The component of this compound name at position 'posn' is removed,
517       * and components at indices greater than 'posn'
518       * are shifted down (towards index 0) by one.
519       *
520       * @param  posn    The index of the component to delete.
521       *         Must be in the range [0,size()).
522       * @return The component removed (a String).
523       * @exception ArrayIndexOutOfBoundsException
524       *     If posn is outside the specified range (includes case where
525       *     compound name is empty).
526       * @exception InvalidNameException If deleting the component
527       *             would violate the compound name's syntax.
528       */
529     public Object   remove(int posn) throws InvalidNameException   {
530     return impl.remove(posn);
531     }
532 
533     /**
534      * Overridden to avoid implementation dependency.
535      * @serialData The syntax <tt>Properties</tt>, followed by
536      * the number of components (an <tt>int</tt>), and the individual
537      * components (each a <tt>String</tt>).
538      */
539     private void writeObject(java.io.ObjectOutputStream   s)
540         throws java.io.IOException   {
541     s.writeObject(mySyntax);
542     s.writeInt(size());
543     Enumeration   comps = getAll();
544     while (comps.hasMoreElements()) {
545         s.writeObject(comps.nextElement());
546     }
547     }
548 
549     /**
550      * Overridden to avoid implementation dependency.
551      */
552     private void readObject(java.io.ObjectInputStream   s)
553         throws java.io.IOException  , ClassNotFoundException   {
554     mySyntax = (Properties  )s.readObject();
555     impl = new NameImpl  (mySyntax);
556     int n = s.readInt();    // number of components
557     try {
558         while (--n >= 0) {
559         add((String  )s.readObject());
560         }
561     } catch (InvalidNameException   e) {
562         throw (new java.io.StreamCorruptedException  ("Invalid name"));
563     }
564     }
565 
566     /**
567      * Use serialVersionUID from JNDI 1.1.1 for interoperability
568      */
569     private static final long serialVersionUID = 3513100557083972036L;
570 
571 /*
572 //   For testing
573 
574     public static void main(String[] args) {
575     Properties dotSyntax = new Properties();
576     dotSyntax.put("jndi.syntax.direction", "right_to_left");
577     dotSyntax.put("jndi.syntax.separator", ".");
578     dotSyntax.put("jndi.syntax.ignorecase", "true");
579     dotSyntax.put("jndi.syntax.escape", "\\");
580 //  dotSyntax.put("jndi.syntax.beginquote", "\"");
581 //  dotSyntax.put("jndi.syntax.beginquote2", "'");
582 
583         Name first = null;
584     try {
585         for (int i = 0; i < args.length; i++) {
586         Name name;
587         Enumeration e;
588         System.out.println("Given name: " + args[i]);
589         name = new CompoundName(args[i], dotSyntax);
590         if (first == null) {
591             first = name;
592         }
593         e = name.getComponents();
594         while (e.hasMoreElements()) {
595             System.out.println("Element: " + e.nextElement());
596         }
597         System.out.println("Constructed name: " + name.toString());
598 
599         System.out.println("Compare " + first.toString() + " with "
600             + name.toString() + " = " + first.compareTo(name));
601         }
602     } catch (Exception ne) {
603         ne.printStackTrace();
604     }
605     }
606 */
607 }
608 
609
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags