com.ca.commons.jndi
Class BasicOps

java.lang.Object
  |
  +--com.ca.commons.jndi.BasicOps

Direct Known Subclasses:

AdvancedOps

public class BasicOps

extends java.lang.Object

The BasicOps class contains methods for performing basic directory operations. Errors are generally caught and handled locally, although return codes usually indicate the general success status of operations.

Two methods, error() and log() are defined. These are intended to be over-ridden by programs wishing application specific handling of these (i.e. for more sensible user output than System.out.println()...).

Field Summary

static int	ALWAYSLOG
static int	CHANGELOG
protected ConnectionData	connectionData
protected javax.naming.directory.DirContext	ctx
static int	DONTLOG
protected static int	ldapVersion
static int	VERBOSELOG

Constructor Summary

BasicOps(javax.naming.directory.DirContext c)
Initialise a Basic Operation object with a context.

Method Summary

boolean	addAttribute(javax.naming.Name Dn, javax.naming.directory.Attribute a) Adds a new attribute to a particular dn.
boolean	addAttributes(javax.naming.Name Dn, javax.naming.directory.Attributes a) Adds a set of attributes to a particular dn.
boolean	addObject(javax.naming.Name Dn, javax.naming.directory.Attributes atts) creates a new object (subcontext) with the given dn and attributes.
void	close() Shuts down the current context.
boolean	copyObject(javax.naming.Name FromDN, javax.naming.Name ToDN) Copies an object to a new DN by the simple expedient of adding an object with the new DN, and the attributes of the old object.
boolean	deleteAttribute(javax.naming.Name Dn, javax.naming.directory.Attribute a) deletes an attribute from an object
boolean	deleteAttributes(javax.naming.Name Dn, javax.naming.directory.Attributes a) deletes a set of attribute-s from an object
boolean	deleteObject(javax.naming.Name Dn) deletes a leaf entry (subcontext).
boolean	error(java.lang.String msg, java.lang.Exception e) This function provides a common point for all error reporting.
boolean	exists(javax.naming.Name NodeDN) Checks the existence of a particular DN, without (necessarily) reading any attributes.
javax.naming.NameParser	getBaseNameParser() This picks up the name parser used at the root level... if the context only spans a single name space (i.e. for an ldap directory) this will be the same as the one used throughout.
javax.naming.directory.DirContext	getContext() Get the raw context for occasions where direct jndi operations must be performed.
static BasicOps	getInstance(ConnectionData cData) Factory Method to create BasicOps objects, initialised with an ldap context created from the connectionData, and maintaining a reference to that connectionData.
int	getLdapVersion() Returns the ldap version of the current connection
javax.naming.directory.DirContext	getSchema() A simple wrapper for a ctx.getSchema("") call.
javax.naming.NamingEnumeration	list(javax.naming.Name Searchbase) returns the next level of a directory tree, returning a Enumeration of the results, *relative* to the SearchBase (i.e. not as absolute DNs).
void	log(java.lang.String msg, int logLevel) This function provides a common point for all logging.
boolean	modifyAttributes(javax.naming.Name Dn, int mod_type, javax.naming.directory.Attributes attr) Modifies an object's attributes, either adding, replacing or deleting the passed attributes.
boolean	modifyAttributes(javax.naming.Name Dn, javax.naming.directory.ModificationItem[] modList) Modifies an object's attributes, either adding, replacing or deleting the passed attributes.
static javax.naming.directory.DirContext	openContext(ConnectionData connectionData) This static ftn. can be used to open an initial context (which can then be used to construct a BasicOps object).
static javax.naming.directory.DirContext	openContext(int version, java.lang.String host, int port, java.lang.String user, char[] pwd, boolean tracing, java.lang.String referralType, java.lang.String aliasHandling) Deprecated. use getInstance() instead
static javax.naming.directory.DirContext	openContext(int version, java.lang.String url, java.lang.String userDN, char[] pwd, boolean tracing, java.lang.String referralType, java.lang.String aliasHandling) Deprecated. use getInstance() instead
static javax.naming.directory.DirContext	openContext(int version, java.lang.String url, java.lang.String userDN, char[] pwd, boolean tracing, java.lang.String referralType, java.lang.String aliasType, boolean useSSL, java.lang.String cacerts, java.lang.String clientcerts, char[] caKeystorePwd, char[] clientKeystorePwd, java.lang.String caKeystoreType, java.lang.String clientKeystoreType) Deprecated. use getInstance() instead
static javax.naming.directory.DirContext	openContext(java.util.Properties env) This is a raw interface to javax.naming.directory.InitialDirContext, that allows an arbitrary environment string to be passed through.
static javax.naming.directory.DirContext	openContext(java.lang.String url) Deprecated. use getInstance() instead.
protected javax.naming.Name	postParse(javax.naming.Name name) This postparses a name, after it has been returned from the jndi operation.
protected javax.naming.NamingEnumeration	postParseNameClassPairs(javax.naming.NamingEnumeration e, javax.naming.Name searchBase) This postparses a namingEnumeration of NameClassPairs, after it has been returned from the jndi operation.
protected javax.naming.Name	preParse(javax.naming.Name name) This preparses a name, preparitory to passing to the jndi operation.
javax.naming.directory.Attributes	read(javax.naming.Name Dn) Reads all the attribute type and values for the given entry.
javax.naming.directory.Attributes	read(javax.naming.Name Dn, java.lang.String[] returnAttributes) Reads all the attribute type and values for the given entry.
boolean	renameObject(javax.naming.Name OldDN, javax.naming.Name NewDN) basically a wrapper for context.rename... changes the distinguished name of an object, checks for error.
javax.naming.NamingEnumeration	searchBaseObject(javax.naming.Name Searchbase, java.lang.String filter, int limit, int timeout) Performs a base object search (i.e. just a search of the current entry, nothing below it), returning no attributes (i.e. just DNs);
javax.naming.NamingEnumeration	searchBaseObject(javax.naming.Name Searchbase, java.lang.String filter, int limit, int timeout, java.lang.String[] returnAttributes) Performs a base object search (i.e. just a search of the current entry, nothing below it).
javax.naming.NamingEnumeration	searchOneLevel(javax.naming.Name Searchbase, java.lang.String filter, int limit, int timeout) Performs a one-level directory search (i.e. a search of immediate children), without returning any attributes (e.g. just returns DNs).
javax.naming.NamingEnumeration	searchOneLevel(javax.naming.Name Searchbase, java.lang.String filter, int limit, int timeout, java.lang.String[] returnAttributes) Performs a one-level directory search (i.e. a search of immediate children)
javax.naming.NamingEnumeration	searchSubTree(javax.naming.Name Searchbase, java.lang.String filter, int limit, int timeout) Performs a directory sub tree search (i.e. of the next level and all subsequent levels below), returning no attributes (i.e. just DNs);
javax.naming.NamingEnumeration	searchSubTree(javax.naming.Name Searchbase, java.lang.String filter, int limit, int timeout, java.lang.String[] returnAttributes) Performs a directory sub tree search (i.e. of the next level and all subsequent levels below).
void	setConnectionData(ConnectionData cData) Sets the details of the connection Data used to make the ldap context.
boolean	updateAttribute(javax.naming.Name Dn, javax.naming.directory.Attribute a) updates an Attribute with a new value set
boolean	updateAttributes(javax.naming.Name Dn, javax.naming.directory.Attributes a) updates a set of Attribute-s.
boolean	updateObject(javax.naming.Name Dn, javax.naming.directory.Attributes atts) Updates an object with a new set of attributes

