eXo Platform 3.5

## Chapter 5. Developer reference

This chapter supplies you with the basic knowledge about overridden components and REST APIs implemented in eXo Collaboration via the following topics:

- Extension points

- Public REST APIs

## Extension points

There are some overridable components in eXo Collaboration so that you can control how these components work by implementing or extending default implementations and then reconfigure these new components in the configuration.xml file.

### ContentDAO

ContentDAO is an overridable component used in the Content application (or called RSS reader) of eXo Collaboration.

You can find the configuration file at WEB-INF/cs-extension/cs/content/content-service-configuration.xml with the declaration as below:

    <component>

      <key>org.exoplatform.content.service.ContentDAO</key>

      <type>org.exoplatform.content.service.impl.ContentDAOImpl</type>

    </component>

The example below is an example of plugin configuration:

    <external-component-plugins>

      <target-component>org.exoplatform.content.service.ContentDAO</target-component>

      <component-plugin>

        <name>rssreader.listener</name>

        <set-method>addPlugin</set-method>

        <type>org.exoplatform.content.service.RSSContentPlugin</type>

        <description>rss reader plugin</description>

      </component-plugin>

      <component-plugin>

        <name>description.listener</name>

        <set-method>addPlugin</set-method>

        <type>org.exoplatform.content.service.DescriptionPlugin</type>

        <description>Description plugin</description>

      </component-plugin>

    </external-component-plugins>

### ContactLifeCycle

ContactLifeCycle is an interface to extend the capabilities of eXo Platform. The ContactLifeCycle lets you be notified during the lifecycle of an address book's contact when a contact is added or modified.

An example of ContactLifeCycle has been implemented to integrate the Address Book application in the eXo Social's Spaces. See the following configuration at: ext/social-integration/src/main/resources/conf/portal/configuration.xml.

See the following example:

    <external-component-plugins>

      <target-component>org.exoplatform.contact.service.ContactService</target-component>

      <component-plugin>

        <name>ContactEventListener</name>

        <set-method>addListenerPlugin</set-method>

        <type>org.exoplatform.cs.ext.impl.ContactSpaceActivityPublisher</type>

      </component-plugin>

    </external-component-plugins>

Details: `ContactSpaceActivityPublisher` implements `ContactLifeCycle`. This implementation publishes activities in the space activity stream to notify of new and updated contacts in the space address book.

### Transport

Transport is an overridable component used in the Chat application of eXo Collaboration.

This overridable component is used to help users add the protocol to the Chat application, such as: ICQ, YAHOO, MSN, XMPP, AIM, GTALk.

The Chat application of eXo Collaboration only uses the XMPP protocol that is implemented in the XMPPTransport object.

### EventLifeCycle

EventLifeCycle is an extension point used in the Calendar application of eXo Collaboration. You can find the configuration file of this component at: ext/social-integration/src/main/resources/conf/portal/configuration.xml.

See the following example:

    <external-component-plugins>

      <target-component>org.exoplatform.calendar.service.CalendarService</target-component>

      <component-plugin>

        <name>CalendarEventListener</name>

        <set-method>addEventListenerPlugin</set-method>

        <type>org.exoplatform.cs.ext.impl.CalendarSpaceActivityPublisher</type>

      </component-plugin>

    </external-component-plugins>

Details: `CalendarSpaceActivityPublisher` implements `EventLifeCycle`. It writes activities in the space activity stream when events or tasks are added/modified.

## Public REST APIs

eXo Collaboration implements and provides many public REST APIS to help built-in applications, such as Calendar, Chat and Mail to communicate and transfer data with the server. By using these public REST APIs, extended or 3rd party applications can make use of this to develop cool web applications faster without much implementation.

### Calendar application

The Calendar application of eXo Collaboration uses CalendarWebservice to provide all APIs for working with calendars, such as creating personal/group calendars, sharing calendars, managing events/tasks.

The REST API of Calendar portlet is exposed by org.exoplatform.services.cs.calendar.CalendarWebservice class.

Service name | Service URL | Location | Description
--- | --- | --- | ---
CalendarWebservice | `$portalname/$restcontextname/cs/calendar` | - Maven groupId: org.exoplatform.cs - ArtifactId: exo.cs.web.webservice | Call extended services of the Calendar application.

