You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@celix.apache.org by pn...@apache.org on 2022/06/06 20:51:37 UTC
[celix] branch feature/update_component_and_pattern_documentation updated: Updates patterns documentation.
This is an automated email from the ASF dual-hosted git repository.
pnoltes pushed a commit to branch feature/update_component_and_pattern_documentation
in repository https://gitbox.apache.org/repos/asf/celix.git
The following commit(s) were added to refs/heads/feature/update_component_and_pattern_documentation by this push:
new 46d8836b Updates patterns documentation.
46d8836b is described below
commit 46d8836b41afad04eebb77c257d56f328badde95
Author: Pepijn Noltes <pe...@gmail.com>
AuthorDate: Mon Jun 6 22:51:30 2022 +0200
Updates patterns documentation.
---
documents/patterns.md | 93 ++++++++++++++++++++++++++++++++++-----------------
1 file changed, 62 insertions(+), 31 deletions(-)
diff --git a/documents/patterns.md b/documents/patterns.md
index e14068d3..b57ce68c 100644
--- a/documents/patterns.md
+++ b/documents/patterns.md
@@ -23,45 +23,54 @@ limitations under the License.
There are several design patterns used in Apache Celix and OSGi.
## Whiteboard Pattern
-The whiteboard pattern is a pattern where the act of registering a service is enough to participate in an existing
-functionality. Another typical concept of the whiteboard pattern is that an application should
-still resolve and startup even if the bundle or bundles that pick up the
-whiteboard pattern services are absent.
+The whiteboard pattern is a pattern where the act of registering a service is enough to participate in or extend
+an existing functionality.
+A typical aspect of the whiteboard pattern is that an application should
+still resolve and startup even if the bundle or bundles that pick up the whiteboard pattern services are absent.
Many Apache Celix services are whiteboard services. For example:
- `celix_shell_command_t` and `celix::IShellCommand` services. These services can be
- picked up by the `Celix::shell` bundle, but applications should still work if there is no `Celix::shell` used.
+ picked up by the `Celix::shell` bundle, but applications should still work if there is no `Celix::shell` installed
+ and started.
- Services marked as remote service (`service.exported.interface=*`). These services will work fine - but only as
- local services - if there are no remote service bundles used.
- - `celix_log_sink_t` services. If there is no `Celix::log_admin` bundle used, the log sinks services will never be
- called, but the application should still work.
-
-On of the downsides of the whiteboard pattern is that it is not always clear why an application is not working as
-expected or what is missing to get the application working as expected. This is because it not an error
-if there are unused services, and as result there is no error/description to help a user what is missing.
-
-For example: A `log_collector` bundle with a `celix_log_sink_t` service is installed and started, so that logging can
-be sent to a central computer for analytic purposes.
-But no logging is received on the central computer. Initially it could seem
-that the `log_collector` bundle has a bug, especially because the application will not print any warnings or errors.
-But if the `Celix::log_admin` bundle is not installed and started the `log_collector` bundle
-`celix_log_sink_t` service will never be called, so installed and starting the `Celix::log_admin` is the issue in this
-example.
+ local services - if there are no remote service bundles installed and started.
+ - `celix_log_sink_t` services. If there is no `Celix::log_admin` bundle installed and started, the log sinks
+ services will never be called, but the application should still work.
+
+For modularity, the whiteboard pattern is a nice fit, because a whiteboard service admin does not need to know how
+many - if any - whiteboard services are going to be provided and how the implementation details work (as long as
+the implementation adheres to the service contract).
+
+Whiteboard pattern services are always [consumer types](https://docs.osgi.org/javadoc/osgi.annotation/8.0.0/org/osgi/annotation/versioning/ConsumerType.html), although for Apache Celix interfaces cannot be annotated as
+consumer or provider type.
+
+One of the downsides of the whiteboard pattern is that it is not always clear why an application is not working as
+expected or what is missing to get the application working as expected. This is because it is not an error
+if there are unused services, and as result there is no error to help a user to identify what is missing.
+
+For example: A `log_collector` bundle which provides a `celix_log_sink_t` service is installed and started,
+so that logging can be collected at in a central log database.
+But no logging is added to the central log database. Initially it could seem that the `log_collector` bundle
+does not work, especially because the application will not print any warnings or errors.
+But if the `Celix::log_admin` bundle is not installed and started the `log_collector` bundle provided
+`celix_log_sink_t` service will never be called, so installing and starting the `Celix::log_admin` is the issue
+in this example.
## Extender Pattern
The extender pattern is a design pattern which leverages the concept of resource containing bundles.
-With the extender pattern, functionality of a extender bundle can extended by installing (extendee) bundles
-containing certain resources files and/or bundle manifest entries.
+With the extender pattern, functionality of an extender bundle can be extended by installing so called extendee bundles.
+The extendee bundles contain certain resources files and/or bundle manifest entries which are used by the extender
+bundle.
-An example of the extender pattern is the `Celix::http_admin` bundle. The `Celix::http_admin` monitors installed
-bundles and read the bundles `MANIFEST.MF` file for a `X-Web-Resource` entry. If a `X-Web-Resource` entry is found,
-its value is used to setup new HTTP endpoint in the HTTP server of `Celix::http_admin` using the static web resources
-of the extendee bundle.
+An example of the extender pattern is the `Celix::http_admin` bundle. The extender bundle `Celix::http_admin`
+monitors installed bundles and reads bundle `MANIFEST.MF` entries for a `X-Web-Resource` entry.
+If a `X-Web-Resource` entry is found, its value is used to set up new HTTP endpoint in the HTTP server of
+the `Celix::http_admin` bundle using the static web resources of the extendee bundle.
### `Celix::http_admin` Extendee Bundle Example
The following example shows how a very simple `Celix::http_admin` extendee bundle, which provided a minimal
@@ -72,11 +81,11 @@ Remarks for the `Celix::http_admin` extendee bundle example:
2. Marks the bundle as a resource-only bundle, i.e. a bundle with no C or C++ activator.
3. Creates a very simple `index.html` file in CMake
4. Adds the `index.html` file to the `http_admin_extendee_bundle` bundle in the bundle directory resources.
-5. Adds a `X-Web-Resource` bundle manifest entry, which marks this bundle as an extendee bundle for the
+5. Adds a `X-Web-Resource` bundle manifest entry, which marks the bundle as an extendee bundle for the
`Celix::http_admin` bundle. See `Celix::http_admin` for more info. Note that `$<SEMICOLON>` is used,
because a literal `;` has a special meaning in CMake.
6. Create a container which installs and starts the `Celix::http_admin` (extender) bundle and the
- `http_admin_extendee_bundle` bundle.
+ `http_admin_extendee_bundle` (extendee) bundle.
```CMake
#CMakeLists.txt
@@ -98,9 +107,31 @@ add_celix_container(extender_pattern_example_container # <----------------------
When the `extender_pattern_example_container` executable is running the web address `http://localhost:8080/hello`
should show the content of the `index.html`
+
## Service on Demand (SOD) Pattern
-TODO example logging service and/or remote service
-TODO also mention FindHook for Java
+A less known Apache Celix / OSGi pattern is the service on demand (SOD) pattern. With the SOD pattern,
+service are adhoc registered at the moment they are requested.
+
+Where the whiteboard pattern can be used to extend functionality in modular and service oriented fashion, the SOD
+pattern can be used to use to provide more functional cohesive services to users in a service oriented fashion.
+
+For the SOD pattern, the service filter to request services is used to extract information about if and how
+a service on demand needs to be created.
+
+Some Apache Celix bundles use the SOD pattern. For example:
+ - The `Celix::log_admin` creates `celix_log_service` services already preconfigured for a requested logger name.
+ - The Apache Celix / OSGi remote services uses SOD, by adhoc imported services only when they are discovered and
+ requested.
+ - The Celix PubSub bundles uses SOD to create `pubsub_publisher` services when these are requested with a valid
+ "topic.name" and "topic.scope".
+
+SOD pattern services are always [provider types](https://docs.osgi.org/javadoc/osgi.annotation/8.0.0/org/osgi/annotation/versioning/ProviderType.html), although for Apache Celix interfaces cannot be annotated as
+consumer or provider type.
+
+For OSGi the [FindHook](https://docs.osgi.org/javadoc/osgi.core/8.0.0/org/osgi/framework/hooks/service/FindHook.html)
+service can be used to further fine tune which services are visible for bundle requesting a SOD service.
+Apache Celix does not yet support the FindHook service.
+
+
-
\ No newline at end of file