Methods inherited from class java.lang.Object

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

Field Detail

DONTLOG

public static final int DONTLOG

See Also:

Constant Field Values

ALWAYSLOG

public static final int ALWAYSLOG

See Also:

Constant Field Values

CHANGELOG

public static final int CHANGELOG

See Also:

Constant Field Values

VERBOSELOG

public static final int VERBOSELOG

See Also:

Constant Field Values

ctx

protected javax.naming.directory.DirContext ctx

connectionData

protected ConnectionData connectionData

ldapVersion

protected static int ldapVersion

Constructor Detail

BasicOps

public BasicOps(javax.naming.directory.DirContext c)

Initialise a Basic Operation object with a context.

Method Detail

getInstance

public static BasicOps getInstance(ConnectionData cData)
                            throws javax.naming.NamingException

Factory Method to create BasicOps objects, initialised with an ldap context created from the connectionData, and maintaining a reference to that connectionData.

Parameters:

cData - the details of the directory to connect to

Returns:

a BasicOps object.

javax.naming.NamingException

setConnectionData

public void setConnectionData(ConnectionData cData)

Sets the details of the connection Data used to make the ldap context.

Parameters:

cData - the ldap connection details

openContext

public static javax.naming.directory.DirContext openContext(ConnectionData connectionData)
                                                     throws javax.naming.NamingException

