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