com.webmethods.sc.directory

Interface IDirectorySession

All Superinterfaces:

AutoCloseable

public interface IDirectorySession
extends AutoCloseable

Main interface to interact with shared directory management component

Field Summary

Fields

Modifier and Type	Field and Description
static String	CURRENT_USER Identifies currently logged in user to be used in the lookupPrincipalByID(String) method.

Method Summary

Modifier and Type	Method and Description
void	addPrincipalToGroup(String principalID, String groupID) Adds a principal to a group.
void	addPrincipalToRole(String principalID, String roleID) Adds a principal to a role.
IDirectoryUser	authenticateUser(String username, String password) Attempts to authenticate the user based on the credentials with any registered directory service in their configured search order.
default void	beginConversation() Mark the current transient conversation long-running.
void	close() Release any resources
IDirectoryPagingCookie	createPagingCookie(String directoryServiceID) Creates instance of directory paging cookie to be used for searchDirectory(String, int, DirectorySearchQuery, IDirectoryPagingCookie) method.
IDirectoryPrincipal	createPrincipal(String directoryServiceID, int principalType, String name, Map properties) Creates a new principal group or user associated with this specified directory service.
IDirectoryRole	createRole(int roleType, String name, Map<String,?> properties) Deprecated. Use createRole(String, String, Map) instead
IDirectoryRole	createRole(String roleType, String name, Map<String,?> properties) Creates new role of the specified type
void	deletePrincipal(String principalID) Deletes a principal by its unique ID
void	destroyPagingCookie(IDirectoryPagingCookie directoryPagingCookie) Destroys directory paging cookie and frees up any associated resources
default void	endConversation() Mark the current long-running conversation transient.
Map<String,Object>	getAttributeExtendedInfo(String principalID, String principalAttributeProviderID, String attributeName) Returns extended information about attributes of the given provider (only if provider supports this
List<String>	getAttributeNames(String principalID, String principalAttributeProviderID) List defined attribute names for the specified attribute provider
IDirectoryPrincipalAttributeProvider	getAttributeProvider(String attributeProviderID) Gets IDirectoryPrincipalAttributeProvider by its ID
List<String>	getAttributeTitles(String principalID, String principalAttributeProviderID, Locale locale) List defined user friendly attribute titles for the specified attribute provider
ICertificateManager	getCertificateManager() Returns instance of certificate manager
IDirectoryService	getDirectoryService(String directoryServiceID) Returns instance of IDirectoryService by its ID.
List<IDirectoryGroup>	getGroupMembership(String principalID) Retrieve the group membership for this principal
List<IDirectoryPrincipal>	getMembers(String principalID) Returns members of the group or role.
List<IDirectoryRole>	getRoleMembership(String principalID) Retrieve the role membership for this principal
default boolean	isConversation() Returns if the conversation is marked transient or long-running
List<IDirectoryPrincipalAttributeProvider>	listAttributeProviders(int principalType) Gets all registered principal attribute providers IDirectoryPrincipalAttributeProvider
List<IDirectoryService>	listDirectoryServices() Retrieves the list of all registeredIDirectoryServices in the search order as defined in MWS directory services administration
List<IDirectoryRole>	listRoles() Lists all roles defined in the system
IDirectoryPrincipal	lookupPrincipalByAlias(String principalAlias) Attempts to lookup a principal by well known alias
IDirectoryPrincipal	lookupPrincipalByDN(String principalDN, int type) Attempts to lookup a principal by their dn.
IDirectoryPrincipal	lookupPrincipalByID(String principalID) Attempts to lookup a principal by their unique ID.
IDirectoryPrincipal	lookupPrincipalByName(String principalName, int type) Attempts to lookup a principal by their name.
void	modifyPrincipal(String principalID, Map attributes) Sets attribute values for the principal.
void	removePrincipalFromGroup(String principalID, String groupID) Removes a principal from a group.
void	removePrincipalFromRole(String principalID, String roleID) Removes a principal from a role.
List<IDirectoryPrincipal>	searchDirectory(String directoryServiceID, int principalType, DirectorySearchQuery query, IDirectoryPagingCookie directoryPagingCookie) Search principals in the given directory service.

Field Detail

CURRENT_USER

static final String CURRENT_USER

Identifies currently logged in user to be used in the lookupPrincipalByID(String) method. Currently logged it user is only valid inside My webMethods Server

See Also:

Constant Field Values

Method Detail

listDirectoryServices

List<IDirectoryService> listDirectoryServices()
                                       throws DirectoryException

Retrieves the list of all registeredIDirectoryServices in the search order as defined in MWS directory services administration

Returns:

Throws:

DirectoryException

getDirectoryService

IDirectoryService getDirectoryService(String directoryServiceID)
                               throws DirectoryException

Returns instance of IDirectoryService by its ID.

Parameters:

directoryServiceID -

Returns:

Throws:

DirectoryException - if directory service ID is invalid

lookupPrincipalByName

IDirectoryPrincipal lookupPrincipalByName(String principalName,
                                          int type)
                                   throws DirectoryException

Attempts to lookup a principal by their name. Delegates to all the directory services in their configured search order if type is IDirectoryPrincipal.TYPE_GROUP or IDirectoryPrincipal.TYPE_USER Lookup a role by its name if type is IDirectoryPrincipal.TYPE_ROLE

Parameters:

principalName -

type - principal type one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP IDirectoryPrincipal.TYPE_ROLE

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

lookupPrincipalByDN

IDirectoryPrincipal lookupPrincipalByDN(String principalDN,
                                        int type)
                                 throws DirectoryException

Attempts to lookup a principal by their dn. Delegates to all the directory services in their configured search order if type is IDirectoryPrincipal.TYPE_GROUP or IDirectoryPrincipal.TYPE_USER Lookup a role by its DN if type is IDirectoryPrincipal.TYPE_ROLE

Parameters:

principalDN -

type - principal type one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP IDirectoryPrincipal.TYPE_ROLE

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

lookupPrincipalByID

IDirectoryPrincipal lookupPrincipalByID(String principalID)
                                 throws DirectoryException

Attempts to lookup a principal by their unique ID.

Parameters:

principalID - unique principal ID

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

lookupPrincipalByAlias

IDirectoryPrincipal lookupPrincipalByAlias(String principalAlias)
                                    throws DirectoryException

Attempts to lookup a principal by well known alias

Parameters:

principalAlias - MWS defined principal alias

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

createPagingCookie

IDirectoryPagingCookie createPagingCookie(String directoryServiceID)
                                   throws DirectoryException

Creates instance of directory paging cookie to be used for searchDirectory(String, int, DirectorySearchQuery, IDirectoryPagingCookie) method. Each session may maintain only a single cookie at a time, this method will destroy any previously created cookie

Returns:

Throws:

DirectoryException

destroyPagingCookie

void destroyPagingCookie(IDirectoryPagingCookie directoryPagingCookie)

Destroys directory paging cookie and frees up any associated resources

Parameters:

directoryPagingCookie -

searchDirectory

List<IDirectoryPrincipal> searchDirectory(String directoryServiceID,
                                          int principalType,
                                          DirectorySearchQuery query,
                                          IDirectoryPagingCookie directoryPagingCookie)
                                   throws DirectoryException

Search principals in the given directory service. This API works only for users and groups, but not for roles. To list all roles use listRoles() API instead

Parameters:

directoryServiceID - ID of the directory service to search.

principalType - principal type one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP

query - directory query. If null all principals will be returned

directoryPagingCookie - directory paging cookie used for paging/sorting of directory search results.

Returns:

list of found principals. May return empty list

Throws:

DirectoryException

listRoles

List<IDirectoryRole> listRoles()
                        throws DirectoryException

Lists all roles defined in the system

Returns:

list of roles. May return empty list.

Throws:

DirectoryException

authenticateUser

IDirectoryUser authenticateUser(String username,
                                String password)
                         throws DirectoryException

Attempts to authenticate the user based on the credentials with any registered directory service in their configured search order.

Parameters:

username -

password -

Returns:

valid authenticated user

Throws:

DirectoryException - if there was a problem authenticating this user

listAttributeProviders

List<IDirectoryPrincipalAttributeProvider> listAttributeProviders(int principalType)
                                                           throws DirectoryException

Gets all registered principal attribute providers IDirectoryPrincipalAttributeProvider

Parameters:

principalType - one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP IDirectoryPrincipal.TYPE_ROLE

Returns:

list of principal attribute providers for specified principal type

Throws:

DirectoryException

getAttributeProvider

IDirectoryPrincipalAttributeProvider getAttributeProvider(String attributeProviderID)
                                                   throws DirectoryException

Gets IDirectoryPrincipalAttributeProvider by its ID

Throws:

DirectoryException

getAttributeNames

List<String> getAttributeNames(String principalID,
                               String principalAttributeProviderID)
                        throws DirectoryException

List defined attribute names for the specified attribute provider

Parameters:

principalID - ID of the principal

principalAttributeProviderID - ID of the principal attribute provider

Returns:

list of attribute names defined for specified attribute provider

Throws:

DirectoryException

getAttributeTitles

List<String> getAttributeTitles(String principalID,
                                String principalAttributeProviderID,
                                Locale locale)
                         throws DirectoryException

List defined user friendly attribute titles for the specified attribute provider

Parameters:

principalID - ID of the principal

principalAttributeProviderID - ID of the principal attribute provider

locale - desired locale for attribute titles

Returns:

list of attribute titles for the specified attribute provider

Throws:

DirectoryException

getAttributeExtendedInfo

Map<String,Object> getAttributeExtendedInfo(String principalID,
                                            String principalAttributeProviderID,
                                            String attributeName)
                                     throws DirectoryException

Returns extended information about attributes of the given provider (only if provider supports this

Parameters:

principalID - ID of the principal

principalAttributeProviderID - ID of the principal attribute provider

attributeName - attribute name

Returns:

Map containing extended information about this attribute

Throws:

DirectoryException

createPrincipal

IDirectoryPrincipal createPrincipal(String directoryServiceID,
                                    int principalType,
                                    String name,
                                    Map properties)
                             throws DirectoryException

Creates a new principal group or user associated with this specified directory service. It may throw exception if directory service does not support creation of principals. Not accounting for custom implementations only MWS System Directory supports creation of principals

Parameters:

directoryServiceID - ID of the directory service to create principal ID.

type - of the principal to create one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP

name - of the principal (UID)

properties - name-value pairs

Returns:

a newly created IDirectoryPrincipal

Throws:

DirectoryException

createRole

@Deprecated
IDirectoryRole createRole(int roleType,
                                      String name,
                                      Map<String,?> properties)
                               throws DirectoryException

Deprecated. Use createRole(String, String, Map) instead

Creates new role of the specified type

Parameters:

roleType - type of the role to create IDirectoryRole

name - of the role (UID)

properties - name-value pairs of properties assigned to the new role

Returns:

a newly created IDirectoryRole

Throws:

DirectoryException

createRole

IDirectoryRole createRole(String roleType,
                          String name,
                          Map<String,?> properties)
                   throws DirectoryException

Creates new role of the specified type

Parameters:

roleType - type of the role to create IDirectoryRole

nameof - the role (UID)

properties - name-value pairs of properties assigned to the new role

Returns:

a newly created IDirectoryRole

Throws:

DirectoryException

deletePrincipal

void deletePrincipal(String principalID)
              throws DirectoryException

Deletes a principal by its unique ID

Parameters:

principalID -

Throws:

DirectoryException

addPrincipalToGroup

void addPrincipalToGroup(String principalID,
                         String groupID)
                  throws DirectoryException

Adds a principal to a group. Note, both the principal and the group must belong to the same IDirectoryService

Parameters:

principalID - ID of the principal to be added to the group

groupID - ID of the group to add principal to

Throws:

DirectoryException

addPrincipalToRole

void addPrincipalToRole(String principalID,
                        String roleID)
                 throws DirectoryException

Adds a principal to a role. Not all role type support modification of membership. Not accounting for custom implementations only static IDirectoryRole.ROLE_TYPE_STATIC role supports this operation

Parameters:

principalID - ID of the principal to be added to the role

roleID - ID of the role to add principal to

Throws:

DirectoryException

removePrincipalFromGroup

void removePrincipalFromGroup(String principalID,
                              String groupID)
                       throws DirectoryException

Removes a principal from a group. Note, both the principal and the group must belong to the same IDirectoryService

Parameters:

principalID - ID of the principal to be removed from the group

groupID - ID of the group to remove principal from

Throws:

DirectoryException

removePrincipalFromRole

void removePrincipalFromRole(String principalID,
                             String roleID)
                      throws DirectoryException

Removes a principal from a role. Not all role type support modification of membership. Not accounting for custom implementations only static IDirectoryRole.ROLE_TYPE_STATIC role supports this operation

Parameters:

principalID - ID of the principal to be removed from the role

roleID - ID of the role to remove principal from

Throws:

DirectoryException

getGroupMembership

List<IDirectoryGroup> getGroupMembership(String principalID)
                                  throws DirectoryException

Retrieve the group membership for this principal

Parameters:

principalID - ID of the principal to get group membership for

Returns:

list of IDirectoryGroup principal is member of

Throws:

DirectoryException

getRoleMembership

List<IDirectoryRole> getRoleMembership(String principalID)
                                throws DirectoryException

Retrieve the role membership for this principal

Parameters:

principalID - IF of the principal to get role membership for

Returns:

list of IDirectoryRole principal is member of

Throws:

DirectoryException

getMembers

List<IDirectoryPrincipal> getMembers(String principalID)
                              throws DirectoryException

Returns members of the group or role. Not all roles types support querying for its members. Not accounting for custom implementations only static IDirectoryRole.ROLE_TYPE_STATIC role supports this operation

Parameters:

principalID - role or group ID

Returns:

a list of members of this role or group

Throws:

DirectoryException

modifyPrincipal

void modifyPrincipal(String principalID,
                     Map attributes)
              throws DirectoryException

Sets attribute values for the principal. Attributes map passed in may contain attributes from different principal attribute providers.

Parameters:

principalID - ID of the principal to be updated

attributes - attribute values to be set

Throws:

DirectoryException

getCertificateManager

ICertificateManager getCertificateManager()

Returns instance of certificate manager

close

void close()

Release any resources

Specified by:

close in interface AutoCloseable

beginConversation

default void beginConversation()

Mark the current transient conversation long-running. Starting with the next exchanged message, all further communication will be handled by the same cluster node until the #end() is invoked.

endConversation

default void endConversation()

Mark the current long-running conversation transient. The next exchanged message will not be sent to a specific cluster node rather the next available one

isConversation

default boolean isConversation()

Returns if the conversation is marked transient or long-running

Returns:

true if a converation is in progress, false otherwise