Skip to content
Permalink
Browse files
Add some basic readme documentation
  • Loading branch information
timothyjward committed Oct 2, 2020
1 parent 413c2e8 commit 13786ab194780f1519968573ede77dda64149321
Showing 4 changed files with 69 additions and 0 deletions.
@@ -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
@@ -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
@@ -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.
@@ -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`.

0 comments on commit 13786ab

Please sign in to comment.