com.tivoli.pd.rgy
Interface RgyRegistry

public interface RgyRegistry

The primary point of contact for accessing the registry. Initial contact will be made via a method from this interface. It may return other classes that operate upon the registry, such as RgyUser, RgyGroup and RgyIterator.

Since SAM layers it's users on top of the native registry users, you will observe this duality in the provided methods. There will be SAM methods and "Native" based method and method parameter names that refer to each layer.

It is expected that only one instance of this Interface will be constructed for a given application, though multiple instances are possible. It supports access to multiple SAM domains, but it is likely that only one domain will be in use at a time.

This interface is thread safe. Some of the returned class instances may not be, their documentation should be examined for thread safety.

Field Summary

static int	RESOURCE_CRED_LENGTH
static int	RESOURCE_CRED_NAME_INDEX
static int	RESOURCE_CRED_PASSWORD_INDEX
static int	RESOURCE_CRED_TYPE_INDEX
static int	RESOURCE_CRED_USER_INDEX

Method Summary

void	close() When finished with the RgyRegistry instance this should be called to release any cached resources.
java.lang.String	condenseResourceCredential(java.lang.String[] expandedResourceCredential) Condenses an array of four strings representing the GSO resource credential data into a single string format required by this API.
RgyGroup	createGroup(java.lang.String domain, java.lang.String groupId, java.lang.String groupNativeId, RgyAttributes rgyAttributes) Creates a new SAM group and underlying Native group.
RgyUser	createUser(java.lang.String domain, java.lang.String userId, java.lang.String userNativeId, char[] password, boolean bypassPasswordPolicy, RgyAttributes rgyAttributes, java.util.Set<java.lang.String> groupIds) Creates a new SAM user and underlying Native user.
void	deleteGroup(java.lang.String domain, java.lang.String groupId, boolean deleteNativeGroup) Delete the SAM group entry, optionally also deleting the Registry entry.
void	deleteUser(java.lang.String domain, java.lang.String userId, boolean deleteNativeUser) Delete the SAM user entry, optionally also deleting the Native user entry.
java.lang.String[]	expandResourceCredential(java.lang.String condensedResourceCredential) Expands a GSO resource credential in this API's format into an array of strings that are the component parts.
java.util.Date	fromRegistryDate(java.lang.String registryDate) Converts a registry date/time String into a Java Date instance.
RgyGroup	getGroup(java.lang.String domain, java.lang.String groupId) Fetch the SAM (and Native) group attributes, wrapped in a class that implements the RgyGroup interface.
RgyGroup	getNativeGroup(java.lang.String domain, java.lang.String groupNativeId) Fetch the Native group attributes wrapped in a class that implements the RgyGroup interface.
RgyUser	getNativeUser(java.lang.String domain, java.lang.String userNativeId) Fetch the Native user attributes wrapped in a class that implements the RgyUser interface.
java.util.Locale	getRgyThreadLocale() Returns the locale for the generation of RgyException messages set for this thread.
RgyUser	getUser(java.lang.String domain, java.lang.String userId) Fetch the SAM (and Native) user attributes, wrapped in a class that implements the RgyUser interface.
RgyIterator	listGroups(java.lang.String domain, java.lang.String groupIdPattern, int maxResults, int pageSize) Lists the SAM groups in the registry that match the pattern provided.
RgyIterator	listNativeGroups(java.lang.String searchAttributeName, java.lang.String searchAttributePattern, int maxResults, int pageSize) Lists the Native group IDs in the registry that match the pattern provided.
RgyIterator	listNativeUsers(java.lang.String searchAttributeName, java.lang.String searchAttributePattern, int maxResults, int pageSize) Lists the Native user IDs in the registry that match the pattern provided.
RgyIterator	listUsers(java.lang.String domain, java.lang.String userIdPattern, int maxResults, int pageSize) Lists the SAM users in the registry that match the pattern provided.
RgyAttributes	newRgyAttributes() Creates a fresh instance of RgyAttributes that can be setup for use with createUser() or createGroup().
void	setRgyThreadLocale(java.util.Locale locale) Sets the locale for the generation of RgyException messages.
java.lang.String	toRegistryDate(java.util.Date javaDate) Converts a Java Date instance into a String suitable for attributes of a user that require a registry specific date format.

Field Detail

RESOURCE_CRED_NAME_INDEX

static final int RESOURCE_CRED_NAME_INDEX

See Also:

Constant Field Values

RESOURCE_CRED_TYPE_INDEX

static final int RESOURCE_CRED_TYPE_INDEX

