Package com.jalios.ldap

Class LDAPMapper

  • public class LDAPMapper
extends java.lang.Object
    This class allows simpler access to LDAP using following ldap properties. It is not thread safe, use one LDAPMapper instance per thread.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected LDAPConfiguration conf  
      static java.lang.String END_OF_RANGE
      The character indicating that the end of the range has been reached.
      protected boolean isConnected  
      protected com.unboundid.ldap.sdk.LDAPException lastException  
      protected com.unboundid.ldap.sdk.LDAPConnection ldc  
      static java.lang.String RANGE_FORMAT
      The format used to calculate attribute IDs for subsequent searches.
      static java.util.regex.Pattern RANGE_PATTERN
      The pattern matching the range attribute ID.
      static java.lang.String RANGE_PATTERN_STRING
      The expression matching the range attribute ID "<id>;range=<X>-<Y>".
      protected com.unboundid.ldap.sdk.RootDSE rootDSE  

    • Constructor Summary

      Constructors 
      Constructor Description
      LDAPMapper​(LDAPConfiguration conf)
      Creates a new mapper and establish the connection using given LDAPConfiguration.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean authenticate​(java.lang.String dn, java.lang.String password)
      Try to establish a new connection and to authenticate to the ldap server specified in the LDAPConfiguration of this mapper, using the given dn connect and password.
      void disconnect()
      Disconnect the underlying LDAPConnection of this mapper.
      com.unboundid.ldap.sdk.SearchResultEntry getGroupLDAPEntryFromDN​(java.lang.String fullDN, java.lang.String[] attrs)
      Retrieve a Group entry from its exact DN.
      com.unboundid.ldap.sdk.SearchResultEntry getGroupLDAPEntryFromGUID​(java.lang.String guidStr, java.lang.String[] attrs)
      Retrieve a Group entry from its GUID.
      java.util.ArrayList<com.unboundid.ldap.sdk.SearchResultEntry> getGroupsLDAPEntries​(java.lang.String dn, java.lang.String[] attrs)
      Return the groups LDAP Entry for the given dn (dn of a user or a sub-group).
      com.unboundid.ldap.sdk.LDAPException getLastException()  
      LDAPConfiguration getLDAPConfiguration()
      Retrieve the LDAPConfiguration object associated to this Mapper.
      com.unboundid.ldap.sdk.LDAPConnection getLDAPConnection()
      Returns the LDAPConnection instance initialized during the construction of this LDAPMapper.
      java.util.ArrayList<com.unboundid.ldap.sdk.SearchResultEntry> getMatchingLDAPEntries​(java.lang.String baseDN, com.unboundid.ldap.sdk.SearchScope scope, java.lang.String searchFilter, java.lang.String[] attrs, java.lang.String[] sortKeys)
      Return the matching LDAP Entries.
      java.util.ArrayList<com.unboundid.ldap.sdk.SearchResultEntry> getMatchingLDAPEntries​(java.lang.String baseDN, java.lang.String searchFilter, java.lang.String[] attrs)
      Return the matching LDAP Entries.
      java.util.ArrayList<com.unboundid.ldap.sdk.SearchResultEntry> getMatchingLDAPEntries​(java.lang.String baseDN, java.lang.String searchFilter, java.lang.String[] attrs, java.lang.String[] sortKeys)
      Return the matching LDAP Entries.
      java.util.List<java.lang.String> getRangedAttributeStringValues​(com.unboundid.ldap.sdk.SearchResultEntry entry, java.lang.String attributeName)
      Retrieve all values of the specified attribute, even if attribute is a ranged attribute of ActiveDirectory.
      com.unboundid.ldap.sdk.RootDSE getRootDSE()
      Retrieves the directory server root DSE, which provides information about the directory server, including the capabilities that it provides and the type of data that it is configured to handle.
      com.unboundid.ldap.sdk.SearchResultEntry getUserLDAPEntry​(java.lang.String login, java.lang.String[] attrs)
      Return the first matching LDAP Entry for the given login.
      com.unboundid.ldap.sdk.SearchResultEntry getUserLDAPEntryFromDN​(java.lang.String fullDN, java.lang.String[] attrs)
      Retrieve a User entry from its exact DN.
      java.util.List<com.unboundid.ldap.sdk.SearchResultEntry> getUsersLDAPEntries​(java.lang.String[] sortKeys, java.lang.String[] attrs)
      Retrieve all user SearchResultEntry matching current configuration.
      boolean isConnected()  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • ldc

        protected final com.unboundid.ldap.sdk.LDAPConnection ldc

      • isConnected

        protected boolean isConnected

      • rootDSE

        protected com.unboundid.ldap.sdk.RootDSE rootDSE

      • lastException

        protected com.unboundid.ldap.sdk.LDAPException lastException

      • END_OF_RANGE

        public static final java.lang.String END_OF_RANGE
        The character indicating that the end of the range has been reached.
        See Also:
        Constant Field Values

      • RANGE_FORMAT

        public static final java.lang.String RANGE_FORMAT
        The format used to calculate attribute IDs for subsequent searches.
        See Also:
        Constant Field Values

      • RANGE_PATTERN_STRING

        public static final java.lang.String RANGE_PATTERN_STRING
        The expression matching the range attribute ID "<id>;range=<X>-<Y>".
        See Also:
        Constant Field Values

      • RANGE_PATTERN

        public static final java.util.regex.Pattern RANGE_PATTERN
        The pattern matching the range attribute ID.

    • Constructor Detail

      • LDAPMapper

        public LDAPMapper​(LDAPConfiguration conf)
        Creates a new mapper and establish the connection using given LDAPConfiguration.
        IMPORTANT: Don't forget to call disconnect() when finished with this mapper.
        If an error occurs during connection, the LDAPException describing the error is accessible using getLastException()
        Parameters:
        conf - the LDAPConfiguration to use for this mapper

    • Method Detail

      • getUserLDAPEntry

        public com.unboundid.ldap.sdk.SearchResultEntry getUserLDAPEntry​(java.lang.String login,
                                                                 java.lang.String[] attrs)
        Return the first matching LDAP Entry for the given login.
        Uses : - LDAPConfiguration.getSuffix() (search baseDN) - LDAPConfiguration.getUserFilter() (search filter)
        Parameters:
        login - the login of the member of which to retrieve SearchResultEntry.
        attrs - attributes you want returned in the result.
        Returns:
        the first SearchResultEntry retrieved from LDAP, or null if member is not found or if an error occured (in which case getLastException(). A warning message is logged if more than one entries have been found (in which case you should refine your user search filter).
        Since:
        jcms-5.7.0

      • getUserLDAPEntryFromDN

        public com.unboundid.ldap.sdk.SearchResultEntry getUserLDAPEntryFromDN​(java.lang.String fullDN,
                                                                       java.lang.String[] attrs)
        Retrieve a User entry from its exact DN.

        This method differs from the LDAPConnection.getEntry(String, String[]) because it will apply the user filter configured in JCMS (LDAPConfiguration.getUserFilter()

        Parameters:
        fullDN - the DN of the User entry to retrieve
        attrs - attributes you want returned in the result entry.
        Returns:
        the SearchResultEntry retrieved from LDAP, null if LDAP entry could not be found. Also returns null if several entries were found, this prevents invalid behavior if bad DN is specified (a warning is issued in the logs)
        Since:
        jcms-7.0

      • getUsersLDAPEntries

        public java.util.List<com.unboundid.ldap.sdk.SearchResultEntry> getUsersLDAPEntries​(java.lang.String[] sortKeys,
                                                                                    java.lang.String[] attrs)
        Retrieve all user SearchResultEntry matching current configuration.

        This implementation does not scale to thousands users/groups and may consume lot of memory as all LDAP user entry are retrieved at once from the LDAP.

        Parameters:
        sortKeys - the LDAP attribute names to use for sorting of LDAP entry, eg "cn"
        attrs - attributes you want returned in the result entry.
        Returns:
        a list of all SearchResultEntry retrieved from LDAP, never return null
        Since:
        jcms-9.0.1

      • getGroupsLDAPEntries

        public java.util.ArrayList<com.unboundid.ldap.sdk.SearchResultEntry> getGroupsLDAPEntries​(java.lang.String dn,
                                                                                          java.lang.String[] attrs)
        Return the groups LDAP Entry for the given dn (dn of a user or a sub-group).
        Uses : - LDAPConfiguration.getGroupSuffix() (search baseDN) - LDAPConfiguration.getGroupFilter() (search filter)
        Parameters:
        dn - the dn of the user of which to retrieve groups' SearchResultEntry.
        attrs - attributes you want returned in the result.
        Returns:
        a list of SearchResultEntry retrieved from LDAP, or null if no group is found or if an error occured (in which case getLastException().
        Since:
        jcms-5.7.0

      • getGroupLDAPEntryFromDN

        public com.unboundid.ldap.sdk.SearchResultEntry getGroupLDAPEntryFromDN​(java.lang.String fullDN,
                                                                        java.lang.String[] attrs)
        Retrieve a Group entry from its exact DN.

        This method differs from the LDAPConnection.getEntry(String, String[]) because it will apply the group filter configured in JCMS (LDAPConfiguration.getGroupFilter()

        Parameters:
        fullDN - the DN of the Group entry to retrieve
        attrs - attributes you want returned in the result entry.
        Returns:
        the SearchResultEntry retrieved from LDAP, null if LDAP entry could not be found. Also returns null if several entries were found, this prevents invalid behavior if bad DN is specified (a warning is issued in the logs)
        Since:
        jcms-7.0

      • getGroupLDAPEntryFromGUID

        public com.unboundid.ldap.sdk.SearchResultEntry getGroupLDAPEntryFromGUID​(java.lang.String guidStr,
                                                                          java.lang.String[] attrs)
        Retrieve a Group entry from its GUID.

        This method applie the group filter configured in JCMS (LDAPConfiguration.getGroupFilter()

        Parameters:
        guidStr - the 16-byte string representation of a the group GUID.
        attrs - attributes you want returned in the result entry.
        Returns:
        the SearchResultEntry retrieved from LDAP, null if LDAP entry could not be found. Also returns null if several entries were found, this prevents invalid behavior if bad DN is specified (a warning is issued in the logs)

      • getMatchingLDAPEntries

        public java.util.ArrayList<com.unboundid.ldap.sdk.SearchResultEntry> getMatchingLDAPEntries​(java.lang.String baseDN,
                                                                                            java.lang.String searchFilter,
                                                                                            java.lang.String[] attrs)
        Return the matching LDAP Entries. (uses the LDAPConfiguration suffix (search baseDN) and user filter (search filter)).
        Does not return entries that may be available on referals servers.
        Parameters:
        baseDN - the base distinguished name from which to search
        searchFilter - the searchFilter to use for with method LDAPConnection.search(String, SearchScope, String, String...)
        attrs - attributes you want returned in the result.
        Returns:
        an ArrayList of SearchResultEntry retrieved from LDAP, (never return null), LDAPException is available using getLastException() if error occured during search.
        Since:
        jcms-5.7.0

      • getMatchingLDAPEntries

        public java.util.ArrayList<com.unboundid.ldap.sdk.SearchResultEntry> getMatchingLDAPEntries​(java.lang.String baseDN,
                                                                                            java.lang.String searchFilter,
                                                                                            java.lang.String[] attrs,
                                                                                            java.lang.String[] sortKeys)
        Return the matching LDAP Entries. (uses the LDAPConfiguration suffix (search baseDN) and user filter (search filter)).
        Does not return entries that may be available on referals servers.
        Parameters:
        baseDN - the base distinguished name from which to search
        searchFilter - the searchFilter to use for with method LDAPConnection.search(String, SearchScope, String, String...)
        attrs - attributes you want returned in the result.
        sortKeys - the LDAP attribute names to use for sorting of LDAP entry, eg "cn"
        Returns:
        an ArrayList of SearchResultEntry retrieved from LDAP, (never return null), LDAPException is available using getLastException() if error occured during search.
        Since:
        jcms-9.0.1

      • getMatchingLDAPEntries

        public java.util.ArrayList<com.unboundid.ldap.sdk.SearchResultEntry> getMatchingLDAPEntries​(java.lang.String baseDN,
                                                                                            com.unboundid.ldap.sdk.SearchScope scope,
                                                                                            java.lang.String searchFilter,
                                                                                            java.lang.String[] attrs,
                                                                                            java.lang.String[] sortKeys)
        Return the matching LDAP Entries. (uses the LDAPConfiguration suffix (search baseDN) and user filter (search filter)).
        Does not return entries that may be available on referals servers.
        Parameters:
        baseDN - the base distinguished name from which to search
        scope - the search scope to apply, SearchScope.SUB is used if null
        searchFilter - the searchFilter to use for with method LDAPConnection.search(String, SearchScope, String, String...)
        attrs - attributes you want returned in the result.
        sortKeys - the LDAP attribute names to use for sorting of LDAP entry, eg "cn"
        Returns:
        an ArrayList of SearchResultEntry retrieved from LDAP, (never return null), LDAPException is available using getLastException() if error occured during search.
        Since:
        10.0.8 / JCMS-9423

      • getRangedAttributeStringValues

        public java.util.List<java.lang.String> getRangedAttributeStringValues​(com.unboundid.ldap.sdk.SearchResultEntry entry,
                                                                       java.lang.String attributeName)
        Retrieve all values of the specified attribute, even if attribute is a ranged attribute of ActiveDirectory.

        If the specified attribute is a ranged attribute of ActiveDirectory, perform the appropriate computation and new LDAP queries to ensure all attribute's values are retrieved.

        See Range Retrieval of Attribute Values at Microsoft.com

        Parameters:
        entry - the entry in which LDAPAttribute was retrieved (must not be null)
        attributeName - the name of the attribute to retrieve (must not be null, may be ranged or not)
        Returns:
        a List of all String values of the specified attribute, never return null

      • authenticate

        public boolean authenticate​(java.lang.String dn,
                            java.lang.String password)
        Try to establish a new connection and to authenticate to the ldap server specified in the LDAPConfiguration of this mapper, using the given dn connect and password. Disconnect immediately.
        Parameters:
        dn - the dn to use to try au
        password - the password to use for authentication.
        Returns:
        true if authentication succeeded, false otherwise, in which case the error is available using getLastException()

      • getLDAPConfiguration

        public LDAPConfiguration getLDAPConfiguration()
        Retrieve the LDAPConfiguration object associated to this Mapper.
        Returns:
        an instance of LDAPConfiguration, never return null.

      • getLastException

        public com.unboundid.ldap.sdk.LDAPException getLastException()
        Returns:
        Returns the last LDAPException thrown during an operation.

      • getLDAPConnection

        public com.unboundid.ldap.sdk.LDAPConnection getLDAPConnection()
        Returns the LDAPConnection instance initialized during the construction of this LDAPMapper.
        Before using this method, you can check that the connection has been properly established using isConnected().
        You should not disconnect using the LDAPConnection.close() method of the returned LDAPConnection object, instead, call the disconnect() method of this LDAPMapper.
        Returns:
        Returns the LDAPConnection instance used by this LDAPMapper.

      • isConnected

        public boolean isConnected()
        Returns:
        true if this a successful LDAP Connection was establish in constructor of this mapper.

      • getRootDSE

        public com.unboundid.ldap.sdk.RootDSE getRootDSE()
        Retrieves the directory server root DSE, which provides information about the directory server, including the capabilities that it provides and the type of data that it is configured to handle.

        Retrieved once and cached for the duration of the connexion, not available until connexion is successful.

        Returns:
        The directory server root DSE, or null if it is not available.

      • disconnect

        public void disconnect()
        Disconnect the underlying LDAPConnection of this mapper.