Home » openjdk-7 » javax » naming » ldap » [javadoc | source]

    1   /*
    2    * Copyright (c) 2003, 2010, 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.ldap;
   27   
   28   import javax.naming.Name;
   29   import javax.naming.InvalidNameException;
   30   
   31   import java.util.Enumeration;
   32   import java.util.Collection;
   33   import java.util.ArrayList;
   34   import java.util.List;
   35   import java.util.Iterator;
   36   import java.util.ListIterator;
   37   import java.util.Collections;
   38   
   39   import java.io.ObjectOutputStream;
   40   import java.io.ObjectInputStream;
   41   import java.io.IOException;
   42   
   43   /**
   44    * This class represents a distinguished name as specified by
   45    * <a href="http://www.ietf.org/rfc/rfc2253.txt">RFC 2253</a>.
   46    * A distinguished name, or DN, is composed of an ordered list of
   47    * components called <em>relative distinguished name</em>s, or RDNs.
   48    * Details of a DN's syntax are described in RFC 2253.
   49    *<p>
   50    * This class resolves a few ambiguities found in RFC 2253
   51    * as follows:
   52    * <ul>
   53    * <li> RFC 2253 leaves the term "whitespace" undefined. The
   54    *      ASCII space character 0x20 (" ") is used in its place.
   55    * <li> Whitespace is allowed on either side of ',', ';', '=', and '+'.
   56    *      Such whitespace is accepted but not generated by this code,
   57    *      and is ignored when comparing names.
   58    * <li> AttributeValue strings containing '=' or non-leading '#'
   59    *      characters (unescaped) are accepted.
   60    * </ul>
   61    *<p>
   62    * String names passed to <code>LdapName</code> or returned by it
   63    * use the full Unicode character set. They may also contain
   64    * characters encoded into UTF-8 with each octet represented by a
   65    * three-character substring such as "\\B4".
   66    * They may not, however, contain characters encoded into UTF-8 with
   67    * each octet represented by a single character in the string:  the
   68    * meaning would be ambiguous.
   69    *<p>
   70    * <code>LdapName</code> will properly parse all valid names, but
   71    * does not attempt to detect all possible violations when parsing
   72    * invalid names.  It is "generous" in accepting invalid names.
   73    * The "validity" of a name is determined ultimately when it
   74    * is supplied to an LDAP server, which may accept or
   75    * reject the name based on factors such as its schema information
   76    * and interoperability considerations.
   77    *<p>
   78    * When names are tested for equality, attribute types, both binary
   79    * and string values, are case-insensitive.
   80    * String values with different but equivalent usage of quoting,
   81    * escaping, or UTF8-hex-encoding are considered equal.  The order of
   82    * components in multi-valued RDNs (such as "ou=Sales+cn=Bob") is not
   83    * significant.
   84    * <p>
   85    * The components of a LDAP name, that is, RDNs, are numbered. The
   86    * indexes of a LDAP name with n RDNs range from 0 to n-1.
   87    * This range may be written as [0,n).
   88    * The right most RDN is at index 0, and the left most RDN is at
   89    * index n-1. For example, the distinguished name:
   90    * "CN=Steve Kille, O=Isode Limited, C=GB" is numbered in the following
   91    * sequence ranging from 0 to 2: {C=GB, O=Isode Limited, CN=Steve Kille}. An
   92    * empty LDAP name is represented by an empty RDN list.
   93    *<p>
   94    * Concurrent multithreaded read-only access of an instance of
   95    * <tt>LdapName</tt> need not be synchronized.
   96    *<p>
   97    * Unless otherwise noted, the behavior of passing a null argument
   98    * to a constructor or method in this class will cause a
   99    * NullPointerException to be thrown.
  100    *
  101    * @author Scott Seligman
  102    * @since 1.5
  103    */
  104   
  105   public class LdapName implements Name {
  106   
  107       // private transient ArrayList<Rdn> rdns;   // parsed name components
  108   
  109       private transient ArrayList rdns;   // parsed name components
  110       private transient String unparsed;  // if non-null, the DN in unparsed form
  111       private static final long serialVersionUID = -1595520034788997356L;
  112   
  113       /**
  114        * Constructs an LDAP name from the given distinguished name.
  115        *
  116        * @param name  This is a non-null distinguished name formatted
  117        * according to the rules defined in
  118        * <a href="http://www.ietf.org/rfc/rfc2253.txt">RFC 2253</a>.
  119        *
  120        * @throws InvalidNameException if a syntax violation is detected.
  121        * @see Rdn#escapeValue(Object value)
  122        */
  123       public LdapName(String name) throws InvalidNameException {
  124           unparsed = name;
  125           parse();
  126       }
  127   
  128       /**
  129        * Constructs an LDAP name given its parsed RDN components.
  130        * <p>
  131        * The indexing of RDNs in the list follows the numbering of
  132        * RDNs described in the class description.
  133        *
  134        * @param rdns The non-null list of <tt>Rdn</tt>s forming this LDAP name.
  135        */
  136       public LdapName(List<Rdn> rdns) {
  137   
  138           // if (rdns instanceof ArrayList<Rdn>) {
  139           //      this.rdns = rdns.clone();
  140           // } else if (rdns instanceof List<Rdn>) {
  141           //      this.rdns = new ArrayList<Rdn>(rdns);
  142           // } else {
  143           //      throw IllegalArgumentException(
  144           //              "Invalid entries, list entries must be of type Rdn");
  145           //  }
  146   
  147           this.rdns = new ArrayList(rdns.size());
  148           for (int i = 0; i < rdns.size(); i++) {
  149               Object obj = rdns.get(i);
  150               if (!(obj instanceof Rdn)) {
  151                   throw new IllegalArgumentException("Entry:" + obj +
  152                           "  not a valid type;list entries must be of type Rdn");
  153               }
  154               this.rdns.add(obj);
  155           }
  156       }
  157   
  158       /*
  159        * Constructs an LDAP name given its parsed components (the elements
  160        * of "rdns" in the range [beg,end)) and, optionally
  161        * (if "name" is not null), the unparsed DN.
  162        *
  163        */
  164       // private LdapName(String name, List<Rdn> rdns, int beg, int end) {
  165   
  166       private LdapName(String name, ArrayList rdns, int beg, int end) {
  167           unparsed = name;
  168           // this.rdns = rdns.subList(beg, end);
  169   
  170           List sList = rdns.subList(beg, end);
  171           this.rdns = new ArrayList(sList);
  172       }
  173   
  174       /**
  175        * Retrieves the number of components in this LDAP name.
  176        * @return The non-negative number of components in this LDAP name.
  177        */
  178       public int size() {
  179           return rdns.size();
  180       }
  181   
  182       /**
  183        * Determines whether this LDAP name is empty.
  184        * An empty name is one with zero components.
  185        * @return true if this LDAP name is empty, false otherwise.
  186        */
  187       public boolean isEmpty() {
  188           return rdns.isEmpty();
  189       }
  190   
  191       /**
  192        * Retrieves the components of this name as an enumeration
  193        * of strings. The effect of updates to this name on this enumeration
  194        * is undefined. If the name has zero components, an empty (non-null)
  195        * enumeration is returned.
  196        * The order of the components returned by the enumeration is same as
  197        * the order in which the components are numbered as described in the
  198        * class description.
  199        *
  200        * @return A non-null enumeration of the components of this LDAP name.
  201        * Each element of the enumeration is of class String.
  202        */
  203       public Enumeration<String> getAll() {
  204           final Iterator iter = rdns.iterator();
  205   
  206           return new Enumeration<String>() {
  207               public boolean hasMoreElements() {
  208                   return iter.hasNext();
  209               }
  210               public String nextElement() {
  211                   return iter.next().toString();
  212               }
  213           };
  214       }
  215   
  216       /**
  217        * Retrieves a component of this LDAP name as a string.
  218        * @param  posn The 0-based index of the component to retrieve.
  219        *              Must be in the range [0,size()).
  220        * @return The non-null component at index posn.
  221        * @exception IndexOutOfBoundsException if posn is outside the
  222        *          specified range.
  223        */
  224       public String get(int posn) {
  225           return rdns.get(posn).toString();
  226       }
  227   
  228       /**
  229        * Retrieves an RDN of this LDAP name as an Rdn.
  230        * @param   posn The 0-based index of the RDN to retrieve.
  231        *          Must be in the range [0,size()).
  232        * @return The non-null RDN at index posn.
  233        * @exception IndexOutOfBoundsException if posn is outside the
  234        *            specified range.
  235        */
  236       public Rdn getRdn(int posn) {
  237           return (Rdn) rdns.get(posn);
  238       }
  239   
  240       /**
  241        * Creates a name whose components consist of a prefix of the
  242        * components of this LDAP name.
  243        * Subsequent changes to this name will not affect the name
  244        * that is returned and vice versa.
  245        * @param  posn     The 0-based index of the component at which to stop.
  246        *                  Must be in the range [0,size()].
  247        * @return  An instance of <tt>LdapName</tt> consisting of the
  248        *          components at indexes in the range [0,posn).
  249        *          If posn is zero, an empty LDAP name is returned.
  250        * @exception   IndexOutOfBoundsException
  251        *              If posn is outside the specified range.
  252        */
  253       public Name getPrefix(int posn) {
  254           try {
  255               return new LdapName(null, rdns, 0, posn);
  256           } catch (IllegalArgumentException e) {
  257               throw new IndexOutOfBoundsException(
  258                   "Posn: " + posn + ", Size: "+ rdns.size());
  259           }
  260       }
  261   
  262       /**
  263        * Creates a name whose components consist of a suffix of the
  264        * components in this LDAP name.
  265        * Subsequent changes to this name do not affect the name that is
  266        * returned and vice versa.
  267        *
  268        * @param  posn     The 0-based index of the component at which to start.
  269        *                  Must be in the range [0,size()].
  270        * @return  An instance of <tt>LdapName</tt> consisting of the
  271        *          components at indexes in the range [posn,size()).
  272        *          If posn is equal to size(), an empty LDAP name is
  273        *          returned.
  274        * @exception IndexOutOfBoundsException
  275        *          If posn is outside the specified range.
  276        */
  277       public Name getSuffix(int posn) {
  278           try {
  279               return new LdapName(null, rdns, posn, rdns.size());
  280           } catch (IllegalArgumentException e) {
  281               throw new IndexOutOfBoundsException(
  282                   "Posn: " + posn + ", Size: "+ rdns.size());
  283           }
  284       }
  285   
  286       /**
  287        * Determines whether this LDAP name starts with a specified LDAP name
  288        * prefix.
  289        * A name <tt>n</tt> is a prefix if it is equal to
  290        * <tt>getPrefix(n.size())</tt>--in other words this LDAP
  291        * name starts with 'n'. If n is null or not a RFC2253 formatted name
  292        * as described in the class description, false is returned.
  293        *
  294        * @param n The LDAP name to check.
  295        * @return  true if <tt>n</tt> is a prefix of this LDAP name,
  296        * false otherwise.
  297        * @see #getPrefix(int posn)
  298        */
  299       public boolean startsWith(Name n) {
  300           if (n == null) {
  301               return false;
  302           }
  303           int len1 = rdns.size();
  304           int len2 = n.size();
  305           return (len1 >= len2 &&
  306                   matches(0, len2, n));
  307       }
  308   
  309       /**
  310        * Determines whether the specified RDN sequence forms a prefix of this
  311        * LDAP name.  Returns true if this LdapName is at least as long as rdns,
  312        * and for every position p in the range [0, rdns.size()) the component
  313        * getRdn(p) matches rdns.get(p). Returns false otherwise. If rdns is
  314        * null, false is returned.
  315        *
  316        * @param rdns The sequence of <tt>Rdn</tt>s to check.
  317        * @return  true if <tt>rdns</tt> form a prefix of this LDAP name,
  318        *          false otherwise.
  319        */
  320       public boolean startsWith(List<Rdn> rdns) {
  321           if (rdns == null) {
  322               return false;
  323           }
  324           int len1 = this.rdns.size();
  325           int len2 = rdns.size();
  326           return (len1 >= len2 &&
  327                   doesListMatch(0, len2, rdns));
  328       }
  329   
  330       /**
  331        * Determines whether this LDAP name ends with a specified
  332        * LDAP name suffix.
  333        * A name <tt>n</tt> is a suffix if it is equal to
  334        * <tt>getSuffix(size()-n.size())</tt>--in other words this LDAP
  335        * name ends with 'n'. If n is null or not a RFC2253 formatted name
  336        * as described in the class description, false is returned.
  337        *
  338        * @param n The LDAP name to check.
  339        * @return true if <tt>n</tt> is a suffix of this name, false otherwise.
  340        * @see #getSuffix(int posn)
  341        */
  342       public boolean endsWith(Name n) {
  343           if (n == null) {
  344               return false;
  345           }
  346           int len1 = rdns.size();
  347           int len2 = n.size();
  348           return (len1 >= len2 &&
  349                   matches(len1 - len2, len1, n));
  350       }
  351   
  352       /**
  353        * Determines whether the specified RDN sequence forms a suffix of this
  354        * LDAP name.  Returns true if this LdapName is at least as long as rdns,
  355        * and for every position p in the range [size() - rdns.size(), size())
  356        * the component getRdn(p) matches rdns.get(p). Returns false otherwise.
  357        * If rdns is null, false is returned.
  358        *
  359        * @param rdns The sequence of <tt>Rdn</tt>s to check.
  360        * @return  true if <tt>rdns</tt> form a suffix of this LDAP name,
  361        *          false otherwise.
  362        */
  363       public boolean endsWith(List<Rdn> rdns) {
  364           if (rdns == null) {
  365               return false;
  366           }
  367           int len1 = this.rdns.size();
  368           int len2 = rdns.size();
  369           return (len1 >= len2 &&
  370                   doesListMatch(len1 - len2, len1, rdns));
  371       }
  372   
  373       private boolean doesListMatch(int beg, int end, List rdns) {
  374           for (int i = beg; i < end; i++) {
  375               if (!this.rdns.get(i).equals(rdns.get(i - beg))) {
  376                   return false;
  377               }
  378           }
  379           return true;
  380       }
  381   
  382       /*
  383        * Helper method for startsWith() and endsWith().
  384        * Returns true if components [beg,end) match the components of "n".
  385        * If "n" is not an LdapName, each of its components is parsed as
  386        * the string form of an RDN.
  387        * The following must hold:  end - beg == n.size().
  388        */
  389       private boolean matches(int beg, int end, Name n) {
  390           if (n instanceof LdapName) {
  391               LdapName ln = (LdapName) n;
  392               return doesListMatch(beg, end, ln.rdns);
  393           } else {
  394               for (int i = beg; i < end; i++) {
  395                   Rdn rdn;
  396                   String rdnString = n.get(i - beg);
  397                   try {
  398                       rdn = (new Rfc2253Parser(rdnString)).parseRdn();
  399                   } catch (InvalidNameException e) {
  400                       return false;
  401                   }
  402                   if (!rdn.equals(rdns.get(i))) {
  403                       return false;
  404                   }
  405               }
  406           }
  407           return true;
  408       }
  409   
  410       /**
  411        * Adds the components of a name -- in order -- to the end of this name.
  412        *
  413        * @param   suffix The non-null components to add.
  414        * @return  The updated name (not a new instance).
  415        *
  416        * @throws  InvalidNameException if <tt>suffix</tt> is not a valid LDAP
  417        *          name, or if the addition of the components would violate the
  418        *          syntax rules of this LDAP name.
  419        */
  420       public Name addAll(Name suffix) throws InvalidNameException {
  421            return addAll(size(), suffix);
  422       }
  423   
  424   
  425       /**
  426        * Adds the RDNs of a name -- in order -- to the end of this name.
  427        *
  428        * @param   suffixRdns The non-null suffix <tt>Rdn</tt>s to add.
  429        * @return  The updated name (not a new instance).
  430        */
  431       public Name addAll(List<Rdn> suffixRdns) {
  432           return addAll(size(), suffixRdns);
  433       }
  434   
  435       /**
  436        * Adds the components of a name -- in order -- at a specified position
  437        * within this name. Components of this LDAP name at or after the
  438        * index (if any) of the first new component are shifted up
  439        * (away from index 0) to accomodate the new components.
  440        *
  441        * @param suffix    The non-null components to add.
  442        * @param posn      The index at which to add the new component.
  443        *                  Must be in the range [0,size()].
  444        *
  445        * @return  The updated name (not a new instance).
  446        *
  447        * @throws  InvalidNameException if <tt>suffix</tt> is not a valid LDAP
  448        *          name, or if the addition of the components would violate the
  449        *          syntax rules of this LDAP name.
  450        * @throws  IndexOutOfBoundsException.
  451        *          If posn is outside the specified range.
  452        */
  453       public Name addAll(int posn, Name suffix)
  454           throws InvalidNameException {
  455           unparsed = null;        // no longer valid
  456           if (suffix instanceof LdapName) {
  457               LdapName s = (LdapName) suffix;
  458               rdns.addAll(posn, s.rdns);
  459           } else {
  460               Enumeration comps = suffix.getAll();
  461               while (comps.hasMoreElements()) {
  462                   rdns.add(posn++,
  463                       (new Rfc2253Parser((String) comps.nextElement()).
  464                       parseRdn()));
  465               }
  466           }
  467           return this;
  468       }
  469   
  470       /**
  471        * Adds the RDNs of a name -- in order -- at a specified position
  472        * within this name. RDNs of this LDAP name at or after the
  473        * index (if any) of the first new RDN are shifted up (away from index 0) to
  474        * accomodate the new RDNs.
  475        *
  476        * @param suffixRdns        The non-null suffix <tt>Rdn</tt>s to add.
  477        * @param posn              The index at which to add the suffix RDNs.
  478        *                          Must be in the range [0,size()].
  479        *
  480        * @return  The updated name (not a new instance).
  481        * @throws  IndexOutOfBoundsException.
  482        *          If posn is outside the specified range.
  483        */
  484       public Name addAll(int posn, List<Rdn> suffixRdns) {
  485           unparsed = null;
  486           for (int i = 0; i < suffixRdns.size(); i++) {
  487               Object obj = suffixRdns.get(i);
  488               if (!(obj instanceof Rdn)) {
  489                   throw new IllegalArgumentException("Entry:" + obj +
  490                   "  not a valid type;suffix list entries must be of type Rdn");
  491               }
  492               rdns.add(i + posn, obj);
  493           }
  494           return this;
  495       }
  496   
  497       /**
  498        * Adds a single component to the end of this LDAP name.
  499        *
  500        * @param comp      The non-null component to add.
  501        * @return          The updated LdapName, not a new instance.
  502        *                  Cannot be null.
  503        * @exception       InvalidNameException If adding comp at end of the name
  504        *                  would violate the name's syntax.
  505        */
  506       public Name add(String comp) throws InvalidNameException {
  507           return add(size(), comp);
  508       }
  509   
  510       /**
  511        * Adds a single RDN to the end of this LDAP name.
  512        *
  513        * @param comp      The non-null RDN to add.
  514        *
  515        * @return          The updated LdapName, not a new instance.
  516        *                  Cannot be null.
  517        */
  518       public Name add(Rdn comp) {
  519           return add(size(), comp);
  520       }
  521   
  522       /**
  523        * Adds a single component at a specified position within this
  524        * LDAP name.
  525        * Components of this LDAP name at or after the index (if any) of the new
  526        * component are shifted up by one (away from index 0) to accommodate
  527        * the new component.
  528        *
  529        * @param  comp     The non-null component to add.
  530        * @param  posn     The index at which to add the new component.
  531        *                  Must be in the range [0,size()].
  532        * @return          The updated LdapName, not a new instance.
  533        *                  Cannot be null.
  534        * @exception       IndexOutOfBoundsException.
  535        *                  If posn is outside the specified range.
  536        * @exception       InvalidNameException If adding comp at the
  537        *                  specified position would violate the name's syntax.
  538        */
  539       public Name add(int posn, String comp) throws InvalidNameException {
  540           Rdn rdn = (new Rfc2253Parser(comp)).parseRdn();
  541           rdns.add(posn, rdn);
  542           unparsed = null;        // no longer valid
  543           return this;
  544       }
  545   
  546       /**
  547        * Adds a single RDN at a specified position within this
  548        * LDAP name.
  549        * RDNs of this LDAP name at or after the index (if any) of the new
  550        * RDN are shifted up by one (away from index 0) to accommodate
  551        * the new RDN.
  552        *
  553        * @param  comp     The non-null RDN to add.
  554        * @param  posn     The index at which to add the new RDN.
  555        *                  Must be in the range [0,size()].
  556        * @return          The updated LdapName, not a new instance.
  557        *                  Cannot be null.
  558        * @exception       IndexOutOfBoundsException
  559        *                  If posn is outside the specified range.
  560        */
  561       public Name add(int posn, Rdn comp) {
  562           if (comp == null) {
  563               throw new NullPointerException("Cannot set comp to null");
  564           }
  565           rdns.add(posn, comp);
  566           unparsed = null;        // no longer valid
  567           return this;
  568       }
  569   
  570       /**
  571        * Removes a component from this LDAP name.
  572        * The component of this name at the specified position is removed.
  573        * Components with indexes greater than this position (if any)
  574        * are shifted down (toward index 0) by one.
  575        *
  576        * @param posn      The index of the component to remove.
  577        *                  Must be in the range [0,size()).
  578        * @return          The component removed (a String).
  579        *
  580        * @throws          IndexOutOfBoundsException
  581        *                  if posn is outside the specified range.
  582        * @throws          InvalidNameException if deleting the component
  583        *                  would violate the syntax rules of the name.
  584        */
  585       public Object remove(int posn) throws InvalidNameException {
  586           unparsed = null;        // no longer valid
  587           return rdns.remove(posn).toString();
  588       }
  589   
  590       /**
  591        * Retrieves the list of relative distinguished names.
  592        * The contents of the list are unmodifiable.
  593        * The indexing of RDNs in the returned list follows the numbering of
  594        * RDNs as described in the class description.
  595        * If the name has zero components, an empty list is returned.
  596        *
  597        * @return  The name as a list of RDNs which are instances of
  598        *          the class {@link Rdn Rdn}.
  599        */
  600       public List<Rdn> getRdns() {
  601           return Collections.unmodifiableList(rdns);
  602       }
  603   
  604       /**
  605        * Generates a new copy of this name.
  606        * Subsequent changes to the components of this name will not
  607        * affect the new copy, and vice versa.
  608        *
  609        * @return A copy of the this LDAP name.
  610        */
  611       public Object clone() {
  612           return new LdapName(unparsed, rdns, 0, rdns.size());
  613       }
  614   
  615       /**
  616        * Returns a string representation of this LDAP name in a format
  617        * defined by <a href="http://www.ietf.org/rfc/rfc2253.txt">RFC 2253</a>
  618        * and described in the class description. If the name has zero
  619        * components an empty string is returned.
  620        *
  621        * @return The string representation of the LdapName.
  622        */
  623       public String toString() {
  624           if (unparsed != null) {
  625               return unparsed;
  626           }
  627           StringBuilder builder = new StringBuilder();
  628           int size = rdns.size();
  629           if ((size - 1) >= 0) {
  630               builder.append((Rdn) rdns.get(size - 1));
  631           }
  632           for (int next = size - 2; next >= 0; next--) {
  633               builder.append(',');
  634               builder.append((Rdn) rdns.get(next));
  635           }
  636           unparsed = builder.toString();
  637           return unparsed;
  638       }
  639   
  640       /**
  641        * Determines whether two LDAP names are equal.
  642        * If obj is null or not an LDAP name, false is returned.
  643        * <p>
  644        * Two LDAP names are equal if each RDN in one is equal
  645        * to the corresponding RDN in the other. This implies
  646        * both have the same number of RDNs, and each RDN's
  647        * equals() test against the corresponding RDN in the other
  648        * name returns true. See {@link Rdn#equals(Object obj)}
  649        * for a definition of RDN equality.
  650        *
  651        * @param  obj      The possibly null object to compare against.
  652        * @return          true if obj is equal to this LDAP name,
  653        *                  false otherwise.
  654        * @see #hashCode
  655        */
  656       public boolean equals(Object obj) {
  657           // check possible shortcuts
  658           if (obj == this) {
  659               return true;
  660           }
  661           if (!(obj instanceof LdapName)) {
  662               return false;
  663           }
  664           LdapName that = (LdapName) obj;
  665           if (rdns.size() != that.rdns.size()) {
  666               return false;
  667           }
  668           if (unparsed != null && unparsed.equalsIgnoreCase(
  669                   that.unparsed)) {
  670               return true;
  671           }
  672           // Compare RDNs one by one for equality
  673           for (int i = 0; i < rdns.size(); i++) {
  674               // Compare a single pair of RDNs.
  675               Rdn rdn1 = (Rdn) rdns.get(i);
  676               Rdn rdn2 = (Rdn) that.rdns.get(i);
  677               if (!rdn1.equals(rdn2)) {
  678                   return false;
  679               }
  680           }
  681           return true;
  682       }
  683   
  684       /**
  685        * Compares this LdapName with the specified Object for order.
  686        * Returns a negative integer, zero, or a positive integer as this
  687        * Name is less than, equal to, or greater than the given Object.
  688        * <p>
  689        * If obj is null or not an instance of LdapName, ClassCastException
  690        * is thrown.
  691        * <p>
  692        * Ordering of LDAP names follows the lexicographical rules for
  693        * string comparison, with the extension that this applies to all
  694        * the RDNs in the LDAP name. All the RDNs are lined up in their
  695        * specified order and compared lexicographically.
  696        * See {@link Rdn#compareTo(Object obj) Rdn.compareTo(Object obj)}
  697        * for RDN comparison rules.
  698        * <p>
  699        * If this LDAP name is lexicographically lesser than obj,
  700        * a negative number is returned.
  701        * If this LDAP name is lexicographically greater than obj,
  702        * a positive number is returned.
  703        * @param obj The non-null LdapName instance to compare against.
  704        *
  705        * @return  A negative integer, zero, or a positive integer as this Name
  706        *          is less than, equal to, or greater than the given obj.
  707        * @exception ClassCastException if obj is null or not a LdapName.
  708        */
  709       public int compareTo(Object obj) {
  710   
  711           if (!(obj instanceof LdapName)) {
  712               throw new ClassCastException("The obj is not a LdapName");
  713           }
  714   
  715           // check possible shortcuts
  716           if (obj == this) {
  717               return 0;
  718           }
  719           LdapName that = (LdapName) obj;
  720   
  721           if (unparsed != null && unparsed.equalsIgnoreCase(
  722                           that.unparsed)) {
  723               return 0;
  724           }
  725   
  726           // Compare RDNs one by one, lexicographically.
  727           int minSize = Math.min(rdns.size(), that.rdns.size());
  728           for (int i = 0; i < minSize; i++) {
  729               // Compare a single pair of RDNs.
  730               Rdn rdn1 = (Rdn)rdns.get(i);
  731               Rdn rdn2 = (Rdn)that.rdns.get(i);
  732   
  733               int diff = rdn1.compareTo(rdn2);
  734               if (diff != 0) {
  735                   return diff;
  736               }
  737           }
  738           return (rdns.size() - that.rdns.size());        // longer DN wins
  739       }
  740   
  741       /**
  742        * Computes the hash code of this LDAP name.
  743        * The hash code is the sum of the hash codes of individual RDNs
  744        * of this  name.
  745        *
  746        * @return An int representing the hash code of this name.
  747        * @see #equals
  748        */
  749       public int hashCode() {
  750           // Sum up the hash codes of the components.
  751           int hash = 0;
  752   
  753           // For each RDN...
  754           for (int i = 0; i < rdns.size(); i++) {
  755               Rdn rdn = (Rdn) rdns.get(i);
  756               hash += rdn.hashCode();
  757           }
  758           return hash;
  759       }
  760   
  761       /**
  762        * Serializes only the unparsed DN, for compactness and to avoid
  763        * any implementation dependency.
  764        *
  765        * @serialData      The DN string
  766        */
  767       private void writeObject(ObjectOutputStream s)
  768               throws java.io.IOException {
  769           s.defaultWriteObject();
  770           s.writeObject(toString());
  771       }
  772   
  773       private void readObject(ObjectInputStream s)
  774               throws java.io.IOException, ClassNotFoundException {
  775           s.defaultReadObject();
  776           unparsed = (String)s.readObject();
  777           try {
  778               parse();
  779           } catch (InvalidNameException e) {
  780               // shouldn't happen
  781               throw new java.io.StreamCorruptedException(
  782                       "Invalid name: " + unparsed);
  783           }
  784       }
  785   
  786       private void parse() throws InvalidNameException {
  787           // rdns = (ArrayList<Rdn>) (new RFC2253Parser(unparsed)).getDN();
  788   
  789           rdns = (ArrayList) (new Rfc2253Parser(unparsed)).parseDn();
  790       }
  791   }

Home » openjdk-7 » javax » naming » ldap » [javadoc | source]