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 2018/07/02 18:34:47 UTC
[4/4] celix git commit: CELIX-449: Restructure of some parts of the
documentation to make it easier to integrate with the celix-site.
CELIX-449: Restructure of some parts of the documentation to make it easier to integrate with the celix-site.
Project: http://git-wip-us.apache.org/repos/asf/celix/repo
Commit: http://git-wip-us.apache.org/repos/asf/celix/commit/3f24edf0
Tree: http://git-wip-us.apache.org/repos/asf/celix/tree/3f24edf0
Diff: http://git-wip-us.apache.org/repos/asf/celix/diff/3f24edf0
Branch: refs/heads/develop
Commit: 3f24edf0bc00b05d28acbbf924851050c23dbccf
Parents: 6779498
Author: Pepijn Noltes <pe...@gmail.com>
Authored: Mon Jul 2 20:33:28 2018 +0200
Committer: Pepijn Noltes <pe...@gmail.com>
Committed: Mon Jul 2 20:33:28 2018 +0200
----------------------------------------------------------------------
bundles/log_service/README.md | 19 -
bundles/log_writer/README.md | 13 -
bundles/remote_services/README.md | 166 --
.../remote_services/discovery_etcd/README.md | 29 -
bundles/shell/remote_shell/README.md | 27 -
bundles/shell/shell/README.md | 51 -
bundles/shell/shell_tui/README.md | 34 -
documents/bundles/log_service/README.md | 19 +
documents/bundles/log_writer/README.md | 13 +
documents/bundles/remote_services/README.md | 176 ++
.../remote_services/discovery_etcd/README.md | 29 +
documents/bundles/remote_shell/README.md | 27 +
documents/bundles/shell/README.md | 51 +
documents/bundles/shell_tui/README.md | 34 +
.../getting_started/creating_a_simple_bundle.md | 333 ---
documents/getting_started/readme.md | 6 +-
.../getting_started/services_with_c/readme.md | 610 ++++++
.../getting_started/services_with_cxx/readme.md | 571 ++++++
.../getting_started/simple_bundle/readme.md | 333 +++
.../getting_started/using_services_with_c.md | 610 ------
.../getting_started/using_services_with_cxx.md | 571 ------
documents/roadmap/api_v3/celix/celix.h | 1896 ------------------
documents/roadmap/api_v3/readme.md | 283 ---
documents/roadmap/improvement_ideas.md | 54 -
documents/roadmap/roadmap.md | 123 --
documents/subprojects/readme.md | 35 +-
misc/roadmap/improvement_ideas.md | 54 +
misc/roadmap/roadmap.md | 123 ++
28 files changed, 2057 insertions(+), 4233 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/bundles/log_service/README.md
----------------------------------------------------------------------
diff --git a/bundles/log_service/README.md b/bundles/log_service/README.md
deleted file mode 100644
index 53d2c3b..0000000
--- a/bundles/log_service/README.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Log Service
-
-The Celix Log Service realizes an adapted implementation of the OSGi Compendium Log Service. This is a very simple implementation which only stores the log in memory. It can be combined with one of the available Log Writers to forward the buffered entries to e.g. stdout or syslog.
-
-To ease the use of the Log Service, the [Log Helper](public/include/log_helper.h) can be used. It wraps and therefore simplifies the log service usage.
-
-## Properties
- LOGHELPER_ENABLE_STDOUT_FALLBACK If set to any value and in case no Log Service is found the logs
- are still printed on stdout.
-
-## CMake option
- BUILD_LOG_SERVICE=ON
-
-## Using info
-
-If the Celix Log Service is installed, 'find_package(Celix)' will set:
- - The `Celix::log_service_api` interface (i.e. header only) library target
- - The `Celix::log_service` bundle target
- - The `Celix::log_helper` static library target
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/bundles/log_writer/README.md
----------------------------------------------------------------------
diff --git a/bundles/log_writer/README.md b/bundles/log_writer/README.md
deleted file mode 100644
index e2d5b34..0000000
--- a/bundles/log_writer/README.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Log Writer
-
-The Celix Log Writers are components that read/listen to the Log Service and print the Log entries to the console or syslog, respectively.
-
-## CMake options
- BUILD_LOG_WRITER=ON
- BUILD_LOG_WRITER_SYSLOG=ON
-
-## Using info
-
-If the Celix Log Writers are installed `find_package(CELIX)` will set:
- - The `Celix::log_writer_stdout` bundle target
- - The `Celix::log_writer_syslog` bundle target
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/bundles/remote_services/README.md
----------------------------------------------------------------------
diff --git a/bundles/remote_services/README.md b/bundles/remote_services/README.md
deleted file mode 100644
index 15365b2..0000000
--- a/bundles/remote_services/README.md
+++ /dev/null
@@ -1,166 +0,0 @@
-<!--
-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.
--->
-
-Title: Apache Celix Remote Service Admin Service
-
-## Introduction
-
-The Remote Service Admin Service subproject contains an adapted implementation of the OSGi Enterprise Remote Service Admin Service Specification. The subproject consists of three parts, each described in more detail in the following sections.
-
-### Topology Manager
-
-The topology manager decides which services should be imported and exported according to a defined policy. Currently, only one policy is implemented in Celix, the *promiscuous* policy, which simply imports and exports all services.
-
-| **Bundle** | `topology_manager.zip` |
-|--|--|
-| **Configuration** | *None* |
-
-### Remote Service Admin
-
-The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.
-
-#### Endpoints and proxies
-
-To delegate a *received* method call to the actual service implementation, the RSA uses an "endpoint" bundle, which has all the knowledge about the marshalling and unmarshalling of data for the service. This endpoint bundle is specific to the used RSA implementation, and as such cannot be reused between various RSA implementations.
-
-Invoking a *remote* method is done by using "proxy" bundles. Similar as to endpoints, proxy bundles encapsulate all knowledge to marshall and unmarshall data for a remote method call and as such can not be shared between RSA implementations.
-
-Both proxy and endpoint bundles are loaded on demand when a service is imported or exported by the RSA. As such, these bundles **must** not be added to the list of "auto started" bundles, but placed in a separate location. By default, `endpoints` is used as location for locating proxy and/or endpoint bundles.
-
-Note that since endpoints and proxies need to be created manually, one has full control about the handling of specifics of marshalling and unmarshalling data and dealing with exceptions.
-
-#### HTTP/JSON
-
-Provides a RSA implementation that uses JSON to marshal requests and HTTP as transport mechanism for its remote method invocation. It is compatible with the *Remote Service Admin HTTP* implementation provided by [Amdatu Remote](https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote).
-
-| **Bundle** | `remote_service_admin_http.zip` |
-|--|--|
-| **Configuration** | `RSA_PORT`: defines the port on which the HTTP server should listen for incoming requests. Defaults to port `8888`; |
-| | `ENDPOINTS`: defines the location in which service endpoints and/or proxies can be found. Defaults to `endpoints` in the current working directory |
-
-#### Shared memory (SHM)
-
-Provides a RSA implementation that uses shared memory for its remote method invocation. Note that this only works when all remote services are located on the same machine.
-
-| **Bundle** | `remote_service_admin_shm.zip` |
-|--|--|
-| **Configuration** | `ENDPOINTS`: defines the location in which service endpoints and/or proxies can be found. Defaults to `endpoints` in the current working directory |
-
-### Discovery
-
-Actively discovers the presence of remote exported services and provides information about local exported services, as given by the Topology Manager, to others.
-
-#### Shared memory (SHM) based discovery
-
-Provides service discovery for the RSA SHM implementation.
-
-| **Bundle** | `discovery_shm.zip` |
-|--|--|
-| **Configuration** | *None* |
-
-#### Configured discovery
-
-Provides a service discovery with preconfigured discovery endpoints, allowing a static mesh of nodes for remote service invocation to be created. The configured discovery bundle in Celix is compatible with the configured discovery implementation provided by [Amdatu Remote](https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote).
-
-| **Bundle** | `discovery_configured.zip` |
-|--|--|
-| **Configuration** | `DISCOVERY_CFG_POLL_ENDPOINTS`: defines a comma-separated list of discovery endpoints that should be used to query for remote services. Defaults to `http://localhost:9999/org.apache.celix.discovery.configured`; |
-| | `DISCOVERY_CFG_POLL_INTERVAL`: defines the interval (in seconds) in which the discovery endpoints should be polled. Defaults to `10` seconds. |
-| | `DISCOVERY_CFG_SERVER_PORT`: defines the port on which the HTTP server should listen for incoming requests from other configured discovery endpoints. Defaults to port `9999`; |
-| | `DISCOVERY_CFG_SERVER_PATH`: defines the path on which the HTTP server should accept requests from other configured discovery endpoints. Defaults to `/org.apache.celix.discovery.configured`. |
-
-Note that for configured discovery, the "Endpoint Description Extender" XML format defined in the OSGi Remote Service Admin specification (section 122.8 of OSGi Enterprise 5.0.0) is used.
-
-See [etcd discovery](discovery_etcd/README.md)
-
-#### etcd discovery
-
-| **Bundle** | `discovery_etcd.zip` |
-
-Provides a service discovery using etcd distributd key/value store.
-
-See [etcd discovery](discovery_etcd/README.md)
-
-## Usage
-
-To develop for the Remote Service Admin implementation of Celix, one needs the following:
-
-1. A service **interface**, describes the actual service and methods[^1] that can be called. The service interface is needed at development time to allow a consistent definition;
-2. A service **implementation**, when exporting it as remote service. A service endpoint is needed to delegate remote requests to your service implementation;
-3. A service **endpoint**, which will be installed by Celix when exporting a local service. The endpoint is responsible for calling the actual Celix service. Endpoint bundles are not needed when *only* importing services in Celix;
-4. A service **proxy**, which will be installed by Celix when importing a remote service. The proxy is responsible for marshalling and unmarshalling method invocations. Proxy bundles are not needed when *only* exposing services from Celix;
-5. A service **client** or user, which invokes methods on the local or remote service. The client is oblivious to the fact whether the service is running locally or remote.
-
-The Celix source repository provides a simple calculator example that shows all of the described parts:
-
-1. [The calculator service interface](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_service/public/include/calculator_service.h), providing three methods: one for adding two numbers, one for subtracting two numbers, and lastly, a method that calculates the square root of a number;
-2. [A calculator service implementation](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_service/private/src/calculator_impl.c) that simply implements the three previously described functions. To mark this service as "remote service", you need to add the `service.exported.interfaces` service property to its service registration. This way, the RSA implementation can expose it as remote service to others;
-3. [A service endpoint](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_endpoint/private/src/calculator_endpoint_impl.c), which is called by the RSA implementation to delegate a method invocation to an actual method in the service implementation. The service endpoint should be registered as `remote_endpoint` service, along with the `remote.interface` service property denoting which service interface this endpoint is capable of handling;
-4. [A service proxy (factory)](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_proxy/private/src/calculator_proxy_impl.c), called by the service client when it wants to invoke a method on a remoted service. The service proxy should be registered as `remote_proxy_factory` service along with the `proxy.interface` service property denoting which service interface the service proxy is capable of handling;
-5. [A service client](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_shell/private/src/add_command.c), that exposes the three calculator methods to as Celix shell commands. The implementation simply retrieves the calculator service as it would do with any other Celix service.
-
-If you have access to the Celix source repository, you can run the calculator example using various discovery implementations by invoking the `deploy` target. You can find the example deployments in the `CELIX_BUILD/deploy` directory. For example, to run the calculator example using the configured discovery mechanism, you should open two terminals. In the first terminal, type:
-
- remote-service-cfg$ export RSA_PORT=18888
- remote-service-cfg$ sh run.sh
- ...
- RSA: Export services (org.apache.celix.calc.api.Calculator)
- ...
- -> _
-
-In the second terminal, type:
-
- remote-service-cfg-client$ export RSA_PORT=28888
- remote-service-cfg-client$ sh run.sh
- ...
- RSA: Import service org.apache.celix.calc.api.Calculator
- ...
- -> _
-
-Now, if all went well, the client (second terminal) has three new shell commands, `add`, `sub` and `sqrt`, which you can use to invoke the calculator service:
-
- -> add 3 5
- CALCULATOR_SHELL: Add: 3.000000 + 5.000000 = 8.000000
- -> _
-
-On the server side (first terminal), you can follow each invocation as well:
-
- CALCULATOR_ENDPOINT: Handle request "add(DD)D" with data "{"m": "add(DD)D", "a": [3.0, 5.0]}"
- CALCULATOR: Add: 3.000000 + 5.000000 = 8.000000
-
-Note that the `RSA_PORT` property needs to be unique for at least the client in order to communicate correctly when running the examples on the same machine.
-
-## Building
-
-To build the Remote Service Admin Service the CMake build option "`BUILD_REMOTE_SERVICE_ADMIN`" has to be enabled.
-
-## Dependencies
-
-The Remote Service Admin Service depends on the following subprojects:
-
-- Framework
-- Utils
-
-Also the following libraries are required for building and/or using the Remote Service Admin Service subproject:
-
-- Jansson (build and runtime)
-- cURL (build and runtime)
-
-
-## Notes
-
-[^1]: Although C does not use the term "method", we use this term to align with the terminology used in the RSA specification.
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/bundles/remote_services/discovery_etcd/README.md
----------------------------------------------------------------------
diff --git a/bundles/remote_services/discovery_etcd/README.md b/bundles/remote_services/discovery_etcd/README.md
deleted file mode 100644
index e560264..0000000
--- a/bundles/remote_services/discovery_etcd/README.md
+++ /dev/null
@@ -1,29 +0,0 @@
-<!--
-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.
--->
-
-## Discovery ETCD
-
-The Celix Discovery ETCD bundles realizes OSGi services discovery based on [etcd](https://github.com/coreos/etcd).
-
-###### Properties
- DISCOVERY_ETCD_ROOT_PATH used path (default: discovery)
- DEFAULT_ETCD_SERVER_IP ip address of the etcd server (default: 127.0.0.1)
- DEFAULT_ETCD_SERVER_PORT port of the etcd server (default: 2379)
- DEFAULT_ETCD_TTL time-to-live for etcd entries in seconds (default: 30)
-
-###### CMake option
- BUILD_RSA_DISCOVERY_ETCD=ON
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/bundles/shell/remote_shell/README.md
----------------------------------------------------------------------
diff --git a/bundles/shell/remote_shell/README.md b/bundles/shell/remote_shell/README.md
deleted file mode 100644
index af28421..0000000
--- a/bundles/shell/remote_shell/README.md
+++ /dev/null
@@ -1,27 +0,0 @@
-<!--
-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.
--->
-
-## Remote Shell
-
-The Celix Remote Shell implements a telnet interface for the Celix Shell.
-
-###### Properties
- remote.shell.telnet.port used port (default: 6666)
- remote.shell.telnet.maxconn amount of concurrent connections (default: 2)
-
-###### CMake option
- BUILD_REMOTE_SHELL=ON
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/bundles/shell/shell/README.md
----------------------------------------------------------------------
diff --git a/bundles/shell/shell/README.md b/bundles/shell/shell/README.md
deleted file mode 100644
index d9f38af..0000000
--- a/bundles/shell/shell/README.md
+++ /dev/null
@@ -1,51 +0,0 @@
-<!--
-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.
--->
-
-# Shell
-
-The Celix Shell provides a service interface which can be used to interact with the Celix framework. Note that it does not offer a user interface. This modular approach enables having multiple frontends, e.g. textual or graphical.
-
-While the shell can be extended with additional commands by other bundles, it already offers some built in commands:
-
- lb list bundles
- install install additional bundle
- uninstall uninstall bundles
- update update bundles
-
- start start bundle
- stop stop bundle
-
- help displays available commands
- inspect inspect service and components
-
- log print log
-
-Further information about a command can be retrieved by using `help` combined with the command.
-
-## CMake options
- BUILD_SHELL=ON
-
-## Shell Config Options
-
-- SHELL_USE_ANSI_COLORS - Whether shell command are allowed to use
-ANSI colors when printing info. default is true.
-
-## Using info
-
-If the Celix Shell is installed, 'find_package(Celix)' will set:
- - The `Celix::shell_api` interface (i.e. header only) library target
- - The `Celix::shell` bundle target
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/bundles/shell/shell_tui/README.md
----------------------------------------------------------------------
diff --git a/bundles/shell/shell_tui/README.md b/bundles/shell/shell_tui/README.md
deleted file mode 100644
index 2b8984f..0000000
--- a/bundles/shell/shell_tui/README.md
+++ /dev/null
@@ -1,34 +0,0 @@
-<!--
-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.
--->
-
-# Shell TUI
-
-The Celix Shell TUI implements a textual user interface for the Celix Shell.
-
-## CMake option
- BUILD_SHELL_TUI=ON
-
-## Config options
-
-- SHELL_USE_ANSI_CONTROL_SEQUENCES - Wether to use ANSI control
-sequences to support backspace, left, up, etc key commands in the
-shell tui. Default is true if a TERM environment is set else false.
-
-## Using info
-
-If the Celix Shell TUI is installed, 'find_package(Celix)' will set:
- - The `Celix::shell_tui` bundle target if the shell_tui is installed
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/bundles/log_service/README.md
----------------------------------------------------------------------
diff --git a/documents/bundles/log_service/README.md b/documents/bundles/log_service/README.md
new file mode 100644
index 0000000..53d2c3b
--- /dev/null
+++ b/documents/bundles/log_service/README.md
@@ -0,0 +1,19 @@
+# Log Service
+
+The Celix Log Service realizes an adapted implementation of the OSGi Compendium Log Service. This is a very simple implementation which only stores the log in memory. It can be combined with one of the available Log Writers to forward the buffered entries to e.g. stdout or syslog.
+
+To ease the use of the Log Service, the [Log Helper](public/include/log_helper.h) can be used. It wraps and therefore simplifies the log service usage.
+
+## Properties
+ LOGHELPER_ENABLE_STDOUT_FALLBACK If set to any value and in case no Log Service is found the logs
+ are still printed on stdout.
+
+## CMake option
+ BUILD_LOG_SERVICE=ON
+
+## Using info
+
+If the Celix Log Service is installed, 'find_package(Celix)' will set:
+ - The `Celix::log_service_api` interface (i.e. header only) library target
+ - The `Celix::log_service` bundle target
+ - The `Celix::log_helper` static library target
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/bundles/log_writer/README.md
----------------------------------------------------------------------
diff --git a/documents/bundles/log_writer/README.md b/documents/bundles/log_writer/README.md
new file mode 100644
index 0000000..e2d5b34
--- /dev/null
+++ b/documents/bundles/log_writer/README.md
@@ -0,0 +1,13 @@
+# Log Writer
+
+The Celix Log Writers are components that read/listen to the Log Service and print the Log entries to the console or syslog, respectively.
+
+## CMake options
+ BUILD_LOG_WRITER=ON
+ BUILD_LOG_WRITER_SYSLOG=ON
+
+## Using info
+
+If the Celix Log Writers are installed `find_package(CELIX)` will set:
+ - The `Celix::log_writer_stdout` bundle target
+ - The `Celix::log_writer_syslog` bundle target
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/bundles/remote_services/README.md
----------------------------------------------------------------------
diff --git a/documents/bundles/remote_services/README.md b/documents/bundles/remote_services/README.md
new file mode 100644
index 0000000..0e0215a
--- /dev/null
+++ b/documents/bundles/remote_services/README.md
@@ -0,0 +1,176 @@
+<!--
+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.
+-->
+
+Title: Apache Celix Remote Service Admin Service
+
+## Introduction
+
+The Remote Service Admin Service subproject contains an adapted implementation of the OSGi Enterprise Remote Service Admin Service Specification. The subproject consists of three parts, each described in more detail in the following sections.
+
+### Topology Manager
+
+The topology manager decides which services should be imported and exported according to a defined policy. Currently, only one policy is implemented in Celix, the *promiscuous* policy, which simply imports and exports all services.
+
+| **Bundle** | `topology_manager.zip` |
+|--|--|
+| **Configuration** | *None* |
+
+### Remote Service Admin
+
+The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.
+
+#### Endpoints and proxies
+
+To delegate a *received* method call to the actual service implementation, the RSA uses an "endpoint" bundle, which has all the knowledge about the marshalling and unmarshalling of data for the service. This endpoint bundle is specific to the used RSA implementation, and as such cannot be reused between various RSA implementations.
+
+Invoking a *remote* method is done by using "proxy" bundles. Similar as to endpoints, proxy bundles encapsulate all knowledge to marshall and unmarshall data for a remote method call and as such can not be shared between RSA implementations.
+
+Both proxy and endpoint bundles are loaded on demand when a service is imported or exported by the RSA. As such, these bundles **must** not be added to the list of "auto started" bundles, but placed in a separate location. By default, `endpoints` is used as location for locating proxy and/or endpoint bundles.
+
+Note that since endpoints and proxies need to be created manually, one has full control about the handling of specifics of marshalling and unmarshalling data and dealing with exceptions.
+
+#### HTTP/JSON
+
+Provides a RSA implementation that uses JSON to marshal requests and HTTP as transport mechanism for its remote method invocation. It is compatible with the *Remote Service Admin HTTP* implementation provided by [Amdatu Remote](https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote).
+
+| **Bundle** | `remote_service_admin_http.zip` |
+|--|--|
+| **Configuration** | `RSA_PORT`: defines the port on which the HTTP server should listen for incoming requests. Defaults to port `8888`; |
+| | `ENDPOINTS`: defines the location in which service endpoints and/or proxies can be found. Defaults to `endpoints` in the current working directory |
+
+#### Shared memory (SHM)
+
+Provides a RSA implementation that uses shared memory for its remote method invocation. Note that this only works when all remote services are located on the same machine.
+
+| **Bundle** | `remote_service_admin_shm.zip` |
+|--|--|
+| **Configuration** | `ENDPOINTS`: defines the location in which service endpoints and/or proxies can be found. Defaults to `endpoints` in the current working directory |
+
+### Discovery
+
+Actively discovers the presence of remote exported services and provides information about local exported services, as given by the Topology Manager, to others.
+
+#### Shared memory (SHM) based discovery
+
+Provides service discovery for the RSA SHM implementation.
+
+| **Bundle** | `discovery_shm.zip` |
+|--|--|
+| **Configuration** | *None* |
+
+#### Configured discovery
+
+Provides a service discovery with preconfigured discovery endpoints, allowing a static mesh of nodes for remote service invocation to be created. The configured discovery bundle in Celix is compatible with the configured discovery implementation provided by [Amdatu Remote](https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote).
+
+| **Bundle** | `discovery_configured.zip` |
+|--|--|
+| **Configuration** | `DISCOVERY_CFG_POLL_ENDPOINTS`: defines a comma-separated list of discovery endpoints that should be used to query for remote services. Defaults to `http://localhost:9999/org.apache.celix.discovery.configured`; |
+| | `DISCOVERY_CFG_POLL_INTERVAL`: defines the interval (in seconds) in which the discovery endpoints should be polled. Defaults to `10` seconds. |
+| | `DISCOVERY_CFG_SERVER_PORT`: defines the port on which the HTTP server should listen for incoming requests from other configured discovery endpoints. Defaults to port `9999`; |
+| | `DISCOVERY_CFG_SERVER_PATH`: defines the path on which the HTTP server should accept requests from other configured discovery endpoints. Defaults to `/org.apache.celix.discovery.configured`. |
+
+Note that for configured discovery, the "Endpoint Description Extender" XML format defined in the OSGi Remote Service Admin specification (section 122.8 of OSGi Enterprise 5.0.0) is used.
+
+See [etcd discovery](discovery_etcd/README.md)
+
+#### etcd discovery
+
+| **Bundle** | `discovery_etcd.zip` |
+
+Provides a service discovery using etcd distributd key/value store.
+
+See [etcd discovery](discovery_etcd/README.md)
+
+## Usage
+
+To develop for the Remote Service Admin implementation of Celix, one needs the following:
+
+1. A service **interface**, describes the actual service and methods[^1] that can be called. The service interface is needed at development time to allow a consistent definition;
+2. A service **implementation**, when exporting it as remote service. A service endpoint is needed to delegate remote requests to your service implementation;
+3. A service **endpoint**, which will be installed by Celix when exporting a local service. The endpoint is responsible for calling the actual Celix service. Endpoint bundles are not needed when *only* importing services in Celix;
+4. A service **proxy**, which will be installed by Celix when importing a remote service. The proxy is responsible for marshalling and unmarshalling method invocations. Proxy bundles are not needed when *only* exposing services from Celix;
+5. A service **client** or user, which invokes methods on the local or remote service. The client is oblivious to the fact whether the service is running locally or remote.
+
+The Celix source repository provides a simple calculator example that shows all of the described parts:
+
+1. [The calculator service interface](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_service/public/include/calculator_service.h), providing three methods: one for adding two numbers, one for subtracting two numbers, and lastly, a method that calculates the square root of a number;
+2. [A calculator service implementation](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_service/private/src/calculator_impl.c) that simply implements the three previously described functions. To mark this service as "remote service", you need to add the `service.exported.interfaces` service property to its service registration. This way, the RSA implementation can expose it as remote service to others;
+3. [A service endpoint](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_endpoint/private/src/calculator_endpoint_impl.c), which is called by the RSA implementation to delegate a method invocation to an actual method in the service implementation. The service endpoint should be registered as `remote_endpoint` service, along with the `remote.interface` service property denoting which service interface this endpoint is capable of handling;
+4. [A service proxy (factory)](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_proxy/private/src/calculator_proxy_impl.c), called by the service client when it wants to invoke a method on a remoted service. The service proxy should be registered as `remote_proxy_factory` service along with the `proxy.interface` service property denoting which service interface the service proxy is capable of handling;
+5. [A service client](http://svn.apache.org/repos/asf/celix/trunk/remote_services/calculator_shell/private/src/add_command.c), that exposes the three calculator methods to as Celix shell commands. The implementation simply retrieves the calculator service as it would do with any other Celix service.
+
+If you have access to the Celix source repository, you can run the calculator example using various discovery implementations by invoking the `deploy` target. You can find the example deployments in the `CELIX_BUILD/deploy` directory. For example, to run the calculator example using the configured discovery mechanism, you should open two terminals. In the first terminal, type:
+
+ remote-service-cfg$ export RSA_PORT=18888
+ remote-service-cfg$ sh run.sh
+ ...
+ RSA: Export services (org.apache.celix.calc.api.Calculator)
+ ...
+ -> _
+
+In the second terminal, type:
+
+ remote-service-cfg-client$ export RSA_PORT=28888
+ remote-service-cfg-client$ sh run.sh
+ ...
+ RSA: Import service org.apache.celix.calc.api.Calculator
+ ...
+ -> _
+
+Now, if all went well, the client (second terminal) has three new shell commands, `add`, `sub` and `sqrt`, which you can use to invoke the calculator service:
+
+ -> add 3 5
+ CALCULATOR_SHELL: Add: 3.000000 + 5.000000 = 8.000000
+ -> _
+
+On the server side (first terminal), you can follow each invocation as well:
+
+ CALCULATOR_ENDPOINT: Handle request "add(DD)D" with data "{"m": "add(DD)D", "a": [3.0, 5.0]}"
+ CALCULATOR: Add: 3.000000 + 5.000000 = 8.000000
+
+Note that the `RSA_PORT` property needs to be unique for at least the client in order to communicate correctly when running the examples on the same machine.
+
+## Building
+
+To build the Remote Service Admin Service the CMake build option "`BUILD_REMOTE_SERVICE_ADMIN`" has to be enabled.
+
+## Dependencies
+
+The Remote Service Admin Service depends on the following subprojects:
+
+- Framework
+- Utils
+
+Also the following libraries are required for building and/or using the Remote Service Admin Service subproject:
+
+- Jansson (build and runtime)
+- cURL (build and runtime)
+
+## RSA Bundles
+
+* [Remote Service Admin HTTP](../bundles/remote_services/remote_service_admin_http) - A HTTP implementation of the RSA.
+* [Remote Service Admin DFI](../bundles/remote_services/remote_service_admin_dfi) - A Dynamic Function Interface (DFI) implementation of the RSA.
+* [Remote Service Admin SHM](../bundles/remote_services/remote_service_admin_shm) - A shared memory implementation of the RSA.
+* [Topology Manager](../bundles/remote_services/topology_manager) - A (scoped) RSA Topology Manager implementation.
+* [Discovery Configured](../bundles/remote_services/discovery_configured) - A RSA Discovery implementation using static configuration (xml).
+* [Discovery Etcd](../bundles/remote_services/dicovery_etcd) - A RSA Discovery implementation using etcd.
+* [Discovery SHM](../bundles/remote_services/dicovery_shm) - A RSA Discovery implementation using shared memory.
+
+
+## Notes
+
+[^1]: Although C does not use the term "method", we use this term to align with the terminology used in the RSA specification.
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/bundles/remote_services/discovery_etcd/README.md
----------------------------------------------------------------------
diff --git a/documents/bundles/remote_services/discovery_etcd/README.md b/documents/bundles/remote_services/discovery_etcd/README.md
new file mode 100644
index 0000000..e560264
--- /dev/null
+++ b/documents/bundles/remote_services/discovery_etcd/README.md
@@ -0,0 +1,29 @@
+<!--
+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.
+-->
+
+## Discovery ETCD
+
+The Celix Discovery ETCD bundles realizes OSGi services discovery based on [etcd](https://github.com/coreos/etcd).
+
+###### Properties
+ DISCOVERY_ETCD_ROOT_PATH used path (default: discovery)
+ DEFAULT_ETCD_SERVER_IP ip address of the etcd server (default: 127.0.0.1)
+ DEFAULT_ETCD_SERVER_PORT port of the etcd server (default: 2379)
+ DEFAULT_ETCD_TTL time-to-live for etcd entries in seconds (default: 30)
+
+###### CMake option
+ BUILD_RSA_DISCOVERY_ETCD=ON
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/bundles/remote_shell/README.md
----------------------------------------------------------------------
diff --git a/documents/bundles/remote_shell/README.md b/documents/bundles/remote_shell/README.md
new file mode 100644
index 0000000..af28421
--- /dev/null
+++ b/documents/bundles/remote_shell/README.md
@@ -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.
+-->
+
+## Remote Shell
+
+The Celix Remote Shell implements a telnet interface for the Celix Shell.
+
+###### Properties
+ remote.shell.telnet.port used port (default: 6666)
+ remote.shell.telnet.maxconn amount of concurrent connections (default: 2)
+
+###### CMake option
+ BUILD_REMOTE_SHELL=ON
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/bundles/shell/README.md
----------------------------------------------------------------------
diff --git a/documents/bundles/shell/README.md b/documents/bundles/shell/README.md
new file mode 100644
index 0000000..d9f38af
--- /dev/null
+++ b/documents/bundles/shell/README.md
@@ -0,0 +1,51 @@
+<!--
+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.
+-->
+
+# Shell
+
+The Celix Shell provides a service interface which can be used to interact with the Celix framework. Note that it does not offer a user interface. This modular approach enables having multiple frontends, e.g. textual or graphical.
+
+While the shell can be extended with additional commands by other bundles, it already offers some built in commands:
+
+ lb list bundles
+ install install additional bundle
+ uninstall uninstall bundles
+ update update bundles
+
+ start start bundle
+ stop stop bundle
+
+ help displays available commands
+ inspect inspect service and components
+
+ log print log
+
+Further information about a command can be retrieved by using `help` combined with the command.
+
+## CMake options
+ BUILD_SHELL=ON
+
+## Shell Config Options
+
+- SHELL_USE_ANSI_COLORS - Whether shell command are allowed to use
+ANSI colors when printing info. default is true.
+
+## Using info
+
+If the Celix Shell is installed, 'find_package(Celix)' will set:
+ - The `Celix::shell_api` interface (i.e. header only) library target
+ - The `Celix::shell` bundle target
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/bundles/shell_tui/README.md
----------------------------------------------------------------------
diff --git a/documents/bundles/shell_tui/README.md b/documents/bundles/shell_tui/README.md
new file mode 100644
index 0000000..2b8984f
--- /dev/null
+++ b/documents/bundles/shell_tui/README.md
@@ -0,0 +1,34 @@
+<!--
+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.
+-->
+
+# Shell TUI
+
+The Celix Shell TUI implements a textual user interface for the Celix Shell.
+
+## CMake option
+ BUILD_SHELL_TUI=ON
+
+## Config options
+
+- SHELL_USE_ANSI_CONTROL_SEQUENCES - Wether to use ANSI control
+sequences to support backspace, left, up, etc key commands in the
+shell tui. Default is true if a TERM environment is set else false.
+
+## Using info
+
+If the Celix Shell TUI is installed, 'find_package(Celix)' will set:
+ - The `Celix::shell_tui` bundle target if the shell_tui is installed
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/getting_started/creating_a_simple_bundle.md
----------------------------------------------------------------------
diff --git a/documents/getting_started/creating_a_simple_bundle.md b/documents/getting_started/creating_a_simple_bundle.md
deleted file mode 100644
index 8f10869..0000000
--- a/documents/getting_started/creating_a_simple_bundle.md
+++ /dev/null
@@ -1,333 +0,0 @@
-<!--
-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 - Getting Started Guide: Creating a Simple Bundle
-
-## Intro
-This page is intended for first time users of Apache Celix. It should guide you through building & installing Apache Celix, setting up a new project, creating your first bundle, setting up the project for use with Eclipse project and finally running and debugging your bundle directly from eclipse workspace.
-
-If there are any uncertainties or question, don't hesitate to ask your questions in the [Apache Celix mailing](https://celix.apache.org/support/mailinglist.html).
-
-## Prerequisite
-Some experience with a command line interface (xterm) is expected to be able to follow this guide.
-
-## Building and Installing
-For Apache Celix see [Building And Installing](../building/readme.md)
-
-## Installing Eclipse CDT
-Download the latest eclipse CDT at [http://www.eclipse.org](http://www.eclipse.org) and install it on your system. For more information on how the install eclipse on your system consult the eclipse documentation. For this getting started guide the luna version of eclipse was used ([linux](http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/luna/R/eclipse-cpp-luna-R-linux-gtk-x86_64.tar.gz) [mac](http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/luna/R/eclipse-cpp-luna-R-macosx-cocoa-x86_64.tar.gz)).
-
-## Apache Celix Bundle project
-Now that Apache Celix and Eclipse is installed, we are ready to create a new Apache Celix Bundle project.
-CMake is used as build tool for Apache Celix projects.
-
-To setup of the project, first create a new project dir to work in:
-
-```bash
-#Create a new workspace to work in, e.g:
-mkdir ${HOME}/workspace
-export WS=${HOME}/workspace
-
-mkdir ${WS}/myproject
-cd ${WS}/myproject
-```
-
-Then create a CMakeLists.txt file - the makefile variant of CMake -in project root directory:
-
-```cmake
-#${WS}/myproject/CMakeLists.txt
-
-#Part 1. setup project
-cmake_minimum_required(VERSION 3.4)
-project(myproject C CXX)
-
-#Part 2. setup compilers
-SET(CMAKE_C_FLAGS "-D_GNU_SOURCE -std=gnu99 -Wall -Werror -fPIC ${CMAKE_C_FLAGS}")
-SET(CMAKE_C_FLAGS_DEBUG "-g -DDEBUG")
-SET(CMAKE_CXX_FLAGS "-std=c++11 ${CMAKE_CXX_FLAGS}")
-SET(CMAKE_CXX_FLAGS_DEBUG "-g -DDEBUG")
-
-#Part 3. Setup Celix cmake files, include paths, libraries and library paths
-#Note. If celix is not installed in /usr/local dir, change the location accordingly.
-set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "/usr/local/share/celix/cmake/modules")
-find_package(CELIX REQUIRED)
-include_directories(${CELIX_INCLUDE_DIRS})
-
-#Part 4. Choose C, C++ or both
-add_subdirectory(bundles/HelloWorld_c) #C
-add_subdirectory(bundles/HelloWorld_cxx) #C++
-```
-
-This CMakeLists.txt file, sets up the following:
-
-* Part 1
- * The minimum cmake version required.
- * The project name
- * The type of source files to expect, in this case C and C++.
-* Part 2
- * Setup the compilers. c99 for C and C++11 for C++
-* Part 3
- * The Celix package should be searched, configured and that the Celix package is required.
- * For all build targets in this CMakeLists.txt file or any sub directory CMakeLists.txt files the Apache Celix headers directory should be included.
-* Part 4
- * The CMakelists.txt file in the subdirectory bundles/hello_world and/or bundles/HelloWorld should also be processed.
-
-
-It is a good practice to create a separate CMakeLists.txt file for every bundle you want to build. For the hello_world bundle a CMakeLists.txt file should be created in the bundles/hello_world sub directory.
-
-Create the sub directory:
-
-```CMake
-#Create directory structure for the hello_world bundles
-cd ${WS}/myproject
-mkdir -p bundles/HelloWorld_c/src
-mkdir -p bundles/HelloWorld_cxx/src
-mkdir -p bundles/HelloWorld_cxx/include
-```
-
-
-And add the following CMakeLists.txt file for the C Bundle:
-
-```CMake
-#${WS}/myproject/bundles/HelloWorld_c/CMakeLists.txt
-
-add_celix_bundle(HelloWorld_c
- VERSION 1.0.0
- SOURCES
- src/HelloWorld_activator.c
-)
-
-if(APPLE)
- target_link_libraries(HelloWorld_c ${CELIX_LIBRARIES} -Wl,-all_load ${CELIX_DM_STATIC_LIB})
-else()
- target_link_libraries(HelloWorld_c -Wl,--no-undefined -Wl,--whole-archive ${CELIX_DM_STATIC_LIB} -Wl,--no-whole-archive ${CELIX_LIBRARIES})
-endif()
-```
-
-And/or the following CMakeLists.txt for the C++ bundle:
-
-```CMake
-#${WS}/myproject/bundles/HelloWorld_cxx/CMakeLists.txt
-
-add_celix_bundle(HelloWorld_cxx
- VERSION 1.0.0
- SOURCES
- src/HelloWorldActivator.cc
-)
-target_include_directories(HelloWorld_cxx PRIVATE include)
-
-IF(APPLE)
- target_link_libraries(HelloWorld_cxx ${CELIX_LIBRARIES} -Wl,-all_load ${CELIX_DM_STATIC_CXX_LIB})
-else()
- target_link_libraries(HelloWorld_cxx -Wl,--no-undefined -Wl,--whole-archive ${CELIX_DM_STATIC_CXX_LIB} -Wl,--no-whole-archive ${CELIX_LIBRARIES})
-endif()
-```
-
-These CMakeLists.txt files declare that the bundles should be build based on the build result (shared library) of the declared sources (in this case the `private/src/hello_world_activator.c` or `private/src/HelloWorldActivator.cc` source).
-The `add_celix_bundle` CMake function is an Apache Celix specific CMake extension.
-The library used for the bundle will also be linked against the dependency manager static library.
-
-
-The Celix framework will install the bundle, load the bundle shared library and call the bundle activator entry symbols. These entries need to be programmed by the user.
-Note that in these examples we use the dependency manager libraries (C and C++ version) instead of developing a "vanilla" bundle activator;
-The dependency manager uses a higher abstraction and is more simple to understand and maintain, but not part of the OSGi standard.
-
-The C Bundle Activator:
-```C
-//${WS}/myproject/bundles/hello_world/src/HelloWorld_activator.c
-#include <stdlib.h>
-#include <stdio.h>
-
-#include "dm_activator.h"
-
-
-struct userData {
- char * word;
-};
-
-celix_status_t dm_create(bundle_context_pt context, void **out) {
- celix_status_t status = CELIX_SUCCESS;
- struct userData* result = calloc(1, sizeof(*result));
- if (result != NULL) {
- result->word = "C World";
- *out = result;
- } else {
- status = CELIX_START_ERROR;
- }
- return status;
-}
-
-celix_status_t dm_init(void* userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
- struct userData* data = (struct userData *) userData;
- printf("Hello %s\n", data->word);
- return CELIX_SUCCESS;
-}
-
-celix_status_t dm_destroy(void* userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
- free(userData);
- return CELIX_SUCCESS;
-}
-```
-
-The C++ Bundle Activator (header + source):
-```C++
-//${WS}/myproject/bundles/HelloWorld/include/HelloWorldActivator.h
-#ifndef HELLOWORLDACTIVATOR_H_
-#define HELLOWORLDACTIVATOR_H_
-
-#include "celix/dm/DmActivator.h"
-
-class HelloWorldActivator : public celix::dm::DmActivator {
-private:
- const std::string word {"C++ World"};
-public:
- HelloWorldActivator(celix::dm::DependencyManager& mng) : DmActivator {mng} {}
- virtual void init();
- virtual void deinit();
-};
-
-#endif //HELLOWORLDACTIVATOR_H_
-```
-
-```C++
-//${WS}/myproject/bundles/HelloWorld/private/src/HelloWorldActivator.cc
-#include "HelloWorldActivator.h"
-#include <iostream>
-
-DmActivator* DmActivator::create(celix::dm::DependencyManager& mng) {
- return new HelloWorldActivator(mng);
-}
-
-void HelloWorldActivator::init() {
- std::cout << "Hello " << this->word << "\n";
-}
-
-void HelloWorldActivator::deinit() {
- //nothing to do
-}
-```
-
-### Building
-One of the highly recommended features of CMake is the ability to do out of source builds, the benefit is that all of the build results will go in a separate directory without cluttering the (source) project.
-CMake also needs to able to find the cmake files Celix provides. This can be achieved by providing a CMAKE_MODULE_PATH variable (or setting the CMAKE_MODULE_PATH in the top level CMakeLists.txt).
-For this example it is assumed that Celix in installed in `/usr/local`.
-To create the build directory and build the project execute the following commands:
-
-
-```bash
-cd ${WS}
-mkdir myproject-build
-cd myproject-build
-cmake ../myproject
-make all
-```
-
-Hopefully you will some some build results scrolling over the screen and actual build results in the build directory.
-There should be a HelloWorld_c.zip in the bundles/HelloWorld_c directory and a HelloWorld_cxx.zip in the bundles/HelloWorld_cxx directory,
-these are the actual bundles.
-A bundle on its own has no real value, so lets setup a Celix container and run Celix with these bundles.
-
-### Running
-
-To create a deployment for the hello world bundles two things are needed:
-
-1. Add a `add_celix_container` statement in the (top level) `CMakeLists.txt` file declaring what to deploy and under which name.
-
-```CMake
-#${WS}/myproject/CMakeLists.txt
-add_celix_container(myproject
- CXX
- BUNDLES
- ${CELIX_BUNDLES_DIR}/shell.zip
- ${CELIX_BUNDLES_DIR}/shell_tui.zip
- ${CELIX_BUNDLES_DIR}/dm_shell.zip
- HelloWorld_c #C bundle
- HelloWorld_cxx #C++ bundle
-)
-```
-
-With the `add_celix_container` CMake function a Celix container will be configured, which bundles to use can be specified with absolute paths to
-bundle files (e.g. the shell.zip bundle) or Celix bundle CMake target (e.g. the HelloWorld_c bundle).
-
-Rerun make again form the build project. the make files generated by CMake will ensure cmake is run it again to update the actual make files.
-
-```bash
-cd ${WS}/myproject-build
-make -j
-```
-
-Now a deploy directory myproject should be available in the deploy directory. This directory contains - among other files - a release.sh script. This can be used to setup the required environment variables (like LD_LIBRARY_PATH).
-
-```bash
-cd ${WS}/myproject-build/deploy/myproject
-./myproject
-```
-
-The HelloWorld_c and HelloWorld_cxx bundles should be started with their own famous "Hello World" text variant printed. One for the C and one for the C++ bundle.
-The shell and shell_tui bundle are also deployed and these can be used to query and control the running framework. Below some commands are shown for querying the installed bundles, listing all known shell command, showing the help of a specific command and stopping a specific bundle (note that bundle 0 is the framework "bundle"):
-
-```
-lb
-help
-stop 0
-```
-
-## Apache Celix Projects in Eclipse
-
-A nice feature of CMake is the ability to generate Eclipse project files, with this feature bundles can also be developed with use of Eclipse. This should help speed up the development process.
-To get started change directory to the build directory and generate a eclipse project file.
-
- cd ${WS}/myproject-build
- cmake -G "Eclipse CDT4 - Unix Makefiles" .
-
-Startup the Eclipse EDI and a chose the `${WS}`
-
-
-
-Import the project with existing project.
-
-
-
-To build the project, use Project->Build All.
-To run or debug from Eclipse navigate to the myproject deploy directory and right click on
-the 'myproject' executable and as "Local C/C++ Application"
-
-
-## Apache Celix Projects in CLion
-
-Using Apache Celix projects in CLion quite easy.
-Just use `File -> Open ...` and select a Apache Celix project.
-Because CLion is a IDE for CMake projects and Apache Celix projects are CMake projects this works out of the box.
-
-To run a Celix container just select the target from CLion and press Run.
-
-
-## Next
-
-The get a complete overview of the available Celix CMake commands see:
- - [Apache Celix - Celix CMake Commands](../cmake_commands/readme.md)
-
-The idea behind service oriented programming is that functionality is provided and used by abstract service, which hide implementation details.
-For a guide how to provide and use services see
-
-- [Apache Celix - Getting Started Guide: Using Services with C](using_services_with_c.md)
-- [Apache Celix - Getting Started Guide: Using Services with C++](using_services_with_cxx.md)
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/getting_started/readme.md
----------------------------------------------------------------------
diff --git a/documents/getting_started/readme.md b/documents/getting_started/readme.md
index 9692bc0..3ca5406 100644
--- a/documents/getting_started/readme.md
+++ b/documents/getting_started/readme.md
@@ -18,9 +18,9 @@ limitations under the License.
# Apache Celix - Getting Started Guide
## Guides
-There are several guide to help you get started. The first guide is [Getting Started: Creating a simple bundle](creating_a_simple_bundle.md)
+There are several guide to help you get started. The first guide is [Getting Started: Creating a simple bundle](simple_bundle/)
and this should get you started for your first C and/or C++ bundle.
After that you can extend the example by using services with the following guides:
- - [Getting Started: Using Services with C](using_services_with_c.md)
- - [Getting Started: Using Services with C++](using_services_with_cxx.md).
+ - [Getting Started: Using Services with C](services_with/)
+ - [Getting Started: Using Services with C++](services_with/).
http://git-wip-us.apache.org/repos/asf/celix/blob/3f24edf0/documents/getting_started/services_with_c/readme.md
----------------------------------------------------------------------
diff --git a/documents/getting_started/services_with_c/readme.md b/documents/getting_started/services_with_c/readme.md
new file mode 100644
index 0000000..75692f9
--- /dev/null
+++ b/documents/getting_started/services_with_c/readme.md
@@ -0,0 +1,610 @@
+<!--
+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 - Using Services with C
+
+## Intro
+
+This example gives an overview for providing and using services with Apache Celix with C.
+
+## Services
+
+To start of, C services in Celix are just a pointer to a memory location registered in the service registry using a name and an optional set of key/value pairs.
+
+By convention use the following service layout:
+
+```C
+//example.h
+#ifndef EXAMPLE_H_
+#define EXAMPLE_H_
+
+#define EXAMPLE_NAME "org.example"
+#define EXAMPLE_VERSION "1.0.0"
+#define EXAMPLE_CONSUMER_RANGE "[1.0.0,2.0.0)"
+
+
+struct example_struct {
+ void *handle;
+ int (*method)(void *handle, int arg1, double arg2, double *result);
+} ;
+
+typedef struct example_struct example_t;
+
+#endif /* EXAMPLE_H_ */
+
+```
+
+
+For a Celix service a service name, service provider version and service consumer range should be declared.
+This is explicitly done with macros to prevent symbols so to that no linking dependencies are introduced.
+
+Then the actual struct for the service needs to be declared.
+The first element of the service struct should be a handle which can be used to store the service context, as convention we keep this pointer a void pointer to explicitly make it opaque.
+Note that also an opaque struct could be used (e.g a declared but not defined struct), but this can become problematic concerning components registering multiple services.
+In that case explicit cast are needed to prevent warning and this can be confusing for the To prevent that issues void pointers are preferred.
+
+The rest of the element should be function pointers, which by convention should return an celix_status_t or int (which is technically the same).
+The return value is used as a way of handling errors and is also needed to be able to make remote services (e.g. to be able to handle remote exceptions).
+
+The first argument of a service function should be the service handle and if there is a result the last argument should be a output parameter (either pre allocated (e.g. double *) or not (e.g. double **)).
+If the caller is not the owner of the output argument, a const pointer should be used (e.g. const char**).
+It is also possible to create typedef of the pointer to the service struct (e.g. typedef struct example_struct example_t), but this is not needed.
+
+In the Celix code base there are still service which uses a typedef with a pointer (e.g. typedef struct example_struct* example_struct_pt). This should be avoided,
+because it is not possible to create the const pointer of those typedefs and it is not possible to include those typedef inside a existing struct without the needed for an additional malloc.
+
+### Semantic Versioning
+
+For versioning, semantic versioning should be used.
+
+A backward incompatible change should lead to a major version increase (e.g. 1.0.0 -> 2.0.0).
+For a C Service versioning is used to express binary compatibility (for the same platform / compiler), change that are incompatible are:
+
+- Removing a function
+- Adding a function to before any other function
+- Moving a function to an other location in the service struct
+- Changing the signature of a function
+- Changing the semantics of a argument (e.g. changing range input from "range in kilometer" to "range in meters")
+
+A backwards binary compatible change which extend the functionality should lead to a minor version increase (e.g. 1.0.0 -> 1.1.0).
+Changes considered backwards compatible which extend the functionality are:
+
+- Adding a function to the back of the service struct
+
+A backwards binary compatible change which does not extend the functionality should lead to a micro version increase (e.g. 1.0.0 -> 1.0.1).
+Changes considered backwards binary compatible which does not extend the functionality are:
+
+- Changes in the documentation
+- Renaming of arguments
+
+For C services generally platform specific calling convention are used therefore binary compatibility between service provider and consumers from different compilers is possible (e.g. gcc and clang),
+ but not advisable
+
+
+## Components
+
+Component should use the ADT principle (see [ADT in C](http://inst.eecs.berkeley.edu/~selfpace/studyguide/9C.sg/Output/ADTs.in.C.html)).
+Note that is a convention.
+
+Components should have a `<cmpName>_create` and `<cmpName>_destroy` function.
+Components can have a `<cmpName>_start` and `<cmpName>_stop` function to start/stop threads or invoke functionality needed a fully created component.
+The start function will only be called if all required service are available and the stop function will be called when some required are going or if the component needs to be stopped.
+
+Components can also have a `<cmpName>_init` and `<cmpName>_deinit` function which will be called before and after respectively the start and stop function.
+The init/deinit function can be used to include (de)initialization which is not needed/wanted every time when service dependencies are being removed/added.
+
+## Code Examples
+
+The next code blocks contains some code examples of components to indicate how to handle service dependencies, how to specify providing services and how to cope with locking/synchronizing.
+The complete example can be found [here](../../examples/services_example_c).
+
+The error checking is very minimal in these example to keep the focus on how to interact with services and how to deal with errors in C / Celix.
+
+
+### Bar example
+
+The bar example is a simple component providing the `example` service.
+
+```C
+//bar.h
+#ifndef BAR_H_
+#define BAR_H_
+
+#include "example.h"
+
+typedef struct bar_struct bar_t;
+
+bar_t* bar_create(void);
+void bar_destroy(bar_t *self);
+
+int bar_method(bar_t *self, int arg1, double arg2, double *out);
+
+#endif //BAR_H_
+```
+
+```C
+//bar.c
+#define OK 0
+#define ERROR 1
+
+struct bar_struct {
+ double prefValue;
+};
+
+bar_t* bar_create(void) {
+ bar_t *self = calloc(1, sizeof(*self));
+ if (self != NULL) {
+ self->prefValue = 42;
+ } else {
+ //log error
+ }
+ return self;
+};
+
+void bar_destroy(bar_t *self) {
+ free(self);
+}
+
+int bar_method(bar_t *self, int arg1, double arg2, double *out) {
+ double update = (self->prefValue + arg1) * arg2;
+ self->prefValue = update;
+ *out = update;
+ return OK;
+}
+```
+
+```C
+//bar_activator.c
+#include "dm_activator.h"
+#include "bar.h"
+
+#include <stdlib.h>
+
+struct activator {
+ bar_t *bar;
+ example_t exampleService;
+};
+
+celix_status_t dm_create(bundle_context_pt context, void **userData) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *act = calloc(1, sizeof(*act));
+ if (act != NULL) {
+
+ act->bar = bar_create();
+ act->exampleService.handle = act->bar;
+ act->exampleService.method = (void*) bar_method;
+
+ if (act->bar != NULL) {
+ *userData = act;
+ } else {
+ free(act);
+ }
+ } else {
+ status = CELIX_ENOMEM;
+ }
+ return status;
+}
+
+celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *activator = userData;
+
+ dm_component_pt cmp = NULL;
+ component_create(context, "BAR", &cmp);
+ component_setImplementation(cmp, activator->bar);
+ component_addInterface(cmp, EXAMPLE_NAME, EXAMPLE_VERSION, &activator->exampleService, NULL);
+
+ dependencyManager_add(manager, cmp);
+ return status;
+}
+
+celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *activator = userData;
+ bar_destroy(activator->bar);
+ free(activator);
+ return status;
+};
+```
+
+### Foo1 example
+
+The Foo1 example shows how add a service dependency, implement the callback, invoke a service and how to protect the usage of service with use of a mutex.
+
+```C
+//foo1.h
+#ifndef FOO1_H_
+#define FOO1_H_
+
+#include "example.h"
+
+typedef struct foo1_struct foo1_t;
+
+foo1_t* foo1_create(void);
+void foo1_destroy(foo1_t *self);
+
+int foo1_start(foo1_t *self);
+int foo1_stop(foo1_t *self);
+
+int foo1_setExample(foo1_t *self, const example_t *example);
+
+
+#endif //FOO1_H_
+```
+
+```C
+//foo1.c
+#include "foo1.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <signal.h>
+#include <stdbool.h>
+#include <pthread.h>
+#include <assert.h>
+
+
+#define OK 0
+#define ERROR 1
+
+static void* foo1_thread(void*);
+
+struct foo1_struct {
+ const example_t *example;
+ pthread_mutex_t mutex; //protecting example
+ pthread_t thread;
+ bool running;
+};
+
+foo1_t* foo1_create(void) {
+ foo1_t *self = calloc(1, sizeof(*self));
+ if (self != NULL) {
+ pthread_mutex_init(&self->mutex, NULL);
+ self->running = false;
+ } else {
+ //log error
+ }
+ return self;
+};
+
+void foo1_destroy(foo1_t *self) {
+ assert(!self->running);
+ pthread_mutex_destroy(&self->mutex);
+ free(self);
+}
+
+int foo1_start(foo1_t *self) {
+ self->running = true;
+ pthread_create(&self->thread, NULL, foo1_thread, self);
+ return OK;
+}
+
+int foo1_stop(foo1_t *self) {
+ self->running = false;
+ pthread_kill(self->thread, SIGUSR1);
+ pthread_join(self->thread, NULL);
+ return OK;
+}
+
+int foo1_setExample(foo1_t *self, const example_t *example) {
+ pthread_mutex_lock(&self->mutex);
+ self->example = example; //NOTE could be NULL if req is not mandatory
+ pthread_mutex_unlock(&self->mutex);
+ return OK;
+}
+
+static void* foo1_thread(void *userdata) {
+ foo1_t *self = userdata;
+ double result;
+ int rc;
+ while (self->running) {
+ pthread_mutex_lock(&self->mutex);
+ if (self->example != NULL) {
+ rc = self->example->method(self->example->handle, 1, 2.0, &result);
+ if (rc == 0) {
+ printf("Result is %f\n", result);
+ } else {
+ printf("Error invoking method for example\n");
+ }
+ }
+ pthread_mutex_unlock(&self->mutex);
+ usleep(10000000);
+ }
+ return NULL;
+}
+```
+
+```C
+//foo1_activator.c
+#include "dm_activator.h"
+#include "foo1.h"
+
+#include <stdlib.h>
+
+struct activator {
+ foo1_t *foo;
+};
+
+celix_status_t dm_create(bundle_context_pt context, void **userData) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *act = calloc(1, sizeof(*act));
+ if (act != NULL) {
+ act->foo = foo1_create();
+ if (act->foo != NULL) {
+ *userData = act;
+ } else {
+ free(act);
+ }
+ } else {
+ status = CELIX_ENOMEM;
+ }
+ return status;
+}
+
+celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *activator = userData;
+
+ dm_component_pt cmp = NULL;
+ component_create(context, "FOO1", &cmp);
+ component_setImplementation(cmp, activator->foo);
+
+ /*
+ With the component_setCallbacksSafe we register callbacks when a component is started / stopped using a component
+ with type foo1_t*
+ */
+ component_setCallbacksSafe(cmp, foo1_t*, NULL, foo1_start, foo1_stop, NULL);
+
+ dm_service_dependency_pt dep = NULL;
+ serviceDependency_create(&dep);
+ serviceDependency_setRequired(dep, true);
+ serviceDependency_setService(dep, EXAMPLE_NAME, EXAMPLE_CONSUMER_RANGE, NULL);
+ serviceDependency_setStrategy(dep, DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING);
+
+ /*
+ With the serviceDependency_setCallbacksSafe we register callbacks when a service
+ is added and about to be removed for the component type foo1_t* and service type example_t*.
+
+ We should protect the usage of the
+ service because after removal of the service the memory location of that service
+ could be freed
+ */
+ serviceDependency_setCallbacksSafe(dep, foo1_t*, const example_t*, foo1_setExample, NULL, NULL, NULL, NULL);
+ component_addServiceDependency(cmp, dep);
+
+ dependencyManager_add(manager, cmp);
+
+ return status;
+}
+
+celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *activator = userData;
+ foo1_destroy(activator->foo);
+ free(activator);
+ return status;
+};
+
+```
+
+### Foo2 example
+
+The Foo2 example shows how to cope with multiple services and how to remove the need for locking by ensuring only access to the services and the services container by a single thread.
+
+```C
+//foo2.h
+#ifndef FOO2_H_
+#define FOO2_H_
+
+#include "example.h"
+
+typedef struct foo2_struct foo2_t;
+
+foo2_t* foo2_create(void);
+void foo2_destroy(foo2_t *self);
+
+int foo2_start(foo2_t *self);
+int foo2_stop(foo2_t *self);
+
+int foo2_addExample(foo2_t *self, const example_t *example);
+int foo2_removeExample(foo2_t *self, const example_t *example);
+
+#endif //FOO2_H_
+```
+
+```C
+//foo2.c
+#include "foo2.h"
+
+#include "array_list.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <signal.h>
+#include <stdbool.h>
+#include <pthread.h>
+#include <assert.h>
+
+
+#define OK 0
+#define ERROR 1
+
+static void* foo2_thread(void*);
+
+struct foo2_struct {
+ array_list_pt examples;
+ pthread_t thread;
+ bool running;
+};
+
+foo2_t* foo2_create(void) {
+ foo2_t *self = calloc(1, sizeof(*self));
+ if (self != NULL) {
+ self->examples = NULL;
+ arrayList_create(&self->examples);
+ self->running = false;
+ } else {
+ //log error
+ }
+ return self;
+};
+
+void foo2_destroy(foo2_t *self) {
+ assert(!self->running);
+ arrayList_destroy(self->examples);
+ free(self);
+}
+
+int foo2_start(foo2_t *self) {
+ self->running = true;
+ pthread_create(&self->thread, NULL, foo2_thread, self);
+ return OK;
+}
+
+int foo2_stop(foo2_t *self) {
+ self->running = false;
+ pthread_kill(self->thread, SIGUSR1);
+ pthread_join(self->thread, NULL);
+ return OK;
+}
+
+int foo2_addExample(foo2_t *self, const example_t *example) {
+ //NOTE foo2 is suspended -> thread is not running -> safe to update
+ int status = OK;
+ status = arrayList_add(self->examples, (void *)example);
+ return status;
+}
+
+int foo2_removeExample(foo2_t *self, const example_t *example) {
+ //NOTE foo2 is suspended -> thread is not running -> safe to update
+ int status = OK;
+ status = arrayList_removeElement(self->examples, (void*)example);
+ return status;
+}
+
+static void* foo2_thread(void *userdata) {
+ foo2_t *self = userdata;
+ double result;
+ int rc;
+ while (self->running) {
+ unsigned int size = arrayList_size(self->examples);
+ int i;
+ for (i = 0; i < size; i += 1) {
+ const example_t* example = arrayList_get(self->examples, i);
+ rc = example->method(example->handle, 1, 2.0, &result);
+ if (rc == 0) {
+ printf("Result is %f\n", result);
+ } else {
+ printf("Error invoking method for example\n");
+ }
+ }
+ usleep(10000000);
+ }
+ return NULL;
+
+```
+
+```C
+//foo2_activator.c
+#include "dm_activator.h"
+#include "foo2.h"
+
+#include <stdlib.h>
+
+struct activator {
+ foo2_t *foo;
+};
+
+celix_status_t dm_create(bundle_context_pt context, void **userData) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *act = calloc(1, sizeof(*act));
+ if (act != NULL) {
+ act->foo = foo2_create();
+ if (act->foo != NULL) {
+ *userData = act;
+ } else {
+ free(act);
+ }
+ } else {
+ status = CELIX_ENOMEM;
+ }
+ return status;
+}
+
+celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *activator = userData;
+
+ dm_component_pt cmp = NULL;
+ component_create(context, "FOO2", &cmp);
+ component_setImplementation(cmp, activator->foo);
+
+ /*
+ With the component_setCallbacksSafe we register callbacks when a component is started / stopped using a component
+ with type foo1_t*
+ */
+ component_setCallbacksSafe(cmp, foo2_t*, NULL, foo2_start, foo2_stop, NULL);
+
+ dm_service_dependency_pt dep = NULL;
+ serviceDependency_create(&dep);
+ serviceDependency_setRequired(dep, false);
+ serviceDependency_setService(dep, EXAMPLE_NAME, EXAMPLE_CONSUMER_RANGE, NULL);
+ serviceDependency_setStrategy(dep, DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND);
+
+ /*
+ With the serviceDependency_setCallbacksSafe we register callbacks when a service
+ is added and about to be removed for the component type foo1_t* and service type example_t*.
+
+ We should protect the usage of the
+ service because after removal of the service the memory location of that service
+ could be freed
+ */
+ serviceDependency_setCallbacksSafe(dep, foo2_t*, const example_t*, NULL, foo2_addExample, NULL, foo2_removeExample, NULL);
+ component_addServiceDependency(cmp, dep);
+
+ dependencyManager_add(manager, cmp);
+
+ return status;
+}
+
+celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *activator = userData;
+ foo2_destroy(activator->foo);
+ free(activator);
+ return status;
+};
+```
+
+## Locking and Suspending
+
+As you may notice, the Foo1 example uses locks.
+In principle, locking is necessary in order to ensure coherence in case service dependencies are removed/added/changed; on the other hands, locking increases latency and, when misused, can lead to poor performance.
+For this reason, the serviceDependency interface gives the possibility to choose between a locking and suspend (a non-locking) strategy through the serviceDependency_setStrategy function, as is used in the Foo2 example.
+
+The locking strategy `DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING` notifies the component in case the dependencies' set changes (e.g. a dependency is added/removed): the component is responsible for protecting via locks the dependencies' list and check (always under lock) if the service he's depending on is still available.
+The suspend or non-locking strategy `DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND` (default when no strategy is explicitly set) reliefs the programmer from dealing with service dependencies' consistency issues: in case this strategy is adopted, the component is stopped and restarted (i.e. temporarily suspended) upon service dependencies' changes.
+
+The suspend strategy has the advantage of reducing locks' usage: of course, suspending the component has its own overhead (e.g. stopping and restarting threads), but this overhead is "paid" only in case of changes in service dependencies, while the locking overhead is always paid.
+
+## See also
+
+See the [C Dependeny Manager](../../libs/dependency_manager/readme.md) and [C Dependency Manager example](../../examples/celix-examples/dm_example) for more information and a more complex working example.