Package org.forgerock.opendj.ldap

Class Dn

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      Dn child​(String dn)
      Returns a DN which is subordinate to this DN and having the additional RDN components contained in the provided DN decoded using the default schema.
      Dn child​(String attributeType, Object attributeValue)
      Returns a DN which is an immediate child of this DN and with an RDN having the provided attribute type and value decoded using the default schema.
      Dn child​(Dn dn)
      Returns a DN which is subordinate to this DN and having the additional RDN components contained in the provided DN.
      Dn child​(Rdn rdn)
      Returns a DN which is an immediate child of this DN and having the specified RDN.
      int compareTo​(Dn dn)  
      static Dn emptyDn()
      Returns the empty DN.
      boolean equals​(Object obj)  
      static String escapeAttributeValue​(Object attributeValue)
      Returns the LDAP string representation of the provided DN attribute value in a form suitable for substitution directly into a DN string.
      static Dn format​(String template, Object... attributeValues)
      Creates a new DN using the provided DN template and unescaped attribute values using the default schema.
      static Dn format​(String template, Schema schema, Object... attributeValues)
      Creates a new DN using the provided DN template and unescaped attribute values using the provided schema.
      int hashCode()  
      boolean isChildOf​(String dn)
      Returns true if this DN is an immediate child of the provided DN decoded using the default schema.
      boolean isChildOf​(Dn dn)
      Returns true if this DN is an immediate child of the provided DN.
      boolean isEmpty()
      Returns true if this DN contains zero RDN components.
      boolean isInScopeOf​(String dn, SearchScope scope)
      Returns true if this DN matches the provided base DN and search scope.
      boolean isInScopeOf​(Dn dn, SearchScope scope)
      Returns true if this DN matches the provided base DN and search scope.
      boolean isParentOf​(String dn)
      Returns true if this DN is the immediate parent of the provided DN.
      boolean isParentOf​(Dn dn)
      Returns true if this DN is the immediate parent of the provided DN.
      boolean isRootDn()
      Deprecated.
      use isEmpty() instead
      boolean isSubordinateOrEqualTo​(String dn)
      Returns true if this DN is subordinate to or equal to the provided DN.
      boolean isSubordinateOrEqualTo​(Dn dn)
      Returns true if this DN is subordinate to or equal to the provided DN.
      boolean isSubordinateTo​(String dn)
      Returns true if this DN is subordinate to, but not equal to the provided DN.
      boolean isSubordinateTo​(Dn dn)
      Returns true if this DN is subordinate to, but not equal to the provided DN.
      boolean isSuperiorOrEqualTo​(String dn)
      Returns true if this DN is superior to or equal to the provided DN.
      boolean isSuperiorOrEqualTo​(Dn dn)
      Returns true if this DN is superior to or equal to the provided DN.
      boolean isSuperiorTo​(String dn)
      Returns true if this DN is superior to, but not equal to the provided DN.
      boolean isSuperiorTo​(Dn dn)
      Returns true if this DN is superior to, but not equal to the provided DN.
      Iterator<Rdn> iterator()
      Returns an iterator of the RDNs contained in this DN.
      Dn localName​(int index)
      Returns the DN whose content is the specified number of RDNs from this DN.
      Dn parent()
      Returns the DN which is the immediate parent of this DN, or null if this DN is the empty DN.
      Dn parent​(int index)
      Returns the DN which is equal to this DN with the specified number of RDNs removed.
      Rdn rdn()
      Returns the RDN of this DN, or null if this DN is the empty DN.
      Rdn rdn​(int index)
      Returns the RDN at the specified index for this DN, or null if no such RDN exists.
      Dn rename​(Dn fromDN, Dn toDN)
      Returns a copy of this DN whose parent DN, fromDN, has been renamed to the new parent DN, toDN.
      Dn rename​(Rdn newRdn, Dn newSuperior)
      Returns a DN whose value is the result of applying LDAP modify DN semantics to this DN.
      static Dn rootDn()
      Deprecated.
      use emptyDn() instead
      int size()
      Returns the number of RDN components in this DN.
      Assertion toAssertion()
      Returns a distinguishedNameMatch equality assertion for this DN which may be used for efficiently matching against LDAP attributes via the Attribute.matchesEqualityAssertion(Assertion, ByteSequence) method using code like:
      ByteString toNormalizedByteString()
      Retrieves a normalized byte string representation of this DN.
      String toNormalizedUrlSafeString()
      Retrieves a normalized string representation of this DN.
      String toString()
      Returns the RFC 4514 string representation of this DN.
      UUID toUuid()
      Returns a UUID whose content is based on the normalized content of this DN.
      static Dn valueOf​(String dn)
      Parses the provided LDAP string representation of a DN using the default schema.
      static Dn valueOf​(String dn, Schema schema)
      Parses the provided LDAP string representation of a DN using the provided schema.
      static Dn valueOf​(ByteString dn)
      Parses the provided LDAP string representation of a DN using the default schema.

    • Method Detail

      • escapeAttributeValue

        public static String escapeAttributeValue​(Object attributeValue)
        Returns the LDAP string representation of the provided DN attribute value in a form suitable for substitution directly into a DN string. This method may be useful in cases where a DN is to be constructed from a DN template using String#format(String, Object...). The following example illustrates two approaches to constructing a DN: 
         
 // This may contain user input.
 String attributeValue = ...;

 // Using the equality filter constructor:
 Dn dn = Dn.valueOf("ou=people,dc=example,dc=com").child("uid", attributeValue);

 // Using a String template:
 String dnTemplate = "uid=%s,ou=people,dc=example,dc=com";
 String dnString = String.format(dnTemplate,
                                 Dn.escapeAttributeValue(attributeValue));
 Dn dn = Dn.valueOf(dnString);
        Note: attribute values do not and should not be escaped before passing them to constructors like child(String, Object). Escaping is only required when creating DN strings.
        Parameters:
        attributeValue - The attribute value.
        Returns:
        The LDAP string representation of the provided filter assertion value in a form suitable for substitution directly into a filter string.

      • format

        public static Dn format​(String template,
                        Object... attributeValues)
                 throws LocalizedIllegalArgumentException
        Creates a new DN using the provided DN template and unescaped attribute values using the default schema. This method first escapes each of the attribute values and then substitutes them into the template using String.format(String, Object...). Finally, the formatted string is parsed as an LDAP DN using valueOf(String).

        This method may be useful in cases where the structure of a DN is not known at compile time, for example, it may be obtained from a configuration file. Example usage: 

         
 String template = "uid=%s,ou=people,dc=example,dc=com";
 Dn dn = Dn.format(template, "bjensen");
        Parameters:
        template - The DN template.
        attributeValues - The attribute values to be substituted into the template.
        Returns:
        The formatted template parsed as a DN.
        Throws:
        LocalizedIllegalArgumentException - If the formatted template is not a valid LDAP string representation of a DN.
        See Also:
        escapeAttributeValue(Object)

      • format

        public static Dn format​(String template,
                        Schema schema,
                        Object... attributeValues)
                 throws LocalizedIllegalArgumentException
        Creates a new DN using the provided DN template and unescaped attribute values using the provided schema. This method first escapes each of the attribute values and then substitutes them into the template using String.format(String, Object...). Finally, the formatted string is parsed as an LDAP DN using valueOf(String).

        This method may be useful in cases where the structure of a DN is not known at compile time, for example, it may be obtained from a configuration file. Example usage: 

         
 String template = "uid=%s,ou=people,dc=example,dc=com";
 Dn dn = Dn.format(template, "bjensen");
        Parameters:
        template - The DN template.
        schema - The schema to use when parsing the DN.
        attributeValues - The attribute values to be substituted into the template.
        Returns:
        The formatted template parsed as a DN.
        Throws:
        LocalizedIllegalArgumentException - If the formatted template is not a valid LDAP string representation of a DN.
        See Also:
        escapeAttributeValue(Object)

      • emptyDn

        public static Dn emptyDn()
        Returns the empty DN. The empty DN does not contain any RDN components and is superior to all other DNs.
        Returns:
        The empty DN.

      • rootDn

        @Deprecated
