com.unboundid.ldap.sdk

Class LDAPURL

java.lang.Object

com.unboundid.ldap.sdk.LDAPURL

All Implemented Interfaces:

java.io.Serializable

@NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
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:

• Scheme -- This specifies the protocol to use when communicating with the server. The official LDAP URL specification only allows a scheme of "ldap", but this implementation also supports the use of the "ldaps" scheme to indicate that clients should attempt to perform SSL-based communication with the target server (LDAPS) rather than unencrypted LDAP. It will also accept "ldapi", which is LDAP over UNIX domain sockets, although the LDAP SDK does not directly support that mechanism of communication.
• Host -- This specifies the address of the directory server to which the URL refers. If no host is provided, then it is expected that the client has some prior knowledge of the host (it often implies the same server from which the URL was retrieved).
• Port -- This specifies the port of the directory server to which the URL refers. If no host or port is provided, then it is assumed that the client has some prior knowledge of the instance to use (it often implies the same instance from which the URL was retrieved). If a host is provided without a port, then it should be assumed that the standard LDAP port of 389 should be used (or the standard LDAPS port of 636 if the scheme is "ldaps", or a value of 0 if the scheme is "ldapi").
• Base DN -- This specifies the base DN for the URL. If no base DN is provided, then a default of the null DN should be assumed.
• Requested attributes -- This specifies the set of requested attributes for the URL. If no attributes are specified, then the behavior should be the same as if no attributes had been provided for a search request (i.e., all user attributes should be included).
  
  In the string representation of an LDAP URL, the names of the requested attributes (if more than one is provided) should be separated by commas.
• Scope -- This specifies the scope for the URL. It should be one of the standard scope values as defined in the SearchRequest class. If no scope is provided, then it should be assumed that a scope of SearchScope.BASE should be used.
  
  In the string representation, the names of the scope values that are allowed include:
  • base -- Equivalent to SearchScope.BASE.
  • one -- Equivalent to SearchScope.ONE.
  • sub -- Equivalent to SearchScope.SUB.
  • subordinates -- Equivalent to SearchScope.SUBORDINATE_SUBTREE.
• Filter -- This specifies the filter for the URL. If no filter is provided, then a default of "(objectClass=*)" should be assumed.

An LDAP URL encapsulates many of the properties of a search request, and in fact the 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:

• ldap:// -- This is the smallest possible LDAP URL that can be represented. The default values will be used for all components other than the scheme.
• ldap://server.example.com:1234/dc=example,dc=com?cn,sn?sub?(uid=john) -- This is an example of a URL containing all of the elements. The scheme is "ldap", the host is "server.example.com", the port is "1234", the base DN is "dc=example,dc=com", the requested attributes are "cn" and "sn", the scope is "sub" (which indicates a subtree scope equivalent to SearchScope.SUB), and a filter of "(uid=john)".

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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(@NotNull
               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(@NotNull
               java.lang.String scheme,
               @Nullable
               java.lang.String host,
               @Nullable
               java.lang.Integer port,
               @Nullable
               DN baseDN,
               @Nullable
               java.lang.String[] attributes,
               @Nullable
               SearchScope scope,
               @Nullable
               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

@NotNull
public static java.lang.String percentDecode(@NotNull
                                                      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

@NotNull
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

@Nullable
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

@NotNull
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

@NotNull
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

@NotNull
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

@NotNull
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

@NotNull
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(@Nullable
                      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

@NotNull
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

@NotNull
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(@NotNull
                               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.