This static ftn. can be used to open an initial context (which can then be used to construct a BasicOps object). Note that this ftn may take some time to return...

Parameters:

connectionData - a data object contain all the connection details.

javax.naming.NamingException

openContext

public static javax.naming.directory.DirContext openContext(int version,
                                                            java.lang.String host,
                                                            int port,
                                                            java.lang.String user,
                                                            char[] pwd,
                                                            boolean tracing,
                                                            java.lang.String referralType,
                                                            java.lang.String aliasHandling)
                                                     throws javax.naming.NamingException

Deprecated. use getInstance() instead

This static ftn. can be used to open an initial context (which can then be used to construct a BasicOps object). Note that this ftn may take some time to return...

Parameters:

version - the LDAP Version (2 or 3) being used.

host - the LDAP server name.

port - the LDAP server port (default 389) being used.

user - the Manager User's DN - (is null if user is not manager)

pwd - the Manager User's password - (is null if user is not manager)

tracing - whether to set BER tracing on or not

referralType - the jndi ldap referral type: [follow:ignore:throw]

aliasHandling - how aliases should be handled in searches ('always'|'never'|'find'|'search')

Returns:

The created context.

javax.naming.NamingException

openContext

public static javax.naming.directory.DirContext openContext(java.lang.String url)
                                                     throws javax.naming.NamingException

Deprecated. use getInstance() instead.

Opens a simple default initial context, with no authentication, using version 3 ldap.

javax.naming.NamingException

openContext

public static javax.naming.directory.DirContext openContext(int version,
                                                            java.lang.String url,
                                                            java.lang.String userDN,
                                                            char[] pwd,
                                                            boolean tracing,
                                                            java.lang.String referralType,
                                                            java.lang.String aliasHandling)
                                                     throws javax.naming.NamingException

Deprecated. use getInstance() instead

This static ftn. can be used to open an initial context (which can then be used to construct a BasicOps object). Note that this ftn may take some time to return...

Parameters:

version - the LDAP Version (2 or 3) being used.

url - a url of the form ldap://hostname:portnumber

userDN - the Manager User's distinguished name (optionally null if not used)

pwd - the Manager User's password - (is null if user is not manager)

tracing - whether to set BER tracing on or not

referralType - the jndi ldap referral type: [follow:ignore:throw] (may be null - defaults to 'follow')

Returns:

The created context.

javax.naming.NamingException

openContext

