com.rli.ldap.util

Class FIDOperationsClientUtil

java.lang.Object

com.rli.ldap.util.FIDOperationsClientUtil

public final class FIDOperationsClientUtil
extends java.lang.Object

This utility class provides a set of basic LDAP operations (search, add, modify, delete) that can be used directly on a local FID server, without the need to manage connection and disconnections to the server. This class can be used with any distinguished name (DN) or naming context that is part of the FID namespace.

Warning: this class is not compatible with external LDAP servers and can only be used for CRUD operations on a local FID server.

Examples:

Example #0: Verifying that a specific entry exists

 
         String entryDn = "cn=Nancy Davolio,o=companydirectory";
         try {
             if (FIDOperationsClientUtil.exists(entryDn)) {
                 // entry exists, you can safely perform an update/delete operation on that DN.
             } else {
                 // entry does not exist.
             }
         } catch (LDAPException e) {
             // A failure occurred while checking if the entry exists. This is usually due to a network error, or the
             // FID Server is not started. Handle exception or log it.
         }
 
 

Example #1: Base search for a single existing entry

 
         try {
             String entryDn = "cn=Nancy Davolio,o=companydirectory";
             LDAPEntry entry = FIDOperationsClientUtil.lookup(entryDn);
             LDAPAttributeSet attributeSet = entry.getAttributeSet();
             LDAPAttribute[] attributesArray = attributeSet.getAttributesArray();
             for(LDAPAttribute attribute: attributesArray) {
                 String attributeName = attribute.getName();
                 Collection<String> attributeValues =  attribute.getListValueString();
             }
         } catch (LDAPException e) {
             // Failed to find the specified entry, handle or log the exception.
         }
 
 

Example #2: Sub-tree search with a filter

 
         String baseDn = "o=companydirectory";
         String ldapFilter = "(&(objectclass=inetOrgPerson)(l=Portland))";
         int searchScope = SearchControls.SUBTREE_SCOPE;
         String[] requestedAttributes = new String[]{"cn", "sn", "mail"}; // pass null if you want all attributes.
         int sizeLimit = 0; // use 0 if you do not want to limit results.

         try (LDAPEnumeration resultsEnumeration = FIDOperationsClientUtil.search(baseDn, ldapFilter, searchScope,
                 requestedAttributes, sizeLimit)) {
             if (resultsEnumeration != null) {
                 while (resultsEnumeration.hasMore()) {
                     LDAPEntry entry = resultsEnumeration.next();
                     LDAPAttribute mailAttribute = entry.getAttribute("mail");
                     Collection<String> mailValues = mailAttribute.getListValueString();
                     System.out.println(mailValues);
                 }
             }
         } catch (LDAPException e) {
             // A failure occurred during the search, handle or log the exception.
         }
 
 

Example #3: Creating a new entry

 
         LDAPEntry newEntry = new LDAPEntry("cn=Nancy Davolio,o=companydirectory");
         newEntry.getAttributeSet().add(new LDAPAttribute("objectclass", new String[]{"top", "person", "organizationalPerson", "inetOrgPerson"}));
         newEntry.getAttributeSet().add(new LDAPAttribute("cn", "Nancy Davolio"));
         newEntry.getAttributeSet().add(new LDAPAttribute("sn", "Davolio"));
         newEntry.getAttributeSet().add(new LDAPAttribute("givenName", "Nancy"));
         newEntry.getAttributeSet().add(new LDAPAttribute("title", new String[]{"Product Manager", "Product Evangelist"}));
         try {
             FIDOperationsClientUtil.add(newEntry);
             // New entry was successfully created
         } catch (LDAPException e) {
             // Failed to create new entry, handle or log the exception.
         }
 
 

