From portal-commits at lists.jboss.org Tue Jan 30 18:55:58 2007
Content-Type: multipart/mixed; boundary="===============0817123182208254494=="
MIME-Version: 1.0
From: portal-commits at lists.jboss.org
To: portal-commits at lists.jboss.org
Subject: [portal-commits] JBoss Portal SVN: r6131 -
 docs/trunk/referenceGuide/en/modules.
Date: Tue, 30 Jan 2007 18:55:58 -0500
Message-ID: <E1HC2pS-0001Cs-CI@committer01.frg.pub.inap.atl.jboss.com>

--===============0817123182208254494==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- docs/trunk/referenceGuide/en/modules/identity.xml	2007-01-30 23:25:48 U=
TC (rev 6130)
+++ docs/trunk/referenceGuide/en/modules/identity.xml	2007-01-30 23:55:58 U=
TC (rev 6131)
@@ -10,19 +10,17 @@
     <para>This chapter addresses identity management in JBoss Portal 2.6</=
para>
     <sect1 id=3D"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 underlayi=
ng 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 i=
dentity related interfaces. The goal of
+            having such a fine grained API is to enable flexible implement=
ations based on different
+            identity storage like relational databases or LDAP servers. Th=
e Membership service takes care of managing the relationship
+            between user objects and role objects. The User Profile servic=
e is responsible for managing the profile of a user,
+            it has database and LDAP implementations as well as a mode tha=
t combines data from both.
         </para>
         <itemizedlist>
             <listitem>
                 <para>
-                    <emphasis role=3D"bold">User</emphasis>
-                    interface which exposes such operations on User object:
+                    The <emphasis role=3D"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 data=
base 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 implementat=
ion. 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 imple=
mentation. It'll probably be String object with the LDAP
+                    implementation and a Long object with the database imp=
lementation but it could be something else
+                    if one has chosen to make its own implementation.
                 </warning>
             </listitem>
             <listitem>
                 <para>
-                    <emphasis role=3D"bold">Role</emphasis>
-                    interface which exposes such operations on
-                    <emphasis role=3D"bold">User</emphasis>
-                    object:
+                    The <emphasis role=3D"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=3D"bold">UserModule</emphasis>
-                    interface which exposes operations for users management
+                    The <emphasis role=3D"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=3D"bold">RoleModule</emphasis>
-                    interface which exposes operations for roles management
+                    The <emphasis role=3D"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=3D"bold">MembershipModule</emphasis>
-                    interface which exposes operations for obtaining or de=
fining 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 ther=
e 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=3D"bold">MembershipModule</emphasis>
+                    interface exposes operations for obtaining or managing=
 relationships beetween users and roles.
+                    The role of this service is to decouple relationship i=
nformation from user and roles.
+                    Indeed while user role relationship is pretty straight=
forward 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=3D"bold">UserProfileModule</emphasis>
-                    interface which exposes operations to access informati=
ons stored in User profile.
+                    The <emphasis role=3D"bold">UserProfileModule</emphasi=
s>
+                    interface exposes operations to access and manage info=
rmations stored in User profile:
                 </para>
                 <programlisting>
                     <![CDATA[
@@ -213,17 +211,17 @@
                 ]]>
                 </programlisting>
                 <warning>
-                    UserProfileModule?.getProperty() method returns Object.
+                    UserProfileModule.getProperty() method returns an Obje=
ct.
                     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=3D"bold">ProfileInfo</emphasis>
-                    interface which can be obtained using
+                    The <emphasis role=3D"bold">ProfileInfo</emphasis>
+                    interface can be obtained using the
                     <emphasis role=3D"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=3D"bold">IdentityServiceController</emphasi=
s>
-                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=3D"bold">IdentityServiceController=
</emphasis>
+                mbean. You may want to inject it into your services like t=
his:
             </para>
             <programlisting>
                 <![CDATA[<depends optional-attribute-name=3D"IdentityServi=
ceController" proxy-type=3D"attribute">portal:service=3DModule,type=3DIdent=
ityServiceController</depends>]]>
             </programlisting>
             <para>
-                or simply obtain in your code using
-                <emphasis role=3D"bold">portal:service=3DModule,type=3DIde=
ntityServiceController</emphasis>
-                name. Please refer to JBoss Application Server documentati=
on 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=3D"bold">portal:service=3DModule,type=
=3DIdentityServiceController</emphasis>
+                name. Please refer to the JBoss Application Server documen=
tation 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=3D"bold">Role</emphasis>
                 interfaces some API usages changed. Here are the most impo=