See Also:

Constant Field Values

RESOURCE_CRED_USER_INDEX

static final int RESOURCE_CRED_USER_INDEX

See Also:

Constant Field Values

RESOURCE_CRED_PASSWORD_INDEX

static final int RESOURCE_CRED_PASSWORD_INDEX

See Also:

Constant Field Values

RESOURCE_CRED_LENGTH

static final int RESOURCE_CRED_LENGTH

See Also:

Constant Field Values

Method Detail

getUser

RgyUser getUser(java.lang.String domain,
                java.lang.String userId)
                throws RgyException

Fetch the SAM (and Native) user attributes, wrapped in a class that implements the RgyUser interface. The user's registry attributes are cached in the returned RgyUser instance, so these can go out of date if other threads/processes are also updating the same user. It is recommended that these RgyUser instances not be cached for long periods, rather freshly fetched if the latest attribute data is required (as an example an invocation of RgyUser.authenticate() would be best to have the latest values for account-valid, password-valid, persistent strikes, etc). Note: the user's password is never cached and will always be checked against the latest value in the registry.

Parameters:

domain - The SAM domain the user is a member of, passing null will cause the configured local domain to be used.

userId - The SAM user ID, such as "sec_master".

Returns:

RgyUser Instance containing the user's attributes and to allow some manipulation of that user. Null will be returned if the user does not exist.

Throws:

RgyException

getNativeUser

RgyUser getNativeUser(java.lang.String domain,
                      java.lang.String userNativeId)
                      throws RgyException

Fetch the Native user attributes wrapped in a class that implements the RgyUser interface. If the Native user also has a SAM user associated with it, in the domain specified, that information is also fetched, giving a similar result to invoking getUser.

Parameters:

domain - The SAM user in this domain will be returned if present for the specified Native user. If domain is null, the configured local domain will be used.

userNativeId - The Native user ID. This is the underlying registry ID, such as the DN: "cn=testuser,o=ibm,c=us"

Returns:

RgyUser Instance containing the Native user's attributes and allow some manipulation of that user. If the Native user also has an associated SAM user in the domain specified, that is also returned.

Throws:

RgyException

listUsers

RgyIterator listUsers(java.lang.String domain,
                      java.lang.String userIdPattern,
                      int maxResults,
                      int pageSize)
                      throws RgyException

Lists the SAM users in the registry that match the pattern provided. The pattern is matched to the SAM User ID of each entry.
Notes:
1) If the LDAP server connection fails while iterating over the users returned, there is no form of automatic failover/recovery. Instead the caller must deal with the situation.
2) The iterator returned will keep busy one of the limited number of connections to the registry. If other RgyRegistry calls are made while the RgyIterator is still open, this will take an additional connection. It is possible to get into a deadlock situation if all available connections are used up by RgyIterators and these RgyIterator owners attempt another RgyRegistry operation, they will block forever waiting for a connection to be released. 3) This list will span LDAP suffixes, even if it requires multiple underlying LDAP/JNDI searches.

Parameters:

domain - The SAM domain the matched users must be a member of. If null is provided, the configured local domain will be used.

userIdPattern - SAM User ID pattern to match. Patterns consist of a mixture of characters and '*' wildcards.

maxResults - Maximum number of SAM user IDs to return. Supply 0 for no limit (other than any registry server defined limit). Note that if there are more result available than maxResults, then after the last SAM User ID is extracted, the RgyIterator hasNext() method will throw an exception that indicates this fact. This exception can be caught and ignored if the caller does not care about the returned list being shorter than the full matching list.

pageSize - Requests that the underlying registry search the be done in pages. Even though the paging will not be visible via the returned RgyIterator, some registries can overcome the underlying registry server max return results limit. To enable, pass in a positive integer.

Returns:

RgyIterator a list of SAM user ID Strings that match the pattern provided.

Throws:

RgyException

listNativeUsers

RgyIterator listNativeUsers(java.lang.String searchAttributeName,
                            java.lang.String searchAttributePattern,
                            int maxResults,
                            int pageSize)
                            throws RgyException

Lists the Native user IDs in the registry that match the pattern provided. To emulate the list-dn provided by the equivalent SAM Management API the searchAttributeName values should be the "cn" attribute of the Native user entry. Both SAM users and non-SAM (Native only) can be returned. Notes:
1) If the LDAP server connection fails while iterating over the users returned, there is no form of automatic failover/recovery. Instead the caller must retry the operation.
2) The iterator returned will keep busy one of the limited number of connections to the registry. If you make other RgyRegistry calls while the RgyIterator is still open, that will take an additional connection. It is possible to get into a deadlock situation if all available connections are used up by RgyIterators and another RgyRegistry operation is attempted. In other words, don't keep too many RgyIterators open at the same time. 3) This list will span LDAP suffixes, even if it requires multiple underlying searches.