public static javax.naming.directory.DirContext openContext(int version,
                                                            java.lang.String url,
                                                            java.lang.String userDN,
                                                            char[] pwd,
                                                            boolean tracing,
                                                            java.lang.String referralType,
                                                            java.lang.String aliasType,
                                                            boolean useSSL,
                                                            java.lang.String cacerts,
                                                            java.lang.String clientcerts,
                                                            char[] caKeystorePwd,
                                                            char[] clientKeystorePwd,
                                                            java.lang.String caKeystoreType,
                                                            java.lang.String clientKeystoreType)
                                                     throws javax.naming.NamingException

Deprecated. use getInstance() instead

This static ftn. can be used to open an initial context (which can then be used to construct a BasicOps object). Note that this ftn may take some time to return...

Parameters:

version - the LDAP Version (2 or 3) being used.

url - a url of the form ldap://hostname:portnumber.

userDN - the Manager User's distinguished name (optionally null if not used).

pwd - the Manager User's password - (is null if user is not manager).

tracing - whether to set BER tracing on or not.

referralType - the jndi ldap referral type: [follow:ignore:throw] (may be null - defaults to 'follow').

aliasType - how aliases should be handled in searches ('always'|'never'|'find'|'search').

useSSL - whether to use SSL (either simple or client-authenticated).

cacerts - the file containing the trusted server certificates (no keys).

clientcerts - the file containing client certificates.

caKeystorePwd - the password to the ca's keystore (may be null for non-client authenticated ssl).

clientKeystorePwd - the password to the client's keystore (may be null for non-client authenticated ssl).

caKeystoreType - the type of keystore file; e.g. 'JKS', or 'PKCS12'.

clientKeystoreType - the type of keystore file; e.g. 'JKS', or 'PKCS12'.

Returns:

The created context.

javax.naming.NamingException

openContext

public static javax.naming.directory.DirContext openContext(java.util.Properties env)
                                                     throws javax.naming.NamingException

This is a raw interface to javax.naming.directory.InitialDirContext, that allows an arbitrary environment string to be passed through. Often the other version of openContext() above will prove more convenient.

Parameters:

env - a list of environment variables for the context

Returns:

a newly created DirContext.

javax.naming.NamingException

getSchema

public javax.naming.directory.DirContext getSchema()
                                            throws javax.naming.NamingException

A simple wrapper for a ctx.getSchema("") call.

javax.naming.NamingException

renameObject

public boolean renameObject(javax.naming.Name OldDN,
                            javax.naming.Name NewDN)

basically a wrapper for context.rename... changes the distinguished name of an object, checks for error.

Returns:

the success status of the operation

copyObject

public boolean copyObject(javax.naming.Name FromDN,
                          javax.naming.Name ToDN)

Copies an object to a new DN by the simple expedient of adding an object with the new DN, and the attributes of the old object.

Returns:

the success status of the operation

addObject

public boolean addObject(javax.naming.Name Dn,
                         javax.naming.directory.Attributes atts)

creates a new object (subcontext) with the given dn and attributes.

Parameters:

atts - attributes for the new object

Returns:

the success status of the operation

deleteObject

public boolean deleteObject(javax.naming.Name Dn)

deletes a leaf entry (subcontext). It is an error to attempt to delete an entry which is not a leaf entry, i.e. which has children.

exists

public boolean exists(javax.naming.Name NodeDN)

Checks the existence of a particular DN, without (necessarily) reading any attributes.

Returns:

the existence of the nodeDN (or false if an error occurs).

read

public javax.naming.directory.Attributes read(javax.naming.Name Dn)

Reads all the attribute type and values for the given entry.

Returns:

an 'Attributes' object containing a list of all Attribute objects.

read

public javax.naming.directory.Attributes read(javax.naming.Name Dn,
                                              java.lang.String[] returnAttributes)

Reads all the attribute type and values for the given entry.

Parameters:

returnAttributes - a list of specific attributes to return.

Returns:

an 'Attributes' object containing a list of all Attribute objects.

modifyAttributes

public boolean modifyAttributes(javax.naming.Name Dn,
                                int mod_type,
                                javax.naming.directory.Attributes attr)

