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 13bf1c15 Updates extender pattern documentation
13bf1c15 is described below
commit 13bf1c15275527e50b94a776200e8f3bb0954474
Author: Pepijn Noltes <[email protected]>
AuthorDate: Mon May 30 22:57:00 2022 +0200
Updates extender pattern documentation
---
documents/diagrams/extender_pattern.png | Bin 0 -> 17297 bytes
.../extender_pattern.puml} | 30 ++++++------
documents/diagrams/service_on_demand_pattern.png | Bin 0 -> 9649 bytes
.../service_on_demand_pattern.puml} | 28 ++++-------
documents/diagrams/whiteboard_pattern.png | Bin 0 -> 12574 bytes
.../whiteboard_pattern.puml} | 26 +++++-----
documents/patterns.md | 53 ++++++++++++++++++++-
.../readme_c_examples/CMakeLists.txt | 15 ++++++
8 files changed, 101 insertions(+), 51 deletions(-)
diff --git a/documents/diagrams/extender_pattern.png
b/documents/diagrams/extender_pattern.png
new file mode 100644
index 00000000..16b8ad25
Binary files /dev/null and b/documents/diagrams/extender_pattern.png differ
diff --git a/documents/patterns.md b/documents/diagrams/extender_pattern.puml
similarity index 59%
copy from documents/patterns.md
copy to documents/diagrams/extender_pattern.puml
index eea8f629..91c91cfa 100644
--- a/documents/patterns.md
+++ b/documents/diagrams/extender_pattern.puml
@@ -1,15 +1,10 @@
----
-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
@@ -17,18 +12,21 @@ 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.
--->
-
-# OSGi pattern in Apache Celix
-
-## Extender Pattern
-TODO example http_admin with html resources
+@startuml
+rectangle "Extendee Bundle" as ExtendeeBundle<<bundle>>
+rectangle "Extender Bundle" as ExtenderBundle<<bundle>>
+rectangle "Plain Bundle" as PlainBundle<<bundle>>
-## Whiteboard Pattern
+rectangle ExtendeeBundle {
+ file resource as "META-INF/extendee_resource.txt"
+ file metainf as "META-INF/MANIFEST.MF"
+}
-TODO example http_admin with http service
-## Service on Demand (SOD) Pattern
+ExtenderBundle .[dotted].> ExtendeeBundle: <<inspects>>
+ExtenderBundle .[dotted].> PlainBundle: <<inspects>>
+ExtenderBundle .[dashed].> resource: <<uses>>
+ExtenderBundle .[dashed].> metainf: <<reads>>
-TODO example logging service and/or remote service
+@enduml
diff --git a/documents/diagrams/service_on_demand_pattern.png
b/documents/diagrams/service_on_demand_pattern.png
new file mode 100644
index 00000000..b76b7b83
Binary files /dev/null and b/documents/diagrams/service_on_demand_pattern.png
differ
diff --git a/documents/patterns.md
b/documents/diagrams/service_on_demand_pattern.puml
similarity index 70%
copy from documents/patterns.md
copy to documents/diagrams/service_on_demand_pattern.puml
index eea8f629..e89c3a8b 100644
--- a/documents/patterns.md
+++ b/documents/diagrams/service_on_demand_pattern.puml
@@ -1,15 +1,10 @@
----
-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
@@ -17,18 +12,13 @@ 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.
--->
-
-# OSGi pattern in Apache Celix
-
-## Extender Pattern
-
-TODO example http_admin with html resources
-
-## Whiteboard Pattern
-
-TODO example http_admin with http service
-## Service on Demand (SOD) Pattern
+@startuml
+component ServiceOnDemandRequester as "Service On Demand Requester"
+component ServiceOnDemandAdmin as "Service On Demand Admin"
+() ServiceOnDemand
-TODO example logging service and/or remote service
+ServiceOnDemandRequester .up.( ServiceOnDemand
+ServiceOnDemandAdmin .[dotted].> ServiceOnDemand : <<monitors>>
+ServiceOnDemandAdmin -- " * "ServiceOnDemand
+@enduml
\ No newline at end of file
diff --git a/documents/diagrams/whiteboard_pattern.png
b/documents/diagrams/whiteboard_pattern.png
new file mode 100644
index 00000000..fe059e90
Binary files /dev/null and b/documents/diagrams/whiteboard_pattern.png differ
diff --git a/documents/patterns.md b/documents/diagrams/whiteboard_pattern.puml
similarity index 61%
copy from documents/patterns.md
copy to documents/diagrams/whiteboard_pattern.puml
index eea8f629..81dc503a 100644
--- a/documents/patterns.md
+++ b/documents/diagrams/whiteboard_pattern.puml
@@ -1,15 +1,10 @@
----
-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
@@ -17,18 +12,21 @@ 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.
--->
-# OSGi pattern in Apache Celix
+@startuml
+component WhiteboardParticipantA as "Whiteboard Participant A"
+component WhiteboardParticipantB as "Whiteboard Participant B"
+component WhiteboardParticipantC as "Whiteboard Participant C"
+component WhiteboardServiceAdmin as "Whiteboard Service Admin"
+() WhiteboardService
-## Extender Pattern
+WhiteboardParticipantA -down- WhiteboardService
+WhiteboardParticipantB -down- WhiteboardService
+WhiteboardParticipantC -down- WhiteboardService
+WhiteboardServiceAdmin " * " .up.( WhiteboardService
-TODO example http_admin with html resources
-## Whiteboard Pattern
-TODO example http_admin with http service
-## Service on Demand (SOD) Pattern
-TODO example logging service and/or remote service
+@enduml
\ No newline at end of file
diff --git a/documents/patterns.md b/documents/patterns.md
index eea8f629..6dfd6545 100644
--- a/documents/patterns.md
+++ b/documents/patterns.md
@@ -19,16 +19,65 @@ See the License for the specific language governing
permissions and
limitations under the License.
-->
-# OSGi pattern in Apache Celix
+# Apache Celix / OSGi patterns
+TODO rephrase
+There are several design patterns typical for Apache Celix and/or OSGi that
are worth mentioned.
## 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
+containing certain resources files and/or bundle manifest entries.
-TODO example http_admin with html resources
+
+
+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.
+
+### `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 this 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.
+
+```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
+)
+```
## Whiteboard Pattern
TODO example http_admin with http service
+
+
+
## Service on Demand (SOD) Pattern
TODO example logging service and/or remote service
+TODO also mention FindHook for Java
+
+
\ No newline at end of file
diff --git a/examples/celix-examples/readme_c_examples/CMakeLists.txt
b/examples/celix-examples/readme_c_examples/CMakeLists.txt
index 2b7d3c39..3861fc4f 100644
--- a/examples/celix-examples/readme_c_examples/CMakeLists.txt
+++ b/examples/celix-examples/readme_c_examples/CMakeLists.txt
@@ -81,4 +81,19 @@ add_celix_container(readme_c_examples_container
simple_component_bundle
component_with_provided_service_bundle
component_with_service_dependency_bundle
+)
+
+
+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
)
\ No newline at end of file
