com.hyperion.css
Interface CSSProviderIF

All Superinterfaces:

com.hyperion.css.common.internal.CSSFrameworkIF

public interface CSSProviderIF

extends com.hyperion.css.common.internal.CSSFrameworkIF

This is the interface to be implemented by the providers. An implementation of this interface is known as a provider The Framework can get a handle to a provider through the CSSProviderFactoryIF.getProvider(Map).

Note that the provider methods can be accessed concurrently by multiple threads, therefore it is the responsibility of the provider implementer to make the implementation thread safe.

Since:

CSSv2.0

Author:

gkhanna

Method Summary

CSSUserIF	authenticate(java.util.Map context) The user is authenticated by the security platform.
java.util.ArrayList	getChildrenForGroup(java.util.Map context, com.hyperion.css.common.CSSNodeImpl groupNode) For Internal Use Only.
CSSGroupIF[]	getDelegatedGroups(java.util.Map context, CSSPrincipalIF principal, CSSDelegatedListIF[] delegatedList, GroupSearchFilter groupSrchFilter) Returns all the groups that are present in the delegated list and the child groups recursively matching the group name filter specified.
CSSGroupIF[]	getDelegatedGroups(java.util.Map context, CSSPrincipalIF principal, CSSDelegatedListIF[] delegatedList, java.lang.String groupNameFilter) Returns all the groups that are present in the delegated list and the child groups recursively matching the group name filter specified.
CSSUserIF[]	getDelegatedUsers(java.util.Map context, CSSPrincipalIF principal, CSSDelegatedListIF[] delegatedList, java.lang.String userNameFilter) Returns all the users that are present in the delegated list and the users in the groups recursively matching the user name filter specified..
CSSUserIF[]	getDelegatedUsers(java.util.Map context, CSSPrincipalIF principal, CSSDelegatedListIF[] delegatedList, UserSearchFilter userSrchFilter) Returns all the users that are present in the delegated list and the users in the groups recursively matching the user name filter specified.
CSSGroupIF	getGroupByIdentity(java.util.Map context, java.lang.String identity) Get a group based on the identity of the group.
CSSGroupIF[]	getGroups(java.util.Map context, CSSPrincipalIF principal, GroupSearchFilter groupSrchFilter) Get a group specified by group search filter passed in The group search filter contains group filter attributes and values like, GROUPNAME, DESCRIPTION.
CSSGroupIF[]	getGroups(java.util.Map context, java.lang.String name) Get a group based on the name .
java.util.ArrayList	getGroupsByIdentities(java.util.Map context, java.lang.String[] ids, java.util.List failedList) For Internal Use only
java.util.ArrayList	getGroupTree(java.util.Map context, java.lang.String identity, boolean indirect) For Internal Use Only.
java.lang.String	getName() Returns the name of the implementing provider with which it is configured.
CSSUserIF	getUserByEmail(java.util.Map context, java.lang.String email) Get a user based on an email match.
CSSUserIF	getUserByIdentity(java.util.Map context, java.lang.String identity) Get a user based on the identity of the user.
java.util.Map	getUserMembersForGroups(java.util.Map context, java.util.Set groupIdentities) Returns a Map containing group id as key and set of user objects as values.
java.util.Set	getUserObjFromGroups(java.util.Map context, java.util.Set identities) Returns set of CSSUserIF objects for the given group identities.
CSSUserIF[]	getUsers(java.util.Map context, CSSPrincipalIF principal, UserSearchFilter userSrchFilter) Gets the user specified by user search filter passed in The user search filter contains user filter attributes and values like, USERNAME,FIRSTNAME,LASTNAME,EMAIL,DESCRIPTION (Also ACTIVE, INACTIVE and ALL for native) Etc.
CSSUserIF[]	getUsers(java.util.Map context, java.lang.String userName) Gets the user specified by userName The userName could be mapped to a particular attribute in a directory through the Configuration.
CSSUserIF[]	getUsers(java.util.Map context, java.lang.String userName, java.lang.String firstName, java.lang.String lastName) Get a user based on a user name , firstName and lastName match.
java.util.ArrayList	getUsersByIdentities(java.util.Map context, java.lang.String[] array) Returns List of CSSUserIF objects for given user identities.
CSSUserIF[]	getUsersByName(java.util.Map context, java.lang.String firstName, java.lang.String lastName) Get a user based on a firstName and lastName match.
boolean	isAvailable(java.util.Map context) Returns true if provider is communicable.
java.util.ArrayList	searchIdentities(java.util.Map context, java.lang.String identity) For Internal Use Only.
void	setEnvironment(java.util.Map env) Sets the environment for the provider.

