MAPIStore 1.0 Development Guide¶

MAPIStore 1.0 Development Guide

What is MAPIStore?¶

MAPIStore is the SAL component of OpenChange server. SAL stands for Storage Abstraction Layer. It is the component used by OpenChange Server to push/get information (messages, folders) to/from storage backends. It is designed as a library called within OpenChange Server and it accesses backends compiled as dynamic shared object (DSO) and loaded when mapistore is initialized.

The main objective of mapistore is to provide an interface layer with a common set of atomic functions (operations) used to trigger and dispatch data and commands to the appropriate backend. MAPIStore relies on a backend mechanism specifically designed to transparently handle some of the MAPI semantics required by any Exchange compatible server.

The initial idea was to provide to OpenChange a highly customizable storage backend mechanism which would fit in any situation and any environments. One of the greatest limitation we have found with existing groupware is the storage layer which is generally limited to a single solution, service or format and is neither scalable nor modifiable when user requirements evolve upon time.

MAPIStore solves this problem and go beyond classical limitations. It is not a revolutionary concept, but the way openchange uses it makes the whole difference and offer administrators an innovative way to customize storage.

MAPIStore allows you to:

use a different backend for any top-folder
transparently move/copy data across backends
develop new backends quickly
access all the different backends through an unique API

For example (assuming all associated backends were developed) a user could have the following storage organization for his mailbox:

Mails stored using an IMAP backend (Cyrus-IMAP or dovecot)
Calendar items stored in CalDAV or pushed in Google calendar
Sent emails and archives/backup stored in a compression backend
Tasks stored in a MySQL database
Notes stored on the filesystem

If the user is not satisfied with one of the backend's performance, they would just have to use an administration tool, change the backend, wait for the replication, synchronization to finish and there data will be available from the new backend.

Information can be completely decentralized, stored on one of several servers and still be accessible transparently from OpenChange server.

Getting started¶

Getting Source code¶

Using mapistore v1 requires to use a different development tree than trunk. You will need to checkout the code from our current mapistore v1 development branches:

svn co http://svnmirror.openchange.org/openchange/branches/sogo-good

Refer to HowTo Install OpenChange From Source (but use svn command above instead of trunk) for instructions on requirements and how to build openchange.

This branch also relies on the sogo backend developed by inverse.ca which provides the most up to date backend's implementation using mapistore v1.
For instructions on how to download and build the backend, refers to HowTo Setup SOGo with OpenChange Server.

Why isn't mapistore v1 available in trunk?¶

Back in February 2010, we have decided to move from our existing mapistore v1 interface to a brand new and completely redesigned mapistore v2 interface. This new interface was introducing new concepts, fixing limitation of v1 implementation. This was a massive work and while it started very well, the effort was too big for the small number of people working on it and became abandoned, while v1 implementation kept progressing.

It means that mapistore v2 in trunk is not usable in current state and will progressively be replaced step by step with an updated version of mapistore v1 covered in this documentation, introducing new concepts progressively.

MAPIStore architecture overview¶

URI and scope¶

A URI is the key (and only) element mapistore and calling applications rely on in order to access and perform operation on a specific backend.

It is made of a prefixing namespace followed by data specific to the backend:

namespace: This is the unique identifier associated to your backend. It is made of your backend's name followed by ://
backend's specific data: This is a set of data that doesn't have any meaning for the calling application but is relevant for the backend. While the format of this data is completely specific to your backend, backends generally set information such as username, password or folder name within the destination system the backend manages.

{namespace}{backend's specific data}

sogo://user:password@folder/
java://user##folder/

Contexts¶

An Exchange user mailbox is (roughly) represented as a top folder (The Mailbox name) holding root (sub) folders (Inbox, Outbox, Calendar, Contacts, Notes, Tasks etc.). In MAPIStore, we consider that we shouldn't have to use the same backend for everything. We should be able to use a backend for Inbox, another for Calendar and so on.

This is where the notion of mapistore context steps in. A context is a sandbox created by a backend when you access root folder. For every operation you perform on this root folder or any data within this folder, the same created context will be used. For example, if we want to open the message Rates in /Inbox/Holidays/, we will:

Create a context on Inbox (it opens the folder)
Open the Holidays folder using the Inbox context
Access the message using the Inbox context

OpenChange

Wiki