JBoss Portal 2.6 Identity management API

API in 2.6

In JBoss Portal 2.6 currently there are 4 identity modules and 2 identity reletad objects:

• User interface which exposes such operations on User object:

   /** The user identifier. */
   public Object getId();

   /** The user name. */
   public String getUserName();

   /** Set the password using proper encoding. */
   public void updatePassword(String password);

   /** Return true if the password is valid. */
   public boolean validatePassword(String password);

Important Note!!! Proper usage of getId() method is:

//Always use it like this:
user.getId().toString()

//NEVER use it like this:
(Long)user.getId()
(String)user.getId()

This is because of that ID depends on User implementation. It'll probably be String in LDAP and Long in Hibernate but it can be anything else...

• Role interface which exposes such operations on User object:

   /** The role identifier. */
   public Object getId();

   /** The role name used in security rules. This name can not be modified */
   public String getName();

   /** The role display name used on screens. This name can be modified */
   public String getDisplayName();

   /** */
   public void setDisplayName(String name);

• UserModule interface which exposes operations for users management

   /**Retrieve a user by its name.*/
   User findUserByUserName(String userName) throws IdentityException, IllegalArgumentException, NoSuchUserException;

   /**Retrieve a user by its id.*/
   User findUserById(Object id) throws IdentityException, IllegalArgumentException, NoSuchUserException;

   /**Retrieve a user by its id.*/
   User findUserById(String id) throws IdentityException, IllegalArgumentException, NoSuchUserException;

   /** Creates a new user with the specified name.*/
   User createUser(String userName, String password) throws IdentityException, IllegalArgumentException;

   /** Remove a user.*/
   void removeUser(Object id) throws IdentityException, IllegalArgumentException;

   /** Get a range of users.*/
   Set findUsers(int offset, int limit) throws IdentityException, IllegalArgumentException;

   /** Get a range of users.*/
   Set findUsersFilteredByUserName(String filter, int offset, int limit) throws IdentityException, IllegalArgumentException;

   /**Returns the number of users.*/
   int getUserCount() throws IdentityException, IllegalArgumentException;

• RoleModule interface which exposes operations for roles management

   /** Retrieves a role by its name*/
   Role findRoleByName(String name) throws IdentityException, IllegalArgumentException;

   /**Retrieve a collection of role from the role names.*/
   Set findRolesByNames(String[] names) throws IdentityException, IllegalArgumentException;

   /** Retrieves a role by its id.*/
   Role findRoleById(Object id) throws IdentityException, IllegalArgumentException;

   /** Retrieves a role by its id.*/
   Role findRoleById(String id) throws IdentityException, IllegalArgumentException;

   /** Create a new role with the specified name.*/
   Role createRole(String name, String displayName) throws IdentityException, IllegalArgumentException;

   /** Remove a role.*/
   void removeRole(Object id) throws IdentityException, IllegalArgumentException;

   /** Returns the number of roles. */
   int getRolesCount() throws IdentityException;

   /** Get all the roles */
   Set findRoles() throws IdentityException;

• MembershipModule interface which exposes operations for obtaining or defining relationship beetween users and roles:

   /** Return the set of role objects that a given user has.*/
   Set getRoles(User user) throws IdentityException, IllegalArgumentException;

   Set getUsers(Role role) throws IdentityException, IllegalArgumentException;

   /** Creates a relationship beetween a role and set of users. Other roles that have assotiontions with those users remain unaffected.*/
   void assignUsers(Role role, Set users) throws IdentityException, IllegalArgumentException;

   /** Creates a relationship beetween a user and set of roles. This operation will erase any other assotientions beetween the user and roles not specified in the provided set.*/
   void assignRoles(User user, Set roles) throws IdentityException, IllegalArgumentException;

   /** Returns role members based on rolename - depreciated method ethod here only for compatibility with old RoleModule interface */
   Set findRoleMembers(String roleName, int offset, int limit, String userNameFilter) throws IdentityException, IllegalArgumentException;

• UserProfileModule interface which exposes operations to access informations stored in User profile

   public Object getProperty(User user, String propertyName) throws IdentityException, IllegalArgumentException;

   public void setProperty(User user, String name, Object property) throws IdentityException, IllegalArgumentException;

   public Map getProperties(User user) throws IdentityException, IllegalArgumentException;

   public ProfileInfo getProfileInfo() throws IdentityException;

