<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="Core.OrganizationService">
  <title>Organization Service</title>

    <para>OrganizationService is the service that allows to access the
    Organization model. This model is composed of:</para>

    <itemizedlist>
      <listitem>
        <para>Users</para>
      </listitem>

      <listitem>
        <para>Groups</para>
      </listitem>

      <listitem>
        <para>Memberships</para>
      </listitem>
    </itemizedlist>

    <para>It is the basis of eXo personalization and authorizations in eXo and
    is used to all over the platform. The model is abstract and does not rely
    on any specific storage. Multiple implementations exist in eXo:</para>

    <itemizedlist>
      <listitem>
        <para>Hibernate: for storage into a RDBMS</para>
      </listitem>

      <listitem>
        <para>Jndi: for storage into a directory such as an LDAP or MS Active
        Directory</para>
      </listitem>

      <listitem>
        <para>Jcr: for storage inside a Java Content Repository</para>
      </listitem>
    </itemizedlist>

  <section id="Core.OrganizationService.OrganizationalModel">
    <title>Organizational Model</title>

    <section id="Core.OrganizationService.OrganizationalModel.User">
      <title>User</title>

      <itemizedlist>
        <listitem>
          <para>Username used as the identified</para>
        </listitem>

        <listitem>
          <para>Profile (identity and preferences)</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="Core.OrganizationService.OrganizationalModel.Group">
      <title>Group</title>

      <para>Gather a set of users</para>

      <itemizedlist>
        <listitem>
          <para>Applicative or business</para>
        </listitem>

        <listitem>
          <para>Tree structure</para>
        </listitem>

        <listitem>
          <para>No inheritance</para>
        </listitem>

        <listitem>
          <para>Expressed as /group/subgroup/subsubgroup</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="Core.OrganizationService.OrganizationalModel.Membership">
      <title>Membership</title>

      <itemizedlist>
        <listitem>
          <para>Qualifies the group belonging</para>
        </listitem>

        <listitem>
          <para>"Member of group as XXX"</para>
        </listitem>

        <listitem>
          <para>Expressed as : manager:/organization/hr, *:/partners</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section id="Core.OrganizationService.CustomOrganizationServiceImplementationInstructions">
    <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 id="Core.OrganizationService.CustomOrganizationServiceImplementationInstructions.BasicEntitiesImplementation">
      <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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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
      github server:</para>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/UserImpl.java">UserImpl</ulink></para>
        </listitem>

        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/UserProfileImpl.java">UserProfileImpl</ulink></para>
        </listitem>

        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/GroupImpl.java">GroupImpl</ulink></para>
        </listitem>

        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/MembershipImpl.java">MembershipImpl</ulink></para>
        </listitem>

        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/MembershipTypeImpl.java">MembershipTypeImpl</ulink></para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="Core.OrganizationService.CustomOrganizationServiceImplementationInstructions.UnitHandlersImplementation">
      <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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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
      github server:</para>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/UserHandlerImpl.java">UserHandlerImpl</ulink></para>
        </listitem>

        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/UserProfileHandlerImpl.java">UserProfileHandlerImpl</ulink></para>
        </listitem>

        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/GroupHandlerImpl.java">GroupHandlerImpl</ulink></para>
        </listitem>

        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/MembershipHandlerImpl.java">MembershipHandlerImpl</ulink></para>
        </listitem>

        <listitem>
          <para><ulink
          url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/MembershipTypeHandlerImpl.java">MembershipTypeHandlerImpl</ulink></para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="Core.OrganizationService.CustomOrganizationServiceImplementationInstructions.ExtendingBaseOrganizationServiceClass">
      <title>Extending BaseOrganizationService class</title>

      <para>Finally you need to create your main custom organization service
      class. It must extend <ulink
      url="https://github.com/exoplatform/core/tree/stable/2.4.x/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://github.com/exoplatform/core/tree/stable/2.4.x/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 github server: <ulink
      url="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/src/main/java/org/exoplatform/services/jcr/ext/organization/JCROrganizationServiceImpl.java">JCROrganizationServiceImpl</ulink>.</para>
    </section>

    <section id="Core.OrganizationService.CustomOrganizationServiceImplementationInstructions.VerificationOfCompliance">
      <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://github.com/exoplatform/core/tree/stable/2.4.x/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="https://github.com/exoplatform/jcr-services/tree/stable/1.14.x/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 section
        called "Organization Service TCK tests configuration"</para>
      </note>
    </section>
  </section>
</section>