net.sf.michaelo.dirctxsrc

Class DirContextSource.Builder

java.lang.Object

net.sf.michaelo.dirctxsrc.DirContextSource.Builder

Enclosing class:

DirContextSource

public static final class DirContextSource.Builder
extends Object

A builder to construct a DirContextSource with a fluent interface.

Notes:

1. This class is not thread-safe. Configure the builder in your main thread, build the object and pass it on to your forked threads.
2. An IllegalStateException is thrown if a property is modified after this builder has already been used to build a DirContextSource, simply create a new builder in this case.
3. All passed arrays will be defensively copied and null/empty values will be skipped except when all elements are invalid, an exception will be raised.

Constructor Summary

Constructors

Constructor and Description
Builder(String... urls) Constructs a new builder for DirContextSource with anonymous authentication.

Method Summary

Modifier and Type	Method and Description
DirContextSource.Builder	additionalProperty(String name, Object value) Sets an additional property not available through the builder interface.
DirContextSource.Builder	anonymousAuth() Enables anonymous authentication.
DirContextSource.Builder	auth(DirContextSource.Auth auth) Sets the authentication scheme.
DirContextSource.Builder	binaryAttributes(String... attributes) Sets those attributes which will be returned as byte[] instead of String.
DirContextSource	build() Builds a DirContextSource and marks this builder as non-modifiable for future use.
DirContextSource.Builder	connectTimeout(int connectTimeout) Sets the connect timeout in milliseconds.
DirContextSource.Builder	contextFactory(String contextFactory) Sets the context factory for this directory context.
DirContextSource.Builder	debug() Enables the redirection of the LDAP debug output to System.err.
DirContextSource.Builder	debug(boolean debug) Enables or disables the redirection of the LDAP debug output to System.err.
DirContextSource.Builder	debug(OutputStream stream) Redirects the LDAP debug output to an OutputStream.
DirContextSource.Builder	derefAliases(String derefAliases) Sets how aliases are dereferenced.
DirContextSource.Builder	gssApiAuth() Enables GSS-API authentication with a default login entry name.
DirContextSource.Builder	gssApiAuth(String loginEntryName) Enables GSS-API authentication with a custom login entry name.
DirContextSource.Builder	loginEntryName(String loginEntryName) Sets the login entry name for GSS-API authentication.
DirContextSource.Builder	mutualAuth() Enables the mutual authentication between client and directory server.
DirContextSource.Builder	mutualAuth(boolean mutualAuth) Enables or disables the mutual authentication between client and directory server.
DirContextSource.Builder	objectFactories(String... objectFactories) Sets the object factories for this directory context.
DirContextSource.Builder	qop(String... qop) Sets the quality of protection in preference order with which the connection to the directory server is secured.
DirContextSource.Builder	readTimeout(int readTimeout) Sets the read timeout in milliseconds.
DirContextSource.Builder	referral(String referral) Sets the referral handling strategy.
DirContextSource.Builder	retries(int retries) Sets the number or connection retries.
DirContextSource.Builder	retryWait(int retryWait) Sets the wait interval between reconnections.
DirContextSource.Builder	version(int version) Sets the LDAP version.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder(String... urls)

Constructs a new builder for DirContextSource with anonymous authentication.

Note: The default context factory com.sun.jndi.ldap.LdapCtxFactory will iterate through all URLs/servers until the first one is reachable/available.

Parameters:

urls - The URL(s) of a directory server. It/they may contain root DNs.

Throws:

NullPointerException - if urls is null

IllegalArgumentException - if urls is empty

Method Detail

contextFactory

public DirContextSource.Builder contextFactory(String contextFactory)

Sets the context factory for this directory context.

Parameters:

contextFactory - the context factory class name

Returns:

this builder

Throws:

NullPointerException - if contextFactory is null

IllegalArgumentException - if contextFactory is empty

auth

public DirContextSource.Builder auth(DirContextSource.Auth auth)

Sets the authentication scheme.

Parameters:

auth - the auth to be used

Returns:

this builder

Throws:

NullPointerException - if auth is null

loginEntryName

public DirContextSource.Builder loginEntryName(String loginEntryName)

Sets the login entry name for GSS-API authentication.

Parameters:

loginEntryName - the login entry name which retrieves the GSS-API credential

Returns:

this builder

Throws:

NullPointerException - if loginEntryName is null

IllegalArgumentException - if loginEntryName is empty

anonymousAuth

public DirContextSource.Builder anonymousAuth()

Enables anonymous authentication.

Returns:

this builder

gssApiAuth

public DirContextSource.Builder gssApiAuth()

Enables GSS-API authentication with a default login entry name.

Returns:

this builder

gssApiAuth

public DirContextSource.Builder gssApiAuth(String loginEntryName)

Enables GSS-API authentication with a custom login entry name.

Parameters:

loginEntryName - the login entry name which retrieves the GSS-API credential

Returns:

this builder

Throws:

NullPointerException - if loginEntryName is null

IllegalArgumentException - if loginEntryName is empty

See Also:

loginEntryName(String)

objectFactories

public DirContextSource.Builder objectFactories(String... objectFactories)

Sets the object factories for this directory context.

Parameters:

objectFactories - the objectFactories class names

