Event admin

bundles/CMakeLists.txt

@@ -22,3 +22,4 @@ add_subdirectory(shell)
 add_subdirectory(remote_services)
 add_subdirectory(cxx_remote_services)
 add_subdirectory(components_ready_check)
+add_subdirectory(event_admin)

bundles/event_admin/CMakeLists.txt

@@ -0,0 +1,24 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+celix_subproject(EVENT_ADMIN "Option to enable building the Event Admin bundles" ON)
+if (EVENT_ADMIN)
+    add_subdirectory(event_admin_api)
+    add_subdirectory(event_admin)
+    add_subdirectory(examples)
+endif()
+

bundles/event_admin/README.md

@@ -0,0 +1,42 @@
+---
+title: Event Admin
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Introduction
+
+The Event Admin subproject implements the [OSGi Event Admin Service Specification](https://docs.osgi.org/specification/osgi.cmpn/7.0.0/service.event.html). It consists of event admin implementation and corresponding examples.
+
+### Event Admin
+
+The Event Admin provides the pubsub mechanism for in-process communication.
+
+| **Bundle**           | `Celix::event_admin` |
+|----------------------|----------------------|
+| **Configuration**    | *None*               |
+
+
+## Building
+
+To build the Event Admin subproject, the cmake option `BUILD_EVENT_ADMIN` or conan option `build_event_admin`must be enabled. These options are disabled by default.
+If we want to build the event admin examples, the cmake option `BUILD_EVENT_ADMIN_EXAMPLES` or conan option `build_event_admin_examples` must be enabled. These options are disabled by default.
+
+## Event Admin Bundles
+
+* [EventAdmin](event_admin/README.md) - The event admin implementation.

bundles/event_admin/event_admin/CMakeLists.txt

@@ -0,0 +1,58 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+# 
+#   http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+set(EVENT_ADMIN_SRC
+        src/celix_event_admin_activator.c
+        src/celix_event_admin.c
+        src/celix_event.c
+        src/celix_event_adapter.c
+        )
+
+set(EVENT_ADMIN_DEPS
+        Celix::event_admin_api
+        Celix::log_helper
+        Celix::framework
+        Celix::utils
+        )
+
+add_celix_bundle(event_admin
+    SYMBOLIC_NAME "apache_celix_event_admin"
+    VERSION "1.0.0"
+    NAME "Apache Celix Event Admin"
+    GROUP "Celix/event_admin"
+    FILENAME celix_event_admin
+    SOURCES
+    ${EVENT_ADMIN_SRC}
+)
+
+target_link_libraries(event_admin PRIVATE ${EVENT_ADMIN_DEPS})
+
+target_include_directories(event_admin PRIVATE ${CMAKE_CURRENT_LIST_DIR}/src)
+
+install_celix_bundle(event_admin EXPORT celix COMPONENT event_admin)
+
+#Setup target aliases to match external usage
+add_library(Celix::event_admin ALIAS event_admin)
+
+if (ENABLE_TESTING)
+    add_library(event_admin_cut STATIC ${EVENT_ADMIN_SRC})
+    target_include_directories(event_admin_cut PUBLIC ${CMAKE_CURRENT_LIST_DIR}/src)
+    target_link_libraries(event_admin_cut PUBLIC ${EVENT_ADMIN_DEPS})
+    add_subdirectory(gtest)
+endif(ENABLE_TESTING)
+
+

bundles/event_admin/event_admin/README.md