Important Note!!!

UserProfileModule.getProperty() method returns Object. In the JBoss Portal 2.6 Alpha this will always be String object. But normally you should check what object will be retreived using getProfileInfo() method.

• ProfileInfo interface which can be obtained using UserProfileModule and exposes information about User profile properties that are accessible:

   /** Returns a Map o PropertyInfo objects describing profile properties */
   public Map getPropertiesInfo();

   public PropertyInfo getPropertyInfo(String name);

• PropertyInfo interface expose methods to obtain information about accessible property in User profile

   public static final String ACCESS_MODE_READ_ONLY = "read-only";
   public static final String ACCESS_MODE_READ_WRITE = "read-write";
   public static final String USAGE_MANDATORY = "mandatory";
   public static final String USAGE_OPTIONAL = "optional";
   public static final String MAPPING_DB_TYPE_COLUMN = "column";
   public static final String MAPPING_DB_TYPE_DYNAMIC = "dynamic";

   public String getName();

   public String getType();

   public String getAccessMode();

   public String getUsage();

   public LocalizedString getDisplayName();

   public LocalizedString getDescription();

   public String getMappingDBType();

   public String getMappingLDAPValue();

   public String getMappingDBValue();

   public boolean isMappedDB();

   public boolean isMappedLDAP();

Important note!!!

At the current stage some of those informations (like getType()) may not affect the real state as implementation is still in a little flux.

Way to access identity modules

The best way to access identity modules is by using JNDI:

import org.jboss.portal.identity.UserModule;
import org.jboss.portal.identity.RoleModule;
import org.jboss.portal.identity.MembershipModule;
import org.jboss.portal.identity.UserProfileModule;

[...]

(UserModule)new InitialContext().lookup("java:portal/UserModule");
(RoleModule)new InitialContext().lookup("java:portal/RoleModule");
(MembershipModule)new InitialContext().lookup("java:portal/MembershipModule");
(UserProfileModule)new InitialContext().lookup("java:portal/UserProfileModule");

API changes since 2.4

• User interface

//Instead of: user.getEnabled()
userProfileModule.getProperty(user, User.INFO_USER_ENABLED);

//Instead of: user.setEnabled(value)
userProfileModule.setProperty(user, User.INFO_USER_ENABLED, value);

In the similar way you should change rest of methods that are missing in User interface in 2.6 by the call to the UserProfileModule:

//Instead of: user.getProperties()
userProfileModule.getProperties(user);

//Instead of: user.getGivenName()
userProfileModule.getProperty(user, User.INFO_USER_NAME_GIVEN);

//Instead of: user.getFamilyName()
userProfileModule.getProperty(user, User.INFO_USER_NAME_FAMILY);

//Instead of: user.getRealEmail()
userProfileModule.getProperty(user, User.INFO_USER_EMAIL_REAL);

//Instead of: user.getFakeEmail()
userProfileModule.getProperty(user, User.INFO_USER_EMAIL_FAKE);

//Instead of: user.getRegistrationDate()
userProfileModule.getProperty(user, User.INFO_USER_REGISTRATION_DATE);

//Instead of: user.getViewRealEmail()
userProfileModule.getProperty(user, User.INFO_USER_VIEW_EMAIL_VIEW_REAL);

//Instead of: user.getPreferredLocale()
userProfileModule.getProperty(user, User.INFO_USER_LOCALE);

//Instead of: user.getSignature()
userProfileModule.getProperty(user, User.INFO_USER_SIGNATURE);

//Instead of: user.getLastVisitDate()
userProfileModule.getProperty(user, User.INFO_USER_LAST_LOGIN_DATE);

• RoleModule interface

//Instead of 
//RoleModule.findRoleMembers(String roleName, int offset, int limit, String userNameFilter) throws IdentityException;
membershipModule.findRoleMembers(String roleName, int offset, int limit, String userNameFilter)

//Instead of
//RoleModule.setRoles(User user, Set roles) throws IdentityException;
membershipModule.assignRoles(User user, Set roles)

//Instead of
//RoleModule.getRoles(User user) throws IdentityException;
membershipModule.getRoles(User user)