Returns:

this builder

Throws:

NullPointerException - if objectFactories is null

IllegalArgumentException - if objectFactories is empty

mutualAuth

public DirContextSource.Builder mutualAuth()

Enables the mutual authentication between client and directory server. This only works with SASL mechanisms which support this feature, e.g., GSS-API.

Returns:

this builder

mutualAuth

public DirContextSource.Builder mutualAuth(boolean mutualAuth)

Enables or disables the mutual authentication between client and directory server. This only works with SASL mechanisms which support this feature, e.g., GSS-API.

Parameters:

mutualAuth - the mutual authentication flag

Returns:

this builder

qop

public DirContextSource.Builder qop(String... qop)

Sets the quality of protection in preference order with which the connection to the directory server is secured. The first negotiated quality is used. Valid values are auth, auth-int, and auth-conf. This only works with SASL mechanisms which support this feature, e.g., Digest MD5 or GSS-API. See here for details.

Parameters:

qop - the quality of protection for this directory context connection

Returns:

this builder

Throws:

NullPointerException - if qop is null

IllegalArgumentException - if qop is empty

debug

public DirContextSource.Builder debug()

Enables the redirection of the LDAP debug output to System.err. This only works if the contextFactory(String) is com.sun.jndi.ldap.LdapCtxFactory.

Returns:

this builder

See Also:

debug(boolean)

debug

public DirContextSource.Builder debug(boolean debug)

Enables or disables the redirection of the LDAP debug output to System.err. This only works if the contextFactory(String) is com.sun.jndi.ldap.LdapCtxFactory.

Parameters:

debug - the debug flag

Returns:

this builder

debug

public DirContextSource.Builder debug(OutputStream stream)

Redirects the LDAP debug output to an OutputStream. This only works if the contextFactory(String) is com.sun.jndi.ldap.LdapCtxFactory.

Parameters:

stream - an OutputStream where debug output will be written to

Returns:

this builder

Throws:

NullPointerException - if stream is null

retries

public DirContextSource.Builder retries(int retries)

Sets the number or connection retries.

Parameters:

retries - The number of retries. This value must be a positive integer.

Returns:

this builder

Throws:

IllegalArgumentException - if retries is not a positive integer

retryWait

public DirContextSource.Builder retryWait(int retryWait)

Sets the wait interval between reconnections.

Parameters:

retryWait - The wait time in milliseconds. This value must be a positive integer.

Returns:

this builder

Throws:

IllegalArgumentException - if retryWait is not a positive integer

binaryAttributes

public DirContextSource.Builder binaryAttributes(String... attributes)

Sets those attributes which will be returned as byte[] instead of String. See here for details.

Parameters:

attributes - the attributes to be returned as byte array

Returns:

this builder

Throws:

NullPointerException - if attributes is null

IllegalArgumentException - if attributes is empty

referral

public DirContextSource.Builder referral(String referral)

Sets the referral handling strategy. Valid values are ignore, follow, and throw. See here for details.

Parameters:

referral - the referral handling strategy

Returns:

this builder

Throws:

NullPointerException - if referral is null

IllegalArgumentException - if referral is empty

derefAliases

public DirContextSource.Builder derefAliases(String derefAliases)

Sets how aliases are dereferenced. Valid values are always, never, finding, and searching. See here for details.

Parameters:

derefAliases - the aliases dereferencing strategy

Returns:

this builder

Throws:

NullPointerException - if derefAliases is null

IllegalArgumentException - if derefAliases is empty

version

public DirContextSource.Builder version(int version)

Sets the LDAP version. Valid values are 2 and 3. See here

Parameters:

version - The LDAP version. This value must be a positive integer.

Returns:

this builder

Throws:

IllegalArgumentException - if version is not a positive integer

connectTimeout

public DirContextSource.Builder connectTimeout(int connectTimeout)

Sets the connect timeout in milliseconds. This only works if the contextFactory(String) is com.sun.jndi.ldap.LdapCtxFactory.

Parameters:

connectTimeout - The connect timeout in milliseconds. This value must be a positive integer.

Returns:

this builder

Throws:

IllegalArgumentException - if connectTimeout is not a positive integer

readTimeout

public DirContextSource.Builder readTimeout(int readTimeout)

Sets the read timeout in milliseconds. This only works if the contextFactory(String) is com.sun.jndi.ldap.LdapCtxFactory. This value will be implicitly propagated to ActiveDirectoryLdapDnsProvider.

Parameters:

readTimeout - The read timeout in milliseconds. This value must be a positive integer.

Returns:

this builder

Throws:

IllegalArgumentException - if readTimeout is not a positive integer

additionalProperty

public DirContextSource.Builder additionalProperty(String name,
                                                   Object value)

Sets an additional property not available through the builder interface.

Parameters:

name - name of the property

value - value of the property

Returns:

this builder

Throws:

NullPointerException - if name is null

IllegalArgumentException - if value is empty

build

public DirContextSource build()

Builds a DirContextSource and marks this builder as non-modifiable for future use. You may call this method as often as you like, it will return a new DirContextSource instance on every call.

Returns:

a DirContextSource object

Throws:

IllegalStateException - if a combination of necessary attributes is not set