[aries-typedevent] branch main updated: Add some basic readme documentation

[ti...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

timothyjward pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/aries-typedevent.git


The following commit(s) were added to refs/heads/main by this push:
     new 13786ab  Add some basic readme documentation
13786ab is described below

commit 13786ab194780f1519968573ede77dda64149321
Author: Tim Ward <ti...@apache.org>
AuthorDate: Fri Oct 2 18:08:24 2020 +0100

    Add some basic readme documentation
---
 README.md                                             | 19 +++++++++++++++++++
 org.apache.aries.typedevent.bus/README.md             | 16 ++++++++++++++++
 org.apache.aries.typedevent.remote/README.md          | 15 +++++++++++++++
 .../README.md                                         | 19 +++++++++++++++++++
 4 files changed, 69 insertions(+)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bb2b3fe
--- /dev/null
+++ b/README.md
@@ -0,0 +1,19 @@
+Apache Aries OSGi Type Safe Events
+-------------------------------------------------------------
+
+This project contains an implementation of the OSGi Typed Safe Event Service specification, and related services to allow the Type Safe Event Service to interoperate with remote event sources and consumers.
+
+The Type Safe Event Service is defined in Chapter 157 of the OSGi R7 specification. This specification is not yet final, but public drafts of this specification are available from the OSGi Alliance.
+
+Given that the specification is non-final the OSGi API declared in this project is subject to change at any time up to its official release. Also the behaviour of this implementation may not always be up-to-date with the latest wording in the specification . The project maintainers will, however try to keep pace with the specification, and to ensure that the implementations remain compliant with any relevant OSGi specifications.
+
+# Modules
+
+The following modules are available for use in OSGi
+
+1. org.apache.aries.typedevent.bus :- This project contains the implementations of the OSGi Type Safe Event Service.
+2. org.apache.aries.typedevent.remote :- This reactor project is the home for "Remote Event" implementations which allow the Typed Event Service to interoperate with remote systems.
+
+## Which modules should I use?
+
+If you're looking at this project then you almost certainly want to use org.apache.aries.typedevent.bus. If you also want to support distributed events then you should also take a look at the various remote event implementations present
\ No newline at end of file
diff --git a/org.apache.aries.typedevent.bus/README.md b/org.apache.aries.typedevent.bus/README.md
new file mode 100644
index 0000000..c22d842
--- /dev/null
+++ b/org.apache.aries.typedevent.bus/README.md
@@ -0,0 +1,16 @@
+Apache Aries OSGi Type Safe Event Service implementation
+-------------------------------------------------------------
+
+This project contains an implementation of the OSGi Typed Safe Event Service specification.
+
+The Type Safe Event Service is defined in Chapter 157 of the OSGi R7 specification. This specification is not yet final, but public drafts of this specification are available from the OSGi Alliance.
+
+Given that the specification is non-final the OSGi API declared in this project is subject to change at any time up to its official release. Also the behaviour of this implementation may not always be up-to-date with the latest wording in the specification . The project maintainers will, however try to keep pace with the specification, and to ensure that the implementations remain compliant with any relevant OSGi specifications.
+
+## Usage
+
+When started this bundle registers a `TypedEvenBus` service which users can use to send events. Events can be received by registering a `TypedEventHandler` or `UntypedEventHandler` whiteboard service.
+
+Events flowing through the system can be monitored with the `TypedEventMonitor` service, which is also registered at startup. This implementation offers limited history playback.
+
+The configuration PID for the Aries implementation is `org.apache.aries.typedevent.bus`. Currently there are no configuration properties
diff --git a/org.apache.aries.typedevent.remote/README.md b/org.apache.aries.typedevent.remote/README.md
new file mode 100644
index 0000000..b000a52
--- /dev/null
+++ b/org.apache.aries.typedevent.remote/README.md
@@ -0,0 +1,15 @@
+Apache Aries OSGi Type Safe Event Service Remote Integration
+-------------------------------------------------------------
+
+This reactor project contains modules which integrate OSGi Typed Safe Events with remote event sources
+and remote event consumers.
+
+Over time it is expected that more modules will be added, each providing remote access using a different technology. 
+
+## Common code
+
+All modules are expected to conform to the common API rules defined by this project. Namely that
+
+* A marker property is added to the untyped event data, indicating that the event is from a remote source (see the constants class for details)
+* A RemoteEventMonitor (which is aware of whether events are from a remote source)
+* A service property that listeners can advertise, to indicate whether their topic/filter should be considered for remote events.
diff --git a/org.apache.aries.typedevent.remote/org.apache.aries.typedevent.remote.remoteservices/README.md b/org.apache.aries.typedevent.remote/org.apache.aries.typedevent.remote.remoteservices/README.md
new file mode 100644
index 0000000..f3239cf
--- /dev/null
+++ b/org.apache.aries.typedevent.remote/org.apache.aries.typedevent.remote.remoteservices/README.md
@@ -0,0 +1,19 @@
+Apache Aries Type Safe Events over OSGi Remote Services
+-------------------------------------------------------------
+
+This project uses OSGi remote services to provide inter-framework integration between OSGi Typed Safe Event Services.
+
+## How does it work
+
+Each instance registers a `RemoteEventBus` service with a service property indicating the event topic(s) and filter(s) for events that it is interested in. 
+
+Each instance consumes the `RemoteEventBus` instances from other nodes and creates `UntypedEventHandler` instances for each topic/filter that the remote nodes have advertised interest in.
+
+Events can then be routed from the local framework to a remote framework by passing the events to the relevant `RemoteEventBus`. When a `RemoteEventBus` receives an event it then publishes it locally using the `TypedEventBus` 
+
+
+## Usage
+
+This module should work automatically when a Remote Services provider is running.
+
+For topic/filters in the local framework to be considered as "remotable" the service should add the `RemoteEventConstants.RECEIVE_REMOTE_EVENTS` property with a value of true. Otherwise this module must be configured to select more local listeners using the PID `org.apache.aries.typedevent.remote.remoteservices`.