Package 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 ofSearchScope.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
.
- base -- Equivalent to
- Filter -- This specifies the filter for the URL. If no filter is
provided, then a default of "
(objectClass=*)
" should be assumed.
toSearchRequest()
method may be used to create aSearchRequest
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 toSearchScope.SUB
), and a filter of "(uid=john)
".
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field 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 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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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.
-
-
-
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 benull
.- 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 benull
and must be either "ldap", "ldaps", or "ldapi".host
- The host for this LDAP URL. It may benull
if no host is to be included.port
- The port for this LDAP URL. It may benull
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 benull
if no base DN is to be included.attributes
- The set of requested attributes for this LDAP URL. It may benull
or empty if no attribute list is to be included.scope
- The scope for this LDAP URL. It may benull
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 benull
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, orfalse
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, orfalse
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, orfalse
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, orfalse
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, orfalse
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, orfalse
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 classjava.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 classjava.lang.Object
- Parameters:
o
- The object for which to make the determination.- Returns:
true
if the provided object is equal to this LDAP URL, orfalse
if not.
-
toString
@NotNull public java.lang.String toString()
Retrieves a string representation of this LDAP URL.- Overrides:
toString
in classjava.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.
-
-