com.autonomy.aci.services
Interface UserFunctionality


public interface UserFunctionality


Method Summary
 AciResponse addPrivilege(Privilege privilege)
          Create a privilege on IDOL.
 AciResponse addRole(Role role, Role parentRole)
          Create a role on IDOL, as a child of another role or not.
 AciResponse addRoleToRole(Role role, Role parentRole)
          Set a role to be the child of another role.
 User addUser(User user)
          Create a user on IDOL.
 User addUserToRole(User user, Role role)
          Adds a user to an existing role and then reads the user's updated details (for new roles and privileges).
 boolean authenticateUser(java.lang.String sUserName, java.lang.String sPassword, java.lang.String sDomain, java.lang.String sRepository)
          Try to authenticate a username and password against the specified repository via IDOL.
 User copyUser(User user, java.lang.String sNewUsername)
          Create a new user by copying the details of an already existing user.
 AciResponse deletePrivilege(Privilege privilege)
          Delete the privilege from IDOL.
 AciResponse deleteRole(Role role)
          Delete the role from IDOL.
 AciResponse deleteUser(User user)
          Remove the user from IDOL.
 java.util.ArrayList getChildRoleList(Role role, int nDepth)
          Read all the roles that have been added to a role as its children, either directly or through inheritence.
 java.util.ArrayList getParentRoleList(Role role, boolean recurse)
          Read all the roles that contain the given role, directly or through inheritence.
 java.util.ArrayList getPrivilegeList()
          Gives a list of all the privileges that exist on IDOL.
 Privilege getPrivilegeValuesForRole(Privilege privilege, Role role, java.lang.String sMode, boolean bRecurse)
          Read the value(s) of a particular privilege for a given role.
 java.util.ArrayList getRoleList()
          Gives a list of all the roles that exist on IDOL.
 User getUser(java.lang.String sUsername)
          Read the details of a user from IDOL.
 User getUserFromID(java.lang.String sUserID)
          Read the details of a user from IDOL.
 java.util.ArrayList getUsernamesInRole(Role role)
          Read the usernames of all users existing on IDOL which belong to a role or all the existing users if no role is specified.
 boolean isRoleInRole(Role role, Role parentRole, boolean bRecurse)
          Check to see whether a given role is contained in another role or its ancestors.
 AciResponse removeRoleFromRole(Role role, Role parentRole)
          Remove a given role from its parent role.
 User removeUserFromRole(User user, Role role)
          Removes a user from an existing role and then reads the user's updated details (for new roles and privileges).
 Privilege setPrivilegeValuesForRole(Privilege privilege, Role role, boolean bPositive)
          Set the values for a particular privilege for a given role.
 User updateUser(User user)
          Modify a user's details as stored on IDOL.
 

Method Detail

addUser

public User addUser(User user)
             throws AciException,
                    UserExistsException
Create a user on IDOL. The username provided should not already exist on IDOL and a user password should be set on the User parameter.

Parameters:
user - the details of the new user. This must give at least a username and should also include a password. If no password is provided, the username will be used for the password value.
Returns:
a User object populated from the information read from IDOL once the user is created. This object will contain additional information such as the user's security string.
Throws:
AciException - if there was an error when making the request.
UserExistsException - if a user with the same username already exists on IDOL.

updateUser

public User updateUser(User user)
                throws AciException,
                       UserNotFoundException
Modify a user's details as stored on IDOL. Note that some user details such as the user's current and maximum number of agents, roles and privileges cannot be modified. See IDOL's online help for the UserEdit action for information on which user details can be changed using this method.

Parameters:
user - a User object specifying the user details which should be modified. Only the information that is set on the object will be updated so this object does not need to be populated with all the user's details. The user object must contain either the username or user ID (or both).
Returns:
a new User object as read from IDOL once the modifications have been made. This will be difference to the User object parameter if for example the user's security type information has been modified.
Throws:
AciException - if there was an error when making the request.
UserNotFoundException - if the specified user does not have an entry on IDOL.

copyUser

public User copyUser(User user,
                     java.lang.String sNewUsername)
              throws AciException,
                     UserExistsException,
                     UserNotFoundException
Create a new user by copying the details of an already existing user. All the new user's information will be the same as the existing one apart from the password which will be blank.

Parameters:
user - the user to copy. Must have at least the username or user ID set.
sNewUsername - the username to give to the new user.
Returns:
the new user's information as stored on IDOL.
Throws:
AciException - if there was an error when making the request.
UserExistsException - if there is already a user with the given new username.
UserNotFoundException - if the user to be copied does not exist on IDOL.

deleteUser

public AciResponse deleteUser(User user)
                       throws AciException,
                              UserNotFoundException
Remove the user from IDOL.

Parameters:
user - the user to delete. Must have at least the username or user ID set.
Returns:
the response from IDOL to the UserDelete action.
Throws:
AciException - if there was an error when making the request.
UserNotFoundException - if the user to be deleted does not exist on IDOL.

