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 <[email protected]>
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`.
