com.unboundid.ldap.sdk
Class LDAPURL

java.lang.Object
  extended by com.unboundid.ldap.sdk.LDAPURL
All Implemented Interfaces:
java.io.Serializable

public final class LDAPURL
extends java.lang.Object
implements java.io.Serializable

This class provides a data structure for interacting with LDAP URLs. It may be used to encode and decode URLs, as well as access the various elements that they contain. Note that this implementation currently does not support the use of extensions in an LDAP URL.

The components that may be included in an LDAP URL include:

An LDAP URL encapsulates many of the properties of a search request, and in fact the LDAPURL#toSearchRequest method may be used to create a SearchRequest object from an LDAP URL.

See RFC 4516 for a complete description of the LDAP URL syntax. Some examples of LDAP URLs include:

See Also:
Serialized Form

Field Summary
static int DEFAULT_LDAP_PORT
          The default port number that will be used for LDAP URLs if none is provided.
static int DEFAULT_LDAPI_PORT
          The default port number that will be used for LDAPI URLs if none is provided.
static int DEFAULT_LDAPS_PORT
          The default port number that will be used for LDAPS URLs if none is provided.
 
Constructor Summary
LDAPURL(java.lang.String urlString)
          Creates a new LDAP URL from the provided string representation.
LDAPURL(java.lang.String scheme, java.lang.String host, java.lang.Integer port, DN baseDN, java.lang.String[] attributes, SearchScope scope, Filter filter)
          Creates a new LDAP URL with the provided information.
 
Method Summary
 boolean attributesProvided()
          Indicates whether the URL explicitly included an attribute list.
 boolean baseDNProvided()
          Indicates whether the URL explicitly included a base DN.
 boolean equals(java.lang.Object o)
          Indicates whether the provided object is equal to this LDAP URL.
 boolean filterProvided()
          Indicates whether the URL explicitly included a search filter.
 java.lang.String[] getAttributes()
          Retrieves the attribute list for this LDAP URL.
 DN getBaseDN()
          Retrieves the base DN for this LDAP URL.
 Filter getFilter()
          Retrieves the filter for this LDAP URL.
 java.lang.String getHost()
          Retrieves the host for this LDAP URL.
 int getPort()
          Retrieves the port for this LDAP URL.
 java.lang.String getScheme()
          Retrieves the scheme for this LDAP URL.
 SearchScope getScope()
          Retrieves the scope for this LDAP URL.
 int hashCode()
          Retrieves a hash code for this LDAP URL.
 boolean hostProvided()
          Indicates whether the URL explicitly included a host address.
static java.lang.String percentDecode(java.lang.String s)
          Decodes any percent-encoded values that may be contained in the provided string.
 boolean portProvided()
          Indicates whether the URL explicitly included a port number.
 boolean scopeProvided()
          Indicates whether the URL explicitly included a search scope.
 java.lang.String toNormalizedString()
          Retrieves a normalized string representation of this LDAP URL.
 void toNormalizedString(java.lang.StringBuilder buffer)
          Appends a normalized string representation of this LDAP URL to the provided buffer.
 SearchRequest toSearchRequest()
          Creates a search request containing the base DN, scope, filter, and requested attributes from this LDAP URL.
 java.lang.String toString()
          Retrieves a string representation of this LDAP URL.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_LDAP_PORT

public static final int DEFAULT_LDAP_PORT
The default port number that will be used for LDAP URLs if none is provided.

See Also:
Constant Field Values

DEFAULT_LDAPS_PORT

public static final int DEFAULT_LDAPS_PORT
The default port number that will be used for LDAPS URLs if none is provided.

See Also:
Constant Field Values

DEFAULT_LDAPI_PORT

public static final int DEFAULT_LDAPI_PORT
The default port number that will be used for LDAPI URLs if none is provided.

See Also:
Constant Field Values
Constructor Detail

LDAPURL

public LDAPURL(java.lang.String urlString)
        throws LDAPException
Creates a new LDAP URL from the provided string representation.

Parameters:
urlString - The string representation for this LDAP URL. It must not be null.
Throws:
LDAPException - If the provided URL string cannot be parsed as an LDAP URL.

LDAPURL

public LDAPURL(java.lang.String scheme,
               java.lang.String host,
               java.lang.Integer port,
               DN baseDN,
               java.lang.String[] attributes,
               SearchScope scope,
               Filter filter)
        throws LDAPException
Creates a new LDAP URL with the provided information.