Details:

- $portalname: The name of the portal

- $restcontextname: The context name of rest webapplication which is deployed to the "$portalname" portal.

- APIs usage:

Use the following APIs to build all functions of the Calendar application:

Name | Service URL endpoint | Parameters | Expected Values | Description
--- | --- | --- | --- | ---
checkpermission | /cs/calendar/checkPermission/{username}/{calendarId}/type} | username calendarId type | user id calendar id INVALID_TYPE = -1 / PRIVATE_TYPE = 0 / SHARED_TYPE = 1 / PUBLIC_TYPE = 2 | Check the permission of a user to a calendar, aiming at defining if the user has the edit permission to the calendar or not.
event | /cs/calendar/event/{username}/{eventFeedName} | username eventFeedName | user id string | Return a feed RSS that lists links to access a specific event.
feed | /cs/calendar/feed/{username}/{feedname}/{filename} | username feedname filename | username string string | Show the content of a feed that is a list of events in the "filename" file.
publicProcess | /cs/calendar/subscribe/{username}/{calendarId}/{type} | username calendarId type | user id calendar id INVALID_TYPE = -1 / PRIVATE_TYPE = 0 / SHARED_TYPE = 1 / PUBLIC_TYPE = 2 | Process the public calendar when having a remote access request.
privateProcess | cs/calendar/private/{username}/{calendarId}/{type} | username calendarID type | user id calendar id INVALID_TYPE = -1 / PRIVATE_TYPE = 0 / SHARED_TYPE = 1 / PUBLIC_TYPE = 2 | Process the public calendar when having a remote access request. User must enter username and password to access.
getEvents | /cs/calendar/events/personal/{type}/{calids}/{from}/{to}/{limit} | type calids from to limit | Event/Task Personal calendar id long long integer | Get personal events/tasks of a particular calendar by time range and limit the number of returned events/tasks by the '`limit`' parameter.
upcomingEvent | /cs/calendar/getissues/{currentdatetime}/{type}/{limit} | currentdatatime type limit | valid time format INVALID_TYPE = -1 / PRIVATE_TYPE = 0 / SHARED_TYPE = 1 / PUBLIC_TYPE = 2 integer | The list of upcoming events in a specific calendar.
updateStatus | /cs/calendar/updatestatus/{taskid}?statusid={status_id} | taskid status_id{noformat} | task id integer with following values: 1 - Need Action 2 - In Progress 3 - Completed 4 - Canceled | Update the status of a task.
getCalendars | /cs/calendar/getcalendars | `no param` |  | Get a list of calendars.

### Mail application

The Mail application of eXo Collaboration uses MailWebservice to provide all APIs for working with mail, such as sending/checking/storing mail to JCR.

REST API of the Mail portlet is exposed by org.exoplatform.services.cs.mail.MailWebservice class.

### Warning

The Mail portlet and its services are deprecated. It remains fully supported for eXo customers, however it will not receive any enhancement and will be removed from the product scope in the future.

Service name | Service URL | Location | Description
--- | --- | --- | ---
MailWebservice | `$portalname/$restcontextname/private/cs/mail` | - Maven groupId: org.exoplatform.cs - artifactId: exo.cs.web.webservice | This service is used to call extended services of the Mail application.

- APIs Usage:

Use the following APIs to build all functions of the Mail application:

Name | Service URL endpoint | Parameters | Expected Values | Description
--- | --- | --- | --- | ---
checkMail | /checkmail/{username}/{accountId}/{folderId/}/ | username accountID folderId | user id account id folder id | Check mails when having a request.
synchFolders | /synchfolders/{username}/{accountId}/ | username accountID | user id account id | Synchronize the mail folders in the clients and those in the mail server.
stopCheckMail | /stopcheckmail/{username}/{accountId}/ | username accountId | user id account id | Stop checking the mail.
getCheckMailJobInfo | /checkmailjobinfo/{username}/{accountId}/ | username accountId | user id account id | The method to get information of the mail-checking job.
searchemail | /searchemail/{keywords} | keywords | string | Search information from emails.

