documents/patterns.md - celix - Git at Google

 ---
 title: Apache Celix Services
 ---

 <!--
 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.
 -->

 # 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 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.

 ![Whiteboard Pattern](diagrams/whiteboard_pattern.png)

 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` installed
    and started. <br/>
    ![Celix Shell](diagrams/whiteboard_pattern_shell.png)
  - `celix_http_service_t` and `celix_websocket_service_t` services. These services can be picked up by the
    `Celix::http_admin` bundle to provide http url endpoints or websocket url endpoints. <br/>
    ![Celix HTTP Admin](diagrams/whiteboard_pattern_http_admin.png)
  - `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. Note that the `Celix::log_admin` bundle
    also uses a service on demand pattern (see below). <br/>
    ![Celix Log Admin](diagrams/whiteboard_pattern_log_sink.png)
  - 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 installed and started.


 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 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.

 ![Extender Pattern](diagrams/extender_pattern.png)

 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
 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`.
 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 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` (extendee) bundle.

 ```CMake
 #CMakeLists.txt
 add_celix_bundle(http_admin_extendee_bundle # <----------------------------------------------------------------------<1>
     VERSION 1.0.0
     NO_ACTIVATOR # <-------------------------------------------------------------------------------------------------<2>
 )
 file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/index.html" "<html><body>Hello World</body></html>") # <---------------------<3>
 celix_bundle_files(http_admin_extendee_bundle "${CMAKE_CURRENT_BINARY_DIR}/index.html" DESTINATION resources) # <----<4>
 celix_bundle_headers(http_admin_extendee_bundle "X-Web-Resource: /hello$<SEMICOLON>/resources") # <------------------<5>

 add_celix_container(extender_pattern_example_container # <-----------------------------------------------------------<6>
     BUNDLES
         Celix::http_admin
         http_admin_extendee_bundle
 )
 ```

 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

 A less known Apache Celix / OSGi pattern is the service on demand (SOD) pattern. With the SOD pattern,
 services are ad hoc 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 can be used to extract information about if and how
 a service on demand needs to be created.

 ![Service On Demand Pattern](diagrams/sod_pattern.png)

 Some Apache Celix bundles use the SOD pattern. For example:
  - The `Celix::log_admin` bundle creates and registers `celix_log_service_t` services already preconfigured for
    a requested logger name. <br/>
    ![Celix Log Admin](diagrams/sod_pattern_log_service.png)
  - The Celix PubSub bundles uses SOD to create and register `pubsub_publisher_t` services when these are requested
    with a valid "topic.name" and "topic.scope" filter attribute. For PubSub, the Celix PubSub Topology Manager monitors
    the `pubsub_publisher_t` requests and instructs the available Celix PubSub Admins to create
    `pubsub_publisher_t`. <br/>
    ![Celix PubSub](diagrams/sod_pattern_publisher_service.png)
  - The Apache Celix / OSGi remote services uses SOD, by ad hoc imported services only when they are discovered and
    requested.

 SOD 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.
	---
	title: Apache Celix Services
	---

	<!--
	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.
	-->

	# 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 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.

	![Whiteboard Pattern](diagrams/whiteboard_pattern.png)

	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` installed
	and started. <br/>
	![Celix Shell](diagrams/whiteboard_pattern_shell.png)
	- `celix_http_service_t` and `celix_websocket_service_t` services. These services can be picked up by the
	`Celix::http_admin` bundle to provide http url endpoints or websocket url endpoints. <br/>
	![Celix HTTP Admin](diagrams/whiteboard_pattern_http_admin.png)
	- `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. Note that the `Celix::log_admin` bundle
	also uses a service on demand pattern (see below). <br/>
	![Celix Log Admin](diagrams/whiteboard_pattern_log_sink.png)
	- 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 installed and started.





	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 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.

	![Extender Pattern](diagrams/extender_pattern.png)

	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
	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`.
	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 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` (extendee) bundle.

	```CMake
	#CMakeLists.txt
	add_celix_bundle(http_admin_extendee_bundle # <----------------------------------------------------------------------<1>
	VERSION 1.0.0
	NO_ACTIVATOR # <-------------------------------------------------------------------------------------------------<2>
	)
	file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/index.html" "<html><body>Hello World</body></html>") # <---------------------<3>
	celix_bundle_files(http_admin_extendee_bundle "${CMAKE_CURRENT_BINARY_DIR}/index.html" DESTINATION resources) # <----<4>
	celix_bundle_headers(http_admin_extendee_bundle "X-Web-Resource: /hello$<SEMICOLON>/resources") # <------------------<5>

	add_celix_container(extender_pattern_example_container # <-----------------------------------------------------------<6>
	BUNDLES
	Celix::http_admin
	http_admin_extendee_bundle
	)
	```

	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

	A less known Apache Celix / OSGi pattern is the service on demand (SOD) pattern. With the SOD pattern,
	services are ad hoc 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 can be used to extract information about if and how
	a service on demand needs to be created.

	![Service On Demand Pattern](diagrams/sod_pattern.png)

	Some Apache Celix bundles use the SOD pattern. For example:
	- The `Celix::log_admin` bundle creates and registers `celix_log_service_t` services already preconfigured for
	a requested logger name. <br/>
	![Celix Log Admin](diagrams/sod_pattern_log_service.png)
	- The Celix PubSub bundles uses SOD to create and register `pubsub_publisher_t` services when these are requested
	with a valid "topic.name" and "topic.scope" filter attribute. For PubSub, the Celix PubSub Topology Manager monitors
	the `pubsub_publisher_t` requests and instructs the available Celix PubSub Admins to create
	`pubsub_publisher_t`. <br/>
	![Celix PubSub](diagrams/sod_pattern_publisher_service.png)
	- The Apache Celix / OSGi remote services uses SOD, by ad hoc imported services only when they are discovered and
	requested.

	SOD 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.