3909N/A * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * This class represents a distinguished name as specified by 0N/A * A distinguished name, or DN, is composed of an ordered list of 0N/A * components called <em>relative distinguished name</em>s, or RDNs. 0N/A * Details of a DN's syntax are described in RFC 2253. 0N/A * This class resolves a few ambiguities found in RFC 2253 0N/A * <li> RFC 2253 leaves the term "whitespace" undefined. The 0N/A * ASCII space character 0x20 (" ") is used in its place. 0N/A * <li> Whitespace is allowed on either side of ',', ';', '=', and '+'. 0N/A * Such whitespace is accepted but not generated by this code, 0N/A * and is ignored when comparing names. 0N/A * <li> AttributeValue strings containing '=' or non-leading '#' 0N/A * characters (unescaped) are accepted. 0N/A * String names passed to <code>LdapName</code> or returned by it 0N/A * use the full Unicode character set. They may also contain 0N/A * characters encoded into UTF-8 with each octet represented by a 0N/A * three-character substring such as "\\B4". 0N/A * They may not, however, contain characters encoded into UTF-8 with 0N/A * each octet represented by a single character in the string: the 0N/A * meaning would be ambiguous. 0N/A * <code>LdapName</code> will properly parse all valid names, but 0N/A * does not attempt to detect all possible violations when parsing 0N/A * invalid names. It is "generous" in accepting invalid names. 0N/A * The "validity" of a name is determined ultimately when it 0N/A * is supplied to an LDAP server, which may accept or 0N/A * reject the name based on factors such as its schema information 0N/A * and interoperability considerations. 0N/A * When names are tested for equality, attribute types, both binary 0N/A * and string values, are case-insensitive. 0N/A * String values with different but equivalent usage of quoting, 0N/A * escaping, or UTF8-hex-encoding are considered equal. The order of 0N/A * components in multi-valued RDNs (such as "ou=Sales+cn=Bob") is not 0N/A * The components of a LDAP name, that is, RDNs, are numbered. The 0N/A * indexes of a LDAP name with n RDNs range from 0 to n-1. 0N/A * This range may be written as [0,n). 0N/A * The right most RDN is at index 0, and the left most RDN is at 0N/A * index n-1. For example, the distinguished name: 0N/A * "CN=Steve Kille, O=Isode Limited, C=GB" is numbered in the following 0N/A * sequence ranging from 0 to 2: {C=GB, O=Isode Limited, CN=Steve Kille}. An 0N/A * empty LDAP name is represented by an empty RDN list. 0N/A * Concurrent multithreaded read-only access of an instance of 0N/A * <tt>LdapName</tt> need not be synchronized. 0N/A * Unless otherwise noted, the behavior of passing a null argument 0N/A * to a constructor or method in this class will cause a 0N/A * NullPointerException to be thrown. 0N/A * @author Scott Seligman 0N/A // private transient ArrayList<Rdn> rdns; // parsed name components 0N/A * Constructs an LDAP name from the given distinguished name. 0N/A * @param name This is a non-null distinguished name formatted 0N/A * according to the rules defined in 0N/A * @throws InvalidNameException if a syntax violation is detected. 0N/A * @see Rdn#escapeValue(Object value) 0N/A * Constructs an LDAP name given its parsed RDN components. 0N/A * The indexing of RDNs in the list follows the numbering of 0N/A * RDNs described in the class description. 0N/A * @param rdns The non-null list of <tt>Rdn</tt>s forming this LDAP name. 0N/A // if (rdns instanceof ArrayList<Rdn>) { 0N/A // this.rdns = rdns.clone(); 0N/A // } else if (rdns instanceof List<Rdn>) { 0N/A // this.rdns = new ArrayList<Rdn>(rdns); 0N/A // throw IllegalArgumentException( 0N/A // "Invalid entries, list entries must be of type Rdn"); 0N/A " not a valid type;list entries must be of type Rdn");
0N/A * Constructs an LDAP name given its parsed components (the elements 0N/A * of "rdns" in the range [beg,end)) and, optionally 0N/A * (if "name" is not null), the unparsed DN. 0N/A // private LdapName(String name, List<Rdn> rdns, int beg, int end) { 0N/A // this.rdns = rdns.subList(beg, end); 0N/A * Retrieves the number of components in this LDAP name. 0N/A * @return The non-negative number of components in this LDAP name. 0N/A * Determines whether this LDAP name is empty. 0N/A * An empty name is one with zero components. 0N/A * @return true if this LDAP name is empty, false otherwise. 0N/A * Retrieves the components of this name as an enumeration 0N/A * of strings. The effect of updates to this name on this enumeration 0N/A * is undefined. If the name has zero components, an empty (non-null) 0N/A * enumeration is returned. 0N/A * The order of the components returned by the enumeration is same as 0N/A * the order in which the components are numbered as described in the 0N/A * class description. 0N/A * @return A non-null enumeration of the components of this LDAP name. 0N/A * Each element of the enumeration is of class String. 0N/A * Retrieves a component of this LDAP name as a string. 0N/A * @param posn The 0-based index of the component to retrieve. 0N/A * Must be in the range [0,size()). 0N/A * @return The non-null component at index posn. 0N/A * @exception IndexOutOfBoundsException if posn is outside the 0N/A * Retrieves an RDN of this LDAP name as an Rdn. 0N/A * @param posn The 0-based index of the RDN to retrieve. 0N/A * Must be in the range [0,size()). 0N/A * @return The non-null RDN at index posn. 0N/A * @exception IndexOutOfBoundsException if posn is outside the 0N/A * Creates a name whose components consist of a prefix of the 0N/A * components of this LDAP name. 1267N/A * Subsequent changes to this name will not affect the name 1267N/A * that is returned and vice versa. 1267N/A * @param posn The 0-based index of the component at which to stop. 1267N/A * Must be in the range [0,size()]. 1267N/A * @return An instance of <tt>LdapName</tt> consisting of the 1267N/A * components at indexes in the range [0,posn). 1267N/A * If posn is zero, an empty LDAP name is returned. 1267N/A * @exception IndexOutOfBoundsException 0N/A * If posn is outside the specified range. 1267N/A * Creates a name whose components consist of a suffix of the 1267N/A * components in this LDAP name. 1267N/A * Subsequent changes to this name do not affect the name that is 1267N/A * @param posn The 0-based index of the component at which to start. 1267N/A * Must be in the range [0,size()]. 1267N/A * @return An instance of <tt>LdapName</tt> consisting of the 1267N/A * components at indexes in the range [posn,size()). 1267N/A * If posn is equal to size(), an empty LDAP name is 1267N/A * @exception IndexOutOfBoundsException 1267N/A * If posn is outside the specified range. 1267N/A * Determines whether this LDAP name starts with a specified LDAP name 0N/A * A name <tt>n</tt> is a prefix if it is equal to 0N/A * <tt>getPrefix(n.size())</tt>--in other words this LDAP 0N/A * name starts with 'n'. If n is null or not a RFC2253 formatted name 0N/A * as described in the class description, false is returned. 0N/A * @param n The LDAP name to check. 0N/A * @return true if <tt>n</tt> is a prefix of this LDAP name, 0N/A * @see #getPrefix(int posn) 0N/A * Determines whether the specified RDN sequence forms a prefix of this 0N/A * LDAP name. Returns true if this LdapName is at least as long as rdns, 0N/A * and for every position p in the range [0, rdns.size()) the component 0N/A * getRdn(p) matches rdns.get(p). Returns false otherwise. If rdns is 0N/A * null, false is returned. 0N/A * @param rdns The sequence of <tt>Rdn</tt>s to check. 0N/A * @return true if <tt>rdns</tt> form a prefix of this LDAP name, 0N/A * Determines whether this LDAP name ends with a specified 0N/A * A name <tt>n</tt> is a suffix if it is equal to 0N/A * <tt>getSuffix(size()-n.size())</tt>--in other words this LDAP 0N/A * name ends with 'n'. If n is null or not a RFC2253 formatted name 0N/A * as described in the class description, false is returned. 0N/A * @param n The LDAP name to check. 0N/A * @return true if <tt>n</tt> is a suffix of this name, false otherwise. 0N/A * @see #getSuffix(int posn) 0N/A * Determines whether the specified RDN sequence forms a suffix of this 0N/A * LDAP name. Returns true if this LdapName is at least as long as rdns, 0N/A * and for every position p in the range [size() - rdns.size(), size()) 0N/A * the component getRdn(p) matches rdns.get(p). Returns false otherwise. 0N/A * If rdns is null, false is returned. 0N/A * @param rdns The sequence of <tt>Rdn</tt>s to check. 0N/A * @return true if <tt>rdns</tt> form a suffix of this LDAP name, 0N/A * Helper method for startsWith() and endsWith(). 0N/A * Returns true if components [beg,end) match the components of "n". 0N/A * If "n" is not an LdapName, each of its components is parsed as 0N/A * the string form of an RDN. 0N/A * The following must hold: end - beg == n.size(). 0N/A * Adds the components of a name -- in order -- to the end of this name. 0N/A * @param suffix The non-null components to add. 0N/A * @return The updated name (not a new instance). 0N/A * @throws InvalidNameException if <tt>suffix</tt> is not a valid LDAP 0N/A * name, or if the addition of the components would violate the 0N/A * syntax rules of this LDAP name. 0N/A * Adds the RDNs of a name -- in order -- to the end of this name. 0N/A * @param suffixRdns The non-null suffix <tt>Rdn</tt>s to add. 0N/A * @return The updated name (not a new instance). 0N/A * Adds the components of a name -- in order -- at a specified position 0N/A * within this name. Components of this LDAP name at or after the 0N/A * index (if any) of the first new component are shifted up 0N/A * (away from index 0) to accomodate the new components. 0N/A * @param suffix The non-null components to add. 0N/A * @param posn The index at which to add the new component. 0N/A * Must be in the range [0,size()]. 3465N/A * @return The updated name (not a new instance). 3465N/A * @throws InvalidNameException if <tt>suffix</tt> is not a valid LDAP 3465N/A * name, or if the addition of the components would violate the 0N/A * syntax rules of this LDAP name. 0N/A * @throws IndexOutOfBoundsException. 0N/A * If posn is outside the specified range. 0N/A * Adds the RDNs of a name -- in order -- at a specified position 0N/A * within this name. RDNs of this LDAP name at or after the 0N/A * index (if any) of the first new RDN are shifted up (away from index 0) to 0N/A * accomodate the new RDNs. 0N/A * @param suffixRdns The non-null suffix <tt>Rdn</tt>s to add. 0N/A * @param posn The index at which to add the suffix RDNs. 0N/A * Must be in the range [0,size()]. 0N/A * @return The updated name (not a new instance). 0N/A * @throws IndexOutOfBoundsException. 0N/A * If posn is outside the specified range. 0N/A " not a valid type;suffix list entries must be of type Rdn");
0N/A * Adds a single component to the end of this LDAP name. 0N/A * @param comp The non-null component to add. 0N/A * @return The updated LdapName, not a new instance. 0N/A * @exception InvalidNameException If adding comp at end of the name 0N/A * would violate the name's syntax. 0N/A * Adds a single RDN to the end of this LDAP name. 0N/A * @param comp The non-null RDN to add. 0N/A * @return The updated LdapName, not a new instance. 0N/A * Adds a single component at a specified position within this 0N/A * Components of this LDAP name at or after the index (if any) of the new 0N/A * component are shifted up by one (away from index 0) to accommodate 0N/A * the new component. 0N/A * @param comp The non-null component to add. 0N/A * @param posn The index at which to add the new component. 0N/A * Must be in the range [0,size()]. 0N/A * @return The updated LdapName, not a new instance. 0N/A * @exception IndexOutOfBoundsException. 0N/A * If posn is outside the specified range. 0N/A * @exception InvalidNameException If adding comp at the 0N/A * specified position would violate the name's syntax. 0N/A * Adds a single RDN at a specified position within this 0N/A * RDNs of this LDAP name at or after the index (if any) of the new 0N/A * RDN are shifted up by one (away from index 0) to accommodate 0N/A * @param comp The non-null RDN to add. 0N/A * @param posn The index at which to add the new RDN. 0N/A * Must be in the range [0,size()]. 0N/A * @return The updated LdapName, not a new instance. 0N/A * @exception IndexOutOfBoundsException 0N/A * If posn is outside the specified range. 0N/A * Removes a component from this LDAP name. 0N/A * The component of this name at the specified position is removed. 0N/A * Components with indexes greater than this position (if any) 0N/A * are shifted down (toward index 0) by one. 0N/A * @param posn The index of the component to remove. 0N/A * Must be in the range [0,size()). 0N/A * @return The component removed (a String). 0N/A * @throws IndexOutOfBoundsException 0N/A * if posn is outside the specified range. 0N/A * @throws InvalidNameException if deleting the component 0N/A * would violate the syntax rules of the name. 0N/A * Retrieves the list of relative distinguished names. 0N/A * The contents of the list are unmodifiable. 0N/A * The indexing of RDNs in the returned list follows the numbering of 0N/A * RDNs as described in the class description. 0N/A * If the name has zero components, an empty list is returned. 0N/A * @return The name as a list of RDNs which are instances of 0N/A * the class {@link Rdn Rdn}. 0N/A * Generates a new copy of this name. 0N/A * Subsequent changes to the components of this name will not 0N/A * affect the new copy, and vice versa. 0N/A * @return A copy of the this LDAP name. 0N/A * Returns a string representation of this LDAP name in a format 0N/A * and described in the class description. If the name has zero 0N/A * components an empty string is returned. 0N/A * @return The string representation of the LdapName. * Determines whether two LDAP names are equal. * If obj is null or not an LDAP name, false is returned. * Two LDAP names are equal if each RDN in one is equal * to the corresponding RDN in the other. This implies * both have the same number of RDNs, and each RDN's * equals() test against the corresponding RDN in the other * name returns true. See {@link Rdn#equals(Object obj)} * for a definition of RDN equality. * @param obj The possibly null object to compare against. * @return true if obj is equal to this LDAP name, // check possible shortcuts // Compare RDNs one by one for equality // Compare a single pair of RDNs. * Compares this LdapName with the specified Object for order. * Returns a negative integer, zero, or a positive integer as this * Name is less than, equal to, or greater than the given Object. * If obj is null or not an instance of LdapName, ClassCastException * Ordering of LDAP names follows the lexicographical rules for * string comparison, with the extension that this applies to all * the RDNs in the LDAP name. All the RDNs are lined up in their * specified order and compared lexicographically. * See {@link Rdn#compareTo(Object obj) Rdn.compareTo(Object obj)} * for RDN comparison rules. * If this LDAP name is lexicographically lesser than obj, * a negative number is returned. * If this LDAP name is lexicographically greater than obj, * a positive number is returned. * @param obj The non-null LdapName instance to compare against. * @return A negative integer, zero, or a positive integer as this Name * is less than, equal to, or greater than the given obj. * @exception ClassCastException if obj is null or not a LdapName. // check possible shortcuts // Compare RDNs one by one, lexicographically. for (
int i =
0; i <
minSize; i++) {
// Compare a single pair of RDNs. * Computes the hash code of this LDAP name. * The hash code is the sum of the hash codes of individual RDNs * @return An int representing the hash code of this name. // Sum up the hash codes of the components. * Serializes only the unparsed DN, for compactness and to avoid * any implementation dependency. * @serialData The DN string // rdns = (ArrayList<Rdn>) (new RFC2253Parser(unparsed)).getDN();