Parameters:

searchAttributeName - The Name of an attribute that Native user entries contain that will be searched for a match to the searchAttributePattern.

searchAttributePattern - This is a pattern for the attribute Name provided. It can contain a mix of characters and '*' wildcards.

maxResults - Maximum number of Native user IDs to return. Supply 0 for no limit (other than any registry server defined limit). Note that if there are more result available than maxResults, then after the last Native User ID is extracted, the RgyIterator hasNext() method will throw an exception that indicates this fact. This exception can be caught and ignored if the caller does not care about the returned list being shorter than the full matching list.

pageSize - Requests that the underlying registry search the be done in pages. Even though the paging will not be visible via the returned RgyIterator, some registries can overcome the underlying registry server max return results limit. To enable, pass in a positive integer.

Returns:

RgyIterator an Iterator over a list of Native user ID's, such as "cn=testuser,o=ibm,c=us".

Throws:

RgyException

createUser

RgyUser createUser(java.lang.String domain,
                   java.lang.String userId,
                   java.lang.String userNativeId,
                   char[] password,
                   boolean bypassPasswordPolicy,
                   RgyAttributes rgyAttributes,
                   java.util.Set<java.lang.String> groupIds)
                   throws RgyException

Creates a new SAM user and underlying Native user. There are required attributes that must be supplied to keep the underlying registry happy. For LDAP these are: RgyAttributes.COMMON_NAME_NAME, and RgyAttributes.SURNAME_NAME. If RgyAttribtues.UID_NAME is not provided a default value will be set (to the same values as userId). For any attributes not known to SAM, these will be added to the Native user entry created. For example you could provide a "telephoneNumber".

Parameters:

domain - The SAM domain to create the user under. If domain is null, the configured local domain will be used.

userId - The ID for the SAM user, for example "testuser".

userNativeId - The ID of the Native user entry to create. The SAM user will be created on top of this. An example might be "cn=testuser,o=ibm,c=us".

password - The password to give the Native/SAM user

bypassPasswordPolicy - If set to "true" then the password provided will not be rejected by SAM if it does not meet the requirements of SAM global password policy. It may not allow bypassing of the underlying Registry's policy, if enabled.

rgyAttributes - Attributes to add to the newly created user. For example, you could override the default "FALSE" value for RgyAttributes.SEC_ACCT_VALID_NAME with RgyAttributes.BOOL_TRUE_VALUE.

groupIds - A Set of groups to add the user to. Each entry in the set is a group SAM Id. The set can be null or empty.

Returns:

RgyUser instance

Throws:

RgyException

deleteUser

void deleteUser(java.lang.String domain,
                java.lang.String userId,
                boolean deleteNativeUser)
                throws RgyException

Delete the SAM user entry, optionally also deleting the Native user entry. Deletion of the Native user entry may fail if other SAM entries from other SAM domains are also layered on the same Native user entry.

Parameters:

domain - The SAM domain of the user to delete. If domain is null, the configured local domain will be used.

userId - The ID for the SAM user, for example "testuser".

deleteNativeUser - When true, the Native user entry will be removed if possible.

Throws:

RgyException

WarningNativeEntityInUseRgyException - This is a warning exception and can be ignored. The Native entity could not be removed as other entries exist under it, possibly it is being used in other Security Access Manager domains. The Security Access Manager User information has been removed so the user is no longer a member of the domain specified.

getGroup

RgyGroup getGroup(java.lang.String domain,
                  java.lang.String groupId)
                  throws RgyException

Fetch the SAM (and Native) group attributes, wrapped in a class that implements the RgyGroup interface. The group's registry attributes are cached in the returned RgyGroup instance, so these can go out of date if other threads/processes are also updating the same group. It is recommended that these RgyGroup instances not be cached for long periods, rather freshly fetched if the latest attribute data is required.
Note: Unlike getUser(), not all attributes of the native group are returned, only a fixed subset.

Parameters:

domain - This is the SAM domain in which to look for a SAM group. If domain is null, the configured local domain will be used.

groupId - The ID for the SAM group, for example "testgroup".

Returns:

RgyGroup instance.

Throws:

RgyException

getNativeGroup

