| |
| <!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>Apache Celix Framework / 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 class="edit-on-gh" href="https://github.com/apache/celix/edit/master/documents/framework.md" title="Edit this page on GitHub">Edit on GitHub</a> |
| |
| |
| |
| |
| |
| <a href="/docs/2.4.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. |
| --> |
| <h1 id="apache-celix-framework">Apache Celix Framework</h1> |
| <p>The Apache Celix framework is the core of Apache Celix applications and provides supports for deployments of |
| dynamic, extensible modules known as bundles.</p> |
| <p>An instance of an Apache Celix framework can be created with the celix framework factory or by configuring |
| <a href="containers.html">Apache Celix containers</a> using the <code>add_celix_container</code> Apache Celix CMake command.</p> |
| <h2 id="framework-factory">Framework factory</h2> |
| <p>A new instance of an Apache Celix framework can be created using the C/C++ function/method:</p> |
| <ul> |
| <li><code>celix_frameworkFactory_createFramework</code></li> |
| <li><code>celix::createFramework</code></li> |
| </ul> |
| <p>When an Apache Celix framework is destroyed it will automatically stop and uninstall all running bundles. |
| For C, an Apache Celix framework needs to be destroyed with the call <code>celix_frameworkFactory_destroyFramework</code> and |
| for C++ this happens when the framework goes out of scope.</p> |
| <h3 id="example-creating-an-apache-celix-framework-in-c">Example: Creating an Apache Celix Framework in C</h3> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-C" data-lang="C"><span style="display:flex;"><span><span style="color:#080;font-style:italic">//src/main.c |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#080">#include</span> <span style="color:#080"><celix_bundle_activator.h></span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080"></span><span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">main</span>() { |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//create framework properties |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> <span style="color:#0b0;font-weight:bold">celix_properties_t</span><span style="color:#666">*</span> properties <span style="color:#666">=</span> <span style="color:#00a000">properties_create</span>(); |
| </span></span><span style="display:flex;"><span> <span style="color:#00a000">properties_set</span>(properties, <span style="color:#b44">"CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL"</span>, <span style="color:#b44">"debug"</span>); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//create framework |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> <span style="color:#0b0;font-weight:bold">celix_framework_t</span><span style="color:#666">*</span> fw <span style="color:#666">=</span> <span style="color:#00a000">celix_frameworkFactory_createFramework</span>(properties); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//get framework bundle context and log hello |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> <span style="color:#0b0;font-weight:bold">celix_bundle_context_t</span><span style="color:#666">*</span> fwContext <span style="color:#666">=</span> <span style="color:#00a000">celix_framework_getFrameworkContext</span>(fw); |
| </span></span><span style="display:flex;"><span> <span style="color:#00a000">celix_bundleContext_log</span>(fwContext, CELIX_LOG_LEVEL_INFO, <span style="color:#b44">"Hello from framework bundle context"</span>); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//destroy framework |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> <span style="color:#00a000">celix_frameworkFactory_destroyFramework</span>(fw); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cmake" data-lang="cmake"><span style="display:flex;"><span><span style="color:#080;font-style:italic">#CMakeLists.txt |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#a2f">find_package</span>(<span style="color:#b44">Celix</span> <span style="color:#b44">REQUIRED</span>)<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#a2f">add_executable</span>(<span style="color:#b44">create_framework_in_c</span> <span style="color:#b44">src/main.c</span>)<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#a2f">target_link_libraries</span>(<span style="color:#b44">create_framework_in_c</span> <span style="color:#b44">PRIVATE</span> <span style="color:#b44">Celix::framework</span>)<span style=""> |
| </span></span></span></code></pre></div><h3 id="example-creating-an-apache-celix-framework-in-c-1">Example: Creating an Apache Celix Framework in C++</h3> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-C++" data-lang="C++"><span style="display:flex;"><span><span style="color:#080;font-style:italic">//src/main.cc |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#080">#include</span> <span style="color:#080"><celix/FrameworkFactory.h></span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080"></span><span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">main</span>() { |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//create framework properties |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> celix<span style="color:#666">::</span>Properties properties{}; |
| </span></span><span style="display:flex;"><span> properties.set(<span style="color:#b44">"CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL"</span>, <span style="color:#b44">"debug"</span>); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//create framework |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> std<span style="color:#666">::</span>shared_ptr<span style="color:#666"><</span>celix<span style="color:#666">::</span>Framework<span style="color:#666">></span> fw <span style="color:#666">=</span> celix<span style="color:#666">::</span>createFramework(properties); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//get framework bundle context and log hello |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> std<span style="color:#666">::</span>shared_ptr<span style="color:#666"><</span>celix<span style="color:#666">::</span>BundleContext<span style="color:#666">></span> ctx <span style="color:#666">=</span> fw<span style="color:#666">-></span>getFrameworkBundleContext(); |
| </span></span><span style="display:flex;"><span> ctx<span style="color:#666">-></span>logInfo(<span style="color:#b44">"Hello from framework bundle context"</span>); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cmake" data-lang="cmake"><span style="display:flex;"><span><span style="color:#080;font-style:italic">#CMakeLists.txt |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#a2f">find_package</span>(<span style="color:#b44">Celix</span> <span style="color:#b44">REQUIRED</span>)<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#a2f">add_executable</span>(<span style="color:#b44">create_framework_in_cxx</span> <span style="color:#b44">src/main.cc</span>)<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#a2f">target_link_libraries</span>(<span style="color:#b44">create_framework_in_cxx</span> <span style="color:#b44">PRIVATE</span> <span style="color:#b44">Celix::framework</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="apache-celix-launcher">Apache Celix launcher</h2> |
| <p>If the Apache Celix framework is the main application, the Apache Celix launcher can be used to create the framework |
| and wait for a framework shutdown.</p> |
| <p>The Apache Celix launcher also does some additional work:</p> |
| <ul> |
| <li>Handles command arguments (mainly to print to embedded and runtime framework properties).</li> |
| <li>Tries to read a “config.properties” file from the current workdir and combines this with the optional provided |
| embedded properties to the Apache Celix Launcher.</li> |
| <li>Configures a framework shutdown for the <code>SIGINT</code> and <code>SIGTERM</code> signal.</li> |
| <li>Configures an “ignore” signal handler for the <code>SIGUSR1</code> and <code>SIGUSR2</code> signal.</li> |
| <li>Calls the <code>curl_global_init</code> to initialize potential use of curl. Note that the <code>curl_global_init</code> is not thread safe |
| or protected by something like pthread_once.</li> |
| <li>Destroys the Apache Celix Framework after shutdown.</li> |
| </ul> |
| <h3 id="example-creating-an-apache-celix-framework-with-the-apache-celix-launcher">Example: Creating an Apache Celix Framework with the Apache Celix Launcher</h3> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-C" data-lang="C"><span style="display:flex;"><span><span style="color:#080;font-style:italic">//src/launcher.c |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#080">#include</span> <span style="color:#080"><celix_bundle_activator.h></span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080"></span><span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">main</span>(<span style="color:#0b0;font-weight:bold">int</span> argc, <span style="color:#0b0;font-weight:bold">char</span><span style="color:#666">**</span> argv) { |
| </span></span><span style="display:flex;"><span> <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#00a000">celixLauncher_launchAndWaitForShutdown</span>(argc, argv, <span style="color:#a2f">NULL</span>); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cmake" data-lang="cmake"><span style="display:flex;"><span><span style="color:#080;font-style:italic">#CMakeLists.txt |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#a2f">find_package</span>(<span style="color:#b44">Celix</span> <span style="color:#b44">REQUIRED</span>)<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#a2f">add_executable</span>(<span style="color:#b44">create_framework_with_celix_launcher</span> <span style="color:#b44">src/launcher.c</span>)<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#a2f">target_link_libraries</span>(<span style="color:#b44">create_framework_with_celix_launcher</span> <span style="color:#b44">PRIVATE</span> <span style="color:#b44">Celix::framework</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="installing-and-starting-bundles-in-an-apache-celix-framework">Installing and starting bundles in an Apache Celix framework</h2> |
| <p>Bundles can be installed and started using the Apache Celix framework bundle context or - when using the Apache Celix |
| launcher - with a “config.properties” file.</p> |
| <p>Bundles are installed using a path to a zip file. If the path is a relative path, the framework will search for the |
| bundle in the directories configured in the framework property <code>CELIX_BUNDLES_PATH</code>. |
| The default value of <code>CELIX_BUNDLES_PATH</code> is “bundles”.</p> |
| <p>Another option is to use framework properties to configure which bundles to install and start. |
| This can be done by using the CELIX_AUTO_START_0 till CELIX_AUTO_START_6 framework properties. |
| (note that bundles configured in CELIX_AUTO_START_0 are installed and started first). |
| For a more complete overview of possible framework properties see <code>celix_constants.h</code></p> |
| <p>If the Apache Celix launcher is used, the framework properties can be provided with a “config.properties” |
| file using the Java Properties File Format.</p> |
| <p>Framework properties to install and start bundles:</p> |
| <ul> |
| <li>CELIX_AUTO_START_0</li> |
| <li>CELIX_AUTO_START_1</li> |
| <li>CELIX_AUTO_START_2</li> |
| <li>CELIX_AUTO_START_3</li> |
| <li>CELIX_AUTO_START_4</li> |
| <li>CELIX_AUTO_START_5</li> |
| <li>CELIX_AUTO_START_6</li> |
| </ul> |
| <h3 id="example-installing-and-starting-bundles-in-c">Example: Installing and starting bundles in C</h3> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-C" data-lang="C"><span style="display:flex;"><span><span style="color:#080;font-style:italic">//src/main.c |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#080">#include</span> <span style="color:#080"><celix_bundle_activator.h></span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080"></span><span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">main</span>() { |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//create framework properties |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> <span style="color:#0b0;font-weight:bold">celix_properties_t</span><span style="color:#666">*</span> properties <span style="color:#666">=</span> <span style="color:#00a000">properties_create</span>(); |
| </span></span><span style="display:flex;"><span> <span style="color:#00a000">properties_set</span>(properties, <span style="color:#b44">"CELIX_BUNDLES_PATH"</span>, <span style="color:#b44">"bundles;/opt/alternative/bundles"</span>); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//create framework |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> <span style="color:#0b0;font-weight:bold">celix_framework_t</span><span style="color:#666">*</span> fw <span style="color:#666">=</span> <span style="color:#00a000">celix_frameworkFactory_createFramework</span>(<span style="color:#a2f">NULL</span>); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//get framework bundle context and install a bundle |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> <span style="color:#0b0;font-weight:bold">celix_bundle_context_t</span><span style="color:#666">*</span> fwContext <span style="color:#666">=</span> <span style="color:#00a000">celix_framework_getFrameworkContext</span>(fw); |
| </span></span><span style="display:flex;"><span> <span style="color:#00a000">celix_bundleContext_installBundle</span>(fwContext, <span style="color:#b44">"FooBundle.zip"</span>, <span style="color:#a2f">true</span>); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//destroy framework |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> <span style="color:#00a000">celix_frameworkFactory_destroyFramework</span>(fw); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><h3 id="example-installing-and-starting-bundles-in-c-1">Example: Installing and starting bundles in C++</h3> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-C++" data-lang="C++"><span style="display:flex;"><span><span style="color:#080;font-style:italic">//src/main.cc |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#080">#include</span> <span style="color:#080"><celix/FrameworkFactory.h></span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080"></span><span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">main</span>() { |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//create framework properties |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> celix<span style="color:#666">::</span>Properties properties{}; |
| </span></span><span style="display:flex;"><span> properties.set(<span style="color:#b44">"CELIX_BUNDLES_PATH"</span>, <span style="color:#b44">"bundles;/opt/alternative/bundles"</span>); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//create framework |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> std<span style="color:#666">::</span>shared_ptr<span style="color:#666"><</span>celix<span style="color:#666">::</span>Framework<span style="color:#666">></span> fw <span style="color:#666">=</span> celix<span style="color:#666">::</span>createFramework(properties); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//get framework bundle context and install a bundle |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> std<span style="color:#666">::</span>shared_ptr<span style="color:#666"><</span>celix<span style="color:#666">::</span>BundleContext<span style="color:#666">></span> ctx <span style="color:#666">=</span> fw<span style="color:#666">-></span>getFrameworkBundleContext(); |
| </span></span><span style="display:flex;"><span> ctx<span style="color:#666">-></span>installBundle(<span style="color:#b44">"FooBundle.zip"</span>); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><h3 id="example-installing-and-starting-bundles-using-the-apache-celix-launcher">Example: Installing and starting bundles using the Apache Celix Launcher</h3> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-C" data-lang="C"><span style="display:flex;"><span><span style="color:#080;font-style:italic">//src/launcher.c |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#080">#include</span> <span style="color:#080"><celix_bundle_activator.h></span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080"></span><span style="color:#0b0;font-weight:bold">int</span> <span style="color:#00a000">main</span>(<span style="color:#0b0;font-weight:bold">int</span> argc, <span style="color:#0b0;font-weight:bold">char</span><span style="color:#666">**</span> argv) { |
| </span></span><span style="display:flex;"><span> <span style="color:#a2f;font-weight:bold">return</span> <span style="color:#00a000">celixLauncher_launchAndWaitForShutdown</span>(argc, argv, <span style="color:#a2f">NULL</span>); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cmake" data-lang="cmake"><span style="display:flex;"><span><span style="color:#080;font-style:italic">#CMakeLists.txt |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span><span style="color:#a2f">find_package</span>(<span style="color:#b44">Celix</span> <span style="color:#b44">REQUIRED</span>)<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#a2f">file</span>(<span style="color:#b44">GENERATE</span> <span style="color:#b44">OUTPUT</span> <span style="color:#666">${</span><span style="color:#b8860b">CMAKE_CURRENT_BINARY_DIR</span><span style="color:#666">}</span><span style="color:#b44">/config.properties</span> <span style="color:#b44">CONTENT</span> <span style="color:#b44">" |
| </span></span></span><span style="display:flex;"><span><span style="color:#b44">CELIX_BUNDLES_PATH=bundles;/opt/alternative/bundles |
| </span></span></span><span style="display:flex;"><span><span style="color:#b44">CELIX_AUTO_START_3=FooBundle.zip |
| </span></span></span><span style="display:flex;"><span><span style="color:#b44">"</span>)<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#a2f">add_executable</span>(<span style="color:#b44">create_framework_with_celix_launcher</span> <span style="color:#b44">src/launcher.c</span>)<span style=""> |
| </span></span></span><span style="display:flex;"><span><span style=""></span><span style="color:#a2f">target_link_libraries</span>(<span style="color:#b44">create_framework_with_celix_launcher</span> <span style="color:#b44">PRIVATE</span> <span style="color:#b44">Celix::framework</span>)<span style=""> |
| </span></span></span></code></pre></div><h2 id="framework-celix_condition-services">Framework <code>celix_condition</code> Services</h2> |
| <p>In a dynamic framework such as Apache Celix, it can sometimes be challenging to ascertain when the framework or |
| certain parts of a dynamic service-based application are ready for use. To address this issue, Apache Celix provides |
| services known as <code>celix_condition</code> services.</p> |
| <p>A <code>celix_condition</code> service is a registered marker interface with a “condition.id” service property. |
| The service’s availability signifies that the condition identified by the “condition.id” has been met.</p> |
| <p>The <code>celix_condition</code> service is an adaptation of the |
| <a href="https://docs.osgi.org/specification/osgi.core/8.0.0/service.condition.html">OSGi 8 Condition Service Specification</a>.</p> |
| <p>The Apache Celix framework will provide the following <code>celix_condition</code> services for the respective states:</p> |
| <ul> |
| <li>Celix condition “true”, which is always available.</li> |
| <li>Celix condition “framework.ready”. This service will be registered when the framework has successfully and fully |
| started, which includes installing and starting all configured bundles and services, and ensuring the event queue is |
| empty after all configured bundles have been started. Note that the “framework.ready” condition is not part of the |
| OSGi condition specification.</li> |
| <li>Celix condition “framework.error”. This service will be registered when the framework has not started successfully. |
| This can occur if any of the configured bundles fail to start or install. Note that the “framework.error” condition |
| is not part of the OSGi condition specification.</li> |
| </ul> |
| <p>Contrary to the OSGi specification, the Apache Celix framework does not provide a public API for adding or removing |
| framework listeners. Instead, framework condition services can be used. This has the advantage of ensuring no |
| framework state changes can be missed, because the state indicating condition services will be available |
| until the framework is stopped.</p> |
| <h2 id="framework-bundle-cache">Framework bundle cache</h2> |
| <p>The Apache Celix framework uses a bundle cache directory to store the installed bundles, their state and for a |
| persistent bundle storage. The bundle cache directory is created in the directory configured in the framework |
| property <code>CELIX_FRAMEWORK_CACHE_DIR</code> (default is “.cache”). A bundle cache consists of a bundle state property file, |
| a resource bundle cache and a persistent storage bundle cache.</p> |
| <p>The resource bundle cache is used to store and access the bundle resources (e.g. the content of the bundle zip file) |
| and should be treated as read-only. The resource bundle cache can be accessed using <code>celix_bundle_getEntry</code> |
| or <code>celix::Bundle::getEntry</code>.</p> |
| <p>The persistent storage bundle cache can be used to store persistent data for a bundle and can be treated as |
| read-write. The persistent storage bundle cache can be accessed using <code>celix_bundle_getDataFile</code> or |
| <code>celix::Bundle::getDataFile</code>.</p> |
| <p>If a framework is started with only a <code>Celix::shell</code> and <code>Celix::shell_tui bundle</code>, the following directory structure |
| is created:</p> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>% find .cache |
| </span></span><span style="display:flex;"><span>.cache/ |
| </span></span><span style="display:flex;"><span>.cache/bundle1 |
| </span></span><span style="display:flex;"><span>.cache/bundle1/bundle_state.properties |
| </span></span><span style="display:flex;"><span>.cache/bundle1/storage |
| </span></span><span style="display:flex;"><span>.cache/bundle1/version1.0 |
| </span></span><span style="display:flex;"><span>.cache/bundle1/version1.0/libshelld.so.2 |
| </span></span><span style="display:flex;"><span>.cache/bundle1/version1.0/libshell.so.2 |
| </span></span><span style="display:flex;"><span>.cache/bundle1/version1.0/META-INF |
| </span></span><span style="display:flex;"><span>.cache/bundle1/version1.0/META-INF/MANIFEST.MF |
| </span></span><span style="display:flex;"><span>.cache/bundle2 |
| </span></span><span style="display:flex;"><span>.cache/bundle2/bundle_state.properties |
| </span></span><span style="display:flex;"><span>.cache/bundle2/storage |
| </span></span><span style="display:flex;"><span>.cache/bundle2/version1.0 |
| </span></span><span style="display:flex;"><span>.cache/bundle2/version1.0/libshell_tuid.so.1 |
| </span></span><span style="display:flex;"><span>.cache/bundle2/version1.0/META-INF |
| </span></span><span style="display:flex;"><span>.cache/bundle2/version1.0/META-INF/MANIFEST.MF |
| </span></span></code></pre></div><p>The entry <code>.cache/bundle1/version1.0</code> is the resource bundle cache and the entry <code>.cache/bundle1/storage</code> is the |
| persistent storage bundle cache for the <code>Celix::shell</code> bundle.</p> |
| <h2 id="framework-configuration-options">Framework configuration options</h2> |
| <p>The Apache Celix framework can be configured using framework properties.</p> |
| <p>The framework properties can be provided in the following ways:</p> |
| <ul> |
| <li>Using the Apache Celix launcher with a “config.properties” file.</li> |
| <li>Creating a framework using the framework factory and providing a celix_properties_t*.</li> |
| <li>Setting environment variables with the prefix “CELIX_”.</li> |
| </ul> |
| <p>Note that the config properties and environment variables are only read once when the framework is created. |
| So changing the environment variables after the framework is created will not have any effect.</p> |
| <p>The following framework properties are supported:</p> |
| <table> |
| <thead> |
| <tr> |
| <th>Framework Property</th> |
| <th>Default Value</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>CELIX_FRAMEWORK_CACHE_DIR</td> |
| <td>“.cache”</td> |
| <td>The directory where the Apache Celix framework will store its data.</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_CACHE_USE_TMP_DIR</td> |
| <td>“false”</td> |
| <td>If true, the Apache Celix framework will use the system temp directory for the cache directory.</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_CLEAN_CACHE_DIR_ON_CREATE</td> |
| <td>“false”</td> |
| <td>If true, the Apache Celix framework will clean the cache directory on create.</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_FRAMEWORK_UUID</td> |
| <td>""</td> |
| <td>The UUID of the Apache Celix framework. If not set, a random UUID will be generated.</td> |
| </tr> |
| <tr> |
| <td>CELIX_BUNDLES_PATH</td> |
| <td>“bundles”</td> |
| <td>The directories where the Apache Celix framework will search for bundles. Multiple directories can be provided separated by a colon.</td> |
| </tr> |
| <tr> |
| <td>CELIX_LOAD_BUNDLES_WITH_NODELETE</td> |
| <td>“false”</td> |
| <td>If true, the Apache Celix framework will load bundle libraries with the RTLD_NODELETE flags. Note for cmake build type Debug, the default is “true”, otherwise the default is “false”</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_STATIC_EVENT_QUEUE_SIZE</td> |
| <td>“100”</td> |
| <td>The size of the static event queue. If more than 100 events in the queue are needed, dynamic memory allocation will be used.</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_AUTO_START_0</td> |
| <td>""</td> |
| <td>The bundles to install and start after the framework is started. Multiple bundles can be provided separated by a space.</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_AUTO_START_1</td> |
| <td>""</td> |
| <td>The bundles to install and start after the framework is started. Multiple bundles can be provided separated by a space.</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_AUTO_START_2</td> |
| <td>""</td> |
| <td>The bundles to install and start after the framework is started. Multiple bundles can be provided separated by a space.</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_AUTO_START_3</td> |
| <td>""</td> |
| <td>The bundles to install and start after the framework is started. Multiple bundles can be provided separated by a space.</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_AUTO_START_4</td> |
| <td>""</td> |
| <td>The bundles to install and start after the framework is started. Multiple bundles can be provided separated by a space.</td> |
| </tr> |
| <tr> |
| <td>CELIX_FRAMEWORK_AUTO_START_5</td> |
| <td>""</td> |
| <td>The bundles to install and start after the framework is started. Multiple bundles can be provided separated by a space.</td> |
| </tr> |
| <tr> |
| <td>CELIX_AUTO_INSTALL</td> |
| <td>""</td> |
| <td>The bundles to install after the framework is started. Multiple bundles can be provided separated by a space.</td> |
| </tr> |
| <tr> |
| <td>CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL</td> |
| <td>“info”</td> |
| <td>The default active log level for created log services. Possible values are “trace”, “debug”, “info”, “warning”, “error” and “fatal”.</td> |
| </tr> |
| <tr> |
| <td>CELIX_ALLOWED_PROCESSING_TIME_FOR_SCHEDULED_EVENT_IN_SECONDS</td> |
| <td>“2”</td> |
| <td>The allowed processing time for scheduled events in seconds, if processing takes longer a warning message will be logged.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| |
| </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> |