getUser

public User getUser(java.lang.String sUsername)
             throws AciException,
                    UserNotFoundException
Read the details of a user from IDOL. The resulting User object will contain details of all the fields set on the user, all the roles that the user belongs to and all the privilege values that are set for the user.

Parameters:
sUsername - the username of the user to read.
Returns:
a User object populated with the details of the specified user.
Throws:
AciException - if there was an error when making the request.
UserNotFoundException - if the specified user does not exist on IDOL.

getUserFromID

public User getUserFromID(java.lang.String sUserID)
                   throws AciException,
                          UserNotFoundException
Read the details of a user from IDOL. The resulting User object will contain details of all the fields set on the user, all the roles that the user belongs to and all the privilege values that are set for the user.

Parameters:
sUserID - the unique user ID of the user to read.
Returns:
a User object populated with the details of the specified user or null if the user does not exist on IDOL.
Throws:
AciException - if there was an error when making the request.
UserNotFoundException - if the specified user does not exist on IDOL.

getUsernamesInRole

public java.util.ArrayList getUsernamesInRole(Role role)
                                       throws AciException,
                                              RoleNotFoundException
Read the usernames of all users existing on IDOL which belong to a role or all the existing users if no role is specified.

Parameters:
role - the role whose users are needed. Can be null in which case all usernames are read.
Returns:
a ArrayList of Strings giving all usernames for a given role.
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if the given role does not exist on IDOL.

addUserToRole

public User addUserToRole(User user,
                          Role role)
                   throws AciException,
                          RoleNotFoundException,
                          UserNotFoundException
Adds a user to an existing role and then reads the user's updated details (for new roles and privileges).

Parameters:
user - the user to add to the given role.
role - the role to add the user to.
Returns:
the user information once the user has been added to the role. Can be null if the user passed in is null.
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if the given role does not exist on IDOL.
UserNotFoundException - if the given user does not exist on IDOL.

removeUserFromRole

public User removeUserFromRole(User user,
                               Role role)
                        throws AciException,
                               RoleNotFoundException,
                               UserNotFoundException
Removes a user from an existing role and then reads the user's updated details (for new roles and privileges).

Parameters:
user - the user to remove from the given role.
role - the role from which to remove the user.
Returns:
the user information once the user has been removed from the role. Can be null if the user passed in is null.
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if the given role does not exist on IDOL.
UserNotFoundException - if the given user does not exist on IDOL.

getRoleList

public java.util.ArrayList getRoleList()
                                throws AciException
Gives a list of all the roles that exist on IDOL.

Returns:
an ArrayList of Strings giving the names of all existing roles.
Throws:
AciException - if there was an error when making the request.

addRole

public AciResponse addRole(Role role,
                           Role parentRole)
                    throws AciException,
                           RoleNotFoundException,
                           RoleExistsException
Create a role on IDOL, as a child of another role or not. If no parent role is given, the role is created as a standalone role. If a parent role is given, the new role is added as a child of the parent role. Note that roles are unique so no two roles can have the same name.

Parameters:
role - the role to create.
parentRole - the parent of the role to create. Can be null in which case the new role is created as a standalone role.
Returns:
the response from IDOL (null if no role is given).
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if the parent role does not exist.
RoleExistsException - if the given role already exists on IDOL.

addRoleToRole

public AciResponse addRoleToRole(Role role,
                                 Role parentRole)
                          throws AciException,
                                 RoleNotFoundException
Set a role to be the child of another role.

Parameters:
role - the role to set as a child role.
parentRole - the role to use as the parent role.
Returns:
the response from IDOL (null if no role or parent role is given).
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if either role does not exist.

deleteRole

public AciResponse deleteRole(Role role)
                       throws AciException,
                              RoleNotFoundException
Delete the role from IDOL.

Parameters:
role - the role to delete.
Returns:
the response from IDOL (null if no role is given).
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if the role does not exist.

getChildRoleList

public java.util.ArrayList getChildRoleList(Role role,
                                            int nDepth)
                                     throws AciException,
                                            RoleNotFoundException
Read all the roles that have been added to a role as its children, either directly or through inheritence.

Parameters:
role - the role whose children are required.
nDepth - the deepest child level from which decendent roles should be read. Set to 0 or 1 for direct children only.
Returns:
an ArrayList of the child Roles.
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if the role does not exist.

getParentRoleList

public java.util.ArrayList getParentRoleList(Role role,
                                             boolean recurse)
                                      throws AciException,
                                             RoleNotFoundException
Read all the roles that contain the given role, directly or through inheritence.

Parameters:
role - the role whose parents are required.
Returns:
an ArrayList of the child Roles.
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if the role does not exist.

removeRoleFromRole

public AciResponse removeRoleFromRole(Role role,
                                      Role parentRole)
                               throws AciException,
                                      RoleNotFoundException
Remove a given role from its parent role.

