Documentation (TODO: more)

*) Licensing

This code is licensed using the GPL licenses.
Applications are GPL-v3, libraries are LGPL-v3
and server code is licensed using AGPL-v3.

Also included is the junit-4.4.jar which is
licensed using CPL. Junit sources are available
at http://junit.org.

*) Introduction

This is a proof of concept for a
mechnaism that allows Android device
to support intra-process and inter-process
asynchronous messaging. I'm now adding supprt
for inter-device communication.

*) Goal

A system of loosely coupled independent
components can exchange messages asynchronously.
These components can reside in one process,
multiple process, multiple devices running
on any hardware, with any OS in any language.

Further more sending a message is non-blocking
and the receiver can not directly effect the
sender. In addition the system should be able
to gracefully handle communication degradation
including complete outages and still remain
responsive to the user. Of course functionality
will be diminished or lost but the user will
remain in control.

The order of the messages sent from component
A to component B is in the order sent. But there
is no ordering guarantees when multiple components
send messages simultaneously to the same component.

*) Package overview

The 'android' directory contains, obviously,
android specific classes and the 'java' directory
contains generic/pure java classes. Because we
have pure java classes that my have instances
of system specific classes (McMgr/McBase) or
indeed even extend classes which are system
specific symbolic links are used so that the
sources appear in the required directories.

Using the symbolic links reduces the amount of
code duplication as was my solution to this
protability issues of different implemenations
of classes. There maybe a better solution, but
for now this seems to work.

... More info in the future ...

*) Building

Ant/Eclipse are the developement environment.
This is my first use of Ant so the these are
probably very sub-optimal. I moved from a pure
Eclipse build system because it appears Ant
is the only way to have Eclipse automatically
build jar library files.

The build.xml in the 'root' will build the
all subprojects. In common-build.xml is a
set of common ant tasks and in
android/android-build.xml is a set of common
android ant tasks. Each of the subprojects
has its own build.xml.