Example #4: Updating an existing entry

 
         List<LDAPModification> modificationsList = new ArrayList<>();

         // Replace an attribute's values with the specified values.
         LDAPModification replaceMailValues = new LDAPModification(LDAPModification.REPLACE, new LDAPAttribute("mail", "ndavolio@radiantlogic.com"));
         modificationsList.add(replaceMailValues);

         // Add only the specified values to an attribute.
         LDAPModification addMobileValues = new LDAPModification(LDAPModification.ADD, new LDAPAttribute("mobile", new String[]{"(415) 209-6800", "(415) 123-4567"}));
         modificationsList.add(addMobileValues);

         // Delete an entire attribute and all its values.
         LDAPModification deleteTitleAttribute = new LDAPModification(LDAPModification.DELETE, new LDAPAttribute("title"));
         modificationsList.add(deleteTitleAttribute);

         // Remove only the specified values from the attribute.
         LDAPModification removeEmployeeTypeValues = new LDAPModification(LDAPModification.DELETE, new LDAPAttribute("employeeType", new String[]{"Contractor", "Part-Time"}));
         modificationsList.add(removeEmployeeTypeValues);

         try {
             FIDOperationsClientUtil.update("cn=Nancy Davolio,o=companydirectory", modificationsList.toArray(new LDAPModification[0]));
             // Existing entry was successfully updated.
         } catch (LDAPException e) {
             // Failed to update existing entry, handle or log the exception.
         }
 
 

Example #5: Deleting an existing entry

         try {
             String entryDn = "cn=Nancy Davolio,o=companydirectory";
             if (FIDOperationsClientUtil.exists(entryDn)) {
                 FIDOperationsClientUtil.delete(entryDn);
                 // Entry was succesfully deleted.
             }
         } catch (LDAPException e) {
             // Failed to delete existing entry, handle or log the exception.
         }
 

Method Summary

Modifier and Type	Method and Description
static void	add(LDAPEntry entry) Creates a new entry (LDAP Add operation) in the FID namespace.
static void	add(java.util.List<LDAPEntry> entries) Creates one or more new entries in the FID namespace.
static void	delete(java.lang.String dn) Deletes an existing entry.
static void	deleteTree(java.lang.String dn) Deletes the specified entry and all of its descendants (the entire sub-tree starting from the specified DN).
static boolean	exists(java.lang.String dn) Indicates if the specified distinguished name (DN) points to an existing entry.
static LDAPEntry	lookup(java.lang.String dn) Performs a base search for the specified entry and returns a single result.
static LDAPEnumeration	search(java.lang.String dn, java.lang.String filter, int scope, java.lang.String[] attributes, int sizeLimit) Performs an LDAP search starting at the specified DN.
static LDAPEntry	searchBase(java.lang.String dn, java.lang.String filter, java.lang.String[] requestedAttributes) Performs an LDAP base search for the specified DN and returns a single result.
static void	update(java.lang.String dn, LDAPModification[] mods) Updates (LDAP Modify operation) the contents of an existing entry.
static void	upsert(LDAPEntry entry) Performs an upsert operation: if the specified entry already exists, it will be updated; if it does not exist, a new entry will be created.
static void	upsert(LDAPEntry entry, boolean mergeInto) Performs an upsert operation: if the specified entry already exists, it will be updated; if it does not exist, a new entry will be created.

Methods inherited from class java.lang.Object

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

Method Detail

add

public static void add(LDAPEntry entry)
                throws LDAPException

Creates a new entry (LDAP Add operation) in the FID namespace.

Parameters:

entry - The new entry that will be created.

Throws:

LDAPException - If a failure occurs while creating the new entry.

add

public static void add(java.util.List<LDAPEntry> entries)
                throws LDAPException

Creates one or more new entries in the FID namespace.

Parameters:

entries - The new entries that will be created.

Throws:

LDAPException - If a failure occurs while creating the new entries.

update

public static void update(java.lang.String dn,
                          LDAPModification[] mods)
                   throws LDAPException

Updates (LDAP Modify operation) the contents of an existing entry.

Parameters:

dn - The distinguished name (DN) of an existing entry.

mods - A set of one or more modifications to apply on the existing entry.

Throws:

LDAPException - If a failure occurs while updating the existing entry, or if the entry does not exist.

upsert

public static void upsert(LDAPEntry entry)
                   throws LDAPException

Performs an upsert operation: if the specified entry already exists, it will be updated; if it does not exist, a new entry will be created.

Parameters:

entry - The entry that will be used to create a new entry, or to update an existing entry.

Throws:

LDAPException - If a failure occurs while updating the existing entry or while creating a new entry.

upsert

public static void upsert(LDAPEntry entry,
                          boolean mergeInto)
                   throws LDAPException

Performs an upsert operation: if the specified entry already exists, it will be updated; if it does not exist, a new entry will be created.

Parameters:

entry - The entry that will be used to create a new entry, or to update an existing entry.

mergeInto - If true, while performing an update operation, only new values for existing attributes will be added. If false, while performing an update operation, all values for existing attributes will be replaced.

Throws:

LDAPException - If a failure occurs while updating the existing entry or while creating a new entry.

delete

public static void delete(java.lang.String dn)
                   throws LDAPException

Deletes an existing entry.

Parameters:

dn - The distinguished name (DN) of an existing entry.

Throws:

LDAPException - If a failure occurs during the delete operation, or if the specified entry does not exist.

deleteTree

public static void deleteTree(java.lang.String dn)
                       throws LDAPException

Deletes the specified entry and all of its descendants (the entire sub-tree starting from the specified DN).

Parameters:

dn - The distinguished name (DN) of an existing entry.

Throws:

LDAPException - If a failure occurs during the delete operation, or if the specified entry does not exist.

lookup

public static LDAPEntry lookup(java.lang.String dn)
                        throws LDAPException

Performs a base search for the specified entry and returns a single result.

Parameters:

dn - The distinguished name (DN) of an entry to do a base search for.

Returns:

The LDAP entry corresponding to the specified DN.

Throws:

LDAPException - If a failure occurs during the search operation, or if the specified entry does not exist.

searchBase

public static LDAPEntry searchBase(java.lang.String dn,
                                   java.lang.String filter,
                                   java.lang.String[] requestedAttributes)
                            throws LDAPException

Performs an LDAP base search for the specified DN and returns a single result.

Parameters:

dn - The distinguished name (DN) of an entry to do a base search for.

filter - The LDAP Filter to apply to the search.

requestedAttributes - The set of attributes to return for the entry. You may pass null to return all attributes.

Returns:

The LDAP entry corresponding to the specified DN.

Throws:

LDAPException - If a failure occurs during the search operation, or if the specified entry does not exist.

search

public static LDAPEnumeration search(java.lang.String dn,
                                     java.lang.String filter,
                                     int scope,
                                     java.lang.String[] attributes,
                                     int sizeLimit)
                              throws LDAPException

Performs an LDAP search starting at the specified DN.

Parameters:

dn - The distinguished name (DN) of an entry used as a base for the search operation.

filter - The LDAP Filter to apply to the search, e.g: (objectclass=*)

scope - The scope to use the search. You must use one of the following values:

• SearchControls.OBJECT_SCOPE
• SearchControls.ONELEVEL_SCOPE
• SearchControls.SUBTREE_SCOPE

attributes - The set of attributes to return for the entry. You may pass null to return all attributes.

sizeLimit - The maximum number of entries to return from the search. You may use the value 0 if you do not wish to apply a limit.

Returns:

An LDAP Enumeration containing the results of the search operation.

Throws:

LDAPException - If a failure occurs during the search operation.

exists

public static boolean exists(java.lang.String dn)
                      throws LDAPException

Indicates if the specified distinguished name (DN) points to an existing entry.

Parameters:

dn - A distinguished name (DN) to search for.

Returns:

true if the specified DN points to an existing entry, or returns false if no entry is found with the specified DN.

Throws:

LDAPException - If a failure occurs during the search operation. Note: if the failure is an LDAP error code 32 (No Such Object), no exception will be thrown and this method simply returns false to indicate that the specified entry does not exist.