eXo Platform 3.5

## Chapter 73. Organization Service

OrganizationService is the service that allows to access the Organization model. This model is composed of:

- Users

- Groups

- Memberships

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:

- Hibernate: for storage into a RDBMS

- Jndi: for storage into a directory such as an LDAP or MS Active Directory

- Jcr: for storage inside a Java Content Repository

## Organizational Model

### User

- Username used as the identified

- Profile (identity and preferences)

### Group

Gather a set of users

- Applicative or business

- Tree structure

- No inheritance

- Expressed as /group/subgroup/subsubgroup

### Membership

- Qualifies the group belonging

- "Member of group as XXX"

- Expressed as : manager:/organization/hr, *:/partners

## Custom Organization Service implementation instructions

To create a custom organization service you need to implement a several interfaces and extend some classes which will be listed below.

### Basic entities implementation

First of all you need to create classes implementing the following interfaces (each of which represent a basic unit of organization service):

- org.exoplatform.services.organization.User

  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.

- org.exoplatform.services.organization.UserProfile

  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.

- org.exoplatform.services.organization.Group

  This is the interface for the group data model.

- org.exoplatform.services.organization.Membership

  This is the interface for the membership data model.

- org.exoplatform.services.organization.MembershipType

  This is the interface for the membership type data model.

### Note

After each set method is called the developer must call UserHandler.saveUser (GroupHandler.saveGroup, MembershipHandler.saveMembership etc.) method to persist the changes.

You can find examples of the mentioned above implementations at subversion server:

- UserImpl

- UserProfileImpl

- GroupImpl

- MembershipImpl

- MembershipTypeImpl

### Unit handlers implementation

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:

- User handler

  - org.exoplatform.services.organization.UserHandler

    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.

  - org.exoplatform.services.organization.ExtendedUserHandler

    Optional. Implement it if you want to be able to use Digest access authentication i.e. you need a one way password encyption for authentication.

  - org.exoplatform.services.organization.UserEventListenerHandler

    Optional. Provides the ability to get the list of org.exoplatform.services.organization.UserEventListener. List should be unmodifiable to prevent modification outside of org.exoplatform.services.organization.UserHandler.

- User profile handler

  - org.exoplatform.services.organization.UserProfileHandler

    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.

  - org.exoplatform.services.organization.UserProfileEventListenerHandler

    Optional. Provides the ability to get the list of org.exoplatform.services.organization.UserProfileEventListener. List should be unmodifiable to prevent modification outside of org.exoplatform.services.organization.UserProfileHandler.

- Group handler

  - org.exoplatform.services.organization.GroupHandler

    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.

  - org.exoplatform.services.organization.GroupEventListenerHandler

    Optional. Provides the ability to get the of org.exoplatform.services.organization.GroupEventListener. List should be unmodifiable to prevent modification outside of org.exoplatform.services.organization.GroupHandler.

- Membership handler

  - org.exoplatform.services.organization.MembershipHandler

    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.

  - org.exoplatform.services.organization.MembershipEventListenerHandler

    Optional. Provides the ability to get the of org.exoplatform.services.organization.MembershipEventListener. List should be unmodifiable to prevent modification outside of org.exoplatform.services.organization.MembershipHandler.

- Membership type handler

  - org.exoplatform.services.organization.MembershipTypeHandler

    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.

  - org.exoplatform.services.organization.MembershipTypeEventListenerHandler

    Optional. Provides the ability to get the list of org.exoplatform.services.organization.MembershipTypeEventListener. List should be unmodifiable to prevent modification outside of org.exoplatform.services.organization.MembershipTypeHandler.

You can find examples of the mentioned above implementations at subversion server:

- UserHandlerImpl

- UserProfileHandlerImpl

- GroupHandlerImpl

- MembershipHandlerImpl

- MembershipTypeHandlerImpl

### Extending BaseOrganizationService class

Finally you need to create your main custom organization service class. It must extend org.exoplatform.services.organization.BaseOrganizationService. BaseOrganizationService class contains organization service unit handlers as protected fields, so you can initialize them in accordance to your purposes. It also has org.exoplatform.services.organization.OrganizationService interface methods' implementations. This is the class you need to mention in the configuration file if you want to use your custom organization service.

You can find example of such class at subversion server: JCROrganizationServiceImpl.

### Verification of compliance

Make sure that your custom organization service implementation is fully compliant with Organization Service TCK tests. Tests are available as maven artifact:

groupId - org.exoplatform.core

artifactId - exo.core.component.organization.tests

You can find TCK tests package source code here

### Note

In order to be able to run unit tests you may need to configure the following maven plugins:

- maven-dependency-plugin

- build-helper-maven-plugin

- maven-surefire-plugin

Check pom.xml 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"

## Related articles and how-tos

- JCR Organization Service

- Update ConversationState when user's Membership changed

- Organization Service Initializer

- How to Access User Profile in your code

- How to create your own Organization Listener

- How to manipulate Users and Memberships Programmatically

Copyright © 2009-2012. All rights reserved. eXo Platform SAS