Modifies an object's attributes, either adding, replacing or deleting the passed attributes.

Parameters:

mod_type - the modification type to be performed; one of DirContext.REPLACE_ATTRIBUTE, DirContext.DELETE_ATTRIBUTE, or DirContext.ADD_ATTRIBUTE.

Returns:

the success status of the operation

modifyAttributes

public boolean modifyAttributes(javax.naming.Name Dn,
                                javax.naming.directory.ModificationItem[] modList)

Modifies an object's attributes, either adding, replacing or deleting the passed attributes.

Parameters:

modList - a list of ModificationItems

Returns:

the success status of the operation

updateObject

public boolean updateObject(javax.naming.Name Dn,
                            javax.naming.directory.Attributes atts)

Updates an object with a new set of attributes

Returns:

the success status of the operation

deleteAttribute

public boolean deleteAttribute(javax.naming.Name Dn,
                               javax.naming.directory.Attribute a)

deletes an attribute from an object

Returns:

Whether the deletion was successful.

deleteAttributes

public boolean deleteAttributes(javax.naming.Name Dn,
                                javax.naming.directory.Attributes a)

deletes a set of attribute-s from an object

Parameters:

a - the Attributes object containing the list of attribute-s to delete

Returns:

Whether the deletion was successful.

updateAttribute

public boolean updateAttribute(javax.naming.Name Dn,
                               javax.naming.directory.Attribute a)

updates an Attribute with a new value set

Returns:

success of operation

updateAttributes

public boolean updateAttributes(javax.naming.Name Dn,
                                javax.naming.directory.Attributes a)

updates a set of Attribute-s.

Parameters:

a - an Attributes object containing the attribute-s to modify

Returns:

success of operation

addAttribute

public boolean addAttribute(javax.naming.Name Dn,
                            javax.naming.directory.Attribute a)

Adds a new attribute to a particular dn.

Returns:

success status

addAttributes

public boolean addAttributes(javax.naming.Name Dn,
                             javax.naming.directory.Attributes a)

Adds a set of attributes to a particular dn.

Parameters:

a - the Attributes (set of attribute-s) to add

Returns:

success status

list

public javax.naming.NamingEnumeration list(javax.naming.Name Searchbase)

returns the next level of a directory tree, returning a Enumeration of the results, *relative* to the SearchBase (i.e. not as absolute DNs).

Returns:

list of results (NameClassPair); the next layer of the tree...

searchOneLevel

public javax.naming.NamingEnumeration searchOneLevel(javax.naming.Name Searchbase,
                                                     java.lang.String filter,
                                                     int limit,
                                                     int timeout)

Performs a one-level directory search (i.e. a search of immediate children), without returning any attributes (e.g. just returns DNs).

Parameters:

filter - the non-null filter to use for the search

limit - the maximum number of results to return

timeout - the maximum time to wait before abandoning the search

Returns:

list of search results ('SearchResult's); entries matching the search filter.

searchOneLevel

public javax.naming.NamingEnumeration searchOneLevel(javax.naming.Name Searchbase,
                                                     java.lang.String filter,
                                                     int limit,
                                                     int timeout,
                                                     java.lang.String[] returnAttributes)

Performs a one-level directory search (i.e. a search of immediate children)

Parameters:

filter - the non-null filter to use for the search

limit - the maximum number of results to return

timeout - the maximum time to wait before abandoning the search

Returns:

list of search results ('SearchResult's); entries matching the search filter.

searchSubTree

public javax.naming.NamingEnumeration searchSubTree(javax.naming.Name Searchbase,
                                                    java.lang.String filter,
                                                    int limit,
                                                    int timeout)

Performs a directory sub tree search (i.e. of the next level and all subsequent levels below), returning no attributes (i.e. just DNs);

Parameters:

filter - the non-null filter to use for the search

limit - the maximum number of results to return

timeout - the maximum time to wait before abandoning the search

