org.mule.module.ldap

Class LDAPConnector

java.lang.Object

org.mule.module.ldap.LDAPConnector

@RequiresEnterpriseLicense(allowEval=true)
@Connector(name="ldap",
           schemaVersion="3.5",
           friendlyName="LDAP",
           description="LDAP Connector that allows you to connect to any LDAP server and perform every LDAP operation")
@ReconnectOn(exceptions=CommunicationException.class)
@MetaDataScope(value=MetadataResolver.class)
public class LDAPConnector
extends Object

The LDAP Connector will allow to connect to any LDAP server and perform every LDAP operation:

• bind: Authenticate against the LDAP server. This occurs automatically before each operation but can also be performed on request
• search: Perform a LDAP search in a base DN with a given filter
• lookup: Retrieve a unique LDAP entry
• add: Creates a new LDAP entry
• add attribute/s: Add specific attributes to an existing LDAP entry
• modify: Update an existing LDAP entry
• modify attribute/s: Update specific attributes of an existing LDAP entry
• delete: Delete an existing LDAP entry
• delete attribute/s: Delete specific attributes of an existing LDAP entry

In order to be able to use any of the operations listed before, you must define a config element with the LDAP connection parameters:

URL	The connection URL to the LDAP server. LDAP connection URLs have the following syntax: ldap[s]://hostname:port/base_dn hostname: Name (or IP address in dotted format) of the LDAP server. For example, ldap.example.com or 192.202.185.90. port: Port number of the LDAP server (for example, 696). If no port is specified, the standard LDAP port (389) or LDAPS port (636) is used. base_dn: distinguished name (DN) of an entry in the directory. This DN identifies the entry that is the starting point of the search. If no base DN is specified, the search starts at the root of the directory tree. Some examples are: ldap://localhost:389/ ldap://localhost:389/dc=mulesoft,dc=org ldaps://localhost:636/dc=mulesoft,dc=org ldaps://ldap.mulesoft.org/
Type	The implementation of the connection to be used. Right now the only available implementation is JNDI, though any other implementation can be used (For example using Novell libraries). If you want to create your own implementation you should extend the class LDAPConnection JNDI: Implementation that uses the JNDI interfaces provided in the standard JRE.
Initial Pool Size	The string representation of an integer that represents the number of connections per connection identity to create when initially creating a connection for the identity. To disable pooling, just set this value to 0 (zero).
Max Pool Size	The string representation of an integer that represents the maximum number of connections per connection identity that can be maintained concurrently.
Pool Timeout	The string representation of an integer that represents the number of milliseconds that an idle connection may remain in the pool without being closed and removed from the pool.
Referral	Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed. The value of the property is one of the following strings: follow: Follow referrals automatically ignore: Ignore referrals throw: Throw ReferralException when a referral is encountered.
Extended Configuration	This is a Map instance holding extended configuration attributes that will be used in the Context environment. Values configured here have less precedence than the other values that are allowed in the module configuration. Some examples of extended properties (key: value) are: java.naming.language: Constant that holds the name of the environment property for specifying the preferred language to use with the service. The value of the property is a colon-separated list of language tags as defined in RFC 1766. java.naming.security.authentication: Constant that holds the name of the environment property for specifying the security level to use. Its value is one of the following strings: "none", "simple", "strong". java.naming.security.protocol: Constant that holds the name of the environment property for specifying the security protocol to use. Its value is a string determined by the service provider (e.g. "ssl"). com.sun.jndi.ldap.connect.pool.authentication: A list of space-separated authentication types of connections that may be pooled. Valid types are "none", "simple", and "DIGEST-MD5". com.sun.jndi.ldap.connect.pool.debug: A string that indicates the level of debug output to produce. Valid values are "fine" (trace connection creation and removal) and "all" (all debugging information). com.sun.jndi.ldap.connect.pool.prefsize: The string representation of an integer that represents the preferred number of connections per connection identity that should be maintained concurrently. com.sun.jndi.ldap.connect.pool.protocol: A list of space-separated protocol types of connections that may be pooled. Valid types are "plain" and "ssl".
Use Schema	If set to true, the LDAP connector will use the LDAP schema (only works for LDAP v3) to define the structure of the LDAP entry (or map). This needs to be 'true' in order to use DataSense. If useSchema is true, then the LDAP server schema will be used to determine if attributes of the LDAPEntry will be Multi Valued (LDAPMultiValueEntryAttribute) or Single Value LDAPSingleValueEntryAttribute. This translates if the value will be a List or a single Object (String, byte[], etc.). In the past, attributes were Multi Valued only when the retrieved LDAP entry had more than one value. Example: Sample LDAP server entry: dn: attr1=Value2,ou=group,dc=company,dc=org attr1: Value1 attr2: Value2 multi1: Value3 multi1: Value4 objectclass: top objectclass: myentry Schema for objectClass myentry: attr1: {SINGLE-VALUE=true} attr2: {SINGLE-VALUE=false} multi1: {SINGLE-VALUE=false} If useSchema is false then the resulting LDAPEntry representing the payload will return: // Using LDAPEntry methods payload.getAttribute("attr1") returns LDAPSingleValueEntryAttribute payload.getAttribute("attr2") returns LDAPSingleValueEntryAttribute (The attribute has only one value) payload.getAttribute("multi1") returns LDAPMultiValueEntryAttribute // Using Map methods payload.get("attr1") returns String payload.get("attr2") returns String (The attribute has only one value) payload.get("multi1") returns List If useSchema is true then the resulting LDAPEntry representing the payload will return: // Using LDAPEntry methods payload.getAttribute("attr1") returns LDAPSingleValueEntryAttribute payload.getAttribute("attr2") returns LDAPMultiValueEntryAttribute (The attribute is multi value) payload.getAttribute("multi1") returns LDAPMultiValueEntryAttribute // Using Map methods payload.get("attr1") returns String payload.get("attr2") returns List (The attribute is multi value) payload.get("multi1") returns List