rtant 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=3D"bold">User</emphasis>
-                        interface
+                        For the <emphasis role=3D"bold">User</emphasis> in=
terface:
                     </para>
                     <programlisting>
                         <![CDATA[
-                    //Instead of: user.getEnabled()
+                    // Instead of: user.getEnabled()
                     userProfileModule.getProperty(user, User.INFO_USER_ENA=
BLED);
 =

-                    //Instead of: user.setEnabled(value)
+                    // Instead of: user.setEnabled(value)
                     userProfileModule.setProperty(user, User.INFO_USER_ENA=
BLED, value);
 =

-                    In the similar way you should change rest of methods t=
hat are missing in User interface in 2.6 by the call to the UserProfileModu=
le?:
+                    // In a similar way you should change rest of methods =
that are missing in User interface in 2.6 by the call to the UserProfileMod=
ule
 =

-                    //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_NAM=
E_GIVEN);
 =

-                    //Instead of: user.getFamilyName()
+                    // Instead of: user.getFamilyName()
                     userProfileModule.getProperty(user, User.INFO_USER_NAM=
E_FAMILY);
 =

-                    //Instead of: user.getRealEmail()
+                    // Instead of: user.getRealEmail()
                     userProfileModule.getProperty(user, User.INFO_USER_EMA=
IL_REAL);
 =

-                    //Instead of: user.getFakeEmail()
+                    // Instead of: user.getFakeEmail()
                     userProfileModule.getProperty(user, User.INFO_USER_EMA=
IL_FAKE);
 =

-                    //Instead of: user.getRegistrationDate()
+                    // Instead of: user.getRegistrationDate()
                     userProfileModule.getProperty(user, User.INFO_USER_REG=
ISTRATION_DATE);
 =

-                    //Instead of: user.getViewRealEmail()
+                    // Instead of: user.getViewRealEmail()
                     userProfileModule.getProperty(user, User.INFO_USER_VIE=
W_EMAIL_VIEW_REAL);
 =

-                    //Instead of: user.getPreferredLocale()
+                    // Instead of: user.getPreferredLocale()
                     userProfileModule.getProperty(user, User.INFO_USER_LOC=
ALE);
 =

-                    //Instead of: user.getSignature()
+                    // Instead of: user.getSignature()
                     userProfileModule.getProperty(user, User.INFO_USER_SIG=
NATURE);
 =

-                    //Instead of: user.getLastVisitDate()
-                    userProfileModule.getProperty(user, User.INFO_USER_LAS=
T_LOGIN_DATE);
-
-                ]]>
+                    // Instead of: user.getLastVisitDate()
+                    userProfileModule.getProperty(user, User.INFO_USER_LAS=
T_LOGIN_DATE);]]>
                     </programlisting>
                 </listitem>
                 <listitem>
                     <para>
-                        <emphasis role=3D"bold">RoleModule</emphasis>
-                        interface
+                        The <emphasis role=3D"bold">RoleModule</emphasis> =
interface:
                     </para>
                     <programlisting>
                         <![CDATA[
-                    //Instead of
-                    //RoleModule.findRoleMembers(String roleName, int offs=
et, int limit, String userNameFilter) throws IdentityException;
+                    // Instead of
+                    // RoleModule.findRoleMembers(String roleName, int off=
set, 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 Ide=
ntityException;
+                    // Instead of
+                    // RoleModule.setRoles(User user, Set roles) throws Id=
entityException;
                     membershipModule.assignRoles(User user, Set roles)
 =

-                    //Instead of
-                    //RoleModule.getRoles(User user) throws IdentityExcept=
ion;
-                    membershipModule.getRoles(User user)
-
-                ]]>
+                    // Instead of
+                    // RoleModule.getRoles(User user) throws IdentityExcep=
tion;
+                    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 su=
pport in JBoss Portal. For additional
-            information you need to study more about
-            configuration of identity and specific implementations of iden=
tity 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 ena=
ble LDAP support in JBoss Portal.
+        For additional information you need to study more about configurat=
ion of identity and specific implementations of identity modules</para>
+        <para>There are two ways to achieve this:</para>
         <itemizedlist>
             <listitem>
                 <para>In


--===============0817123182208254494==--