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.... + + <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.... + + <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.... + + <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.... + + <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.... + + <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... + </listitem> + + <listitem> + <para><ulink + url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA... + </listitem> + + <listitem> + <para><ulink + url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA... + </listitem> + + <listitem> + <para><ulink + url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA... + </listitem> + + <listitem> + <para><ulink + url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA... + </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.... + + <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.... + + <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"... + 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.... + + <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....;. + 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.... + </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.... + + <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.... + + <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....;. + 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.... + </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.... + + <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.... + + <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....;. + 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.... + </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.... + + <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.... + + <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....;. + 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.... + </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.... + + <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.... + + <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....;. + 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.... + </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... + </listitem> + + <listitem> + <para><ulink + url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA... + </listitem> + + <listitem> + <para><ulink + url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA... + </listitem> + + <listitem> + <para><ulink + url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA... + </listitem> + + <listitem> + <para><ulink + url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA... + </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....;. + 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.... + 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... + </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.... + + <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/"&... + </listitem> + + <listitem> + <para><ulink + url="http://mojo.codehaus.org/build-helper-maven-plugin/">bu... + </listitem> + + <listitem> + <para><ulink + url="http://maven.apache.org/plugins/maven-surefire-plugin/">... + </listitem> + </itemizedlist> Check <ulink + url="http://svn.exoplatform.org/projects/jcr-services/tags/1.14.5-GA... + 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>