Method Detail

authenticate

public CSSUserIF authenticate(java.util.Map context)
                       throws CSSAuthenticationException,
                              CSSCommunicationException,
                              CSSException

The user is authenticated by the security platform. It is the security platform's responsibility to create and set the token. The provider returns an instance of CSSUserIF with the token unset.

The context can specify the following:

1. login name
2. password
3. locale

These properties are discussed in the field description for CSSAPIIF. The token is never passed to the provider.

The \domainName\entryName syntax is also supported for the benefit of applications using NTLM as the authentication protocol.

Specified by:

authenticate in interface com.hyperion.css.common.internal.CSSFrameworkIF

Parameters:

context - the various parameters are specified here.

Returns:

CSSUserIF - null if there is no match

Throws:

CSSAuthenticationException - - if the user name exists but the password does not match.

CSSException - - Any other abnormality. Do not throw if the provider can make a recovery or is improperly configured.

CSSCommunicationException - - The provider could not connect to the directory.

See Also:

CSSUserIF

getUsers

public CSSUserIF[] getUsers(java.util.Map context,
                            java.lang.String userName)
                     throws CSSCommunicationException,
                            CSSException

Gets the user specified by userName The userName could be mapped to a particular attribute in a directory through the Configuration. The search for users based on *userName* should be based on getting all users who have userName as a part of the value of the attribute specified.

The userName could contain a wildcard such as "*". This implies that all the users in the directory need to be returned.

The context can specify the following:

1. locale
2. CSSAPIIF.ENTITY_DEACTIVATE- if specified, then the deactivated users will be returned.

These properties are discussed in the field description for CSSAPIIF.

Specified by:

getUsers in interface com.hyperion.css.common.internal.CSSFrameworkIF

Parameters:

context - Map structure holding key-value information about locale.

userName - String argument representing the user login name.

Returns:

CSSUserIF[] - Returns null if there is no match

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSException - - Any other abnormality.

getUsers

public CSSUserIF[] getUsers(java.util.Map context,
                            CSSPrincipalIF principal,
                            UserSearchFilter userSrchFilter)
                     throws CSSCommunicationException,
                            CSSException

Gets the user specified by user search filter passed in The user search filter contains user filter attributes and values like, USERNAME,FIRSTNAME,LASTNAME,EMAIL,DESCRIPTION (Also ACTIVE, INACTIVE and ALL for native) Etc. This supports wild card search. Eg. The search for users based on *userName* should return all users matching this pattern.

when the attribute value is specified as "*" This implies that all the users in the directory need to be returned.The query can be based on any one of the above attributes. For native if the filter attribute can be set to ACTIVE, INACTIVE or ALL to return active, inactive and all users respectively.There may be a performence hit for NTLM because in case no group is passed as search criteria for NTLM and search is made on FIRSTNAME or LASTNAME. In this case first all the users are obtained and then they are filtered out based on FIRSTNAME or LASTNAME Etc.

Parameters:

context - - Map structure holding key-value information about locale and other parameters.

principal - - identity of the caller. Can not be null.

userSrchFilter - - contains the search filter attributes and values.

Returns:

CSSUserIF[] - Returns null if there is no match. Returns null incase userSrchFilter is null.

Throws:

CSSCommunicationException - - The provider could not connect to the directory server.

CSSException - - Any other abnormality.

getUserByEmail