Parameters:
scheme - The scheme for this LDAP URL. It must not be null and must be either "ldap", "ldaps", or "ldapi".
host - The host for this LDAP URL. It may be null if no host is to be included.
port - The port for this LDAP URL. It may be null if no port is to be included. If it is provided, it must be between 1 and 65535, inclusive.
baseDN - The base DN for this LDAP URL. It may be null if no base DN is to be included.
attributes - The set of requested attributes for this LDAP URL. It may be null or empty if no attribute list is to be included.
scope - The scope for this LDAP URL. It may be null if no scope is to be included. Otherwise, it must be a value between zero and three, inclusive.
filter - The filter for this LDAP URL. It may be null if no filter is to be included.
Throws:
LDAPException - If there is a problem with any of the provided arguments.
Method Detail

percentDecode

public static java.lang.String percentDecode(java.lang.String s)
                                      throws LDAPException
Decodes any percent-encoded values that may be contained in the provided string.

Parameters:
s - The string to be decoded.
Returns:
The percent-decoded form of the provided string.
Throws:
LDAPException - If a problem occurs while attempting to decode the provided string.

getScheme

public java.lang.String getScheme()
Retrieves the scheme for this LDAP URL. It will either be "ldap", "ldaps", or "ldapi".

Returns:
The scheme for this LDAP URL.

getHost

public java.lang.String getHost()
Retrieves the host for this LDAP URL.

Returns:
The host for this LDAP URL, or null if the URL does not include a host and the client is supposed to have some external knowledge of what the host should be.

hostProvided

public boolean hostProvided()
Indicates whether the URL explicitly included a host address.

Returns:
true if the URL explicitly included a host address, or false if it did not.

getPort

public int getPort()
Retrieves the port for this LDAP URL.

Returns:
The port for this LDAP URL.

portProvided

public boolean portProvided()
Indicates whether the URL explicitly included a port number.

Returns:
true if the URL explicitly included a port number, or false if it did not and the default should be used.

getBaseDN

public DN getBaseDN()
Retrieves the base DN for this LDAP URL.

Returns:
The base DN for this LDAP URL.

baseDNProvided

public boolean baseDNProvided()
Indicates whether the URL explicitly included a base DN.

Returns:
true if the URL explicitly included a base DN, or false if it did not and the default should be used.

getAttributes

public java.lang.String[] getAttributes()
Retrieves the attribute list for this LDAP URL.

Returns:
The attribute list for this LDAP URL.

attributesProvided

public boolean attributesProvided()
Indicates whether the URL explicitly included an attribute list.

Returns:
true if the URL explicitly included an attribute list, or false if it did not and the default should be used.

getScope

public SearchScope getScope()
Retrieves the scope for this LDAP URL.

Returns:
The scope for this LDAP URL.

scopeProvided

public boolean scopeProvided()
Indicates whether the URL explicitly included a search scope.

Returns:
true if the URL explicitly included a search scope, or false if it did not and the default should be used.

getFilter

public Filter getFilter()
Retrieves the filter for this LDAP URL.

Returns:
The filter for this LDAP URL.

filterProvided

public boolean filterProvided()
Indicates whether the URL explicitly included a search filter.

Returns:
true if the URL explicitly included a search filter, or false if it did not and the default should be used.

toSearchRequest

public SearchRequest toSearchRequest()
Creates a search request containing the base DN, scope, filter, and requested attributes from this LDAP URL.

Returns:
The search request created from the base DN, scope, filter, and requested attributes from this LDAP URL.

hashCode

public int hashCode()
Retrieves a hash code for this LDAP URL.

Overrides:
hashCode in class java.lang.Object
Returns:
A hash code for this LDAP URL.

equals

public boolean equals(java.lang.Object o)
Indicates whether the provided object is equal to this LDAP URL. In order to be considered equal, the provided object must be an LDAP URL with the same normalized string representation.

Overrides:
equals in class java.lang.Object
Parameters:
o - The object for which to make the determination.
Returns:
true if the provided object is equal to this LDAP URL, or false if not.

toString

public java.lang.String toString()
Retrieves a string representation of this LDAP URL.

Overrides:
toString in class java.lang.Object
Returns:
A string representation of this LDAP URL.

toNormalizedString

public java.lang.String toNormalizedString()
Retrieves a normalized string representation of this LDAP URL.

Returns:
A normalized string representation of this LDAP URL.

toNormalizedString

public void toNormalizedString(java.lang.StringBuilder buffer)
Appends a normalized string representation of this LDAP URL to the provided buffer.

Parameters:
buffer - The buffer to which to append the normalized string representation of this LDAP URL.