Author:

MuleSoft, Inc.

Constructor Summary

Constructors

Constructor and Description
LDAPConnector()

Method Summary

Methods

Modifier and Type	Method and Description
void	add(Map<String,Object> entry, String structuralObjectClass) Creates a new LDAPEntry in the LDAP server.
void	addMultiValueAttribute(String dn, String attributeName, List<Object> attributeValues, boolean ignoreInvalidAttribute) Adds all the values for an attribute in an existing LDAP entry.
void	addSingleValueAttribute(String dn, String attributeName, String attributeValue, boolean ignoreInvalidAttribute) Adds a value for an attribute in an existing LDAP entry.
LDAPEntry	bind(String authDn, String authPassword, String authentication) Performs an LDAP bind (login) operation.
void	delete(String dn) Deletes the LDAP entry represented by the provided distinguished name.
void	deleteMultiValueAttribute(String dn, String attributeName, List<Object> attributeValues, boolean ignoreInvalidAttribute) Deletes all the values matching attributeValues of the attribute defined by attributeName.
void	deleteSingleValueAttribute(String dn, String attributeName, String attributeValue, boolean ignoreInvalidAttribute) Deletes the value matching attributeValue of the attribute defined by attributeName.
boolean	exists(String dn) Checks whether a LDAP entry exists in the LDAP server or not.
AbstractConfig	getConfig()
String	ldapEntryToLdif(LDAPEntry entry) Transforms a LDAPEntry to a String in LDIF representation (RFC 2849).
LDAPEntry	lookup(String dn, List<String> attributes, String structuralObjectClass) Retrieves an entry from the LDAP server base on its distinguished name (DN).
void	modify(LDAPEntry entry, String structuralObjectClass) Updates an existing LDAPEntry in the LDAP server.
void	modifyMultiValueAttribute(String dn, String attributeName, List<Object> attributeValues, boolean ignoreInvalidAttribute) Updates (replaces) the value or values of the attribute defined by attributeName with the new values defined by attributeValues.
void	modifySingleValueAttribute(String dn, String attributeName, String attributeValue, boolean ignoreInvalidAttribute) Updates (replaces) the value or values of the attribute defined by attributeName with the new value defined by attributeValue.
org.mule.streaming.ProviderAwarePagingDelegate<LDAPEntry,LDAPConnector>	pagedResultSearch(String baseDn, String filter, List<String> attributes, SearchScope scope, int timeout, long maxResults, boolean returnObject, int pageSize, String orderBy, boolean ascending, String structuralObjectClass, org.mule.streaming.PagingConfiguration pagingConfiguration) Performs a LDAP search and streams result to the rest of the flow.
void	rename(String oldDn, String newDn) Renames and existing LDAP entry (moves and entry from a DN to another one).
List<LDAPEntry>	search(String baseDn, String filter, List<String> attributes, SearchScope scope, int timeout, long maxResults, boolean returnObject, int pageSize, String structuralObjectClass) Performs a LDAP search returning a list with all the resulting LDAP entries.
LDAPEntry	searchOne(String baseDn, String filter, List<String> attributes, SearchScope scope, int timeout, long maxResults, boolean returnObject, String structuralObjectClass) Performs a LDAP search that is supposed to return a unique result.
void	setConfig(AbstractConfig config)
void	unbind(Boolean force) Closes the current connection, forcing the login operation (bind) the next time it is used.

