This section will show how to perform the basic Identity Manager operations. Since the Identity Manager implementations implement the IIdentityManager interface the code snippets heres hold true for all implementations. There four different types of operations:
It's assumed that an object named idManager of the type IIdentityManager was created prior to each of the following code snippet.
Besides the standard CRUD operations there's also means to check if a given user exists and if it's identity is valid. The code for all these operations is shown below.
User addition is done through the addUser(IDIFUser) method. As it can be seen on the method's signature, it takes an IDIFUser argument. Prior to addition, the user must be created and the passed to the method.
Here's an example with a simple user with just login (ID) and password attributes:
// Set the user up
IDIFUser user = ...;
user.setID("userId");
user.setPassword("password");
// Add the user to the Identity Manager
idManager.addUser(user);
After the user has been added to the manager, one can check it's existence. To do so the method userExists(String) might be used. It takes the user ID as parameter. Here's an example:
System.out.println("userId exists: " + idManager.userExists("userId"));
System.out.println("nonExistingUser exists: " + idManager.userExists("nonExistingUser"));
The previous snippet will yield the following result:
userId exists: true nonExistingUser exists: false
Users on the Identity Manager can be read with the getUser(String) method. It takes the user ID as parameter. Here's an example:
// Create the user
IDIFUser user = ...;
// Read user from identity manager
user = idManager.getUser("userId");
// do stuff with user
The identity manager offers a method to check a user's credentials without having to write comparison code. This is done with the isIdentityValid(String,String) method. It takes the user ID and password as parameters. To see if a user's login/password pair exists on the system use the following code:
// Correct login name and password
System.out.println("userId/password is correct: " + idManager.isIdentityValid("userId", "password"));
// Correct login name and bad password
System.out.println("userId/badPassword is correct: " + idManager.isIdentityValid("userId", "badPassword"));
// Bad login name and correct password
System.out.println("badUserId/password is correct: " + idManager.isIdentityValid("badUserId", "password"));
// Bad login name and password
System.out.println("badUserId/badPassword is correct: " + idManager.isIdentityValid("badUserId", "badPassword"));
The preceding code produces the following results:
userId/password is correct: true userId/badPassword is correct: false badUserId/password is correct: false badUserId/badPassword is correct: false
To change a given user's data, one must use the updateUser(IDIFUser,String) method. It takes an IDIFUser object and the ID of the user to change as parameters. The current ID must be supplied separately to ensure data integrity if the user ID is changed. Here's an example:
// Sets the user changes
user.setEmail("user@dif2.pt");
// Commit changes to the identity manager
idManager.updateUser(user, "userId");
To delete a given user the removeUser(String) method is used. It takes the ID of the user to remove as parameter. Here's an example:
// Check that user exists
System.out.println("userId is on the IdentityManager: " + idManager.userExists("userId"));
// Remove user
idManager.removeUser("userId");
// Check that user doesn't exists anymore
System.out.println("userId is STILL on the IdentityManager: " + idManager.userExists("userId"));
The previous code will yield the following result:
userId is on the IdentityManager: true userId is STILL on the IdentityManager: false
Group management operations are similar to the user management ones. In fact, only the isIdentityValid(String, String) method is not present. The remaining methods are the same and work on s similar fashion.
See the code examples below.
Group addition is done through the addGroup(IDIFGroup) method. As it can be seen on the method's signature, it takes an IDIFGroup argument. Prior to addition, the group must be created and the passed to the method.
Here's an example with a simple group with just an ID attribute:
// Set up the group
IDIFGroup group = ...;
group.setID("groupId");
// Add the group to the Identity Manager
idManager.addGroup(group);
After the group has been added to the manager, one can check it's existence. To do so the method groupExists(String) might be used. It takes the group ID as parameter. Here's an example:
System.out.println("groupId exists: " + idManager.groupExists("groupId"));
System.out.println("nonExistingGroup exists: " + idManager.groupExists("nonExistingGroup"));
The previous snippet will yield the following result:
groupId exists: true nonExistingGroup exists: false
Groups on the Identity Manager can be read with the getGroup(String) method. It takes the group ID as parameter. Here's an example:
// Create the group
IDIFGroup group = ...;
// Read group from identity manager
group = idManager.getGroup("groupId");
// do stuff with group
To change a given group's data, one must use the updateGroup(IDIFGroup) method. It takes an IDIFGroup object as parameter. Here's an example:
// Sets the group changes
group.setDescription("This is a group.");
// Commit changes to the identity manager
idManager.updateGroup(group);
To delete a given group the removeGroup(String) method is used. It takes the ID of the group to remove as parameter. Here's an example:
// Check that group exists
System.out.println("groupId is on the IdentityManager: " + idManager.groupExists("groupId"));
// Remove group
idManager.removeGroup("groupId");
// Check that group doesn't exists anymore
System.out.println("groupId is STILL on the IdentityManager: " + idManager.groupExists("groupId"));
The previous code will yield the following result:
groupId is on the IdentityManager: true groupId is STILL on the IdentityManager: false
This type of operations is aimed to user/group associations. It's possible to add and remove users to groups, check if a user belongs to a group and get user groups and groups users.
The following code snippets assume that exists an user with ID userId and a group with ID groupId.
Adding a user to a group is done through the addUserToGroup(String, String) method. The method takes the userId and groupId as parameters. Here's an example:
idManager.addUserToGroup("userId", "groupId");
To check if a given user belongs to a given group the isUserInGroup(String, String) method can be used. The method takes the userId and groupId as parameters. Here's an example:
// Existing user belongs to existing group?
System.out.println("userId belongs to groupId: " + idManager.isUserInGroup("userId", "groupId"));
// Existing user belongs to non-existing group?
System.out.println("userId belongs to badGroupId: " + idManager.isUserInGroup("userId", "badGroupId"));
// Non-existing user belongs to existing group? (ie, user DOES NOT belong to group)
System.out.println("badUserId belongs to groupId: " + idManager.isUserInGroup("badUserId", "groupId"));
// Non-existing user belongs to non-existing group?
System.out.println("badUserId belongs to badGroupId: " + idManager.isUserInGroup("badUserId", "badGroupId"));
The preceding code will yield the following output:
userId belongs to groupId: true userId belongs to badGroupId: false badUserId belongs to groupId: false badUserId belongs to badGroupId: false
There are two flavors to read fetch the users that belong to a group. There's a shorter form, using getUserIDsInGroup(String) method, that just returns the IDs of the group users. And there's a longer form, using getGroupUsers(String) method, that returns the complete IDIFUser objects for all group users. The first method is well suited for simple tasks, such as administration interface user listing, or simple statistics. The latter aims for more in-deep user prospection or mass attribute changing. Both methods take the group ID as parameter.
An example of both methods usage is presented below:
// Fetch user IDs
Set<String> userIDs = idManager.getUserIDsInGroup("groupId");
// Fetch users
Map<String, IDIFUser> users = idManager.getGroupUsers("groupId");
This operation can be seen as the previous operation counterpart. It fetches all the groups that a given user belongs to. There's also the "long" and "short" flavors to this operation. The short form uses the getUserGroupsIDs(String) method to retrieve just the groups IDs. The long form uses the getUserGroupss(String) method to retrieve the complete groups. Both methods take the user ID as parameter.
An example of both methods usage is presented below:
// Fetch group IDs
Set<String> groupsIDs = idManager.getUserGroupsIDs("userId");
// Fetch groups
Map<String, IDIFGroup> groups = idManager.getUserGroups("userId");
As is referred here a group can have one or more subgroups. There's an operation to fetch all the subgroups of a given group: the getGroupGroups(String) method. The method takes the group ID as parameter.
// Fetch subgroups
Map<String, IDIFGroup> groups = idManager.getGroupGroups("groupId");
To remove a user from a group the removeUserFromGroup(String,String) method can be used. The method takes two parameters: the user ID and the group ID.
// Check that user is on the group
System.out.println("userId belongs to groupId: " + idManager.isUserInGroup("userId","groupId"));
// Remove group
idManager.removeUserFromGroup("userId","groupId");
// Check that group doesn't contain user anymore
System.out.println("userId STILL belongs to groupId: " + idManager.isUserInGroup("userId","groupId"));
The previous code will yield the following result:
userId belongs to groupId: true userId STILL belongs to groupId: false
At the present time, the identity manager just offers a single self-management method: the resetIdentityManager(). This method is implementation-dependent and you should check each implementation documentation to see what the implementation provides.