content/docs/2.3.0/celix/bundles/remote_services/README.html - celix-site - Git at Google


 <!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <meta name="description" content="">
     <meta name="author" content="">

     <title>Remote Service Admin Service / Apache Celix</title>


     <link rel="icon" href="/assets/img/favicon.ico">


     <link href="/assets/css/bootstrap.min.css" rel="stylesheet">


     <link href="/assets/css/style.css" rel="stylesheet">

     <style>


         .card-body img {
             max-width: 100%;
             width: 100%;
             height: auto;
         }


         .card-body img + em {
             text-decoration: underline;
         }
     </style>


 <script>
   var _paq = window._paq = window._paq || [];

   _paq.push(['disableCookies']);

   _paq.push(['trackPageView']);
   _paq.push(['enableLinkTracking']);
   (function() {
     var u="https://analytics.apache.org/";
     _paq.push(['setTrackerUrl', u+'matomo.php']);
     _paq.push(['setSiteId', '9']);
     var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
     g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
   })();
 </script>


 </head>
 <body class="light-grey">

 <a href="https://github.com/apache/celix" class="github-ribbon">
     <img src="/assets/img/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
 </a>


 <nav class="navbar navbar-expand-lg navbar-dark bg-primary fixed-top">
     <div class="container">
         <a class="navbar-brand" href="/">
             <img src="/assets/img/celix-white.svg" height="40" class="d-inline-block align-top" alt="Celix Logo">
         </a>
         <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation">
             <span class="navbar-toggler-icon"></span>
         </button>
         <div class="collapse navbar-collapse" id="navbarResponsive">
             <ul class="navbar-nav ml-auto">
                 <li class="nav-item">
                     <a class="nav-link" href="/">Home</a>
                 </li>
                 <li class="nav-item">
                     <a class="nav-link" href="/download.cgi">Download</a>
                 </li>
                 <li class="nav-item dropdown active">
                     <a class="nav-link dropdown-toggle" href="#" id="ddDocs" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
                         Docs
                     </a>
                     <div class="dropdown-menu" aria-labelledby="ddDocs">
                         <a class="dropdown-item" href="/docs/2.4.0/docs.html">2.4.0 (latest)</a>
                         <a class="dropdown-item" href="/docs/2.3.0/docs.html">2.3.0</a>
                         <a class="dropdown-item" href="/docs/2.2.1/docs.html">2.2.1</a>
                         <a class="dropdown-item" href="/docs/2.1.0/docs.html">2.1.0</a>
                     </div>
                 </li>
                 <li class="nav-item dropdown">
                     <a class="nav-link dropdown-toggle" href="#" id="ddContributing" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
                         Contributing
                     </a>
                     <div class="dropdown-menu" aria-labelledby="ddContributing">
                         <a class="dropdown-item" href="/contributing/youatcelix.html">You at Celix</a>
                         <a class="dropdown-item" href="/contributing/submitting-patches.html">Submitting patches</a>
                         <a class="dropdown-item" href="/contributing/source-and-builds.html">Source code and builds</a>
                         <hr>
                         <a class="dropdown-item" href="/contributing/releasing.html">Releasing</a>
                         <a class="dropdown-item" href="/contributing/volunteers.html">Volunteers</a>
                         <a class="dropdown-item" href="https://whimsy.apache.org/board/minutes/Celix.html">Board Reports</a>
                     </div>
                 </li>
                 <li class="nav-item dropdown">
                     <a class="nav-link dropdown-toggle" href="#" id="ddSupport" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
                         Support
                     </a>
                     <div class="dropdown-menu" aria-labelledby="ddSupport">
                         <a class="dropdown-item" href="/support/mailing-list.html">Mailing Lists</a>
                         <a class="dropdown-item" href="/support/issue-tracking.html">Issue Tracking</a>
                     </div>
                 </li>
                 <li class="nav-item dropdown">
                     <a class="nav-link dropdown-toggle" href="#" id="ddFoundation" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
                         ASF
                     </a>
                     <div class="dropdown-menu" aria-labelledby="ddFoundation">
                         <a class="dropdown-item" href="https://www.apache.org/">ASF Home</a>
                         <a class="dropdown-item" href="https://www.apache.org/foundation/how-it-works.html">How it works</a>
                         <a class="dropdown-item" href="https://www.apache.org/licenses/">License</a>
                         <a class="dropdown-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
                         <a class="dropdown-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a>
                         <a class="dropdown-item" href="https://www.apache.org/security/">Security</a>
                         <a class="dropdown-item" href="https://www.apache.org/foundation/policies/conduct">Code of Conduct</a>
                     </div>
                 </li>
             </ul>
         </div>
     </div>
 </nav>


 <div class="section">
     <div class="container">
         <div class="row py-4">
             <div class="col-sm-12 card">
                 <div class="card-body pt-5">


                         <a href="/docs/2.3.0/docs.html" title="back to documentation">&lt;&lt; back to documentation</a>


 	<!--
 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.
 -->
 <h2 id="introduction">Introduction</h2>
 <p>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.</p>
 <h3 id="topology-manager">Topology Manager</h3>
 <p>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 <em>promiscuous</em> policy, which simply imports and exports all services.</p>
 <table>
 <thead>
 <tr>
 <th><strong>Bundle</strong></th>
 <th><code>topology_manager.zip</code></th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td><strong>Configuration</strong></td>
 <td><em>None</em></td>
 </tr>
 </tbody>
 </table>
 <h3 id="remote-service-admin">Remote Service Admin</h3>
 <p>The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.</p>
 <h4 id="endpoints-and-proxies">Endpoints and proxies</h4>
 <p>To delegate a <em>received</em> method call to the actual service implementation, the RSA uses an &ldquo;endpoint&rdquo; 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.</p>
 <p>Invoking a <em>remote</em> method is done by using &ldquo;proxy&rdquo; 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.</p>
 <p>Both proxy and endpoint bundles are loaded on demand when a service is imported or exported by the RSA. As such, these bundles <strong>must</strong> not be added to the list of &ldquo;auto started&rdquo; bundles, but placed in a separate location. By default, <code>endpoints</code> is used as location for locating proxy and/or endpoint bundles.</p>
 <p>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.</p>
 <h4 id="httpjson">HTTP/JSON</h4>
 <p>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 <em>Remote Service Admin HTTP</em> implementation provided by <a href="https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote">Amdatu Remote</a>.</p>
 <table>
 <thead>
 <tr>
 <th><strong>Bundle</strong></th>
 <th><code>remote_service_admin_http.zip</code></th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td><strong>Configuration</strong></td>
 <td><code>RSA_PORT</code>: defines the port on which the HTTP server should listen for incoming requests. Defaults to port <code>8888</code>;</td>
 </tr>
 <tr>
 <td></td>
 <td><code>ENDPOINTS</code>: defines the location in which service endpoints and/or proxies can be found. Defaults to <code>endpoints</code> in the current working directory</td>
 </tr>
 </tbody>
 </table>
 <h4 id="shared-memory-shm">Shared memory (SHM)</h4>
 <p>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.</p>
 <table>
 <thead>
 <tr>
 <th><strong>Bundle</strong></th>
 <th><code>remote_service_admin_shm.zip</code></th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td><strong>Configuration</strong></td>
 <td><code>ENDPOINTS</code>: defines the location in which service endpoints and/or proxies can be found. Defaults to <code>endpoints</code> in the current working directory</td>
 </tr>
 </tbody>
 </table>
 <h3 id="discovery">Discovery</h3>
 <p>Actively discovers the presence of remote exported services and provides information about local exported services, as given by the Topology Manager, to others.</p>
 <h4 id="shared-memory-shm-based-discovery">Shared memory (SHM) based discovery</h4>
 <p>Provides service discovery for the RSA SHM implementation.</p>
 <table>
 <thead>
 <tr>
 <th><strong>Bundle</strong></th>
 <th><code>discovery_shm.zip</code></th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td><strong>Configuration</strong></td>
 <td><em>None</em></td>
 </tr>
 </tbody>
 </table>
 <h4 id="configured-discovery">Configured discovery</h4>
 <p>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 <a href="https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote">Amdatu Remote</a>.</p>
 <table>
 <thead>
 <tr>
 <th><strong>Bundle</strong></th>
 <th><code>discovery_configured.zip</code></th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td><strong>Configuration</strong></td>
 <td><code>DISCOVERY_CFG_POLL_ENDPOINTS</code>: defines a comma-separated list of discovery endpoints that should be used to query for remote services. Defaults to <code>http://localhost:9999/org.apache.celix.discovery.configured</code>;</td>
 </tr>
 <tr>
 <td></td>
 <td><code>DISCOVERY_CFG_POLL_INTERVAL</code>: defines the interval (in seconds) in which the discovery endpoints should be polled. Defaults to <code>10</code> seconds.</td>
 </tr>
 <tr>
 <td></td>
 <td><code>DISCOVERY_CFG_POLL_TIMEOUT</code>: defines the maximum time (in seconds) a request of the discovery endpoint poller may take. Defaults to <code>10</code> seconds.</td>
 </tr>
 <tr>
 <td></td>
 <td><code>DISCOVERY_CFG_SERVER_PORT</code>: defines the port on which the HTTP server should listen for incoming requests from other configured discovery endpoints. Defaults to port <code>9999</code>;</td>
 </tr>
 <tr>
 <td></td>
 <td><code>DISCOVERY_CFG_SERVER_PATH</code>: defines the path on which the HTTP server should accept requests from other configured discovery endpoints. Defaults to <code>/org.apache.celix.discovery.configured</code>.</td>
 </tr>
 </tbody>
 </table>
 <p>Note that for configured discovery, the &ldquo;Endpoint Description Extender&rdquo; XML format defined in the OSGi Remote Service Admin specification (section 122.8 of OSGi Enterprise 5.0.0) is used.</p>
 <p>See <a href="discovery_etcd/README.html">etcd discovery</a></p>
 <h4 id="etcd-discovery">etcd discovery</h4>
 <p>| <strong>Bundle</strong> | <code>discovery_etcd.zip</code> |</p>
 <p>Provides a service discovery using etcd distributed key/value store.</p>
 <p>See <a href="discovery_etcd/README.html">etcd discovery</a></p>
 <h2 id="usage">Usage</h2>
 <p>To develop for the Remote Service Admin implementation of Celix, one needs the following:</p>
 <ol>
 <li>A service <strong>interface</strong>, describes the actual service and methods<sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup> that can be called. The service interface is needed at development time to allow a consistent definition;</li>
 <li>A service <strong>implementation</strong>, when exporting it as remote service. A service endpoint is needed to delegate remote requests to your service implementation;</li>
 <li>A service <strong>client</strong> 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.</li>
 </ol>
 <p>The Celix source repository provides a simple calculator example that shows all of the described parts:</p>
 <ol>
 <li><a href="https://github.com/apache/celix/blob/master/bundles/remote_services/examples/calculator_api/include/calculator_service.h">The calculator service interface</a>, 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;</li>
 <li><a href="https://github.com/apache/celix/blob/master/bundles/remote_services/examples/calculator_service/src/calculator_impl.c">A calculator service implementation</a> that simply implements the three previously described functions. To mark this service as &ldquo;remote service&rdquo;, you need to add the <code>service.exported.interfaces</code> service property to its service registration. This way, the RSA implementation can expose it as remote service to others;</li>
 <li><a href="https://github.com/apache/celix/blob/master/bundles/remote_services/examples/calculator_shell/src/add_command.c">A service client</a>, 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.</li>
 </ol>
 <p>If you have access to the Celix source repository, you can run the calculator example using various discovery implementations by invoking the <code>deploy</code> target. You can find the example deployments in the <code>CELIX_BUILD/deploy</code> directory. For example, to run the calculator example using the configured discovery mechanism, you should open two terminals. In the first terminal, type:</p>
 <pre><code>remote-service-cfg$ export RSA_PORT=18888
 remote-service-cfg$ sh run.sh
 ...
 RSA: Export services (org.apache.celix.calc.api.Calculator)
 ...
 -&gt; _
 </code></pre>
 <p>In the second terminal, type:</p>
 <pre><code>remote-service-cfg-client$ export RSA_PORT=28888
 remote-service-cfg-client$ sh run.sh
 ...
 RSA: Import service org.apache.celix.calc.api.Calculator
 ...
 -&gt; _
 </code></pre>
 <p>Now, if all went well, the client (second terminal) has three new shell commands, <code>add</code>, <code>sub</code> and <code>sqrt</code>, which you can use to invoke the calculator service:</p>
 <pre><code>-&gt; add 3 5
 CALCULATOR_SHELL: Add: 3.000000 + 5.000000 = 8.000000
 -&gt; _
 </code></pre>
 <p>On the server side (first terminal), you can follow each invocation as well:</p>
 <pre><code>CALCULATOR_ENDPOINT: Handle request &quot;add(DD)D&quot; with data &quot;{&quot;m&quot;: &quot;add(DD)D&quot;, &quot;a&quot;: [3.0, 5.0]}&quot;
 CALCULATOR: Add: 3.000000 + 5.000000 = 8.000000
 </code></pre>
 <p>Note that the <code>RSA_PORT</code> property needs to be unique for at least the client in order to communicate correctly when running the examples on the same machine.</p>
 <h2 id="building">Building</h2>
 <p>To build the Remote Service Admin Service the CMake build option &ldquo;<code>BUILD_REMOTE_SERVICE_ADMIN</code>&rdquo; has to be enabled.</p>
 <h2 id="dependencies">Dependencies</h2>
 <p>The Remote Service Admin Service depends on the following subprojects:</p>
 <ul>
 <li>Framework</li>
 <li>Utils</li>
 </ul>
 <p>Also the following libraries are required for building and/or using the Remote Service Admin Service subproject:</p>
 <ul>
 <li>Jansson (build and runtime)</li>
 <li>cURL (build and runtime)</li>
 </ul>
 <h2 id="rsa-bundles">RSA Bundles</h2>
 <ul>
 <li><a href="remote_service_admin_dfi">Remote Service Admin DFI</a> - A Dynamic Function Interface (DFI) implementation of the RSA.</li>
 <li><a href="remote_service_admin_shm">Remote Service Admin SHM</a> - A shared memory implementation of the RSA.</li>
 <li><a href="topology_manager">Topology Manager</a> - A (scoped) RSA Topology Manager implementation.</li>
 <li><a href="discovery_configured">Discovery Configured</a> - A RSA Discovery implementation using static configuration (xml).</li>
 <li><a href="discovery_etcd/README.html">Discovery Etcd</a> - A RSA Discovery implementation using etcd.</li>
 <li><a href="discovery_shm">Discovery SHM</a> - A RSA Discovery implementation using shared memory.</li>
 </ul>
 <h2 id="notes">Notes</h2>
 <div class="footnotes" role="doc-endnotes">
 <hr>
 <ol>
 <li id="fn:1">
 <p>Although C does not use the term &ldquo;method&rdquo;, we use this term to align with the terminology used in the RSA specification.&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p>
 </li>
 </ol>
 </div>


                 </div>
             </div>
         </div>
     </div>
 </div>


 <footer class="py-3 bg-secondary">
     <div class="container">
         <div class="row">
             <div class="col-md-8 text-center">
                 <p class="m-0 text-white">
                     Copyright &copy; 2024 The Apache Software Foundation, Licensed under
                     the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
                     <br>
                     Apache Celix, Celix, Apache, the Apache feather logo and the Apache Celix logo are trademarks of The Apache Software Foundation.
                 </p>
             </div>
             <div class="col-md-4 text-center">
                 <a href="https://www.apache.org/events/current-event.html" target="_blank">
                     <img src="https://www.apache.org/events/current-event-234x60.png" title="Apache Event" width="234" height="60" border="0">
                 </a>
             </div>
         </div>
     </div>
 </footer>


 <script src="/assets/js/jquery.min.js"></script>
 <script src="/assets/js/bootstrap.bundle.min.js"></script>


 </body>
 </html>

	<!DOCTYPE html>
	<html lang="en">
	<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<meta name="description" content="">
	<meta name="author" content="">

	<title>Remote Service Admin Service / Apache Celix</title>


	<link rel="icon" href="/assets/img/favicon.ico">


	<link href="/assets/css/bootstrap.min.css" rel="stylesheet">


	<link href="/assets/css/style.css" rel="stylesheet">

	<style>


	.card-body img {
	max-width: 100%;
	width: 100%;
	height: auto;
	}


	.card-body img + em {
	text-decoration: underline;
	}
	</style>


	<script>
	var _paq = window._paq = window._paq \|\| [];

	_paq.push(['disableCookies']);

	_paq.push(['trackPageView']);
	_paq.push(['enableLinkTracking']);
	(function() {
	var u="https://analytics.apache.org/";
	_paq.push(['setTrackerUrl', u+'matomo.php']);
	_paq.push(['setSiteId', '9']);
	var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
	g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
	})();
	</script>


	</head>
	<body class="light-grey">

	<a href="https://github.com/apache/celix" class="github-ribbon">
	<img src="/assets/img/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
	</a>


	<nav class="navbar navbar-expand-lg navbar-dark bg-primary fixed-top">
	<div class="container">
	<a class="navbar-brand" href="/">
	<img src="/assets/img/celix-white.svg" height="40" class="d-inline-block align-top" alt="Celix Logo">
	</a>
	<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation">
	<span class="navbar-toggler-icon"></span>
	</button>
	<div class="collapse navbar-collapse" id="navbarResponsive">
	<ul class="navbar-nav ml-auto">
	<li class="nav-item">
	<a class="nav-link" href="/">Home</a>
	</li>
	<li class="nav-item">
	<a class="nav-link" href="/download.cgi">Download</a>
	</li>
	<li class="nav-item dropdown active">
	<a class="nav-link dropdown-toggle" href="#" id="ddDocs" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
	Docs
	</a>
	<div class="dropdown-menu" aria-labelledby="ddDocs">
	<a class="dropdown-item" href="/docs/2.4.0/docs.html">2.4.0 (latest)</a>
	<a class="dropdown-item" href="/docs/2.3.0/docs.html">2.3.0</a>
	<a class="dropdown-item" href="/docs/2.2.1/docs.html">2.2.1</a>
	<a class="dropdown-item" href="/docs/2.1.0/docs.html">2.1.0</a>
	</div>
	</li>
	<li class="nav-item dropdown">
	<a class="nav-link dropdown-toggle" href="#" id="ddContributing" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
	Contributing
	</a>
	<div class="dropdown-menu" aria-labelledby="ddContributing">
	<a class="dropdown-item" href="/contributing/youatcelix.html">You at Celix</a>
	<a class="dropdown-item" href="/contributing/submitting-patches.html">Submitting patches</a>
	<a class="dropdown-item" href="/contributing/source-and-builds.html">Source code and builds</a>
	<hr>
	<a class="dropdown-item" href="/contributing/releasing.html">Releasing</a>
	<a class="dropdown-item" href="/contributing/volunteers.html">Volunteers</a>
	<a class="dropdown-item" href="https://whimsy.apache.org/board/minutes/Celix.html">Board Reports</a>
	</div>
	</li>
	<li class="nav-item dropdown">
	<a class="nav-link dropdown-toggle" href="#" id="ddSupport" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
	Support
	</a>
	<div class="dropdown-menu" aria-labelledby="ddSupport">
	<a class="dropdown-item" href="/support/mailing-list.html">Mailing Lists</a>
	<a class="dropdown-item" href="/support/issue-tracking.html">Issue Tracking</a>
	</div>
	</li>
	<li class="nav-item dropdown">
	<a class="nav-link dropdown-toggle" href="#" id="ddFoundation" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
	ASF
	</a>
	<div class="dropdown-menu" aria-labelledby="ddFoundation">
	<a class="dropdown-item" href="https://www.apache.org/">ASF Home</a>
	<a class="dropdown-item" href="https://www.apache.org/foundation/how-it-works.html">How it works</a>
	<a class="dropdown-item" href="https://www.apache.org/licenses/">License</a>
	<a class="dropdown-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
	<a class="dropdown-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a>
	<a class="dropdown-item" href="https://www.apache.org/security/">Security</a>
	<a class="dropdown-item" href="https://www.apache.org/foundation/policies/conduct">Code of Conduct</a>
	</div>
	</li>
	</ul>
	</div>
	</div>
	</nav>


	<div class="section">
	<div class="container">
	<div class="row py-4">
	<div class="col-sm-12 card">
	<div class="card-body pt-5">








	<a href="/docs/2.3.0/docs.html" title="back to documentation"><< back to documentation</a>



	<!--
	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.
	-->
	<h2 id="introduction">Introduction</h2>
	<p>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.</p>
	<h3 id="topology-manager">Topology Manager</h3>
	<p>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 <em>promiscuous</em> policy, which simply imports and exports all services.</p>
	<table>
	<thead>
	<tr>
	<th><strong>Bundle</strong></th>
	<th><code>topology_manager.zip</code></th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td><strong>Configuration</strong></td>
	<td><em>None</em></td>
	</tr>
	</tbody>
	</table>
	<h3 id="remote-service-admin">Remote Service Admin</h3>
	<p>The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.</p>
	<h4 id="endpoints-and-proxies">Endpoints and proxies</h4>
	<p>To delegate a <em>received</em> 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.</p>
	<p>Invoking a <em>remote</em> 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.</p>
	<p>Both proxy and endpoint bundles are loaded on demand when a service is imported or exported by the RSA. As such, these bundles <strong>must</strong> not be added to the list of “auto started” bundles, but placed in a separate location. By default, <code>endpoints</code> is used as location for locating proxy and/or endpoint bundles.</p>
	<p>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.</p>
	<h4 id="httpjson">HTTP/JSON</h4>
	<p>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 <em>Remote Service Admin HTTP</em> implementation provided by <a href="https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote">Amdatu Remote</a>.</p>
	<table>
	<thead>
	<tr>
	<th><strong>Bundle</strong></th>
	<th><code>remote_service_admin_http.zip</code></th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td><strong>Configuration</strong></td>
	<td><code>RSA_PORT</code>: defines the port on which the HTTP server should listen for incoming requests. Defaults to port <code>8888</code>;</td>
	</tr>
	<tr>
	<td></td>
	<td><code>ENDPOINTS</code>: defines the location in which service endpoints and/or proxies can be found. Defaults to <code>endpoints</code> in the current working directory</td>
	</tr>
	</tbody>
	</table>
	<h4 id="shared-memory-shm">Shared memory (SHM)</h4>
	<p>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.</p>
	<table>
	<thead>
	<tr>
	<th><strong>Bundle</strong></th>
	<th><code>remote_service_admin_shm.zip</code></th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td><strong>Configuration</strong></td>
	<td><code>ENDPOINTS</code>: defines the location in which service endpoints and/or proxies can be found. Defaults to <code>endpoints</code> in the current working directory</td>
	</tr>
	</tbody>
	</table>
	<h3 id="discovery">Discovery</h3>
	<p>Actively discovers the presence of remote exported services and provides information about local exported services, as given by the Topology Manager, to others.</p>
	<h4 id="shared-memory-shm-based-discovery">Shared memory (SHM) based discovery</h4>
	<p>Provides service discovery for the RSA SHM implementation.</p>
	<table>
	<thead>
	<tr>
	<th><strong>Bundle</strong></th>
	<th><code>discovery_shm.zip</code></th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td><strong>Configuration</strong></td>
	<td><em>None</em></td>
	</tr>
	</tbody>
	</table>
	<h4 id="configured-discovery">Configured discovery</h4>
	<p>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 <a href="https://amdatu.atlassian.net/wiki/display/AMDATUDEV/Amdatu+Remote">Amdatu Remote</a>.</p>
	<table>
	<thead>
	<tr>
	<th><strong>Bundle</strong></th>
	<th><code>discovery_configured.zip</code></th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td><strong>Configuration</strong></td>
	<td><code>DISCOVERY_CFG_POLL_ENDPOINTS</code>: defines a comma-separated list of discovery endpoints that should be used to query for remote services. Defaults to <code>http://localhost:9999/org.apache.celix.discovery.configured</code>;</td>
	</tr>
	<tr>
	<td></td>
	<td><code>DISCOVERY_CFG_POLL_INTERVAL</code>: defines the interval (in seconds) in which the discovery endpoints should be polled. Defaults to <code>10</code> seconds.</td>
	</tr>
	<tr>
	<td></td>
	<td><code>DISCOVERY_CFG_POLL_TIMEOUT</code>: defines the maximum time (in seconds) a request of the discovery endpoint poller may take. Defaults to <code>10</code> seconds.</td>
	</tr>
	<tr>
	<td></td>
	<td><code>DISCOVERY_CFG_SERVER_PORT</code>: defines the port on which the HTTP server should listen for incoming requests from other configured discovery endpoints. Defaults to port <code>9999</code>;</td>
	</tr>
	<tr>
	<td></td>
	<td><code>DISCOVERY_CFG_SERVER_PATH</code>: defines the path on which the HTTP server should accept requests from other configured discovery endpoints. Defaults to <code>/org.apache.celix.discovery.configured</code>.</td>
	</tr>
	</tbody>
	</table>
	<p>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.</p>
	<p>See <a href="discovery_etcd/README.html">etcd discovery</a></p>
	<h4 id="etcd-discovery">etcd discovery</h4>
	<p>\| <strong>Bundle</strong> \| <code>discovery_etcd.zip</code> \|</p>
	<p>Provides a service discovery using etcd distributed key/value store.</p>
	<p>See <a href="discovery_etcd/README.html">etcd discovery</a></p>
	<h2 id="usage">Usage</h2>
	<p>To develop for the Remote Service Admin implementation of Celix, one needs the following:</p>
	<ol>
	<li>A service <strong>interface</strong>, describes the actual service and methods<sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup> that can be called. The service interface is needed at development time to allow a consistent definition;</li>
	<li>A service <strong>implementation</strong>, when exporting it as remote service. A service endpoint is needed to delegate remote requests to your service implementation;</li>
	<li>A service <strong>client</strong> 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.</li>
	</ol>
	<p>The Celix source repository provides a simple calculator example that shows all of the described parts:</p>
	<ol>
	<li><a href="https://github.com/apache/celix/blob/master/bundles/remote_services/examples/calculator_api/include/calculator_service.h">The calculator service interface</a>, 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;</li>
	<li><a href="https://github.com/apache/celix/blob/master/bundles/remote_services/examples/calculator_service/src/calculator_impl.c">A calculator service implementation</a> that simply implements the three previously described functions. To mark this service as “remote service”, you need to add the <code>service.exported.interfaces</code> service property to its service registration. This way, the RSA implementation can expose it as remote service to others;</li>
	<li><a href="https://github.com/apache/celix/blob/master/bundles/remote_services/examples/calculator_shell/src/add_command.c">A service client</a>, 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.</li>
	</ol>
	<p>If you have access to the Celix source repository, you can run the calculator example using various discovery implementations by invoking the <code>deploy</code> target. You can find the example deployments in the <code>CELIX_BUILD/deploy</code> directory. For example, to run the calculator example using the configured discovery mechanism, you should open two terminals. In the first terminal, type:</p>
	<pre><code>remote-service-cfg$ export RSA_PORT=18888
	remote-service-cfg$ sh run.sh
	...
	RSA: Export services (org.apache.celix.calc.api.Calculator)
	...
	-> _
	</code></pre>
	<p>In the second terminal, type:</p>
	<pre><code>remote-service-cfg-client$ export RSA_PORT=28888
	remote-service-cfg-client$ sh run.sh
	...
	RSA: Import service org.apache.celix.calc.api.Calculator
	...
	-> _
	</code></pre>
	<p>Now, if all went well, the client (second terminal) has three new shell commands, <code>add</code>, <code>sub</code> and <code>sqrt</code>, which you can use to invoke the calculator service:</p>
	<pre><code>-> add 3 5
	CALCULATOR_SHELL: Add: 3.000000 + 5.000000 = 8.000000
	-> _
	</code></pre>
	<p>On the server side (first terminal), you can follow each invocation as well:</p>
	<pre><code>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
	</code></pre>
	<p>Note that the <code>RSA_PORT</code> property needs to be unique for at least the client in order to communicate correctly when running the examples on the same machine.</p>
	<h2 id="building">Building</h2>
	<p>To build the Remote Service Admin Service the CMake build option “<code>BUILD_REMOTE_SERVICE_ADMIN</code>” has to be enabled.</p>
	<h2 id="dependencies">Dependencies</h2>
	<p>The Remote Service Admin Service depends on the following subprojects:</p>
	<ul>
	<li>Framework</li>
	<li>Utils</li>
	</ul>
	<p>Also the following libraries are required for building and/or using the Remote Service Admin Service subproject:</p>
	<ul>
	<li>Jansson (build and runtime)</li>
	<li>cURL (build and runtime)</li>
	</ul>
	<h2 id="rsa-bundles">RSA Bundles</h2>
	<ul>
	<li><a href="remote_service_admin_dfi">Remote Service Admin DFI</a> - A Dynamic Function Interface (DFI) implementation of the RSA.</li>
	<li><a href="remote_service_admin_shm">Remote Service Admin SHM</a> - A shared memory implementation of the RSA.</li>
	<li><a href="topology_manager">Topology Manager</a> - A (scoped) RSA Topology Manager implementation.</li>
	<li><a href="discovery_configured">Discovery Configured</a> - A RSA Discovery implementation using static configuration (xml).</li>
	<li><a href="discovery_etcd/README.html">Discovery Etcd</a> - A RSA Discovery implementation using etcd.</li>
	<li><a href="discovery_shm">Discovery SHM</a> - A RSA Discovery implementation using shared memory.</li>
	</ul>
	<h2 id="notes">Notes</h2>
	<div class="footnotes" role="doc-endnotes">
	<hr>
	<ol>
	<li id="fn:1">
	<p>Although C does not use the term “method”, we use this term to align with the terminology used in the RSA specification. <a href="#fnref:1" class="footnote-backref" role="doc-backlink">↩︎</a></p>
	</li>
	</ol>
	</div>


	</div>
	</div>
	</div>
	</div>
	</div>


	<footer class="py-3 bg-secondary">
	<div class="container">
	<div class="row">
	<div class="col-md-8 text-center">
	<p class="m-0 text-white">
	Copyright © 2024 The Apache Software Foundation, Licensed under
	the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
	<br>
	Apache Celix, Celix, Apache, the Apache feather logo and the Apache Celix logo are trademarks of The Apache Software Foundation.
	</p>
	</div>
	<div class="col-md-4 text-center">
	<a href="https://www.apache.org/events/current-event.html" target="_blank">
	<img src="https://www.apache.org/events/current-event-234x60.png" title="Apache Event" width="234" height="60" border="0">
	</a>
	</div>
	</div>
	</div>
	</footer>


	<script src="/assets/js/jquery.min.js"></script>
	<script src="/assets/js/bootstrap.bundle.min.js"></script>


	</body>
	</html>