Methods inherited from class java.lang.Object

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

Constructor Detail

LDAPConnector

public LDAPConnector()

Method Detail

getConfig

public AbstractConfig getConfig()

setConfig

public void setConfig(@NotNull
             AbstractConfig config)

bind

@Processor
public LDAPEntry bind(@FriendlyName(value="Principal DN")@Optional
                       String authDn,
                       @FriendlyName(value="Password")@Password@Optional
                       String authPassword,
                       @Optional
                       String authentication)
               throws Exception

Performs an LDAP bind (login) operation. After login there will be a LDAP connection pool ready to use for other operations using the authenticated user. If no values are provided to override authDn and authPassword then using this operation will just re-bind (re-authenticate) the user/password defined in the config element. If new values are provided for authDn and authPassword, then authentication will be performed. The operation supports the following four scenarios.

Re-authenticating and returning the LDAP entry using config level credentials (authDn & authPassword)

Authenticating and returning the LDAP entry using new credentials (authDn & authPassword)

Authenticating as anonymous user (returns always null)

Authenticating and returning the LDAP entry using credentials (authDn & authPassword) from Mule Expression

Returns:

The LDAPEntry of the authenticated user.

Throws:

NoPermissionException - If the current binded user has no permissions to perform the lookup for its own LDAP entry.

