public final class LdapService extends Object implements AutoCloseable
PersonRecord
, RoleRecord
, UnitRecord
and GroupRecord
.
close()
method should be called to ensure a clean JVM shutdown. It is annotated
with PreDestroy
so it will be automatically called by supporting containers. It may
also be called using try-with-resources as LdapService
implements
AutoCloseable
.
com.sun.jndi.ldap.connect.pool.protocol
to value "plain ssl"
on loading, to
try and ensure that connection pooling works for encrypted connections. See the
JNDI docs for
details.Modifier and Type | Class and Description |
---|---|
static class |
LdapService.ConnectionType |
Modifier and Type | Method and Description |
---|---|
void |
close()
Disposes of any resources and terminates any threads that are held by the instance.
|
InitialLdapContext |
connect()
Establishes an LDAP connection using the normal credentials, or an anonymous bind if none are
configured.
|
InitialLdapContext |
connect(LdapService.ConnectionType type)
Establishes an LDAP connection using the specified set of credentials.
|
InitialLdapContext |
connectGroup()
Establishes an LDAP connection using the group credentials, or an anonymous bind if none are
configured.
|
void |
deleteEntry(String dn)
Deletes an LDAP entry recursively, using the appropriate set of credentials.
|
GroupRecord |
getGroup(String cn)
|
GroupRecord |
getGroup(String cn,
String searchBase)
Gets a
GroupRecord from within the specified search base of the LDAP. |
String |
getGroupPrincipal()
Gets the principal used for group actions.
|
List<GroupRecord> |
getGroupsForUser(String username,
boolean includeMembers)
Gets
GroupRecord s from the LDAP for all groups containing the specified user. |
static LdapService |
getInstance(String url,
String principal,
String password)
Static factory method for
LdapService s configured with one set of credentials to
use for all operations. |
static LdapService |
getInstanceAnon(String url)
Static factory method for unauthenticated
LdapService s. |
static LdapService |
getInstanceExplicitlyConfigured(String url,
String generalPrincipal,
String generalPassword,
String groupPrincipal,
String groupPassword,
String configPrincipal,
String configPassword,
int maxPageSize,
int maxRetries)
Static factory method for
LdapService s configured with one set of credentials for
general operations, a separate set for group operations, and a third set for config
operations (e.g. |
static LdapService |
getInstanceGroup(String url,
String generalPrincipal,
String generalPassword,
String groupPrincipal,
String groupPassword)
Static factory method for
LdapService s configured with one set of credentials for
general operations and a separate set for group operations. |
static LdapService |
getInstanceGroupConfig(String url,
String generalPrincipal,
String generalPassword,
String groupPrincipal,
String groupPassword,
String configPrincipal,
String configPassword)
Static factory method for
LdapService s configured with one set of credentials for
general operations, a separate set for group operations, and a third set for config
operations (e.g. |
List<String> |
getListedPeople(boolean bathPeople,
boolean applicants,
boolean externalPeople,
boolean nonPeople)
Returns a list of all the person entries of the specified type(s) currently present in
ou=people in the LDAP. |
List<PersonRecord> |
getListedPersonRecords(boolean bathPeople,
boolean applicants,
boolean externalPeople,
boolean nonPeople)
Returns a list of
PersonRecord s for all the person entries of the specified type(s)
currently present in ou=people in the LDAP. |
int |
getMaxPageSize()
Gets the maximum page size that will be used for Virtual List View queries.
|
int |
getMaxRetries()
Gets the maximum number of retries that will be attempted for a given operation.
|
PersonRecord |
getPerson(String username)
Gets a PersonRecord (with nested RoleRecords as appropriate) from the LDAP.
|
String |
getPrincipal()
Gets the principal used for all actions unless
groupPrincipal is set. |
RoleRecord |
getRole(String id)
Gets a
RoleRecord from the LDAP. |
UnitRecord |
getUnit(String shortOu)
Gets a UnitRecord from the LDAP.
|
String |
getUrl() |
<T> List<T> |
search(String name,
String filter,
int scope,
ResultHandler<T> handler,
String[] attributes,
String[] sortOn)
Searches using the general credentials in the named context for entries that match the filter
and invokes the supplied
ResultHandler instance on each in turn - or on several at
once if it is a ParallelResultHandler instance. |
<T> List<T> |
search(String name,
String filter,
int scope,
ResultHandler<T> handler,
String[] attributes,
String[] sortOn,
boolean group)
Searches using the specified credentials in the named context for entries that match the
filter and invokes the supplied
ResultHandler instance on each in turn - or on
several at once if it is a ParallelResultHandler instance. |
<T> List<T> |
searchSmall(String name,
String filter,
int scope,
ResultHandler<T> handler,
String[] attributes)
Searches using the general credentials in the named context for entries that match the filter
and invokes the supplied
ResultHandler instance on each in turn - or on several at
once if it is a ParallelResultHandler instance. |
<T> List<T> |
searchSmall(String name,
String filter,
int scope,
ResultHandler<T> handler,
String[] attributes,
boolean group)
Searches using the specified credentials in the named context for entries that match the
filter and invokes the supplied
ResultHandler instance on each in turn - or on
several at once if it is a ParallelResultHandler instance. |
void |
setGroup(GroupRecord groupData,
boolean createOnly)
Sets the state of a group in the LDAP from a
GroupRecord . |
void |
setPerson(PersonRecord personData)
Sets the state of a person in the LDAP from a PersonRecord and any nested
RoleRecords.
|
void |
setUnit(UnitRecord unitData)
Sets the state of a unit in the LDAP from a
UnitRecord . |
static String |
toBetterString(Object o) |
public static LdapService getInstanceAnon(String url) throws NamingException
LdapService
s. A test connection is made.url
- the URL of the LDAP service to use, not including the directory root or slashLdapService
instance configured as specifiedNamingException
- if the the test connection failsNullPointerException
- if a null
URL is passedIllegalArgumentException
- if bad arguments are passedpublic static LdapService getInstance(String url, String principal, String password) throws NamingException
LdapService
s configured with one set of credentials to
use for all operations. A test connection is made.url
- the URL of the LDAP service to use, not including the directory root or slashprincipal
- the principal to bind withpassword
- the password to bind withLdapService
instance configured as specifiedNamingException
- if the the test connection failsNullPointerException
- if a null
URL is passedIllegalArgumentException
- if bad arguments are passedpublic static LdapService getInstanceGroup(String url, String generalPrincipal, String generalPassword, String groupPrincipal, String groupPassword) throws NamingException
LdapService
s configured with one set of credentials for
general operations and a separate set for group operations. Test connections are made.url
- the URL of the LDAP service to use, not including the directory root or slashgeneralPrincipal
- the general operation principal to bind withgeneralPassword
- the general operation password to bind withgroupPrincipal
- the group operation principal to bind withgroupPassword
- the group operation password to bind withLdapService
instance configured as specifiedNamingException
- if the the test connection failsNullPointerException
- if a null
URL is passedIllegalArgumentException
- if bad arguments are passedpublic static LdapService getInstanceGroupConfig(String url, String generalPrincipal, String generalPassword, String groupPrincipal, String groupPassword, String configPrincipal, String configPassword) throws NamingException
LdapService
s configured with one set of credentials for
general operations, a separate set for group operations, and a third set for config
operations (e.g. posixGroup
). Test connections are made.url
- the URL of the LDAP service to use, not including the directory root or slashgeneralPrincipal
- the general operation principal to bind withgeneralPassword
- the general operation password to bind withgroupPrincipal
- the group operation principal to bind withgroupPassword
- the group operation password to bind withconfigPrincipal
- the config operation principal to bind withconfigPassword
- the config operation password to bind withLdapService
instance configured as specifiedNamingException
- if the the test connection failsNullPointerException
- if a null
URL is passedIllegalArgumentException
- if bad arguments are passedpublic static LdapService getInstanceExplicitlyConfigured(String url, String generalPrincipal, String generalPassword, String groupPrincipal, String groupPassword, String configPrincipal, String configPassword, int maxPageSize, int maxRetries) throws NamingException
LdapService
s configured with one set of credentials for
general operations, a separate set for group operations, and a third set for config
operations (e.g. posixGroup
), and allowing the maximum page size and the number of
retries to be set. Test connections are made.url
- the URL of the LDAP service to use, not including the directory root or slashgeneralPrincipal
- the general operation principal to bind withgeneralPassword
- the general operation password to bind withgroupPrincipal
- the group operation principal to bind withgroupPassword
- the group operation password to bind withconfigPrincipal
- the config operation principal to bind withconfigPassword
- the config operation password to bind withmaxPageSize
- the maximum page size to use for paged queriesmaxRetries
- the number of times to retry in case of connection errorsLdapService
instance configured as specifiedNamingException
- if the the test connection failsNullPointerException
- if a null
URL is passedIllegalArgumentException
- if bad arguments are passedpublic String getUrl()
public String getPrincipal()
groupPrincipal
is set.null
public String getGroupPrincipal()
null
public int getMaxPageSize()
public int getMaxRetries()
public PersonRecord getPerson(String username) throws NamingException, LdapDataException
username
- The uid of the record to getNamingException
- if an LDAP-related error occursLdapDataException
- if invalid data is found in the LDAPpublic RoleRecord getRole(String id) throws NamingException, LdapDataException
RoleRecord
from the LDAP.id
- the ID of the role to getRoleRecord
containing the data, or null if not foundNamingException
- if an LDAP error occursLdapDataException
- if invalid data is found in the LDAPpublic UnitRecord getUnit(String shortOu) throws NamingException, LdapDataException
shortOu
- The shortou
of the unit to getNamingException
- if an LDAP error occursLdapDataException
- if invalid data is found in the LDAPpublic GroupRecord getGroup(String cn) throws NamingException, LdapDataException
GroupRecord
from within the ou=groups
or
ou=unixgroups,ou=config
branches of the LDAP.
membershipHidden = TRUE
and the configured user doesn't have permission to
read the membership of the group then no members will be returned.cn
- the cn
of the group to getGroupRecord
containing the data, or null
if not foundNamingException
- if an LDAP error occursLdapDataException
- if invalid data is found in the LDAP, including multiple matching
groups being foundpublic GroupRecord getGroup(String cn, String searchBase) throws NamingException, LdapDataException
GroupRecord
from within the specified search base of the LDAP.
membershipHidden = TRUE
and the configured user doesn't have permission to
read the membership of the group then no members will be returned.cn
- the cn
of the group to getsearchBase
- the search base to use, relative to o=bath.ac.uk
GroupRecord
containing the data, or null
if not foundNamingException
- if an LDAP error occursLdapDataException
- if invalid data is found in the LDAP, including multiple matching
groups being foundpublic List<GroupRecord> getGroupsForUser(String username, boolean includeMembers) throws NamingException, LdapDataException
GroupRecord
s from the LDAP for all groups containing the specified user.
membershipHidden = TRUE
will only be returned if the configured
user has permission to read the membership.username
- the username of to search onincludeMembers
- true
to include group membersList
of GroupRecord
objects sorted by DNNamingException
- if an LDAP error occursLdapDataException
- if invalid data is found in the LDAPpublic void setPerson(PersonRecord personData) throws NamingException
personData
- The PersonRecord containing the data to setNamingException
- if an LDAP error occursIllegalArgumentException
- if there are problems with the supplied PersonRecord
public void setUnit(UnitRecord unitData) throws NamingException
UnitRecord
. The record will be created
if it doesn't exist.unitData
- The UnitRecord
containing the data to setNamingException
- if an LDAP error occursIllegalArgumentException
- if there are problems with the supplied UnitRecord
public void setGroup(GroupRecord groupData, boolean createOnly) throws NamingException, LdapDataException
GroupRecord
. The record will be created
if it doesn't exist. If it does exist, only those attributes defined by GroupRecord
and relevant to the type of group being updated will be affected - with the exception of
membershipHidden
which will not be touched and the members which will only be updated
if membersOmitted
is not set. This method will only permit groups to be set in
ou=groups,o=bath.ac.uk
(for regular groups) or
ou=unixgroups,ou=config,o=bath.ac.uk
(for POSIX
groups), not in sub-ous or
elsewhere in the directory. If the distinguishedName
is absent then it will be
generated from the cn
in the appropriate location, and the supplied object updated.groupData
- the GroupRecord
containing the data to setcreateOnly
- pass true
to prevent updates to existing groupsNamingException
- if an LDAP error occursLdapDataException
- if the group is not located in the permitted place, the cn is not
unique, there are already multiple groups with this cn on the LDAP server, or the group
already exists and createOnly
is true
IllegalArgumentException
- if there are problems with the supplied GroupRecord
public <T> List<T> search(String name, String filter, int scope, ResultHandler<T> handler, String[] attributes, String[] sortOn) throws NamingException, ResultHandlerException
ResultHandler
instance on each in turn - or on several at
once if it is a ParallelResultHandler
instance. A List
is made of the objects
returned by the handler, if any. No guarantee is made as to the ordering of the results; the
sortOn
parameter is only used in some circumstances.T
- the type of the result object that will be returned by the ResultHandler
name
- the name of the context to searchfilter
- the search filter to usescope
- the search scope to use, as defined by SearchControls
handler
- the ResultHandler
instance to use to handle each resultattributes
- an array of names of attributes to return, or null
to return allsortOn
- an array of attributes to be used to sort pages of the underlying LDAP searchList
of objects returned by the handler (which may be empty - never null)NamingException
- in case of LDAP errorResultHandlerException
- if thrown by the supplied ResultHandler
instanceConcurrentModificationException
- if VirtualListViewControl
omits entries,
most likely due to concurrent modification of the LDAP, even after retriespublic <T> List<T> search(String name, String filter, int scope, ResultHandler<T> handler, String[] attributes, String[] sortOn, boolean group) throws NamingException, ResultHandlerException
ResultHandler
instance on each in turn - or on
several at once if it is a ParallelResultHandler
instance. A List
is made of
the objects returned by the handler, if any. No guarantee is made as to the ordering of the
results; the sortOn
parameter is only used in some circumstances.T
- the type of the result object that will be returned by the ResultHandler
name
- the name of the context to searchfilter
- the search filter to usescope
- the search scope to use, as defined by SearchControls
handler
- the ResultHandler
instance to use to handle each resultattributes
- an array of names of attributes to return, or null
to return allsortOn
- an array of attributes to be used to sort pages of the underlying LDAP searchgroup
- true
to use the group credentials instead of the general onesList
of objects returned by the handler (which may be empty - never null)NamingException
- in case of LDAP errorResultHandlerException
- if thrown by the supplied ResultHandler
instanceConcurrentModificationException
- if VirtualListViewControl
omits entries,
most likely due to concurrent modification of the LDAP, even after retriespublic <T> List<T> searchSmall(String name, String filter, int scope, ResultHandler<T> handler, String[] attributes) throws NamingException, ResultHandlerException, SizeLimitExceededException
ResultHandler
instance on each in turn - or on several at
once if it is a ParallelResultHandler
instance. No provision for paging through large
result sets is made, which results in significant performance advantages over search(java.lang.String, java.lang.String, int, uk.ac.bath.bucs.idm.ldap.ResultHandler<T>, java.lang.String[], java.lang.String[])
for small searches. If the server result limit is exceeded then a
SizeLimitExceededException
is thrown. A List is made of the objects returned by the
handler, if any. No guarantee is made as to the ordering of the results.T
- the type of the result object that will be returned by the ResultHandler
name
- the name of the context to searchfilter
- the search filter to usescope
- the search scope to use, as defined by SearchControls
handler
- the ResultHandler
instance to use to handle each resultattributes
- an array of names of attributes to return, or null
to return allList
of objects returned by the handler (which may be empty - never null)NamingException
- in case of LDAP errorResultHandlerException
- if thrown by the supplied ResultHandler
instanceSizeLimitExceededException
- if the result set isn't small after allpublic <T> List<T> searchSmall(String name, String filter, int scope, ResultHandler<T> handler, String[] attributes, boolean group) throws NamingException, ResultHandlerException, SizeLimitExceededException
ResultHandler
instance on each in turn - or on
several at once if it is a ParallelResultHandler
instance. No provision for paging
through large result sets is made, which results in significant performance advantages over
search(java.lang.String, java.lang.String, int, uk.ac.bath.bucs.idm.ldap.ResultHandler<T>, java.lang.String[], java.lang.String[])
for small searches. If the server result limit is exceeded then a
SizeLimitExceededException
is thrown. A List is made of the objects returned by the
handler, if any. No guarantee is made as to the ordering of the results.T
- the type of the result object that will be returned by the ResultHandler
name
- the name of the context to searchfilter
- the search filter to usescope
- the search scope to use, as defined by SearchControls
handler
- the ResultHandler
instance to use to handle each resultattributes
- an array of names of attributes to return, or null
to return allgroup
- true
to use the group credentials instead of the general onesList
of objects returned by the handler (which may be empty - never null)NamingException
- in case of LDAP errorResultHandlerException
- if thrown by the supplied ResultHandler
instanceSizeLimitExceededException
- if the result set isn't small after allpublic List<String> getListedPeople(boolean bathPeople, boolean applicants, boolean externalPeople, boolean nonPeople) throws NamingException
ou=people
in the LDAP.bathPeople
- true
to return all people in BathPersonapplicants
- true
to return all people in BathApplicantexternalPeople
- true
to return all people in BathExternalPersonnonPeople
- true
to return all people in BathNonPersonAccountList
of usernames (which may be empty - will never return null)NamingException
- in case of LDAP errorIllegalArgumentException
- if called with all arguments false
ConcurrentModificationException
- if VirtualListViewControl
omits entries,
most likely due to concurrent modification of the LDAP, even after retriespublic List<PersonRecord> getListedPersonRecords(boolean bathPeople, boolean applicants, boolean externalPeople, boolean nonPeople) throws NamingException, LdapDataException
PersonRecord
s for all the person entries of the specified type(s)
currently present in ou=people
in the LDAP.bathPeople
- true
to return all people in BathPersonapplicants
- true
to return all people in BathApplicantexternalPeople
- true
to return all people in BathExternalPersonnonPeople
- true
to return all people in BathNonPersonAccountList
of PersonRecord
s (which may be empty - will never return null)NamingException
- in case of LDAP errorLdapDataException
- if invalid data is found in the LDAPIllegalArgumentException
- if called with all arguments false
ConcurrentModificationException
- if VirtualListViewControl
omits entries,
most likely due to concurrent modification of the LDAP, even after retriespublic void deleteEntry(String dn) throws NamingException
dn
- the DN of the object to delete, relative to the configured directory rootNamingException
public InitialLdapContext connect() throws NamingException
InitialLdapContext
representing the connectionNamingException
- in case of failurepublic InitialLdapContext connectGroup() throws NamingException
InitialLdapContext
representing the connectionNamingException
- in case of failurepublic InitialLdapContext connect(LdapService.ConnectionType type) throws NamingException
type
- the set of credentials to useInitialLdapContext
representing the connectionNamingException
- in case of failure@PreDestroy public void close() throws NamingException
close
in interface AutoCloseable
NamingException
- if the instance cannot be closedCopyright © 2018. All rights reserved.