RgyGroup getNativeGroup(java.lang.String domain,
                        java.lang.String groupNativeId)
                        throws RgyException

Fetch the Native group attributes wrapped in a class that implements the RgyGroup interface. If the Native group also has a SAM group associated with it, in the domain specified, that information is also fetched.

Parameters:

domain - This is the SAM domain in which to look for a SAM group entry to also return. If domain is null, the configured local domain will be used.

groupNativeId - The Native group ID. This is the underlying registry ID, such as the DN: cn=testgroup,o=ibm,c=us

Returns:

RgyGroup instance. This may not contain the SAM group domain info if this group does not have one associated with it (IE not imported).

Throws:

RgyException

listGroups

RgyIterator listGroups(java.lang.String domain,
                       java.lang.String groupIdPattern,
                       int maxResults,
                       int pageSize)
                       throws RgyException

Lists the SAM groups in the registry that match the pattern provided. The pattern is matched to the SAM Group ID.
Notes:
1) If the LDAP server connection fails while iterating over the groups returned, there is no form of automatic failover/recovery. Instead the caller must deal with the situation.
2) The iterator returned will keep busy one of the limited number of connections to the registry. If other RgyRegistry calls are made while the RgyIterator is still open, this will take an additional connection. It is possible to get into a deadlock situation if all available connections are used up by RgyIterators and these RgyIterator owners attempt another RgyRegistry operation, they will block forever waiting for a connection to be released. 3) This list will span LDAP suffixes, even if it requires multiple underlying searches.

Parameters:

domain - The SAM domain the matched groups must be a member of. If null is provided, the configured local domain will be used.

groupIdPattern - SAM Group ID pattern to match. Patterns consist of a mixture of characters and '*' wildcards.

maxResults - Maximum number of SAM group IDs to return. Supply 0 for no limit (other than any registry server defined limit). Note that if there are more result available than maxResults, then after the last SAM Group ID is extracted, the RgyIterator hasNext() method will throw an exception that indicates this fact. This exception can be caught and ignored if the caller does not care about the returned list being shorter than the full matching list.

pageSize - Requests that the underlying registry search the be done in pages. Even though the paging will not be visible via the returned RgyIterator, some registries can overcome the underlying registry server max return results limit. To enable, pass in a positive integer.

Returns:

RgyIterator a list of SAM group ID Strings that match the pattern provided.

Throws:

RgyException

listNativeGroups

RgyIterator listNativeGroups(java.lang.String searchAttributeName,
                             java.lang.String searchAttributePattern,
                             int maxResults,
                             int pageSize)
                             throws RgyException

Lists the Native group IDs in the registry that match the pattern provided. To emulate the list-dn provided by the equivalent SAM Management API the searchAttributeName values should be the "cn" attribute of the Native group entry. Both SAM groups and non-SAM (Native only) groups can be returned. Notes:
1) If the LDAP server connection fails while iterating over the groups returned, there is no form of automatic failover/recovery. Instead the caller must retry the operation.
2) The iterator returned will keep busy one of the limited number of connections to the registry. If you make other RgyRegistry calls while the RgyIterator is still open, that will take an additional connection. It is possible to get into a deadlock situation if all available connections are used up by RgyIterators and another RgyRegistry operation is attempted. In other words, don't keep too many RgyIterators open at the same time. 3) This list will span LDAP suffixes, even if it requires multiple underlying searches.

Parameters:

searchAttributeName - The Name of an attribute that Native group entries contain that will be searched for a match to the searchNativePattern.

searchAttributePattern - This is a pattern for the attribute Name provided. It can contain a mix of characters and '*' wildcards.

maxResults - Maximum number of Native group IDs to return. Supply 0 for no limit (other than any registry server defined limit). Note that if there are more result available than maxResults, then after the last Native User ID is extracted, the RgyIterator hasNext() method will throw an exception that indicates this fact. This exception can be caught and ignored if the caller does not care about the returned list being shorter than the full matching list.

pageSize - Requests that the underlying registry search the be done in pages. Even though the paging will not be visible via the returned RgyIterator, some registries can overcome the underlying registry server max return results limit. To enable, pass in a positive integer.

Returns:

RgyIterator an Iterator over a list of Native group ID's, such as "cn=testgroup,o=ibm,c=us".

Throws:

RgyException

createGroup

RgyGroup createGroup(java.lang.String domain,
                     java.lang.String groupId,
                     java.lang.String groupNativeId,
                     RgyAttributes rgyAttributes)
                     throws RgyException

