[portal-commits] JBoss Portal SVN: r6131 - docs/trunk/referenceGuide/en/modules.

Author: julien(a)jboss.com Date: 2007-01-30 18:55:58 -0500 (Tue, 30 Jan 2007) New Revision: 6131 Modified: docs/trunk/referenceGuide/en/modules/identity.xml Log: updated the identity doc wording Modified: docs/trunk/referenceGuide/en/modules/identity.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/identity.xml 2007-01-30 23:25:48 UTC (rev 6130) +++ docs/trunk/referenceGuide/en/modules/identity.xml 2007-01-30 23:55:58 UTC (rev 6131) @@ -10,19 +10,17 @@ <para>This chapter addresses identity management in JBoss Portal 2.6</para> <sect1 id="management_api"> <title>Identity management API</title> - <para>In JBoss Portal currently there are 4 identity modules and 2 identity reletad objects. The goal about - having such wide API is to - enable flexible implementations related to different underlaying technologies like RDBS or LDAP. With such - data storage mechanisms things like - User/Role relationship are defined in slightly different way. Another thing is User Profile where - information about user can be grabbed from database - column or LDAP entry or even mixed. + <para>Since JBoss Portal 2.6 there are 4 identity services and 2 identity related interfaces. The goal of + having such a fine grained API is to enable flexible implementations based on different + identity storage like relational databases or LDAP servers. The Membership service takes care of managing the relationship + between user objects and role objects. The User Profile service is responsible for managing the profile of a user, + it has database and LDAP implementations as well as a mode that combines data from both. </para> <itemizedlist> <listitem> <para> - <emphasis role="bold">User</emphasis> - interface which exposes such operations on User object: + The <emphasis role="bold">org.jboss.portal.identity.User</emphasis> + interface represents a user and exposes the following operations: </para> <programlisting> <![CDATA[ @@ -40,28 +38,30 @@ ]]> </programlisting> <warning> - Important Note!!! Proper usage of getId() method is: + Important Note! The proper usage of getId() method is: <programlisting> <![CDATA[ - //Always use it like this: - user.getId().toString() + // Always use it like this: + user.getId().toString(); - //NEVER use it like this: - (Long)user.getId() - (String)user.getId() + // Do not use it like this: + + // We would get a Long object if we are using the database implementation + (Long)user.getId(); + + // We would get a String with an LDAP server + (String)user.getId(); ]]> </programlisting> - 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... - + This is because the ID value depends on the User implementation. It'll probably be String object with the LDAP + implementation and a Long object with the database implementation but it could be something else + if one has chosen to make its own implementation. </warning> </listitem> <listitem> <para> - <emphasis role="bold">Role</emphasis> - interface which exposes such operations on - <emphasis role="bold">User</emphasis> - object: + The <emphasis role="bold">org.jboss.portal.identity.Role</emphasis> interface represents a Role + and exposes the following operations: </para> <programlisting> <![CDATA[ @@ -81,8 +81,8 @@ </listitem> <listitem> <para> - <emphasis role="bold">UserModule</emphasis> - interface which exposes operations for users management + The <emphasis role="bold">org.jboss.portal.identity.UserModule</emphasis> + interface exposes operations for users management: </para> <programlisting> <![CDATA[ @@ -114,8 +114,8 @@ </listitem> <listitem> <para> - <emphasis role="bold">RoleModule</emphasis> - interface which exposes operations for roles management + The <emphasis role="bold">org.jboss.portal.identity.RoleModule</emphasis> + interface exposes operations for roles management: </para> <programlisting> <![CDATA[ @@ -169,14 +169,12 @@ </listitem> <listitem> <para> - <emphasis role="bold">MembershipModule</emphasis> - interface which exposes operations for obtaining or defining relationship beetween users and roles. - The role of this module is to - decouple relationship information from user and roles. Whith different implementations definition of - such relationship can be specified on different sides. - With Relational DB it's quite simple, but in LDAP there are several ways to store such information. - Role of this module is to bring flexibility - in defining contract beetween user and role. + The <emphasis role="bold">MembershipModule</emphasis> + interface exposes operations for obtaining or managing relationships beetween users and roles. + The role of this service is to decouple relationship information from user and roles. + Indeed while user role relationship is pretty straightforward with a relational database (using + a many to many relationship with an intermediary table), with an LDAP server there a different + ways to define relationships between users and roles. </para> <programlisting> <![CDATA[ @@ -198,8 +196,8 @@ </listitem> <listitem> <para> - <emphasis role="bold">UserProfileModule</emphasis> - interface which exposes operations to access informations stored in User profile. + The <emphasis role="bold">UserProfileModule</emphasis> + interface exposes operations to access and manage informations stored in User profile: </para> <programlisting> <![CDATA[ @@ -213,17 +211,17 @@ ]]> </programlisting> <warning> - UserProfileModule?.getProperty() method returns Object. + UserProfileModule.getProperty() method returns an Object. In most cases with DB backend it will always be String object. But normally you should check what object will be retreived using getProfileInfo() method. </warning> </listitem> <listitem> <para> - <emphasis role="bold">ProfileInfo</emphasis> - interface which can be obtained using + The <emphasis role="bold">ProfileInfo</emphasis> + interface can be obtained using the <emphasis role="bold">UserProfileModule</emphasis> - and exposes information about User profile properties that are accessible: + and exposes meta information of a profile: </para> <programlisting> <![CDATA[ @@ -276,7 +274,7 @@ </itemizedlist> <sect2> - <title>Way to access identity modules</title> + <title>Ways to access identity modules</title> <para> The best way to access identity modules is by using JNDI: </para> @@ -295,18 +293,18 @@ </programlisting> <para> - Another way to do this is, if you are fimiliar with JBoss Mikrokernel architecture is by obtaining - <emphasis role="bold">IdentityServiceController</emphasis> - mbean. You may want to inject it into your mbean like this: + Another way to do this is, if you are fimiliar with JBoss Mikrokernel architecture is to + get the <emphasis role="bold">IdentityServiceController</emphasis> + mbean. You may want to inject it into your services like this: </para> <programlisting> <![CDATA[<depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends>]]> </programlisting> <para> - or simply obtain in your code using - <emphasis role="bold">portal:service=Module,type=IdentityServiceController</emphasis> - name. Please refer to JBoss Application Server documentation if you want to learn more - about MBeans. Once you obtained the object you can use it: + or simply obtain in your code by doing a lookup using + the <emphasis role="bold">portal:service=Module,type=IdentityServiceController</emphasis> + name. Please refer to the JBoss Application Server documentation if you want to learn more + about service MBeans. Once you obtained the object you can use it: </para> <programlisting> @@ -328,90 +326,81 @@ and <emphasis role="bold">Role</emphasis> interfaces some API usages changed. Here are the most important changes you will need to aply to your - code - while migrating your aplication to 2.6: + code while migrating your aplication to 2.6: </para> <itemizedlist> <listitem> <para> - <emphasis role="bold">User</emphasis> - interface + For the <emphasis role="bold">User</emphasis> interface: </para> <programlisting> <![CDATA[ - //Instead of: user.getEnabled() + // Instead of: user.getEnabled() userProfileModule.getProperty(user, User.INFO_USER_ENABLED); - //Instead of: user.setEnabled(value) + // 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?: + // In a 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() + // Instead of: user.getProperties() userProfileModule.getProperties(user); - //Instead of: user.getGivenName() + // Instead of: user.getGivenName() userProfileModule.getProperty(user, User.INFO_USER_NAME_GIVEN); - //Instead of: user.getFamilyName() + // Instead of: user.getFamilyName() userProfileModule.getProperty(user, User.INFO_USER_NAME_FAMILY); - //Instead of: user.getRealEmail() + // Instead of: user.getRealEmail() userProfileModule.getProperty(user, User.INFO_USER_EMAIL_REAL); - //Instead of: user.getFakeEmail() + // Instead of: user.getFakeEmail() userProfileModule.getProperty(user, User.INFO_USER_EMAIL_FAKE); - //Instead of: user.getRegistrationDate() + // Instead of: user.getRegistrationDate() userProfileModule.getProperty(user, User.INFO_USER_REGISTRATION_DATE); - //Instead of: user.getViewRealEmail() + // Instead of: user.getViewRealEmail() userProfileModule.getProperty(user, User.INFO_USER_VIEW_EMAIL_VIEW_REAL); - //Instead of: user.getPreferredLocale() + // Instead of: user.getPreferredLocale() userProfileModule.getProperty(user, User.INFO_USER_LOCALE); - //Instead of: user.getSignature() + // Instead of: user.getSignature() userProfileModule.getProperty(user, User.INFO_USER_SIGNATURE); - //Instead of: user.getLastVisitDate() - userProfileModule.getProperty(user, User.INFO_USER_LAST_LOGIN_DATE); - - ]]> + // Instead of: user.getLastVisitDate() + userProfileModule.getProperty(user, User.INFO_USER_LAST_LOGIN_DATE);]]> </programlisting> </listitem> <listitem> <para> - <emphasis role="bold">RoleModule</emphasis> - interface + The <emphasis role="bold">RoleModule</emphasis> interface: </para> <programlisting> <![CDATA[ - //Instead of - //RoleModule.findRoleMembers(String roleName, int offset, int limit, String userNameFilter) throws IdentityException; + // 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; + // 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) - - ]]> + // Instead of + // RoleModule.getRoles(User user) throws IdentityException; + membershipModule.getRoles(User user)]]> </programlisting> </listitem> </itemizedlist> </sect2> </sect1> <sect1> - <title>How to enable LDAP in JBoss Portal</title> - <para>Here are just few simple steps you'll need to enable LDAP support in JBoss Portal. For additional - information you need to study more about - configuration of identity and specific implementations of identity modules - </para> - <para>There are two ways to achive this goal:</para> + <title>How to enable LDAP usage in JBoss Portal</title> + <para>We'll describe here the simple steps that you'll need to enable LDAP support in JBoss Portal. + For additional information you need to study more about configuration of identity and specific implementations of identity modules</para> + <para>There are two ways to achieve this:</para> <itemizedlist> <listitem> <para>In