public static Dn rootDn()
        Deprecated.
        use emptyDn() instead
        Returns the Root DN which represents the root of a tree. It is a synonym to the empty DN.
        Returns:
        The Root DN.

      • child

        public Dn child​(Dn dn)
        Returns a DN which is subordinate to this DN and having the additional RDN components contained in the provided DN.
        Parameters:
        dn - The DN containing the RDN components to be added to this DN.
        Returns:
        The subordinate DN.
        Throws:
        NullPointerException - If dn was null.

      • child

        public Dn child​(Rdn rdn)
        Returns a DN which is an immediate child of this DN and having the specified RDN.

        Note: the child DN whose RDN is Rdn.maxValue() compares greater than all other possible child DNs, and may be used to construct range queries against DN keyed sorted collections such as SortedSet and SortedMap.

        Parameters:
        rdn - The RDN for the child DN.
        Returns:
        The child DN.
        Throws:
        NullPointerException - If rdn was null.
        See Also:
        Rdn.maxValue()

      • child

        public Dn child​(String dn)
         throws LocalizedIllegalArgumentException
        Returns a DN which is subordinate to this DN and having the additional RDN components contained in the provided DN decoded using the default schema.
        Parameters:
        dn - The DN containing the RDN components to be added to this DN.
        Returns:
        The subordinate DN.
        Throws:
        LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.
        NullPointerException - If dn was null.

      • child

        public Dn child​(String attributeType,
                Object attributeValue)
        Returns a DN which is an immediate child of this DN and with an RDN having the provided attribute type and value decoded using the default schema.

        If attributeValue is not an instance of ByteString then it will be converted using the ByteString.valueOfObject(Object) method.

        Parameters:
        attributeType - The attribute type.
        attributeValue - The attribute value.
        Returns:
        The child DN.
        Throws:
        UnknownSchemaElementException - If attributeType was not found in the default schema.
        NullPointerException - If attributeType or attributeValue was null.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • isChildOf

        public boolean isChildOf​(Dn dn)
        Returns true if this DN is an immediate child of the provided DN.
        Parameters:
        dn - The potential parent DN.
        Returns:
        true if this DN is the immediate child of the provided DN, otherwise false.
        Throws:
        NullPointerException - If dn was null.

      • isChildOf

        public boolean isChildOf​(String dn)
                  throws LocalizedIllegalArgumentException
        Returns true if this DN is an immediate child of the provided DN decoded using the default schema.
        Parameters:
        dn - The potential parent DN.
        Returns:
        true if this DN is the immediate child of the provided DN, otherwise false.
        Throws:
        LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.
        NullPointerException - If dn was null.

      • isInScopeOf

        public boolean isInScopeOf​(Dn dn,
                           SearchScope scope)
        Returns true if this DN matches the provided base DN and search scope.
        Parameters:
        dn - The base DN.
        scope - The search scope.
        Returns:
        true if this DN matches the provided base DN and search scope, otherwise false.
        Throws:
        NullPointerException - If dn or scope was null.

      • isParentOf

        public boolean isParentOf​(Dn dn)
        Returns true if this DN is the immediate parent of the provided DN.
        Parameters:
        dn - The potential child DN.
        Returns:
        true if this DN is the immediate parent of the provided DN, otherwise false.
        Throws:
        NullPointerException - If dn was null.

      • isRootDn

        @Deprecated