Creates a new SAM group and underlying Native group. There is a required attribute that must be supplied to keep the underlying registry happy. For LDAP this is: RgyAttributes.COMMON_NAME_NAME.

Parameters:

domain - The SAM domain to create the group in. If domain is null, the configured local domain will be used.

groupId - The ID for the SAM group, for example "testgroup".

groupNativeId - The ID of the Native group entry to create. The SAM group will be created on top of this. An example might be "cn=testgroup,o=ibm,c=us".

rgyAttributes - Attributes to add to the newly created group. For example RgyAttributes.COMMON_NAME_NAME.

Returns:

RgyGroup instance

Throws:

RgyException

deleteGroup

void deleteGroup(java.lang.String domain,
                 java.lang.String groupId,
                 boolean deleteNativeGroup)
                 throws RgyException

Delete the SAM group entry, optionally also deleting the Registry entry. Deletion of the Registry entry may fail if other SAM entries from other SAM domains are also layered on the Registry entry.

Parameters:

domain -

groupId -

deleteNativeGroup -

Throws:

RgyException

WarningNativeEntityInUseRgyException - This is a warning exception and can be ignored. The Native entity could not be removed as other entries exist under it, possibly it is being used in other Security Access Manager domains. The Security Access Manager Group information has been removed so the group is no longer a member of the domain specified.

newRgyAttributes

RgyAttributes newRgyAttributes()

Creates a fresh instance of RgyAttributes that can be setup for use with createUser() or createGroup().

Returns:

Empty RgyAttributes instance;

close

void close()

When finished with the RgyRegistry instance this should be called to release any cached resources. The resource would eventually be reclaimed by Java if this call was not made, however, it may be useful to stop the connection recovery threads, and close JNDI connection sooner especially if a another RgyRegistry instance is to be instantiated.

setRgyThreadLocale

void setRgyThreadLocale(java.util.Locale locale)

Sets the locale for the generation of RgyException messages. If never set for the current thread, then the default Locale will be used. This does not effect the locale used for log messages.

Parameters:

locale - Locale used for this thread and this instance of RgyRegistry only.

getRgyThreadLocale

java.util.Locale getRgyThreadLocale()

Returns the locale for the generation of RgyException messages set for this thread.

Returns:

Locale used for this thread and this instance of RgyRegistry only.

toRegistryDate

java.lang.String toRegistryDate(java.util.Date javaDate)
                                throws RgyException

Converts a Java Date instance into a String suitable for attributes of a user that require a registry specific date format. For example RgyAttributes.ACCOUNT_EXPIRY_DATE_NAME. Note that this method is only accurate to the second, so the millisecond resolution is lost.

Parameters:

javaDate - is the Java Date instance to convert to a String. If null is provided, a special value is returned that SAM uses to represent unlimited date for the underlying registry type.

Returns:

a String that can be used for date attributes of the user.

Throws:

RgyException

fromRegistryDate

java.util.Date fromRegistryDate(java.lang.String registryDate)
                                throws RgyException

Converts a registry date/time String into a Java Date instance. Note that this method is only accurate to the second, so the millisecond resolution is not provided. Null can be returned for values that represent the unlimited date.

Parameters:

registryDate - A date/time String from a user attribute to convert.

Returns:

A Java Date instance converted from registryDate. Null is returned for special dates that represent SAM unlimited dates for the underlying registry type.

Throws:

InvalidParametersRgyException - for an invalid registryDate string.

RgyException

condenseResourceCredential

java.lang.String condenseResourceCredential(java.lang.String[] expandedResourceCredential)
                                            throws RgyException

Condenses an array of four strings representing the GSO resource credential data into a single string format required by this API.

See RESOURCE_CRED_*_INDEX for the indexes of the components of String[].

Parameters:

expandedResourceCredential - The components of the resource credential to condense into a single String.

Returns:

The condensed Resource Credential string made from the supplied components. RESOURCE_CRED_LENGTH

Throws:

InvalidParametersRgyException - if an incorrect number of components was supplied.

RgyException

expandResourceCredential

java.lang.String[] expandResourceCredential(java.lang.String condensedResourceCredential)
                                            throws RgyException

Expands a GSO resource credential in this API's format into an array of strings that are the component parts.

See RESOURCE_CRED_*_INDEX for the indexes of the components of String[].

Parameters:

condensedResourceCredential -

Returns:

the expanded Resource Credential as an array of String.

Throws:

InvalidParametersRgyException - if the condensedResourceCredential could not be parsed into it's components.

RgyException