/*
|
* CDDL HEADER START
|
*
|
* The contents of this file are subject to the terms of the
|
* Common Development and Distribution License, Version 1.0 only
|
* (the "License"). You may not use this file except in compliance
|
* with the License.
|
*
|
* You can obtain a copy of the license at
|
* trunk/opends/resource/legal-notices/OpenDS.LICENSE
|
* or https://OpenDS.dev.java.net/OpenDS.LICENSE.
|
* See the License for the specific language governing permissions
|
* and limitations under the License.
|
*
|
* When distributing Covered Code, include this CDDL HEADER in each
|
* file and include the License file at
|
* trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
|
* add the following below this CDDL HEADER, with the fields enclosed
|
* by brackets "[]" replaced with your own identifying information:
|
* Portions Copyright [yyyy] [name of copyright owner]
|
*
|
* CDDL HEADER END
|
*
|
*
|
* Copyright 2009-2010 Sun Microsystems, Inc.
|
*/
|
|
package org.opends.sdk;
|
|
|
|
import static com.sun.opends.sdk.messages.Messages.ERR_RDN_TYPE_NOT_FOUND;
|
|
import java.util.ArrayList;
|
import java.util.Arrays;
|
import java.util.Iterator;
|
import java.util.List;
|
|
import org.opends.sdk.schema.AttributeType;
|
import org.opends.sdk.schema.Schema;
|
import org.opends.sdk.schema.UnknownSchemaElementException;
|
|
import com.sun.opends.sdk.util.Iterators;
|
import com.sun.opends.sdk.util.SubstringReader;
|
|
|
|
/**
|
* A relative distinguished name (RDN) as defined in RFC 4512 section 2.3 is the
|
* name of an entry relative to its immediate superior. An RDN is composed of an
|
* unordered set of one or more attribute value assertions (AVA) consisting of
|
* an attribute description with zero options and an attribute value. These AVAs
|
* are chosen to match attribute values (each a distinguished value) of the
|
* entry.
|
* <p>
|
* An entry's relative distinguished name must be unique among all immediate
|
* subordinates of the entry's immediate superior (i.e. all siblings).
|
* <p>
|
* The following are examples of string representations of RDNs:
|
*
|
* <pre>
|
* uid=12345
|
* ou=Engineering
|
* cn=Kurt Zeilenga+L=Redwood Shores
|
* </pre>
|
*
|
* The last is an example of a multi-valued RDN; that is, an RDN composed of
|
* multiple AVAs.
|
*
|
* @see <a href="http://tools.ietf.org/html/rfc4512#section-2.3">RFC 4512 -
|
* Lightweight Directory Access Protocol (LDAP): Directory Information
|
* Models </a>
|
*/
|
public final class RDN implements Iterable<AVA>, Comparable<RDN>
|
{
|
/**
|
* Parses the provided LDAP string representation of an RDN using the default
|
* schema.
|
*
|
* @param rdn
|
* The LDAP string representation of a RDN.
|
* @return The parsed RDN.
|
* @throws LocalizedIllegalArgumentException
|
* If {@code rdn} is not a valid LDAP string representation of a
|
* RDN.
|
* @throws NullPointerException
|
* If {@code rdn} was {@code null}.
|
*/
|
public static RDN valueOf(final String rdn)
|
throws LocalizedIllegalArgumentException, NullPointerException
|
{
|
return valueOf(rdn, Schema.getDefaultSchema());
|
}
|
|
|
|
/**
|
* Parses the provided LDAP string representation of a RDN using the provided
|
* schema.
|
*
|
* @param rdn
|
* The LDAP string representation of a RDN.
|
* @param schema
|
* The schema to use when parsing the RDN.
|
* @return The parsed RDN.
|
* @throws LocalizedIllegalArgumentException
|
* If {@code rdn} is not a valid LDAP string representation of a
|
* RDN.
|
* @throws NullPointerException
|
* If {@code rdn} or {@code schema} was {@code null}.
|
*/
|
public static RDN valueOf(final String rdn, final Schema schema)
|
throws LocalizedIllegalArgumentException, NullPointerException
|
{
|
final SubstringReader reader = new SubstringReader(rdn);
|
try
|
{
|
return decode(rdn, reader, schema);
|
}
|
catch (final UnknownSchemaElementException e)
|
{
|
final LocalizableMessage message = ERR_RDN_TYPE_NOT_FOUND.get(rdn, e
|
.getMessageObject());
|
throw new LocalizedIllegalArgumentException(message);
|
}
|
}
|
|
|
|
// FIXME: ensure that the decoded RDN does not contain multiple AVAs
|
// with the same type.
|
static RDN decode(final String rdnString, final SubstringReader reader,
|
final Schema schema) throws LocalizedIllegalArgumentException,
|
UnknownSchemaElementException
|
{
|
final AVA firstAVA = AVA.decode(reader, schema);
|
|
// Skip over any spaces that might be after the attribute value.
|
reader.skipWhitespaces();
|
|
reader.mark();
|
if (reader.remaining() > 0 && reader.read() == '+')
|
{
|
final List<AVA> avas = new ArrayList<AVA>();
|
avas.add(firstAVA);
|
|
do
|
{
|
avas.add(AVA.decode(reader, schema));
|
|
// Skip over any spaces that might be after the attribute value.
|
reader.skipWhitespaces();
|
|
reader.mark();
|
}
|
while (reader.remaining() > 0 && reader.read() == '+');
|
|
reader.reset();
|
return new RDN(avas.toArray(new AVA[avas.size()]), null);
|
}
|
else
|
{
|
reader.reset();
|
return new RDN(new AVA[] { firstAVA }, null);
|
}
|
}
|
|
|
|
// In original order.
|
private final AVA[] avas;
|
|
// We need to store the original string value if provided in order to
|
// preserve the original whitespace.
|
private String stringValue;
|
|
|
|
/**
|
* Creates a new RDN using the provided attribute type and value.
|
*
|
* @param attributeType
|
* The attribute type.
|
* @param attributeValue
|
* The attribute value.
|
* @throws NullPointerException
|
* If {@code attributeType} or {@code attributeValue} was {@code
|
* null}.
|
*/
|
public RDN(final AttributeType attributeType, final ByteString attributeValue)
|
throws NullPointerException
|
{
|
this.avas = new AVA[] { new AVA(attributeType, attributeValue) };
|
}
|
|
|
|
/**
|
* Creates a new RDN using the provided attribute type and value decoded using
|
* the default schema.
|
* <p>
|
* If {@code attributeValue} is not an instance of {@code ByteString} then it
|
* will be converted using the {@link ByteString#valueOf(Object)} method.
|
*
|
* @param attributeType
|
* The attribute type.
|
* @param attributeValue
|
* The attribute value.
|
* @throws UnknownSchemaElementException
|
* If {@code attributeType} was not found in the default schema.
|
* @throws NullPointerException
|
* If {@code attributeType} or {@code attributeValue} was {@code
|
* null}.
|
*/
|
public RDN(final String attributeType, final Object attributeValue)
|
throws UnknownSchemaElementException, NullPointerException
|
{
|
this.avas = new AVA[] { new AVA(attributeType, attributeValue) };
|
}
|
|
|
|
private RDN(final AVA[] avas, final String stringValue)
|
{
|
this.avas = avas;
|
this.stringValue = stringValue;
|
}
|
|
|
|
/**
|
* {@inheritDoc}
|
*/
|
public int compareTo(final RDN rdn)
|
{
|
final int sz1 = avas.length;
|
final int sz2 = rdn.avas.length;
|
|
if (sz1 != sz2)
|
{
|
return sz1 - sz2 > 0 ? 1 : -1;
|
}
|
|
if (sz1 == 1)
|
{
|
return avas[0].compareTo(rdn.avas[0]);
|
}
|
|
// Need to sort the AVAs before comparing.
|
final AVA[] a1 = new AVA[sz1];
|
System.arraycopy(avas, 0, a1, 0, sz1);
|
Arrays.sort(a1);
|
|
final AVA[] a2 = new AVA[sz1];
|
System.arraycopy(rdn.avas, 0, a2, 0, sz1);
|
Arrays.sort(a2);
|
|
for (int i = 0; i < sz1; i++)
|
{
|
final int result = a1[i].compareTo(a2[i]);
|
if (result != 0)
|
{
|
return result;
|
}
|
}
|
|
return 0;
|
}
|
|
|
|
/**
|
* {@inheritDoc}
|
*/
|
@Override
|
public boolean equals(final Object obj)
|
{
|
if (this == obj)
|
{
|
return true;
|
}
|
else if (obj instanceof RDN)
|
{
|
return compareTo((RDN) obj) == 0;
|
}
|
else
|
{
|
return false;
|
}
|
}
|
|
|
|
/**
|
* Returns the attribute value contained in this RDN which is associated with
|
* the provided attribute type, or {@code null} if this RDN does not include
|
* such an attribute value.
|
*
|
* @param attributeType
|
* The attribute type.
|
* @return The attribute value.
|
*/
|
public ByteString getAttributeValue(final AttributeType attributeType)
|
{
|
for (final AVA ava : avas)
|
{
|
if (ava.getAttributeType().equals(attributeType))
|
{
|
return ava.getAttributeValue();
|
}
|
}
|
return null;
|
}
|
|
|
|
/**
|
* Returns the first AVA contained in this RDN.
|
*
|
* @return The first AVA contained in this RDN.
|
*/
|
public AVA getFirstAVA()
|
{
|
return avas[0];
|
}
|
|
|
|
/**
|
* {@inheritDoc}
|
*/
|
@Override
|
public int hashCode()
|
{
|
// Avoid an algorithm that requires the AVAs to be sorted.
|
int hash = 0;
|
for (final AVA ava : avas)
|
{
|
hash += ava.hashCode();
|
}
|
return hash;
|
}
|
|
|
|
/**
|
* Returns {@code true} if this RDN contains more than one AVA.
|
*
|
* @return {@code true} if this RDN contains more than one AVA, otherwise
|
* {@code false}.
|
*/
|
public boolean isMultiValued()
|
{
|
return avas.length > 1;
|
}
|
|
|
|
/**
|
* Returns an iterator of the AVAs contained in this RDN. The AVAs will be
|
* returned in the user provided order.
|
* <p>
|
* Attempts to remove AVAs using an iterator's {@code remove()} method are not
|
* permitted and will result in an {@code UnsupportedOperationException} being
|
* thrown.
|
*
|
* @return An iterator of the AVAs contained in this RDN.
|
*/
|
public Iterator<AVA> iterator()
|
{
|
return Iterators.arrayIterator(avas);
|
}
|
|
|
|
/**
|
* Returns the number of AVAs in this RDN.
|
*
|
* @return The number of AVAs in this RDN.
|
*/
|
public int size()
|
{
|
return avas.length;
|
}
|
|
|
|
/**
|
* Returns the RFC 4514 string representation of this RDN.
|
*
|
* @return The RFC 4514 string representation of this RDN.
|
* @see <a href="http://tools.ietf.org/html/rfc4514">RFC 4514 - Lightweight
|
* Directory Access Protocol (LDAP): String Representation of
|
* Distinguished Names </a>
|
*/
|
@Override
|
public String toString()
|
{
|
// We don't care about potential race conditions here.
|
if (stringValue == null)
|
{
|
final StringBuilder builder = new StringBuilder();
|
avas[0].toString(builder);
|
for (int i = 1; i < avas.length; i++)
|
{
|
builder.append('+');
|
avas[i].toString(builder);
|
}
|
stringValue = builder.toString();
|
}
|
return stringValue;
|
}
|
|
|
|
StringBuilder toString(final StringBuilder builder)
|
{
|
return builder.append(toString());
|
}
|
}
|
