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 com.hyperion.css.spi.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.
com.hyperion.css.cache.CacheMap	createCache(java.util.Map context, CSSPrincipalIF principal) Responsible to create the Provider level cache that contains the group hierarchy and user nodes.
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	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.Set<java.lang.String>	searchGroups(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.
java.util.Set<java.lang.String>	searchGroups(java.util.Map context, java.lang.String name) Get a group based on the name .
java.util.ArrayList	searchIdentities(java.util.Map context, java.lang.String identity) For Internal Use Only.
void	setEnvironment(java.util.Map context, java.util.Map env) Sets the environment for the provider.

Method Detail

authenticate

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.

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

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

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.

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

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

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

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

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

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

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

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.

setEnvironment

void setEnvironment(java.util.Map context,
                    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.

getGroupTree

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

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 will 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 similar identities.

Throws:

CSSException - - Any other abnormality.

getName

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

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

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

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

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

createCache

com.hyperion.css.cache.CacheMap createCache(java.util.Map context,
                                            CSSPrincipalIF principal)

Responsible to create the Provider level cache that contains the group hierarchy and user nodes. This is required as a part of unified cache.

Parameters:

context -

searchGroups

java.util.Set<java.lang.String> searchGroups(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.

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.

searchGroups

java.util.Set<java.lang.String> searchGroups(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.