@@ -0,0 +1,107 @@
+---
+title: Event Admin Service
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Event Admin
+
+The Event Admin provides the pubsub mechanism for in-process communication. It has implemented two delivery mechanisms:
+- Synchronous delivery
+- Asynchronous delivery
+
+In addition, the Event Admin provides an adapter for the celix framework-level event. It maps the celix framework-level event to the
+event admin pubsub model, and events are delivered asynchronously.
+
+### Cmake options
+
+    BUILD_EVENT_ADMIN=OFF
+
+### Conan options
+
+    build_event_admin=false
+
+### Software Design
+
+#### Synchronous Delivery
+
+In the synchronous delivery, the event handler will be notified in the caller's thread. And the `sendEvent` method will return after all the event handlers have been called.
+The diagram of synchronous delivery is shown in the following figure:
+
+![sync_delivery_seq.png](diagrams/sync_delivery_seq.png)
+
+#### Asynchronous Delivery
+
+In the asynchronous delivery, the event handler will be notified in a separate event-delivery thread. And the `postEvent` method will return immediately.
+The diagram of asynchronous delivery is shown in the following figure:
+
+![sync_delivery_seq.png](diagrams/async_delivery_seq.png)
+
+In the above figure, if the event handler sets the "event.delivery" property to "async.ordered", each event handler can hold 
+at most one event-delivery thread at a time, so that events can be delivered in order. If the event handler sets the 
+"event.delivery" property to "async.unordered", the event handler can hold multiple event-delivery threads at the same 
+time, so that events can be delivered in parallel.
+
+
+#### Event Adapter
+
+In order to present a consistent view of all the events occurring in the system, the Event Admin provides an adapter for the celix framework-level event.
+The events are mapped as follows:
+
+- **Celix Framework Event**
+
+For celix framework Event, we map the celix framework condition id to the event admin event topic. The event admin event properties are none.
+The details mappings are shown in the following table:
+
+| Celix Framework Condition ID       | Event Admin Event topic                     |
+|------------------------------------|---------------------------------------------|
+| CELIX_CONDITION_ID_FRAMEWORK_READY | "org/osgi/framework/FrameworkEvent/STARTED" |
+| CELIX_CONDITION_ID_FRAMEWORK_ERROR | "org/osgi/framework/FrameworkEvent/ERROR"   |
+
+- **Celix Bundle Event**
+
+For celix bundle Event, we map the celix bundle event type to the event admin event topic. And The event admin event properties are as follows:
+- bundle.id
+- bundle.symbolicName
+- bundle.version
+
+The details mappings are shown in the following table:
+
+| Celix Bundle Event Type        | Event Admin Event topic                      |
+|--------------------------------|----------------------------------------------|
+| CELIX_BUNDLE_EVENT_INSTALLED   | "org/osgi/framework/BundleEvent/INSTALLED"   |
+| CELIX_BUNDLE_EVENT_STARTED     | "org/osgi/framework/BundleEvent/STARTED"     |
+| CELIX_BUNDLE_EVENT_STOPPED     | "org/osgi/framework/BundleEvent/STOPPED"     |
+| CELIX_BUNDLE_EVENT_UPDATED     | "org/osgi/framework/BundleEvent/UPDATED"     |
+| CELIX_BUNDLE_EVENT_UNINSTALLED | "org/osgi/framework/BundleEvent/UNINSTALLED" |
+| CELIX_BUNDLE_EVENT_RESOLVED    | "org/osgi/framework/BundleEvent/RESOLVED"    |
+| CELIX_BUNDLE_EVENT_UNRESOLVED  | "org/osgi/framework/BundleEvent/UNRESOLVED"  |
+
+- **Celix Service Event**
+
+For celix service Event, we map the celix service register/unregister operation to the event admin event topic. And The event admin event properties are as follows:
+- service.id
+- service.objectClass
+- service.pid
+
+The details mappings are shown in the following table:
+
+| Celix Service Operation | Event Admin Event topic                         |
+|-------------------------|-------------------------------------------------|
+| Register Service        | "org/osgi/framework/ServiceEvent/REGISTERED"    |
+| Unregister Service      | "org/osgi/framework/ServiceEvent/UNREGISTERING" |

bundles/event_admin/event_admin/diagrams/async_delivery_seq.puml

@@ -0,0 +1,43 @@
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+@startuml
+'https://plantuml.com/sequence-diagram
+
+participant EventPublisher
+box "EventAdmin"
+participant EventAdmin
+== init ==
+create queue EventQueue
+EventAdmin -> EventQueue: new
+create control DeliveryEventThreads
+EventAdmin -> DeliveryEventThreads: new
+end box
+== postEvent ==
+EventPublisher -> EventAdmin: postEvent
+EventAdmin -> EventAdmin: collect event handlers for event
+EventAdmin -> EventQueue: add event with a list of event handlers to the queue
+EventQueue --> EventAdmin: return
+EventAdmin --> EventPublisher: return
+loop has event in queue
+    EventQueue -> DeliveryEventThreads: get event and event handler
+    DeliveryEventThreads -> EventHandler: handleEvent
+    return
+    alt event has been notified to all event handlers
+    DeliveryEventThreads -> EventQueue: remove event from queue
+    end alt
+end loop
+
+@enduml

bundles/event_admin/event_admin/diagrams/sync_delivery_seq.puml

@@ -0,0 +1,27 @@
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+@startuml
+'https://plantuml.com/sequence-diagram
+
+EventPublisher -> EventAdmin: sendEvent
+EventAdmin -> EventAdmin: collect event handlers for event
+loop  for each event handler
+    EventAdmin -> EventHandler: handleEvent
+    EventHandler --> EventAdmin: return
+end loop
+EventAdmin --> EventPublisher: return
+
+@enduml