public boolean isRootDn()
        Deprecated.
        use isEmpty() instead
        Returns true if this DN contains zero RDN components. In other words, this method returns true if this DN is the empty DN.
        Returns:
        true if this DN contains zero RDN components.
        See Also:
        emptyDn()

      • isEmpty

        public boolean isEmpty()
        Returns true if this DN contains zero RDN components. In other words, this method returns true if this DN is the empty DN.
        Returns:
        true if this DN contains zero RDN components.
        See Also:
        emptyDn()

      • isSubordinateOrEqualTo

        public boolean isSubordinateOrEqualTo​(Dn dn)
        Returns true if this DN is subordinate to or equal to the provided DN.
        Parameters:
        dn - The potential parent DN.
        Returns:
        true if this DN is subordinate to or equal to the provided DN, otherwise false.
        Throws:
        NullPointerException - If dn was null.

      • isSubordinateOrEqualTo

        public boolean isSubordinateOrEqualTo​(String dn)
                               throws LocalizedIllegalArgumentException
        Returns true if this DN is subordinate to or equal to the provided DN.
        Parameters:
        dn - The potential parent DN.
        Returns:
        true if this DN is subordinate to or equal to the provided DN, otherwise false.
        Throws:
        LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.
        NullPointerException - If dn was null.

      • isSubordinateTo

        public boolean isSubordinateTo​(String dn)
        Returns true if this DN is subordinate to, but not equal to the provided DN.
        Parameters:
        dn - The potential parent DN.
        Returns:
        true if this DN is subordinate to, but not equal to the provided DN, otherwise false.
        Throws:
        NullPointerException - If dn was null.

      • isSubordinateTo

        public boolean isSubordinateTo​(Dn dn)
        Returns true if this DN is subordinate to, but not equal to the provided DN.
        Parameters:
        dn - The potential parent DN.
        Returns:
        true if this DN is subordinate to, but not equal to the provided DN, otherwise false.
        Throws:
        NullPointerException - If dn was null.

      • isSuperiorOrEqualTo

        public boolean isSuperiorOrEqualTo​(Dn dn)
        Returns true if this DN is superior to or equal to the provided DN.
        Parameters:
        dn - The potential child DN.
        Returns:
        true if this DN is superior to or equal to the provided DN, otherwise false.
        Throws:
        NullPointerException - If dn was null.

      • isSuperiorTo

        public boolean isSuperiorTo​(String dn)
        Returns true if this DN is superior to, but not equal to the provided DN.
        Parameters:
        dn - The potential child DN.
        Returns:
        true if this DN is superior to, but not equal to the provided DN, otherwise false.
        Throws:
        NullPointerException - If dn was null.

      • isSuperiorTo

        public boolean isSuperiorTo​(Dn dn)
        Returns true if this DN is superior to, but not equal to the provided DN.
        Parameters:
        dn - The potential child DN.
        Returns:
        true if this DN is superior to, but not equal to the provided DN, otherwise false.
        Throws:
        NullPointerException - If dn was null.

      • iterator

        public Iterator<Rdn> iterator()
        Returns an iterator of the RDNs contained in this DN. The RDNs will be returned in the order starting with this DN's RDN, followed by the RDN of the parent DN, and so on.

        Attempts to remove RDNs using an iterator's remove() method are not permitted and will result in an UnsupportedOperationException being thrown.

        Specified by:
        iterator in interface Iterable<Rdn>
        Returns:
        An iterator of the RDNs contained in this DN.

      • localName

        public Dn localName​(int index)
        Returns the DN whose content is the specified number of RDNs from this DN. The following equivalences hold: 
         dn.localName(0).isRootDN();
 dn.localName(1).equals(rootDN.child(dn.rdn()));
 dn.localName(dn.size()).equals(dn);
        Said otherwise, a new DN is built using index RDNs, retained in the same order, starting from the left.
        Parameters:
        index - The number of RDNs to be included in the local name.
        Returns:
        The DN whose content is the specified number of RDNs from this DN.
        Throws:
        IllegalArgumentException - If index is less than zero.
        See Also:
        for the reverse operation (starting from the right)

      • parent

        public Dn parent()
        Returns the DN which is the immediate parent of this DN, or null if this DN is the empty DN.

        This method is equivalent to: 

         
 parent(1);
        Returns:
        The DN which is the immediate parent of this DN, or null if this DN is the empty DN.

      • parent

        public Dn parent​(int index)
        Returns the DN which is equal to this DN with the specified number of RDNs removed. Note that if index is zero then this DN will be returned (identity). Said otherwise, a new DN is built using index RDNs, retained in the same order, starting from the right.
        Parameters:
        index - The number of RDNs to be removed.
        Returns:
        The DN which is equal to this DN with the specified number of RDNs removed, or null if the parent of the empty DN is reached.
        Throws:
        IllegalArgumentException - If index is less than zero.
        See Also:
        for the reverse operation (starting from the left)

      • rdn

        public Rdn rdn()
        Returns the RDN of this DN, or null if this DN is the empty DN.

        This is the equivalent of calling dn.rdn(0).

        Returns:
        The RDN of this DN, or null if this DN is the empty DN.

      • rdn

        public Rdn rdn​(int index)
        Returns the RDN at the specified index for this DN, or null if no such RDN exists.

        Here is an example usage: 

         
 Dn.valueOf("ou=people,dc=example,dc=com").rdn(0) => "ou=people"
 Dn.valueOf("ou=people,dc=example,dc=com").rdn(1) => "dc=example"
 Dn.valueOf("ou=people,dc=example,dc=com").rdn(2) => "dc=com"
 Dn.valueOf("ou=people,dc=example,dc=com").rdn(3) => null
        Parameters:
        index - The index of the requested RDN.
        Returns:
        The RDN at the specified index, or null if no such RDN exists.
        Throws:
        IllegalArgumentException - If index is less than zero.

      • rename

        public Dn rename​(Dn fromDN,
                 Dn toDN)
        Returns a copy of this DN whose parent DN, fromDN, has been renamed to the new parent DN, toDN. If this DN is not subordinate or equal to fromDN then this DN is returned (i.e. the DN is not renamed).
        Parameters:
        fromDN - The old parent DN.
        toDN - The new parent DN.
        Returns:
        The renamed DN, or this DN if no renaming was performed.
        Throws:
        NullPointerException - If fromDN or toDN was null.

      • rename

        public Dn rename​(Rdn newRdn,
                 Dn newSuperior)
        Returns a DN whose value is the result of applying LDAP modify DN semantics to this DN. Specifically, the parent of the returned DN will be newSuperior, if provided, otherwise it will be left unchanged. The RDN of the returned DN will be set to newRdn.
        Parameters:
        newRdn - The new RDN, which must not be null.
        newSuperior - The optional new parent, which may be null indicating that the parent should remain the same.
        Returns:
        The renamed DN according to LDAP modify DN semantics.
        Throws:
        NullPointerException - If newRdn was null.

      • size

        public int size()
        Returns the number of RDN components in this DN.
        Returns:
        The number of RDN components in this DN.

      • toNormalizedByteString

        public ByteString toNormalizedByteString()
        Retrieves a normalized byte string representation of this DN.

        This representation is suitable for equality and comparisons, and for providing a natural hierarchical ordering. However, it is not a valid DN and can't be reverted to a valid DN. You should consider using a CompactDn as an alternative.

        Returns:
        The normalized string representation of this DN.

      • toAssertion

        public Assertion toAssertion()
        Returns a distinguishedNameMatch equality assertion for this DN which may be used for efficiently matching against LDAP attributes via the Attribute.matchesEqualityAssertion(Assertion, ByteSequence) method using code like: 
             Attribute attribute = new LinkedAttribute("member", "uid=bjensen,ou=people,dc=example,dc=com");
     Dn dn = Dn.valueOf("uid=bjensen,ou=people,dc=example,dc=com");
     // Assumes that the raw assertion value is not required by the attribute implementation.
     ConditionResult result = attribute.matchesEqualityAssertion(dn.toAssertion(), ByteString.empty());
        Returns:
        A distinguishedNameMatch equality assertion for this DN which may be used for efficiently matching against LDAP attributes.

      • toNormalizedUrlSafeString

        public String toNormalizedUrlSafeString()
        Retrieves a normalized string representation of this DN.

        This representation is safe to use in an URL or in a file name. However, it is not a valid DN and can't be reverted to a valid DN.

        Returns:
        The normalized string representation of this DN.

      • toUuid

        public UUID toUuid()
        Returns a UUID whose content is based on the normalized content of this DN. Two equivalent DNs subject to the same schema will always yield the same UUID.
        Returns:
        the UUID representing this DN