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 3ddbae03 Adds whiteboard pattern documentation
3ddbae03 is described below
commit 3ddbae031e36412b77daa18b23c6af8adb56b7c5
Author: Pepijn Noltes <[email protected]>
AuthorDate: Tue May 31 23:09:29 2022 +0200
Adds whiteboard pattern documentation
---
documents/components.md | 8 ++++---
documents/patterns.md | 55 +++++++++++++++++++++++++++++++++++--------------
2 files changed, 44 insertions(+), 19 deletions(-)
diff --git a/documents/components.md b/documents/components.md
index 2f20555b..85aa6d97 100644
--- a/documents/components.md
+++ b/documents/components.md
@@ -25,10 +25,12 @@ Components can provide services and depend on services.
Components are configure
Service dependencies will influence the component's lifecycle as a component
will only be active when all required
dependencies are available.
-The DM is responsible for managing the co7mponent's service dependencies, the
component's lifecycle and when
+The DM is responsible for managing the component's service dependencies, the
component's lifecycle and when
to register/unregister the component's provided services.
-Note that the Apache Celix Dependency Manager is inspired by the [Apache Felix
Dependency
Manager](http://felix.apache.org/documentation/subprojects/apache-felix-dependency-manager.html),
adapted to Apache Celix and the C/C++ usage.
+Note that the Apache Celix Dependency Manager is inspired by the
+[Apache Felix Dependency
Manager](http://felix.apache.org/documentation/subprojects/apache-felix-dependency-manager.html),
+adapted to Apache Celix and the C/C++ usage.
# Component Lifecycle
Each component has its own lifecycle.
@@ -342,7 +344,7 @@ CELIX_GEN_BUNDLE_ACTIVATOR(
## Example: Component with a provided service in C++
The following example shows how a C++ component that provide a C++
`celix::IShellCommand` service
-and a C `elix_shell_command` service. For a C++ component it's possible to
provide C and C++ services.
+and a C `celix_shell_command` service. For a C++ component it's possible to
provide C and C++ services.
Remarks for the C++ example:
1. If a component provides a C++ services, it also expected that the component
implementation inherits the service
diff --git a/documents/patterns.md b/documents/patterns.md
index 6dfd6545..e14068d3 100644
--- a/documents/patterns.md
+++ b/documents/patterns.md
@@ -19,26 +19,53 @@ See the License for the specific language governing
permissions and
limitations under the License.
-->
-# Apache Celix / OSGi patterns
-TODO rephrase
-There are several design patterns typical for Apache Celix and/or OSGi that
are worth mentioned.
+# Apache Celix / OSGi patterns
+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.
+
+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.
+ - 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.
+
+
+
## Extender Pattern
-The extender pattern is a design pattern which leverages the concept of
bundles containing resources.
-It is a pattern where functionality of an extender bundle can be extended by
installing other (extendee) bundles
+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.
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 web resources to the `Celix::http_admin`. This can be used to
dynamically add/remove static web resources
-to an HTTP server.
+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.
### `Celix::http_admin` Extendee Bundle Example
The following example shows how a very simple `Celix::http_admin` extendee
bundle, which provided a minimal
-hello world `index.html` page for the `Celix::http_admin` to pick up.
-
+hello world `index.html` page for the `Celix::http_admin` to pick up.
Remarks for the `Celix::http_admin` extendee bundle example:
1. Creates a bundle which will function as an extendee bundle for the
`Celix::http_admin`.
@@ -68,12 +95,8 @@ add_celix_container(extender_pattern_example_container #
<----------------------
)
```
-## Whiteboard Pattern
-
-TODO example http_admin with http service
-
-
-
+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