Returns:

list of search results ('SearchResult's); entries matching the search filter.

searchSubTree

public javax.naming.NamingEnumeration searchSubTree(javax.naming.Name Searchbase,
                                                    java.lang.String filter,
                                                    int limit,
                                                    int timeout,
                                                    java.lang.String[] returnAttributes)

Performs a directory sub tree search (i.e. of the next level and all subsequent levels below).

Parameters:

filter - the non-null filter to use for the search

limit - the maximum number of results to return

timeout - the maximum time to wait before abandoning the search

Returns:

list of search results ('SearchResult's); entries matching the search filter.

searchBaseObject

public javax.naming.NamingEnumeration searchBaseObject(javax.naming.Name Searchbase,
                                                       java.lang.String filter,
                                                       int limit,
                                                       int timeout)

Performs a base object search (i.e. just a search of the current entry, nothing below it), returning no attributes (i.e. just DNs);

Parameters:

Searchbase - the domain name (relative to initial context in ldap) to seach from.

filter - the non-null filter to use for the search

limit - the maximum number of results to return

timeout - the maximum time to wait before abandoning the search

Returns:

list of search results ('SearchResult's); entries matching the search filter.

searchBaseObject

public javax.naming.NamingEnumeration searchBaseObject(javax.naming.Name Searchbase,
                                                       java.lang.String filter,
                                                       int limit,
                                                       int timeout,
                                                       java.lang.String[] returnAttributes)

Performs a base object search (i.e. just a search of the current entry, nothing below it).

Parameters:

Searchbase - the domain name (relative to initial context in ldap) to seach from.

filter - the non-null filter to use for the search

limit - the maximum number of results to return

timeout - the maximum time to wait before abandoning the search

Returns:

list of search results ('SearchResult's); entries matching the search filter.

close

public void close()

Shuts down the current context.

nb. It is not an error to call this method multiple times.

getBaseNameParser

public javax.naming.NameParser getBaseNameParser()

This picks up the name parser used at the root level... if the context only spans a single name space (i.e. for an ldap directory) this will be the same as the one used throughout.

error

public boolean error(java.lang.String msg,
                     java.lang.Exception e)

This function provides a common point for all error reporting. In order to customise it, simply over-ride this function in a class inheriting from BasicOps.

Parameters:

msg - User friendly error message

e - The exception

Returns:

returns false (always) for easy chaining.

log

public void log(java.lang.String msg,
                int logLevel)

This function provides a common point for all logging. In order to customise it, simply over-ride this function in a class inheriting from BasicOps.

Parameters:

msg - log Message

preParse

protected javax.naming.Name preParse(javax.naming.Name name)

This preparses a name, preparitory to passing to the jndi operation. Usefull to over-ride if a Name needs to be escaped or re-formatted.

Parameters:

name - the pre jndi operation name.

Returns:

the version used by the operation.

postParse

protected javax.naming.Name postParse(javax.naming.Name name)

This postparses a name, after it has been returned from the jndi operation. Usefull to over-ride if the name needs to be unescaped or reformatted.

Parameters:

name - the post jndi operation name.

Returns:

the re-formatted version used by the application.

postParseNameClassPairs

protected javax.naming.NamingEnumeration postParseNameClassPairs(javax.naming.NamingEnumeration e,
                                                                 javax.naming.Name searchBase)
                                                          throws javax.naming.NamingException

This postparses a namingEnumeration of NameClassPairs, after it has been returned from the jndi operation. Usefull to over-ride if the names in the enumeration need to be unescaped or reformatted.

Parameters:

e - the post jndi operation namingEnumeration.

Returns:

the re-formatted version used by the application.

javax.naming.NamingException

getLdapVersion

public int getLdapVersion()

Returns the ldap version of the current connection

getContext

public javax.naming.directory.DirContext getContext()

Get the raw context for occasions where direct jndi operations must be performed.