[exo-jcr-commits] exo-jcr SVN: r5519 - jcr/branches/1.15.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/core.
do-not-reply at jboss.org
do-not-reply at jboss.org
Wed Jan 25 10:36:50 EST 2012
Author: dkuleshov
Date: 2012-01-25 10:36:50 -0500 (Wed, 25 Jan 2012)
New Revision: 5519
Modified:
jcr/branches/1.15.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/core/organization-service.xml
Log:
EXOJCR-1717: added a chapter to docbook describing how to implement a custom organization service
Modified: jcr/branches/1.15.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/core/organization-service.xml
===================================================================
--- jcr/branches/1.15.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/core/organization-service.xml 2012-01-25 15:04:48 UTC (rev 5518)
+++ jcr/branches/1.15.x/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/core/organization-service.xml 2012-01-25 15:36:50 UTC (rev 5519)
@@ -107,6 +107,373 @@
</section>
<section>
+ <title>Custom Organization Service implementation instructions</title>
+
+ <para>To create a custom organization service you need to implement a
+ several interfaces and extend some classes which will be listed
+ below.</para>
+
+ <section>
+ <title>Basic entities implementation</title>
+
+ <para>First of all you need to create classes implementing the following
+ interfaces (each of which represent a basic unit of organization
+ service):</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/User.java">org.exoplatform.services.organization.User</ulink></para>
+
+ <para>This is the interface for a User data model. The
+ OrganizationService implementor can use the different strategy to
+ implement this class, he can use the native field for each get
+ method or use a Map to hold the user data.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/UserProfile.java">org.exoplatform.services.organization.UserProfile</ulink></para>
+
+ <para>This is the interface for a UserProfile data model. The
+ implementor should have an user map info in the implementation. The
+ map should only accept the java.lang.String for the key and the
+ value.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/Group.java">org.exoplatform.services.organization.Group</ulink></para>
+
+ <para>This is the interface for the group data model.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/Membership.java">org.exoplatform.services.organization.Membership</ulink></para>
+
+ <para>This is the interface for the membership data model.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/MembershipType.java">org.exoplatform.services.organization.MembershipType</ulink></para>
+
+ <para>This is the interface for the membership type data
+ model.</para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>After each set method is called the developer must call
+ UserHandler.saveUser (GroupHandler.saveGroup,
+ MembershipHandler.saveMembership etc.) method to persist the
+ changes.</para>
+ </note>
+
+ <para>You can find examples of the mentioned above implementations at
+ subversion server:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/UserImpl.java">UserImpl</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/UserProfileImpl.java">UserProfileImpl</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/GroupImpl.java">GroupImpl</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/MembershipImpl.java">MembershipImpl</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/MembershipTypeImpl.java">MembershipTypeImpl</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Unit handlers implementation</title>
+
+ <para>After you created basic organization service unit instances you
+ need to create classess to handle them e.g. to persist changes, to add
+ listener etc. For that purpose you need to implement a several
+ interfaces correspondingly:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>User handler</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/UserHandler.java">org.exoplatform.services.organization.UserHandler</ulink></para>
+
+ <para>This class is acted as a sub component of the organization
+ service. It is used to manage the user account and broadcast the
+ user event to all the registered listener in the organization
+ service. The user event can be: new user event, update user
+ event and delete user event. Each event should have 2 phases:
+ pre event and post event. The method createUser , saveUser and
+ removeUser broadcast the event at each phase so the listeners
+ can handle the event properly.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/ExtendedUserHandler.java">org.exoplatform.services.organization.ExtendedUserHandler</ulink></para>
+
+ <para><emphasis role="bold">Optional</emphasis>. Implement it if
+ you want to be able to use <ulink
+ url="http://en.wikipedia.org/wiki/Digest_access_authentication">Digest
+ access authentication</ulink> i.e. you need a one way password
+ encyption for authentication.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/UserEventListenerHandler.java">org.exoplatform.services.organization.UserEventListenerHandler</ulink></para>
+
+ <para><emphasis role="bold">Optional</emphasis>. Provides the
+ ability to get the list of <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/UserEventListener.java">org.exoplatform.services.organization.UserEventListener</ulink>.
+ List should be unmodifiable to prevent modification outside of
+ <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/UserHandler.java">org.exoplatform.services.organization.UserHandler</ulink>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>User profile handler</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/UserProfileHandler.java">org.exoplatform.services.organization.UserProfileHandler</ulink></para>
+
+ <para>This interface is acted as a sub interface of the
+ organization service. It is used to manage the the UserProfile
+ record, the extra information of an user such address, phone...
+ The interface should allow the developer create, delete and
+ update a UserProfile. and broadcast the event to the user
+ profile event listeners.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/UserProfileEventListenerHandler.java">org.exoplatform.services.organization.UserProfileEventListenerHandler</ulink></para>
+
+ <para><emphasis role="bold">Optional</emphasis>. Provides the
+ ability to get the list of <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/UserProfileEventListener.java">org.exoplatform.services.organization.UserProfileEventListener</ulink>.
+ List should be unmodifiable to prevent modification outside of
+ <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/UserProfileHandler.java">org.exoplatform.services.organization.UserProfileHandler</ulink>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Group handler</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/GroupHandler.java">org.exoplatform.services.organization.GroupHandler</ulink></para>
+
+ <para>This class is acted as a sub component of the organization
+ service. It is used to manage the group and broadcast the group
+ event to all the registered listener in the organization
+ service. The group event can be: new group event, update group
+ event and delete group event. Each event should have 2 phases:
+ pre event and post event. The methods createGroup, saveGroup and
+ removeGroup broadcast the event at each phase so the listeners
+ can handle the event properly.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/GroupEventListenerHandler.java">org.exoplatform.services.organization.GroupEventListenerHandler</ulink></para>
+
+ <para><emphasis role="bold">Optional</emphasis>. Provides the
+ ability to get the of <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/GroupEventListener.java">org.exoplatform.services.organization.GroupEventListener</ulink>.
+ List should be unmodifiable to prevent modification outside of
+ <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/GroupHandler.java">org.exoplatform.services.organization.GroupHandler</ulink>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Membership handler</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/MembershipHandler.java">org.exoplatform.services.organization.MembershipHandler</ulink></para>
+
+ <para>This class is acted as a sub component of the organization
+ service. It is used to manage the membership - the relation of
+ user , group, and membership type - and broadcast the membership
+ event to all the registered listener in the organization
+ service. The membership event can be: new linked membership and
+ delete the membership type event. Each event should have 2
+ phases: pre event and post event. The method linkMembership and
+ removeMembership broadcast the event at each phase so the
+ listeners can handle the event properly.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/MembershipEventListenerHandler.java">org.exoplatform.services.organization.MembershipEventListenerHandler</ulink></para>
+
+ <para><emphasis role="bold">Optional</emphasis>. Provides the
+ ability to get the of <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/MembershipEventListener.java">org.exoplatform.services.organization.MembershipEventListener</ulink>.
+ List should be unmodifiable to prevent modification outside of
+ <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/MembershipHandler.java">org.exoplatform.services.organization.MembershipHandler</ulink>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Membership type handler</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/MembershipTypeHandler.java">org.exoplatform.services.organization.MembershipTypeHandler</ulink></para>
+
+ <para>This class is acted as a sub component of the organization
+ service. It is used to manage the membership - the relation of
+ user , group, and membership type - and broadcast the membership
+ event to all the registered listener in the organization
+ service. The membership event can be: new linked membership and
+ delete the membership type event. Each event should have 2
+ phases: pre event and post event. The method linkMembership and
+ removeMembership broadcast the event at each phase so the
+ listeners can handle the event properly.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/MembershipTypeEventListenerHandler.java">org.exoplatform.services.organization.MembershipTypeEventListenerHandler</ulink></para>
+
+ <para><emphasis role="bold">Optional</emphasis>. Provides the
+ ability to get the list of <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/MembershipTypeEventListener.java">org.exoplatform.services.organization.MembershipTypeEventListener</ulink>.
+ List should be unmodifiable to prevent modification outside of
+ <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/MembershipTypeHandler.java">org.exoplatform.services.organization.MembershipTypeHandler</ulink>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>You can find examples of the mentioned above implementations at
+ subversion server:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/UserHandlerImpl.java">UserHandlerImpl</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/UserProfileHandlerImpl.java">UserProfileHandlerImpl</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/GroupHandlerImpl.java">GroupHandlerImpl</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/MembershipHandlerImpl.java">MembershipHandlerImpl</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/MembershipTypeHandlerImpl.java">MembershipTypeHandlerImpl</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Extending BaseOrganizationService class</title>
+
+ <para>Finally you need to create your main custom organization service
+ class. It must extend <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/BaseOrganizationService.java">org.exoplatform.services.organization.BaseOrganizationService</ulink>.
+ BaseOrganizationService class contains organization service unit
+ handlers as protected fields, so you can initialize them in accordance
+ to your purposes. It also has <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.api/src/main/java/org/exoplatform/services/organization/OrganizationService.java">org.exoplatform.services.organization.OrganizationService</ulink>
+ interface methods' implementations. This is the class you need to
+ mention in the configuration file if you want to use your custom
+ organization service.</para>
+
+ <para>You can find example of such class at subversion server: <ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/src/main/java/org/exoplatform/services/jcr/ext/organization/JCROrganizationServiceImpl.java">JCROrganizationServiceImpl</ulink>.</para>
+ </section>
+
+ <section>
+ <title>Verification of compliance</title>
+
+ <para>Make sure that your custom organization service implementation is
+ fully compliant with Organization Service TCK tests. Tests are available
+ as maven artifact:</para>
+
+ <para>groupId - <emphasis>org.exoplatform.core</emphasis></para>
+
+ <para>artifactId -
+ <emphasis>exo.core.component.organization.tests</emphasis></para>
+
+ <para>You can find TCK tests package source code <ulink
+ url="https://anonsvn.jboss.org/repos/exo-jcr/core/tags/2.4.5-GA/exo.core.component.organization.tests/">here</ulink></para>
+
+ <note>
+ <para>In order to be able to run unit tests you may need to configure
+ the following maven plugins:<itemizedlist>
+ <listitem>
+ <para><ulink
+ url="http://maven.apache.org/plugins/maven-dependency-plugin/">maven-dependency-plugin</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://mojo.codehaus.org/build-helper-maven-plugin/">build-helper-maven-plugin</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://maven.apache.org/plugins/maven-surefire-plugin/">maven-surefire-plugin</ulink></para>
+ </listitem>
+ </itemizedlist> Check <ulink
+ url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA/pom.xml">pom.xml</ulink>
+ file to find out one of the ways to configure maven project object
+ model. More detailed description you can find in the dedicated chapter
+ called "Organization Service TCK tests configuration"</para>
+ </note>
+ </section>
+ </section>
+
+ <section>
<title>Related articles and how-tos</title>
<itemizedlist>
More information about the exo-jcr-commits
mailing list