### Chat application

The Chat application uses some APIs to help users create a room, join a room, invite other users to room, or send files, and more.

The Chat application of eXo Collaboration uses two services: RESTXMPPService and FileExchangeService to do these tasks.

### Warning

The Chat portlet and its services are deprecated. It remains fully supported for eXo customers, however it will not receive any enhancement and will be removed from the product scope in the future.

#### RESTXMPPService

REST API RESTXMPPService of the Chat portlet is exposed by org.exoplatform.services.xmpp.rest.RESTXMPPService class.

Service name | Service URL | Location | Description
--- | --- | --- | ---
RESTXMPPService | `$portalname/$restcontextname/xmpp` | * Maven groupid: org.exoplatform.cs * exo.cs.eXoApplication.chat.service | Implement all actions sent to the Chat server;

- APIs Usage:

Use the following APIs to build all functions of the Chat application:

Name | Service URL endpoint | Parameters | Expected Values | Description
--- | --- | --- | --- | ---
loadJsResourceBundle | /loadJsResourceBundle/{locale}/ | locale | locale id | Read the language files in the Chat server.
createRoom | /muc/createroom/{username}/ | username room nickname | user id room name display name | Create a chat room or a group chat.
configRoom | /muc/configroom/{username}/ | username room | user id room name | Establish the configuration of a chat room.
getRoomConfigForm | /muc/getroomconfig/{username}/ | username room | user id room name | Get the configuration of a chat room created.
getRoomInfo | /muc/getroominfo/{username}/ | username room | user id string | Get the inforamtion of a chat room created.
getJoinedRooms | /muc/joinedrooms/{username}/ | username | user id | List chat rooms that a user has been joined.
getRooms | /muc/rooms/{username}/ | username | user id | Get a list of group chat or chat rooms created.
declineToRoom | /muc/decline/{username}/{inviter}/ | username inviter room reason | user id user id room name string | Refuse the invitation to join the chat room.
destroyRoom | /muc/destroy/{username} | username room reason altroom | user id room name string room id | Delete a chat room created.
inviteToRoom | /muc/invite/{username}/{invitee}/ | username invitee room reason | user id user id room name string | Invite other users to join a chat room.
joinRoom | /muc/join/{username}/ | username room nickname password | user id room name display name room password | Join a chat room.
leftRoom | /muc/leaveroom/{username}/ | username room | user id room name | Leave a chat room.
changeNickname | /muc/changenickname/{username}/{nickname}/ | username nickname | user id display name | Change the nickname of users.
changeAvailabilityStatusInRoom | /muc/changestatus/{username}/{mode}/ | username mood room status | user id presence type room name presence type | Change the status of a user in the chat room.
changeSubject | muc/changesubject/{username}/ | username room subject | user id room name string | Change the subject of a chat room.
manageRoleRoom | /muc/managerole/{username}/ | username room nickname role command | user id room name display name Participant / moderator grant/revoke | Change the role of each user in a chat room.
manageAffilationRoom | /muc/manageaffiliation/{username}/ | username room nickname affiliation command | user id room name display name String affiliation grant / revoke | Change the ownership of a chat room.
kickUserFromRoom | /muc/kick/{username}/ | username nickname room reason | user id display name room name string | Remove a user from the chat room.
banUserFromRoom | /muc/ban/{username}/ | username room name reason | user id room name user id string | Ban a user in the chat room.
addBoddyToRoster | /roster/add/{username}/{adduser} | username adduser nickname group | user id use id display name group id | Add a user into the contact list.
updateBoddy | /roster/update/{username}/{upduser}/ | username upduser nickname group | user id user id display name group id | Update new users into the contact list.
createGroup | /roster/group/{username}/{group}/ | username group | user id group id | Create a chat room.
askForSubscription | /askforsubscription/{username}/{askuser}/ | username askuser nickname | user id user id display name | Change the presence type of a user into Subscription.
cleanBuddylist | /rosterclean/{username}/ | username | user id | Remove a user from the contact list.
getAllHistory | /history/getmessages/{usernameto}/{isGroupChat}/ | usernameto isGroupChat usernamefrom | user id true / false user id | Get all the chat history of two users.
getHistoryBetweenDate | /history/getmessages/{usernameto}/{isGroupChat}/{from}/{to}/ | usernameto isgroupchat from to usernamefrom | user id true / false valid date format valid date format user id | Get the chat history of two users in a specific period.
getHistoryFromDateToNow | /history/getmessages/{usernameto}/{isGroupChat}/{from}/ | username isGroupChat from usernamefrom | user id true / false valid date format valid date format user id | Get the chat history of two users from a specific date to the current time.
getAllHistoryFile | /history/file/getmessages/{usernameto}/{isGroupChat}/{clientTimezoneOffset}/ | uernameto isGroupChat clientTimezoneOffset usernamefrom | user id true / false Long user id | Download all the chat history file of two users.
getHistoryFromDateToNowFile | /history/file/getmessages/{usernameto}/{isGroupChat}/{from}/{clientTimezoneOffset}/ | usernameto isGroupChat from clientTimezoneOffset usernamefrom | user id true / false valid date format Long user id | Download the chat history file of two users from a specific date to the current time
getHistoryBetweenDateFile | /history/file/getmessages/{usernameto}/{isGroupChat}/{from}/{to}/{clientTimezoneOffset}/ | usernameto isGroupChat from to clientTimezoneOffset usernamefrom | user id true / false valid date format valid date format Long user id | Download the chat history file of two users in the specific date.
getUserInfo | /getuserinfo/{username}/{needinfo}/ | username needinfo | user id string | Get the information of a user.
login2 | /login2/{forcache}/ | forcache |  | Allow a user to log in the chat server.
logout | /logout/{username}/{presencestatus}/ | username presencestatus | user id presencestatus | Allow a user to log out the chat server.
messageReceive | /history/messagereceive/{username}/{messageid}/ | username messageid | user id message id | Receive a message from other users.
removeBuddy | /roster/del/{username}/{removeboddy}/ | username removeboddy | user id user id | Delete a contact from the contact list.
removeTransport | /removetransport/{username}/{transport}/ | username transport | user id transport servive (e.g: Yahoo, XMPP) | Reset the presence type at the service that is being used.
searchUsers | /searchuser/{username}/ | username search byUsername byName byEmail searchService | user id string true / false true /false true / false string | Search users in the chat server.
sendMessage | /sendmessage/{username}/ | username messageBean | usesr id object | Send an message to other users.
sendMUCMessage | /muc/sendmessage/{username}/ | username messageBean | user id object | Send a message to multile users or a group.
setUserStatus | /sendstatus/{username}/{status}/ | username status | user id available/ unavailabe / do not disturb / away / extend away | Change the status of a user.
subscribeUser | /subscribeuser/{username}/{subsuser}/ | username subsuser | user id user id | Change presence type into Subcribed type.
unsubscribeUser | /unsubscribeuser/{username}/{unsubsuser}/ | username unsubsuser | user id user id | Change presence type into the Unsubscribed type.
acceptFile | /fileexchange/accept/{username}/{uuid}/ | username uuid | user id string | Accept getting a file sent from another user.
rejectFile | /fileexchange/reject/{username}/{uuid}/ | username uuid | user id string | Refuse getting a file sent from another user.
getPreviousStatus | /getprevstatus/{username}/ | username | user id | Get the tatus of a user in the last log-in.

#### FileExchangeService

REST API FileExchangeService for uploading files is defined in org.exoplatform.services.xmpp.rest.FileExchangeService class.

Service name | Service URL | Location | Description
--- | --- | --- | ---
FileExchangeService | `$portalname/$restcontextname/fileexchange` | - Maven groupid: org.exoplatform.cs - InterfactId: exo.cs.eXoApplication.chat.service | Upload a file to the server and inform the user that the file can be downloaded to the local computer.

- APIs usage: Use the following APIs to upload and send files to other users:

Name | Service URL endpoint | Parameters | Expected Values | Description
--- | --- | --- | --- | ---
upload | $portalname/$restcontextname/fileexchange | description username requestor isroom | string user id user id true / false | Upload a file to the server.