NameNotFoundException - If base DN is invalid (for example it doesn't exist)

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error performing the login and posterior lookup.

unbind

@Processor
public void unbind(@Default(value="false")@Optional
                    Boolean force)

Closes the current connection, forcing the login operation (bind) the next time it is used.

Since:

1.3.1

lookup

@Processor
public LDAPEntry lookup(@FriendlyName(value="DN")
                         String dn,
                         @Optional
                         List<String> attributes,
                         @MetaDataKeyParam(affects=OUTPUT)@Optional
                         String structuralObjectClass)
                 throws Exception

Retrieves an entry from the LDAP server base on its distinguished name (DN). DNs are the unique identifiers of an LDAP entry, so this method will perform a search based on this ID and so return a single entry as result or throw an exception if the DN is invalid or inexistent.

Use this operation over searchOne(String, String, List, SearchScope, int, long, boolean, String) when you know the DN of the object you want to retrieve.

Lookup returning all attributes for the entry

Lookup returning the attributes in the list obtained by expression

Lookup returning the attributes defined in the XML config file

Parameters:

dn - The DN of the LDAP entry that will be retrieved.

attributes - A list of the attributes that should be returned in the result. If the attributes list is empty or null, then by default all LDAP entry attributes are returned.

structuralObjectClass - The type of entry that will be returned. Only for DataSense purposes to be used in Anypoint Studio IDE. Has no impact on runtime, that's why it is optional.

Returns:

The LDAPEntry for the given dn parameter.

Throws:

NoPermissionException - If the current binded user has no permissions to perform the lookup for the given DN.

NameNotFoundException - If base DN is invalid (for example it doesn't exist)

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error performing the lookup.

exists

@Processor
public boolean exists(@FriendlyName(value="DN")
                       String dn)
               throws Exception

Checks whether a LDAP entry exists in the LDAP server or not.

Check if LDAP entry exists

Parameters:

dn - The DN of the LDAP entry that will be retrieved.

Returns:

true if the LDAP entry represented by dn exists or false if not

Throws:

NoPermissionException - If the current binded user has no permissions to perform the lookup for the given DN.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

NameNotFoundException - Only in case throwException is true and the LDAP entry does not exist.

Exception - In case there is any other error checking for entry existence.

search

@Processor
public List<LDAPEntry> search(@FriendlyName(value="Base DN")
                               String baseDn,
                               String filter,
                               @Optional
                               List<String> attributes,
                               @Default(value="ONE_LEVEL")
                               SearchScope scope,
                               @Placement(group="Search Controls")@Default(value="0")
                               int timeout,
                               @Placement(group="Search Controls")@Default(value="0")
                               long maxResults,
                               @Placement(group="Search Controls")@Default(value="false")
                               boolean returnObject,
                               @Placement(group="Search Controls")@Default(value="0")
                               int pageSize,
                               @MetaDataKeyParam(affects=OUTPUT)@Optional
                               String structuralObjectClass)
                       throws Exception

Performs a LDAP search returning a list with all the resulting LDAP entries.

For queries returning large results it is recommended to use pagination (not all LDAP servers support this or are configured to support it). For that you need to provide a page size value that should be less or equal than max results (count limit). If you are getting a Sizelimit Exceeded exception then you should check that the authenticated user has enough privileges or the LDAP server is not limited by configuration.

Returning all attributes for all persons that have Doe as surname

Returning username and fullname for the first 100 person entries

Search that receives all configuration attributes using Mule Expressions

Parameters:

baseDn - The base DN of the LDAP search.

filter - A valid LDAP filter. The LDAP connector supports LDAP search filters as defined in RFC 2254. Some examples are:

• (objectClass=*): All objects.
• (&(objectClass=person)(!cn=andy)): All persons except for the one with common name (cn) "andy".
• (sn=sm*): All objects with a surname that starts with "sm".
• (&(objectClass=person)(|(sn=Smith)(sn=Johnson))): All persons with a surname equal to "Smith" or "Johnson".

attributes - A list of the attributes that should be returned in the result. If the attributes list is empty or null, then by default all LDAP entry attributes are returned.

scope - The scope of the search. Valid attributes are:

• OBJECT: This value is used to indicate searching only the entry at the base DN, resulting in only that entry being returned (keeping in mind that it also has to meet the search filter criteria!)
• ONE_LEVEL: This value is used to indicate searching all entries one level under the base DN - but not including the base DN and not including any entries under that one level under the base DN.
• SUB_TREE: This value is used to indicate searching of all entries at all levels under and including the specified base DN.

timeout - Search timeout in milliseconds. If the value is 0, this means to wait indefinitely.

maxResults - The maximum number of entries that will be returned as a result of the search. 0 indicates that all entries will be returned.

returnObject - Enables/disables returning objects returned as part of the result. If disabled, only the name and class of the object is returned. If enabled, the object will be returned.

pageSize - If the LDAP server supports paging results set in this attribute the size of the page. If the pageSize is less or equals than 0, then paging will be disabled.

structuralObjectClass - The type of entry that will be returned. Only for DataSense purposes to be used in Anypoint Studio IDE. Has no impact on runtime, that's why it is optional.

Returns:

A List of LDAPEntry objects with the results of the search. If the search throws no results, then this is an empty list.

Throws:

NoPermissionException - If the current binded user has no permissions to perform the search under the given base DN.

NameNotFoundException - If base DN is invalid (for example it doesn't exist)

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error performing the search.

pagedResultSearch

@Processor
@Paged(defaultFetchSize=200)
public org.mule.streaming.ProviderAwarePagingDelegate<LDAPEntry,LDAPConnector> pagedResultSearch(@FriendlyName(value="Base DN")
                                                                                                        String baseDn,
                                                                                                        String filter,
                                                                                                        @Optional
                                                                                                        List<String> attributes,
                                                                                                        @Default(value="ONE_LEVEL")
                                                                                                        SearchScope scope,
                                                                                                        @Placement(group="Search Controls")@Default(value="0")
                                                                                                        int timeout,
                                                                                                        @Placement(group="Search Controls")@Default(value="0")
                                                                                                        long maxResults,
                                                                                                        @Placement(group="Search Controls")@Default(value="false")
                                                                                                        boolean returnObject,
                                                                                                        @Placement(group="Search Controls")@Default(value="0")
                                                                                                        int pageSize,
                                                                                                        @FriendlyName(value="Order by attribute")@Placement(group="Search Controls",order=1)@Optional
                                                                                                        String orderBy,
                                                                                                        @FriendlyName(value="Ascending order?")@Placement(group="Search Controls",order=2)@Default(value="true")
                                                                                                        boolean ascending,
                                                                                                        @MetaDataKeyParam(affects=OUTPUT)@Optional
                                                                                                        String structuralObjectClass,
                                                                                                        @RefOnly
                                                                                                        org.mule.streaming.PagingConfiguration pagingConfiguration)
                                                                                          throws Exception

Performs a LDAP search and streams result to the rest of the flow. This means that instead of returning a list with all results it partitions the LDAP search result into pages (individual entry if resultPageSize is 1) or lists of size resultPageSize.

This is an intercepting operation what means that for each result (individual entry if resultPageSize is 1 or List of resultPageSize size) the rest of the flow will be executed. Each of these executions will return a result that will be aggregated into a List of results.

For queries returning large results it is recommended to use pagination (not all LDAP servers support this or are configured to support it). For that you need to provide a fetch size (page size) value that should be less or equal than max results (count limit). If you are getting a Size Limit Exceeded exception message then you should check that the authenticated user has enough privileges or the LDAP server is not limited by configuration. In that case, just reduce the value of the fetch size.

Returning all persons LDAP entries in pages of 100 entries each

Parameters:

baseDn - The base DN of the LDAP search.

filter - A valid LDAP filter. The LDAP connector supports LDAP search filters as defined in RFC 2254. Some examples are:

• (objectClass=*): All objects.
• (&(objectClass=person)(!cn=andy)): All persons except for the one with common name (cn) "andy".
• (sn=sm*): All objects with a surname that starts with "sm".
• (&(objectClass=person)(|(sn=Smith)(sn=Johnson))): All persons with a surname equal to "Smith" or "Johnson".

attributes - A list of the attributes that should be returned in the result. If the attributes list is empty or null, then by default all LDAP entry attributes are returned.

scope - The scope of the search. Valid attributes are:

• OBJECT: This value is used to indicate searching only the entry at the base DN, resulting in only that entry being returned (keeping in mind that it also has to meet the search filter criteria!)
• ONE_LEVEL: This value is used to indicate searching all entries one level under the base DN - but not including the base DN and not including any entries under that one level under the base DN.
• SUB_TREE: This value is used to indicate searching of all entries at all levels under and including the specified base DN.

timeout - Search timeout in milliseconds. If the value is 0, this means to wait indefinitely.

maxResults - The maximum number of entries that will be returned as a result of the search. 0 indicates that all entries will be returned.

returnObject - Enables/disables returning objects returned as part of the result. If disabled, only the name and class of the object is returned. If enabled, the object will be returned.

pageSize - If the LDAP server supports paging results set in this attribute the size of the page. If the pageSize is less or equals than 0, then paging will be disabled.

orderBy - Name of the LDAP attribute used to sort results.

ascending - If orderBy was set, whether to sort in ascending or descending order.

structuralObjectClass - The type of entry that will be returned. Only for DataSense purposes to be used in Anypoint Studio IDE. Has no impact on runtime, that's why it is optional.

pagingConfiguration - Paging configuration. The field fetchSize in this object represents the size of pages Mule will use while iterating (vs pageSize that is an LDAP related attribute used for the amount of LDAP entries retrieved at once while iterating at low level the LDAP results)

Returns:

A list with individual results of executing the rest of flow with each results page.

Throws:

NoPermissionException - If the current binded user has no permissions to perform the search under the given base DN.

NameNotFoundException - If base DN is invalid (for example it doesn't exist)

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error performing the search.

searchOne

@Processor
public LDAPEntry searchOne(@FriendlyName(value="Base DN")
                            String baseDn,
                            String filter,
                            @Optional
                            List<String> attributes,
                            @Default(value="ONE_LEVEL")
                            SearchScope scope,
                            @Placement(group="Search Controls")@Default(value="0")
                            int timeout,
                            @Placement(group="Search Controls")@Default(value="0")
                            long maxResults,
                            @Placement(group="Search Controls")@Default(value="false")
                            boolean returnObject,
                            @MetaDataKeyParam(affects=OUTPUT)@Optional
                            String structuralObjectClass)
                    throws Exception

Performs a LDAP search that is supposed to return a unique result. If the search returns more than one result, then a warn log message is generated and the first element of the result is returned.

Use this operation over lookup(String, List, String) when you know don't know the DN of the entry you need to retrieve but you have a set of attributes that you know should return a single entry (for example an email address)

Parameters:

baseDn - The base DN of the LDAP search.

filter - A valid LDAP filter. The LDAP connector supports LDAP search filters as defined in RFC 2254. Some examples are:

• (objectClass=*): All objects.
• (&(objectClass=person)(!cn=andy)): All persons except for the one with common name (cn) "andy".
• (sn=sm*): All objects with a surname that starts with "sm".
• (&(objectClass=person)(|(sn=Smith)(sn=Johnson))): All persons with a surname equal to "Smith" or "Johnson".

attributes - A list of the attributes that should be returned in the result. If the attributes list is empty or null, then by default all LDAP entry attributes are returned.

scope - The scope of the search. Valid attributes are:

• OBJECT: This value is used to indicate searching only the entry at the base DN, resulting in only that entry being returned (keeping in mind that it also has to meet the search filter criteria!)
• ONE_LEVEL: This value is used to indicate searching all entries one level under the base DN - but not including the base DN and not including any entries under that one level under the base DN.
• SUB_TREE: This value is used to indicate searching of all entries at all levels under and including the specified base DN.

timeout - Search timeout in milliseconds. If the value is 0, this means to wait indefinitely.

maxResults - The maximum number of entries that will be returned as a result of the search. 0 indicates that all entries will be returned.

returnObject - Enables/disables returning objects returned as part of the result. If disabled, only the name and class of the object is returned. If enabled, the object will be returned.

structuralObjectClass - The type of entry that will be returned. Only for DataSense purposes to be used in Anypoint Studio IDE. Has no impact on runtime, that's why it is optional.

Returns:

A LDAPEntry with the first element of the search result or null if there are no results.

Throws:

NoPermissionException - If the current binded user has no permissions to perform the search under the given base DN.

NameNotFoundException - If base DN is invalid (for example it doesn't exist)

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error performing the search.

add

@Processor(friendlyName="Add entry")
public void add(@RefOnly@Default(value="#[payload]")
                 Map<String,Object> entry,
                 @MetaDataKeyParam(affects=INPUT)@Optional
                 String structuralObjectClass)
         throws Exception

Creates a new LDAPEntry in the LDAP server. The entry should contain the distinguished name (DN), the objectClass attributes that define its structure and at least a value for all the required attributes (required attributes depend on the object classes assigned to the entry. You can refer to RFC 4519 for standard object classes and attributes.

LDAPEntry object provided with expression

LDAPEntry object provided in payload

Parameters:

entry - The LDAPEntry that should be added.

structuralObjectClass - The type of entry that will be added. If the entry doesn't have the objectClass attribute set, then this one will be used to retrieved the whole objectClass hierarchy. If performance is a requirement, don't rely on this functionality as several calls to the LDAP server will be done to trasverse the object class hierarchy.

Throws:

NoPermissionException - If the current binded user has no permissions to add entries under any of the RDN (relative DN) that compose the entry DN.

InvalidAttributeException - If the structure of the entry is invalid (for example there are missing required attributes or it has attributes that are not part of any of the defined object classes)

NameAlreadyBoundException - If there is already an existing entry with the same DN in the LDAP server tree.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error creating the entry.

modify

@Processor(friendlyName="Modify entry")
public void modify(@RefOnly@Default(value="#[payload]")
                    LDAPEntry entry,
                    @MetaDataKeyParam(affects=INPUT)@Optional
                    String structuralObjectClass)
            throws Exception

Updates an existing LDAPEntry in the LDAP server. The entry should contain an existing distinguished name (DN), and at least a value for all the required attributes (required attributes depend on the object classes assigned to the entry. You can refer to RFC 4519 for standard object classes and attributes.

When updating a LDAP entry, only the attributes in the entry passed as parameter are updated or added. If you need to delete an attribute, you should use the delete attribute operation.

Example: Updating one attributes and adding one.

Original LDAP server entry:
dn: cn=entry,ou=group,dc=company,dc=org
cn: entry
attr1: Value1
attr2: Value2
multi1: Value3
multi1: Value4
objectclass: top
objectclass: myentry

Entry map passed as parameter:
dn: cn=entry,ou=group,dc=company,dc=org
attr1: NewValue
attr3: NewAttributeValue

Resulting LDAP server entry:
dn: cn=entry,ou=group,dc=company,dc=org
cn: entry
attr1: NewValue
attr2: Value2
multi1: Value3
multi1: Value4
attr3: NewAttributeValue
objectclass: top
objectclass: myentry

The LDAP entry is in the payload

The LDAP entry is in a session variable

Parameters:

entry - The LDAPEntry that should be updated.

structuralObjectClass - The type of entry that will be updated. Only for DataSense purposes to be used in Anypoint Studio IDE. Has no impact on runtime, that's why it is optional.

Throws:

NoPermissionException - If the current binded user has no permissions to update entries under any of the RDN (relative DN) that compose the entry DN.

InvalidAttributeException - If the structure of the entry is invalid (for example there are missing required attributes or it has attributes that are not part of any of the defined object classes)

NameNotFoundException - If there is no existing entry with the same DN in the LDAP server tree.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error updating the entry.

delete

@Processor(friendlyName="Delete entry")
public void delete(@FriendlyName(value="DN")@Default(value="#[payload]")
                    String dn)
            throws Exception

Deletes the LDAP entry represented by the provided distinguished name. The entry should not have child entries, in which case a ContextNotEmptyException is thrown.

This operation is idempotent. It succeeds even if the terminal atomic name is not bound in the target context, but throws NameNotFoundException if any of the intermediate contexts do not exist.

Parameters:

dn - The DN of the LDAP entry to delete

Throws:

NoPermissionException - If the current binded user has no permissions to delete the entry.

NameNotFoundException - If an intermediate context does not exist.

ContextNotEmptyException - If the entry to delete has child entries.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error deleting the entry.

rename

@Processor(friendlyName="Rename entry")
public void rename(@Placement(order=1)@FriendlyName(value="Current DN")
                    String oldDn,
                    @Placement(order=2)@FriendlyName(value="New DN")
                    String newDn)
            throws Exception

Renames and existing LDAP entry (moves and entry from a DN to another one).

Parameters:

oldDn - DN of the existing entry that will be renamed.

newDn - Destination DN

Throws:

NameAlreadyBoundException - If there is already an existing entry with the same DN as newDn.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error deleting the entry.

addSingleValueAttribute

@Processor
public void addSingleValueAttribute(@FriendlyName(value="DN")
                                     String dn,
                                     String attributeName,
                                     String attributeValue,
                                     @Default(value="false")
                                     boolean ignoreInvalidAttribute)
                             throws Exception

Adds a value for an attribute in an existing LDAP entry. If the entry already contained a value for the given attributeName then this value will be added (only if the attribute is multi value and there entry didn't have the value already).

If you want to add a value with a type different than String, then you can use the add-multi-value-attribute operation and define a one element list with the value.

Parameters:

dn - The DN of the LDAP entry to modify

attributeName - The name of the attribute to add a value to.

attributeValue - The value for the attribute

ignoreInvalidAttribute - If the attribute value to add is already present, then don't throw InvalidAttributeException

Throws:

NoPermissionException - If the current binded user has no permissions to update the entry.

InvalidAttributeException - If the attribute value is invalid or the entry already has the provided value.

NameNotFoundException - If there is no existing entry for the given DN.

InvalidAttributeException - If the entry does have the attribute value that should be added. Ignored if ignoreInvalidAttribute is true. Note: Not every LDAP server will through this exception.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error updating the entry.

addMultiValueAttribute

@Processor
public void addMultiValueAttribute(@FriendlyName(value="DN")
                                    String dn,
                                    String attributeName,
                                    @RefOnly@Default(value="#[payload]")
                                    List<Object> attributeValues,
                                    @Default(value="false")
                                    boolean ignoreInvalidAttribute)
                            throws Exception

Adds all the values for an attribute in an existing LDAP entry. If the entry already contained a value (or values) for the given attributeName then these values will be added. The attribute should allow multiple values or an exception will be raised.

Parameters:

dn - The DN of the LDAP entry to modify

attributeName - The name of the attribute to add values to.

attributeValues - The values for the attribute

ignoreInvalidAttribute - If the attribute value to add is already present, then don't throw InvalidAttributeException

Throws:

NoPermissionException - If the current binded user has no permissions to update the entry.

NameNotFoundException - If there is no existing entry for the given DN.

InvalidAttributeException - If the attribute value is invalid or the entry already has the provided value.

InvalidAttributeException - If the entry does have the attribute value that should be added. Ignored if ignoreInvalidAttribute is true. Note: Not every LDAP server will through this exception.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error updating the entry.

modifySingleValueAttribute

@Processor
public void modifySingleValueAttribute(@FriendlyName(value="DN")
                                        String dn,
                                        String attributeName,
                                        String attributeValue,
                                        @Default(value="false")
                                        boolean ignoreInvalidAttribute)
                                throws Exception

Updates (replaces) the value or values of the attribute defined by attributeName with the new value defined by attributeValue. If the attribute was not present in the entry, then the value is added.

If you want to update a value with a type different than String, then you can use the update-multi-value-attribute operation and define a one element list with the value.

Parameters:

dn - The DN of the LDAP entry to modify

attributeName - The name of the attribute to update its value.

attributeValue - The new value for the attribute

ignoreInvalidAttribute - If the attribute value to modify is already present, then don't throw InvalidAttributeException

Throws:

NoPermissionException - If the current binded user has no permissions to update the entry.

NameNotFoundException - If there is no existing entry for the given DN.

InvalidAttributeException - If the entry does have the attribute value that should be modified. Ignored if ignoreInvalidAttribute is true. Note: Not every LDAP server will through this exception.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error updating the entry.

modifyMultiValueAttribute

@Processor
public void modifyMultiValueAttribute(@FriendlyName(value="DN")
                                       String dn,
                                       String attributeName,
                                       @RefOnly
                                       List<Object> attributeValues,
                                       @Default(value="false")
                                       boolean ignoreInvalidAttribute)
                               throws Exception

Updates (replaces) the value or values of the attribute defined by attributeName with the new values defined by attributeValues. If the attribute was not present in the entry, then the value is added.

Parameters:

dn - The DN of the LDAP entry to modify

attributeName - The name of the attribute to update its values.

attributeValues - The new values for the attribute

ignoreInvalidAttribute - If the attribute value to modify is already present, then don't throw InvalidAttributeException

Throws:

NoPermissionException - If the current binded user has no permissions to update the entry.

NameNotFoundException - If there is no existing entry for the given DN.

InvalidAttributeException - If the entry does have the attribute value that should be modified. Ignored if ignoreInvalidAttribute is true. Note: Not every LDAP server will through this exception.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error updating the entry.

deleteSingleValueAttribute

@Processor
public void deleteSingleValueAttribute(@FriendlyName(value="DN")
                                        String dn,
                                        String attributeName,
                                        @Optional
                                        String attributeValue,
                                        @Default(value="false")
                                        boolean ignoreInvalidAttribute)
                                throws Exception

Deletes the value matching attributeValue of the attribute defined by attributeName. If the entry didn't have the value, then the entry stays the same. If no value is specified, then the whole attribute is deleted from the entry.

If you want to delete a value with a type different than String, then you can use the delete-multi-value-attribute operation and define a one element list with the value.

Parameters:

dn - The DN of the LDAP entry to modify

attributeName - The name of the attribute to delete its value.

attributeValue - The value that should be deleted.

ignoreInvalidAttribute - If the attribute or value to delete is no present, then don't throw InvalidAttributeException

Throws:

NoPermissionException - If the current binded user has no permissions to update the entry.

NameNotFoundException - If there is no existing entry for the given DN.

InvalidAttributeException - If the entry doesn't have the attribute or value that should be deleted. Ignored if ignoreInvalidAttribute is true. Note: Not every LDAP server will through this exception.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error updating the entry.

deleteMultiValueAttribute

@Processor
public void deleteMultiValueAttribute(@FriendlyName(value="DN")
                                       String dn,
                                       String attributeName,
                                       @RefOnly@Optional
                                       List<Object> attributeValues,
                                       @Default(value="false")
                                       boolean ignoreInvalidAttribute)
                               throws Exception

Deletes all the values matching attributeValues of the attribute defined by attributeName. Values that are not present in the entry are ignored. If no values are specified, then the whole attribute is deleted from the entry.

Parameters:

dn - The DN of the LDAP entry to modify

attributeName - The name of the attribute to delete its values.

attributeValues - The values that should be deleted.

ignoreInvalidAttribute - If the attribute or value to delete is no present, then don't throw InvalidAttributeException

Throws:

NoPermissionException - If the current binded user has no permissions to update the entry.

NameNotFoundException - If there is no existing entry for the given DN.

InvalidAttributeException - If the entry doesn't have the attribute or value that should be deleted. Ignored if ignoreInvalidAttribute is true. Note: Not every LDAP server will through this exception.

LDAPException - In case there is any other exception, mainly related to connectivity problems or referrals.

Exception - In case there is any other error updating the entry.

ldapEntryToLdif

@Processor
public String ldapEntryToLdif(@RefOnly@Default(value="#[payload]")
                               LDAPEntry entry)

Transforms a LDAPEntry to a String in LDIF representation (RFC 2849).

Parameters:

entry - The LDAPEntry to transform to LDIF.

Returns:

The LDIF representation of the entry.