Parameters:
role - the role to remove.
parentRole - the parent role.
Returns:
the response from IDOL (null if no role is given).
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if either of the roles does not exist.

isRoleInRole

public boolean isRoleInRole(Role role,
                            Role parentRole,
                            boolean bRecurse)
                     throws AciException,
                            RoleNotFoundException
Check to see whether a given role is contained in another role or its ancestors.

Parameters:
role - the role to be looked for.
parentRole - the role in which the given role is being looked for.
bRecurse - whether the check should include the parent role's ancestors as well as itself.
Returns:
true if the role was found to be a child of the parent role (or that parent role's ancestors), false otherwise.
Throws:
AciException - if there was an error when making the request.
RoleNotFoundException - if either of the roles does not exist.

addPrivilege

public AciResponse addPrivilege(Privilege privilege)
                         throws AciException,
                                PrivilegeExistsException
Create a privilege on IDOL. Note that privileges are unique so no two privileges can have the same name (case-insensitive). The privilege is created as single- or multi-valued according to the result of calling isSingleValued() on the privilege.

Parameters:
privilege - the privilege to create.
Returns:
the response from IDOL (null if no privilege is given).
Throws:
AciException - if there was an error when making the request.
PrivilegeExistsException - if the given privilege already exists on IDOL.

deletePrivilege

public AciResponse deletePrivilege(Privilege privilege)
                            throws AciException,
                                   PrivilegeNotFoundException
Delete the privilege from IDOL.

Parameters:
privilege - the privilege to delete.
Returns:
the response from IDOL (null if no privilege is given).
Throws:
AciException - if there was an error when making the request.
PrivilegeNotFoundException - if the privilege does not exist.

getPrivilegeList

public java.util.ArrayList getPrivilegeList()
                                     throws AciException
Gives a list of all the privileges that exist on IDOL.

Returns:
an ArrayList of Privileges giving the details of all existing privileges (although no values are read as these are only relevent when a role is specified).
Throws:
AciException - if there was an error when making the request.

setPrivilegeValuesForRole

public Privilege setPrivilegeValuesForRole(Privilege privilege,
                                           Role role,
                                           boolean bPositive)
                                    throws AciException,
                                           PrivilegeNotFoundException,
                                           RoleNotFoundException
Set the values for a particular privilege for a given role. The given values are included or excluded from the privilege according to the bPositive parameter. Look at the online help for the "RoleSetPrivilegeForRole" action for more information on the behaviour of this parameter.

Parameters:
privilege - the privilege whose values should be set for the role. The values of the Privilege object given are those used to populated the role values.
role - the role whose privilege values are to be set.
bPositive - the value of the 'Positive' parameter sent with the RoleSetPrivilegeForRole action.
Returns:
the privilege passed in.
Throws:
AciException - if there was an error when making the request.
PrivilegeNotFoundException - if the privilege does not exist.
RoleNotFoundException - if the role does not exist.

getPrivilegeValuesForRole

public Privilege getPrivilegeValuesForRole(Privilege privilege,
                                           Role role,
                                           java.lang.String sMode,
                                           boolean bRecurse)
                                    throws AciException,
                                           PrivilegeNotFoundException,
                                           RoleNotFoundException
Read the value(s) of a particular privilege for a given role. See the online help for the "RoleGetPrivilegeValueList" action for more information on the behaviour of the Mode and Recurse parameters.

Parameters:
privilege - the privilege whose values should be read. Must have at least the privilege name set.
role - the role whose privilege values are to be read.
sMode - the mode which should be used for restricting privilege values. Should be one of IDOLConstants.ROLE_GET_PRIVILEGE_MODE_PARAM_VALUE_RESOLVED, IDOLConstants.ROLE_GET_PRIVILEGE_MODE_PARAM_VALUE_POSITIVE or IDOLConstants.ROLE_GET_PRIVILEGE_MODE_PARAM_VALUE_NEGATIVE or null which is equivalent to using ROLE_GET_PRIVILEGE_MODE_PARAM_VALUE_RESOLVED.
bRecurse - whether or not the privilege values of parent roles should be included in the list of values for this role.
Returns:
the privilege passed in with its values set to those read from IDOL.
Throws:
AciException - if there was an error when making the request.
PrivilegeNotFoundException - if the privilege does not exist.
RoleNotFoundException - if the role does not exist.

authenticateUser

public boolean authenticateUser(java.lang.String sUserName,
                                java.lang.String sPassword,
                                java.lang.String sDomain,
                                java.lang.String sRepository)
                         throws AciException
Try to authenticate a username and password against the specified repository via IDOL.

Parameters:
sPassword - the password supplied.
sDomain - if checking against the NT repository, the user's domain should be given. Otherwise, leave null.
sRepository - the repository against which this user should be authenticated. IDOL must be configured to use this repository for authentication before this method can be used.
Returns:
true if the username and password supplied is accepted by the relevent repository, false otherwise.
Throws:
AciException - if there was an error when making the request.