public CSSUserIF getUserByEmail(java.util.Map context,
                                java.lang.String email)
                         throws CSSCommunicationException,
                                CSSOperationNotSupportedException,
                                CSSException

Get a user based on an email match. The email could be mapped to a particular attribute in a directory through the Configuration. The search for users based on email should be absolute.

The context can specify the following:

1. locale

These properties are discussed in the field description for CSSAPIIF.

Specified by:

getUserByEmail in interface com.hyperion.css.common.internal.CSSFrameworkIF

Parameters:

context - Map structure holding key-value information about locale.

email - The complete e-mail address string for the user.

Returns:

CSSUserIF - null if there is no match

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSOperationNotSupportedException - - this is thrown if the provider does not support this operation.

CSSException - - Any other abnormality.

getUsersByName

public CSSUserIF[] getUsersByName(java.util.Map context,
                                  java.lang.String firstName,
                                  java.lang.String lastName)
                           throws CSSCommunicationException,
                                  CSSOperationNotSupportedException,
                                  CSSException

Get a user based on a firstName and lastName match. The firstName and lastName could be mapped to a particular set of attributes in a directory through the Configuration. If there are two attributes, one each for firstName and lastName, then the search is absolute and an AND is performed.

If one of the parameters is not specified then results for the other are returned.

The context can specify the following:

1. locale

These properties are discussed in the field description for CSSAPIIF.

Specified by:

getUsersByName in interface com.hyperion.css.common.internal.CSSFrameworkIF

Parameters:

context - Map structure holding key-value information about locale.

firstName - The user's first name, with appended middle name if one exists.

lastName - The user's last name.

Returns:

CSSUserIF[] - null if there is no match

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSOperationNotSupportedException - - This is thrown if the provider does not support this operation.

CSSException - - Any other abnormality.

getUsers

public CSSUserIF[] getUsers(java.util.Map context,
                            java.lang.String userName,
                            java.lang.String firstName,
                            java.lang.String lastName)
                     throws CSSCommunicationException,
                            CSSException

Get a user based on a user name , firstName and lastName match. All the atttributes are absolute and required. The way this is evaluated is as follows:

 (&(userName="gkhanna")(firstName="Gaurav")(lastName="khanna") )
 

The context can specify the following:

1. locale

These properties are discussed in the field description for CSSAPIIF.

Specified by:

getUsers in interface com.hyperion.css.common.internal.CSSFrameworkIF

Parameters:

context - Map structure holding key-value information about locale.

userName - String argument representing the user login name.

firstName - The user's first name, with appended middle name if one exists.

lastName - The user's last name.

Returns:

CSSUserIF[] - null if there is no match

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSException - - Any other abnormality.

See Also:

getUsersByName(Map, String, String), getUsers(Map, String)

getUserByIdentity

public CSSUserIF getUserByIdentity(java.util.Map context,
                                   java.lang.String identity)
                            throws CSSCommunicationException,
                                   CSSException

Get a user based on the identity of the user. The identity is stored by the application and is generated by the security platform.

The context can specify the following:

1. locale

These properties are discussed in the field description for CSSAPIIF.

Specified by:

getUserByIdentity in interface com.hyperion.css.common.internal.CSSFrameworkIF

Parameters:

context - Map structure holding key-value information about locale.

identity - String returned from the user object that uniquely identifies one user on a provider.

Returns:

CSSUserIF

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSException - - Any other abnormality.

getGroups

public CSSGroupIF[] getGroups(java.util.Map context,
                              java.lang.String name)
                       throws CSSCommunicationException,
                              CSSException

Get a group based on the name . The name could be mapped to a particular attribute in a directory through the Configuration. The search for groups based on *name* should be based on getting all groups who have name as a part of the value of the attribute specified.

if name is null then it gets the "domain/s" or the groups.

The name could contain a wildcard such as "*". This implies that all the groups in the directory need to be returned.

The context can specify the following:

1. locale

These properties are discussed in the field description for CSSAPIIF.

Specified by:

getGroups in interface com.hyperion.css.common.internal.CSSFrameworkIF

Parameters:

context - Map structure holding key-value information about locale.

name - Name of the group.

Returns:

CSSGroupIF[] - empty if there is no match

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSException - - Any other abnormality.

getGroups

public CSSGroupIF[] getGroups(java.util.Map context,
                              CSSPrincipalIF principal,
                              GroupSearchFilter groupSrchFilter)
                       throws CSSCommunicationException,
                              CSSException

Get a group specified by group search filter passed in The group search filter contains group filter attributes and values like, GROUPNAME, DESCRIPTION. The name could be mapped to a particular attribute in a directory through the Configuration. The search for groups based on *name* should be based on getting all groups who have name as a part of the value of the attribute specified.

The attribute could contain a wildcard such as "*". This implies that all the groups in the directory need to be returned.The query can be based on any one of the above attributes.

Parameters:

context - Map structure holding key-value information about locale.

principal - - identity of the caller. Can not be null.

groupSrchFilter - - contains the group filter attributes and values.

Returns:

CSSGroupIF[] - empty if there is no match.Returns null incase groupSrchFilter is null.

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSException - - Any other abnormality.

getGroupByIdentity

public CSSGroupIF getGroupByIdentity(java.util.Map context,
                                     java.lang.String identity)
                              throws CSSCommunicationException,
                                     CSSException

Get a group based on the identity of the group. The identity is stored by the application and is generated by the security platform.

The context can specify the following:

1. locale

These properties are discussed in the field description for CSSAPIIF.

Specified by:

getGroupByIdentity in interface com.hyperion.css.common.internal.CSSFrameworkIF

Parameters:

context - Map structure holding key-value information about locale.

identity - String returned from the group object that uniquely identifies one group on a provider.

Returns:

CSSGroupIF

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSException - - Any other abnormality.

getGroupsByIdentities

public java.util.ArrayList getGroupsByIdentities(java.util.Map context,
                                                 java.lang.String[] ids,
                                                 java.util.List failedList)
                                          throws CSSCommunicationException,
                                                 CSSException

For Internal Use only

Get groups based on the identities of the group array. The identity is stored by the application and is generated by the security platform.

The context can specify the following:

1. locale

These properties are discussed in the field description for CSSAPIIF.

Parameters:

context - Map structure holding key-value information about locale.

ids - String array of group identities.

failedList - List of group identities that failed to get fetched.

Returns:

CSSGroupIF

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSException - - Any other abnormality.

setEnvironment

public void setEnvironment(java.util.Map env)

Sets the environment for the provider. This can be used by the framework to reset the environment for the provider that was set up during the creation/initialization.

Parameters:

env - Map containing environment for Provider.

getChildrenForGroup

public java.util.ArrayList getChildrenForGroup(java.util.Map context,
                                               com.hyperion.css.common.CSSNodeImpl groupNode)
                                        throws CSSCommunicationException,
                                               CSSException

For Internal Use Only. This API is used by getGraphForGroupEntries() and expected the child tree of the specified groupNode. The implementation should return the user as well as group nodes. Return an array list of User and Groups nodes for the specified CSSNodeIF. This is used for interaction from the Native Provider to other providers.

Throws:

CSSCommunicationException

CSSException

getGroupTree

public java.util.ArrayList getGroupTree(java.util.Map context,
                                        java.lang.String identity,
                                        boolean indirect)
                                 throws CSSException

For Internal Use Only. Returns a flat list of child group identities of the specified group identity. If indirect flag is true then returns all the child group identities recursively. This is used for interaction from the Native Provider to other providers.

Throws:

CSSException

searchIdentities

public java.util.ArrayList searchIdentities(java.util.Map context,
                                            java.lang.String identity)
                                     throws CSSException

For Internal Use Only. This is used to search user or group identities with in provider. It will search only if the identity baseDN and provider baseDN matches. And it wil search based on identityCN to see if they are moved to some other OU and re-create the identity with updated OU.

