Feature/585 celix conditions

bundles/shell/shell/gtest/src/ShellTestSuite.cc

@@ -25,6 +25,7 @@
 #include "celix_bundle_context.h"
 #include "celix_shell.h"
 #include "celix_framework_utils.h"
+#include "celix_constants.h"
 
 class ShellTestSuite : public ::testing::Test {
 public:
@@ -40,6 +41,9 @@ class ShellTestSuite : public ::testing::Test {
         celix_properties_set(properties, "org.osgi.framework.storage", ".cacheShellTestSuite");
         celix_properties_set(properties, "CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL", "trace");
 
+        //to ensure "query 0" is still a test case for am empty result.
+        celix_properties_setBool(properties, CELIX_FRAMEWORK_CONDITION_SERVICES_ENABLED, false);
+
         auto* cFw = celix_frameworkFactory_createFramework(properties);
         auto cCtx = celix_framework_getFrameworkContext(cFw);
 

bundles/shell/shell/src/query_command.c

@@ -20,13 +20,13 @@
 #include <string.h>
 #include <stdlib.h>
 
+#include "celix_bundle.h"
+#include "celix_bundle_context.h"
+#include "celix_constants.h"
 #include "celix_framework.h"
 #include "celix_shell_constants.h"
-#include "celix_bundle_context.h"
-#include "std_commands.h"
-#include "celix_bundle.h"
 #include "celix_utils.h"
-
+#include "std_commands.h"
 
 struct query_options {
     bool useColors;
@@ -143,9 +143,13 @@ static void queryCommand_listServices(celix_bundle_context_t *ctx, const struct
     data.nrOfProvidedServicesFound = 0;
     data.nrOfRequestedServicesFound = 0;
 
-    if (opts->bndId >= 0L) {
+    if (opts->bndId >= CELIX_FRAMEWORK_BUNDLE_ID) {
         queryCommand_listServicesForBundle(ctx, opts->bndId, &data, opts, sout, serr);
     } else {
+        //query framework bundle
+        queryCommand_listServicesForBundle(ctx, CELIX_FRAMEWORK_BUNDLE_ID, &data, opts, sout, serr);
+
+        //query rest of the bundles
         celix_array_list_t *bundleIds = celix_bundleContext_listBundles(ctx);
         for (int i = 0; i < celix_arrayList_size(bundleIds); ++i) {
             long bndId = celix_arrayList_getLong(bundleIds, i);
@@ -199,7 +203,7 @@ bool queryCommand_execute(void *_ptr, const char *command_line_str, FILE *sout,
             //check if its a number (bundle id)
             errno = 0;
             long bndId = strtol(sub_str, NULL, 10);
-            if (bndId > 0 && errno == 0 /*not EINVAL*/) {
+            if (bndId >= CELIX_FRAMEWORK_BUNDLE_ID && errno == 0 /*not EINVAL*/) {
                 opts.bndId = bndId;
             } else {
                 //not option and not a bundle id -> query

documents/framework.md

@@ -206,6 +206,36 @@ add_executable(create_framework_with_celix_launcher src/launcher.c)
 target_link_libraries(create_framework_with_celix_launcher PRIVATE Celix::framework)
 ```
 
+## Framework `celix_condition` Services
+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 `celix_condition` services.
+
+A `celix_condition` 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.
+
+The `celix_condition` service is an adaptation of the
+[OSGi 8 Condition Service Specification](https://docs.osgi.org/specification/osgi.core/8.0.0/service.condition.html).
+
+The Apache Celix framework will provide the following `celix_condition` services for the respective states:
+
+- Celix condition "true", which is always available.
+- 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.
+- 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.
+- Celix condition "components.ready". This service will be registered when the "framework.ready" or "framework.error" 
+  service is registered, all components have become active and the event queue is empty. 
+  Note that the "components.ready" condition is not part of the OSGi condition specification.
+
+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.
+
 ## Framework bundle cache
 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 

libs/framework/CMakeLists.txt

@@ -35,6 +35,7 @@ set(FRAMEWORK_SRC
         src/celix_bundle_state.c
         src/celix_framework_utils.c
         src/celix_scheduled_event.c
+        src/celix_framework_bundle.c
 )
 set(FRAMEWORK_DEPS libuuid::libuuid CURL::libcurl ZLIB::ZLIB ${CMAKE_DL_LIBS})
 

libs/framework/gtest/CMakeLists.txt

@@ -30,7 +30,8 @@ celix_bundle_headers(bundle_with_bad_export "Export-Library: $<SEMICOLON>")
 add_celix_bundle(simple_cxx_bundle SOURCES src/HelloWorldCxxActivator.cc VERSION 1.0.0)
 celix_bundle_libs(simple_cxx_bundle "PRIVATE" TRUE Celix::framework)
 add_celix_bundle(simple_cxx_dep_man_bundle SOURCES src/HelloWorldCxxActivatorWithDepMan.cc VERSION 1.0.0)
-add_celix_bundle(cmp_test_bundle SOURCES src/CmpTestBundleActivator.cc)
+add_celix_bundle(cmp_test_bundle SOURCES src/CmpTestBundleActivator.cc VERSION 1.0.0)
+add_celix_bundle(cond_test_bundle SOURCES src/CondTestBundleActivator.cc VERSION 1.0.0)
 add_subdirectory(subdir) #simple_test_bundle4, simple_test_bundle5 and sublib
 
 add_celix_bundle(unresolvable_bundle SOURCES src/nop_activator.c VERSION 1.0.0)
@@ -52,12 +53,13 @@ set(CELIX_FRAMEWORK_TEST_SOURCES
     src/DependencyManagerTestSuite.cc
     src/CxxBundleContextTestSuite.cc
     src/HelloWorldCxxActivator.cc
-    src/CxxFrameworkFactoryTestSuite.cc
+    src/FrameworkFactoryTestSuite.cc
     src/CxxBundleActivatorTestSuite.cc
     src/BundleArchiveTestSuite.cc
     src/CelixLauncherTestSuite.cc
     src/CelixBundleCacheTestSuite.cc
     src/ScheduledEventTestSuite.cc
+    src/FrameworkBundleTestSuite.cc
 )
 
 add_executable(test_framework ${CELIX_FRAMEWORK_TEST_SOURCES})
@@ -99,6 +101,7 @@ celix_get_bundle_filename(unresolvable_bundle UNRESOLVABLE_BUNDLE)
 celix_get_bundle_file(simple_cxx_bundle SIMPLE_CXX_BUNDLE_LOC)
 celix_get_bundle_file(simple_cxx_dep_man_bundle SIMPLE_CXX_DEP_MAN_BUNDLE_LOC)
 celix_get_bundle_file(cmp_test_bundle CMP_TEST_BUNDLE_LOC)
+celix_get_bundle_file(cond_test_bundle COND_TEST_BUNDLE_LOC)
 
 configure_file(config.properties.in config.properties @ONLY)
 configure_file(framework1.properties.in framework1.properties @ONLY)
@@ -118,6 +121,7 @@ target_compile_definitions(test_framework PRIVATE
         CMP_TEST_BUNDLE_LOC="${CMP_TEST_BUNDLE_LOC}"
         SIMPLE_CXX_DEP_MAN_BUNDLE_LOC="${SIMPLE_CXX_DEP_MAN_BUNDLE_LOC}"
         CMP_TEST_BUNDLE_LOC="${CMP_TEST_BUNDLE_LOC}"
+        COND_TEST_BUNDLE_LOC="${COND_TEST_BUNDLE_LOC}"
         INSTALL_AND_START_BUNDLES_CONFIG_PROPERTIES_FILE="${CMAKE_CURRENT_BINARY_DIR}/install_and_start_bundles.properties"
 )
 add_test(NAME test_framework COMMAND test_framework)
@@ -130,6 +134,8 @@ if (LINKER_WRAP_SUPPORTED)
             src/CelixBundleContextBundlesWithErrorTestSuite.cc
             src/CelixBundleCacheErrorInjectionTestSuite.cc
             src/ScheduledEventWithErrorInjectionTestSuite.cc
+            src/FrameworkBundleWithErrorInjectionTestSuite.cc
+            src/FrameworkFactoryWithErrorInjectionTestSuite.cc
     )
     target_compile_definitions(test_framework_with_ei PRIVATE
             SIMPLE_TEST_BUNDLE1_LOCATION="${SIMPLE_TEST_BUNDLE1}"
@@ -150,6 +156,7 @@ if (LINKER_WRAP_SUPPORTED)
             Celix::properties_ei
             Celix::stdlib_ei
             Celix::stat_ei
+            Celix::threads_ei
             GTest::gtest GTest::gtest_main
     )
 
@@ -222,6 +229,7 @@ if (ENABLE_TESTING_FOR_CXX14)
             CMP_TEST_BUNDLE_LOC="${CMP_TEST_BUNDLE_LOC}"
             SIMPLE_CXX_DEP_MAN_BUNDLE_LOC="${SIMPLE_CXX_DEP_MAN_WITH_CXX11_BUNDLE_LOC}"
             CMP_TEST_BUNDLE_LOC="${CMP_TEST_BUNDLE_LOC}"
+            COND_TEST_BUNDLE_LOC="${COND_TEST_BUNDLE_LOC}"
             INSTALL_AND_START_BUNDLES_CONFIG_PROPERTIES_FILE="${CMAKE_CURRENT_BINARY_DIR}/install_and_start_bundles.properties"
     )
     add_test(NAME test_framework_with_cxx14 COMMAND test_framework_with_cxx14)

libs/framework/gtest/src/BundleArchiveWithErrorInjectionTestSuite.cc

@@ -43,8 +43,9 @@
 class BundleArchiveWithErrorInjectionTestSuite : public ::testing::Test {
   public:
     BundleArchiveWithErrorInjectionTestSuite() {
-        fw = celix::createFramework(
-            {{"CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL", "trace"}, {CELIX_FRAMEWORK_CLEAN_CACHE_DIR_ON_CREATE, "true"}});
+        fw = celix::createFramework({{"CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL", "trace"},
+                                     {CELIX_FRAMEWORK_CLEAN_CACHE_DIR_ON_CREATE, "true"},
+                                     {CELIX_FRAMEWORK_CONDITION_SERVICES_ENABLED, "false"}});
         ctx = fw->getFrameworkBundleContext();
     }
 

libs/framework/gtest/src/CelixBundleContextBundlesTestSuite.cc

@@ -46,10 +46,12 @@ class CelixBundleContextBundlesTestSuite : public ::testing::Test {
     const char * const TEST_BND_UNRESOLVABLE_LOC = "" TEST_BUNDLE_UNRESOLVABLE_LOCATION "";
 
     CelixBundleContextBundlesTestSuite() {
-        properties = properties_create();
-        properties_set(properties, "LOGHELPER_ENABLE_STDOUT_FALLBACK", "true");
-        properties_set(properties, "org.osgi.framework.storage.clean", "true");
-        properties_set(properties, "org.osgi.framework.storage", ".cacheBundleContextTestFramework");
+        properties = celix_properties_create();
+        celix_properties_set(properties, "LOGHELPER_ENABLE_STDOUT_FALLBACK", "true");
+        celix_properties_set(properties, "org.osgi.framework.storage.clean", "true");
+        celix_properties_set(properties, "org.osgi.framework.storage", ".cacheBundleContextTestFramework");
+        celix_properties_set(properties, "CELIX_FRAMEWORK_CONDITION_SERVICES_ENABLED", "false");
+
 
         fw = celix_frameworkFactory_createFramework(properties);
         ctx = framework_getContext(fw);

libs/framework/gtest/src/CelixBundleContextServicesTestSuite.cc

@@ -47,6 +47,7 @@ class CelixBundleContextServicesTestSuite : public ::testing::Test {
         celix_properties_set(properties, "org.osgi.framework.storage.clean", "onFirstInit");
         celix_properties_set(properties, "org.osgi.framework.storage", ".cacheBundleContextTestFramework");
         celix_properties_set(properties, "CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL", "trace");
+        celix_properties_set(properties, "CELIX_FRAMEWORK_CONDITION_SERVICES_ENABLED", "false");
         celix_properties_setLong(properties, CELIX_FRAMEWORK_STATIC_EVENT_QUEUE_SIZE,  256); //ensure that the floodEventLoopTest overflows the static event queue size
 
         fw = celix_frameworkFactory_createFramework(properties);

libs/framework/gtest/src/CondTestBundleActivator.cc

@@ -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.
+ */
+
+#include "celix/BundleActivator.h"
+#include "celix_condition.h"
+
+/**
+ * @brief Empty Test Component for testing the condition service
+ */
+class CondComponent {
+public:
+    CondComponent() = default;
+};
+
+class CondTestBundleActivator {
+  public:
+    explicit CondTestBundleActivator(const std::shared_ptr<celix::BundleContext>& ctx) {
+        registration = ctx->registerUnmanagedService<celix_condition>(&condition, CELIX_CONDITION_SERVICE_NAME)
+                .addProperty(CELIX_CONDITION_ID, "test")
+                .build();
+
+        auto& cmp = ctx->getDependencyManager()->createComponent<CondComponent>();
+        cmp.createServiceDependency<celix_condition>(CELIX_CONDITION_SERVICE_NAME)
+                .setFilter("(condition.id=does-not-exists)")
+                .setRequired(true);
+
+        cmp.build();
+    }
+
+  private:
+    std::shared_ptr<celix::ServiceRegistration> registration{};
+    celix_condition condition{};
+};
+
+CELIX_GEN_CXX_BUNDLE_ACTIVATOR(CondTestBundleActivator)

libs/framework/gtest/src/CxxBundleContextTestSuite.cc

@@ -33,10 +33,10 @@ class CxxBundleContextTestSuite : public ::testing::Test {
     static constexpr const char * const TEST_BND2_LOC = "" SIMPLE_TEST_BUNDLE2_LOCATION "";
 
     CxxBundleContextTestSuite() {
-        auto* properties = properties_create();
-        properties_set(properties, "LOGHELPER_ENABLE_STDOUT_FALLBACK", "true");
-        properties_set(properties, "org.osgi.framework.storage.clean", "onFirstInit");
-        properties_set(properties, "org.osgi.framework.storage", ".cacheCxxBundleContextTestFramework");
+        auto* properties = celix_properties_create();
+        celix_properties_set(properties, "LOGHELPER_ENABLE_STDOUT_FALLBACK", "true");
+        celix_properties_set(properties, "org.osgi.framework.storage.clean", "onFirstInit");
+        celix_properties_set(properties, "CELIX_FRAMEWORK_CONDITION_SERVICES_ENABLED", "false");
 
         auto* cfw = celix_frameworkFactory_createFramework(properties);
         fw = std::shared_ptr<celix_framework_t>{cfw, [](celix_framework_t* f){ celix_frameworkFactory_destroyFramework(f); }};