Parameters:

context - Map structure holding key-value information about locale.

identity - String object holding identity that need to be searched.

Returns:

a list of simillar identities.

Throws:

CSSException - - Any other abnormality.

getDelegatedGroups

public CSSGroupIF[] getDelegatedGroups(java.util.Map context,
                                       CSSPrincipalIF principal,
                                       CSSDelegatedListIF[] delegatedList,
                                       java.lang.String groupNameFilter)

Returns all the groups that are present in the delegated list and the child groups recursively matching the group name filter specified.

Parameters:

context -

principal - - logged-in user

delegatedList -

groupNameFilter - group name filter

Returns:

array of group objects.

getDelegatedUsers

public CSSUserIF[] getDelegatedUsers(java.util.Map context,
                                     CSSPrincipalIF principal,
                                     CSSDelegatedListIF[] delegatedList,
                                     java.lang.String userNameFilter)

Returns all the users that are present in the delegated list and the users in the groups recursively matching the user name filter specified..

Parameters:

context -

principal - - logged-in user

delegatedList -

userNameFilter - user name filter

Returns:

array of group objects.

getDelegatedUsers

public CSSUserIF[] getDelegatedUsers(java.util.Map context,
                                     CSSPrincipalIF principal,
                                     CSSDelegatedListIF[] delegatedList,
                                     UserSearchFilter userSrchFilter)

Returns all the users that are present in the delegated list and the users in the groups recursively matching the user name filter specified. The user search filter passed as argument should have the user name filter.

Parameters:

context -

principal - - logged-in user

delegatedList -

userSrchFilter - user search filter

Returns:

array of user objects.

getDelegatedGroups

public CSSGroupIF[] getDelegatedGroups(java.util.Map context,
                                       CSSPrincipalIF principal,
                                       CSSDelegatedListIF[] delegatedList,
                                       GroupSearchFilter groupSrchFilter)

Returns all the groups that are present in the delegated list and the child groups recursively matching the group name filter specified. The user search filter passed as argument should have the group name filter.

Parameters:

context -

principal - - logged-in user

delegatedList -

groupSrchFilter - group search filter

Returns:

array of group objects.

getName

public java.lang.String getName()

Returns the name of the implementing provider with which it is configured. This is not to be confused with the provider type. For e.g., in , "Native Directory" is the name of the provider, and "native" is the provider type.

Returns:

string - name of the implementing provider

isAvailable

public boolean isAvailable(java.util.Map context)
                    throws CSSCommunicationException,
                           CSSException

Returns true if provider is communicable. If the provider is not communicable this method will throw CSSException.

Parameters:

context - Map structure holding key-value information about locale.

Returns:

boolean value TRUE if provider is reachable

Throws:

CSSCommunicationException - - The provider could not connect to the directory.

CSSException - - Any other abnormality.

getUserObjFromGroups

public java.util.Set getUserObjFromGroups(java.util.Map context,
                                          java.util.Set identities)
                                   throws CSSException

Returns set of CSSUserIF objects for the given group identities. This API will return only direct members of the group. Note: - Use this API only for LDAP and MSAD providers, since implementation is available only for these two Providers.

Parameters:

context -

identities - - set of group identities

Returns:

- set of CSSUserIF objects.

Throws:

CSSException

getUsersByIdentities

public java.util.ArrayList getUsersByIdentities(java.util.Map context,
                                                java.lang.String[] array)
                                         throws CSSException

Returns List of CSSUserIF objects for given user identities. Note: - Use this API only for NATIVE, LDAP and MSAD providers only.

Parameters:

context -

array -

Returns:

- ArraList - list of CSSUserIF objects.

Throws:

CSSException

getUserMembersForGroups

public java.util.Map getUserMembersForGroups(java.util.Map context,
                                             java.util.Set groupIdentities)
                                      throws CSSException

Returns a Map containing group id as key and set of user objects as values. This API will return only direct members of the group.

Parameters:

context -

groupIdentities -

Returns:

Throws:

CSSException