Apache Celix  2.4.0
Apache Celix is a framework for C, C++14 and C++17 to develop dynamic modular software applications using component and in-process service-oriented programming.
Namespaces | Classes | Enumerations | Functions | Variables
celix Namespace Reference

Namespaces

 dm
 
 impl
 

Classes

class  AbstractTracker
 The AbstractTracker class is the base of all C++ Celix trackers. More...
 
class  Bundle
 An installed bundle in the Celix framework. More...
 
class  BundleContext
 The bundle context is used to interact with the Celix framework. More...
 
class  BundleTracker
 The BundleTracker class tracks bundles. More...
 
class  BundleTrackerBuilder
 Fluent builder API to track bundles. More...
 
class  Framework
 A Celix framework instance. A framework is also known as a system bundle. More...
 
class  GenericServiceTracker
 he GenericServiceTracker class is a specialization of the AbstractTracker for managing a service tracker. More...
 
class  MetaTracker
 The MetaTracker track service trackers. More...
 
class  MetaTrackerBuilder
 Fluent builder API to track service trackers. More...
 
class  ScheduledEvent
 A C++ abstraction for a scheduled event in Celix. More...
 
class  ScheduledEventBuilder
 A C++ builder for a ScheduledEvent object. More...
 
class  ServiceFactory
 
class  ServiceRegistration
 A registered service. More...
 
class  ServiceRegistrationBuilder
 Fluent builder API to build a new service registration for a service. More...
 
class  ServiceRegistrationException
 Celix Service Registration Exception. More...
 
class  ServiceTracker
 The ServiceTracker class tracks services. More...
 
class  ServiceTrackerBuilder
 Fluent builder API to track services. More...
 
struct  ServiceTrackerInfo
 A trivial struct containing information about a service tracker. More...
 
class  TrackerException
 Celix Tracker Exception. More...
 
class  UseServiceBuilder
 Fluent builder API to use a service or services. More...
 

Enumerations

enum  BundleState : std::uint8_t {
  BundleState::UNKNOWN, BundleState::UNINSTALLED, BundleState::INSTALLED, BundleState::RESOLVED,
  BundleState::STARTING, BundleState::STOPPING, BundleState::ACTIVE
}
 
enum  ServiceRegistrationState : std::uint8_t { ServiceRegistrationState::REGISTERING, ServiceRegistrationState::REGISTERED, ServiceRegistrationState::UNREGISTERING, ServiceRegistrationState::UNREGISTERED }
 
enum  TrackerState : std::uint8_t { TrackerState::OPENING, TrackerState::OPEN, TrackerState::CLOSING, TrackerState::CLOSED }
 The tracker state. More...
 

Functions

std::shared_ptr< celix::FrameworkcreateFramework (const celix::Properties &properties={})
 Create a new celix Framework instance. More...
 
std::vector< std::string > listEmbeddedBundles ()
 List the embedded bundles in the executable. More...
 
std::size_t installEmbeddedBundles (celix::Framework &framework, bool autoStart=true)
 Install the embedded bundles in the executable. More...
 
std::size_t installBundleSet (celix::Framework &framework, std::string_view bundleSet, bool autoStart=true)
 Install bundles to the provided framework using the provided bundle set. More...
 

Variables

constexpr long FRAMEWORK_BUNDLE_ID = CELIX_FRAMEWORK_BUNDLE_ID
 The bundle id (value 0) used to identify the Celix framework. More...
 
constexpr const char *const SERVICE_NAME = CELIX_FRAMEWORK_SERVICE_NAME
 Service property (named "objectClass") identifying the service name under which a service was registered in the Celix framework. More...
 
constexpr const char *const SERVICE_ID = CELIX_FRAMEWORK_SERVICE_ID
 Service property (named "service.id") identifying a service's registration number (of type long). More...
 
constexpr const char *const SERVICE_BUNDLE_ID = CELIX_FRAMEWORK_SERVICE_BUNDLE_ID
 Service property (named service.bundleid) identifying the bundle id of the bundle registering the service. More...
 
constexpr const char *const SERVICE_SCOPE = CELIX_FRAMEWORK_SERVICE_SCOPE
 Service property (named service.scope) identifying a service's scope. More...
 
constexpr const char *const SERVICE_SCOPE_SINGLETON = CELIX_FRAMEWORK_SERVICE_SCOPE_SINGLETON
 Service scope is singleton. All bundles using the service receive the same service object. More...
 
constexpr const char *const SERVICE_SCOPE_BUNDLE = CELIX_FRAMEWORK_SERVICE_SCOPE_BUNDLE
 Service scope is bundle. Each bundle using the service receives a customized service object. More...
 
constexpr const char *const SERVICE_RANKING = CELIX_FRAMEWORK_SERVICE_RANKING
 Service property (named "service.ranking") identifying a service's ranking number (of type long). More...
 
constexpr const char *const SERVICE_VERSION = CELIX_FRAMEWORK_SERVICE_VERSION
 Service property (named "service.version") specifying the optional version of a service. More...
 
constexpr const char *const FRAMEWORK_CACHE_DIR = CELIX_FRAMEWORK_FRAMEWORK_CACHE_DIR
 Celix framework environment property (named "CELIX_FRAMEWORK_CACHE_DIR") specifying the cache directory used for the bundle caches. More...
 
constexpr const char *const FRAMEWORK_STORAGE = CELIX_FRAMEWORK_FRAMEWORK_STORAGE
 
constexpr const char *const FRAMEWORK_UUID = CELIX_FRAMEWORK_FRAMEWORK_UUID
 Celix framework environment property (named "org.osgi.framework.uuid") specifying the UUID for the framework UUID. More...
 
constexpr const char *const FRAMEWORK_STATIC_EVENT_QUEUE_SIZE = CELIX_FRAMEWORK_STATIC_EVENT_QUEUE_SIZE
 Celix framework environment property (named "CELIX_FRAMEWORK_STATIC_EVENT_QUEUE_SIZE") which configures the static event size queue used by the Celix framework. More...
 
constexpr const char *const AUTO_START_0 = CELIX_AUTO_START_0
 Celix framework environment property (named "CELIX_AUTO_START_0") which specified a (ordered) space separated set of bundles to load and auto start when the Celix framework is started. More...
 
constexpr const char *const AUTO_START_1 = CELIX_AUTO_START_1
 
constexpr const char *const AUTO_START_2 = CELIX_AUTO_START_2
 
constexpr const char *const AUTO_START_3 = CELIX_AUTO_START_3
 
constexpr const char *const AUTO_START_4 = CELIX_AUTO_START_4
 
constexpr const char *const AUTO_START_5 = CELIX_AUTO_START_5
 
constexpr const char *const AUTO_START_6 = CELIX_AUTO_START_6
 
constexpr const char *const AUTO_INSTALL = CELIX_AUTO_INSTALL
 Celix framework environment property (named "CELIX_AUTO_INSTALL") which specified a (ordered) space separated set of bundles to install when the Celix framework is started. More...
 
constexpr const char *const BUNDLES_PATH_NAME = CELIX_BUNDLES_PATH_NAME
 Celix framework environment property (named "CELIX_BUNDLES_PATH") which specified a ; separated list of bundles path used when installing bundles with relative paths. More...
 
constexpr const char *const LOAD_BUNDLES_WITH_NODELETE = CELIX_LOAD_BUNDLES_WITH_NODELETE
 Celix framework environment property (named "CELIX_LOAD_BUNDLES_WITH_NODELETE") which configures if library loaded from bundles should be opened with the RTLD_NODELETE flag. More...
 
constexpr const char *const FRAMEWORK_CONDITION_SERVICES_ENABLED = CELIX_FRAMEWORK_CONDITION_SERVICES_ENABLED
 Celix framework environment property (named "CELIX_FRAMEWORK_CONDITION_SERVICES_ENABLED") to configure whether framework condition services are enabled or not. Default is true. Should be a boolean value. More...
 

Enumeration Type Documentation

◆ BundleState

enum celix::BundleState : std::uint8_t
strong
Enumerator
UNKNOWN 
UNINSTALLED 
INSTALLED 
RESOLVED 
STARTING 
STOPPING 
ACTIVE 

◆ ServiceRegistrationState

enum celix::ServiceRegistrationState : std::uint8_t
strong
Enumerator
REGISTERING 
REGISTERED 
UNREGISTERING 
UNREGISTERED 

◆ TrackerState

enum celix::TrackerState : std::uint8_t
strong

The tracker state.

Enumerator
OPENING 
OPEN 
CLOSING 
CLOSED 

Function Documentation

◆ createFramework()

std::shared_ptr<celix::Framework> celix::createFramework ( const celix::Properties &  properties = {})
inline

Create a new celix Framework instance.

Exceptions
celix::Exceptionif the framework could not be created.

◆ installBundleSet()

std::size_t celix::installBundleSet ( celix::Framework framework,
std::string_view  bundleSet,
bool  autoStart = true 
)
inline

Install bundles to the provided framework using the provided bundle set.

Bundles will be installed in the order they appear in the provided bundleSet. If autStart is true, all bundles will be installed first and then started in the same order.

The bundle set should be , separated set of bundle urls. Example:

constexpr std::string_view bundleSet = "file:///usr/local/share/celix/bundles/celix_shell.zip,embedded://example_bundle";

This function is designed to be used in combination with the Celix CMake command celix_target_bundle_set_definition.

Parameters
fwThe Celix framework used to install the bundles.
bundleSetA set of , seperated bundles urls.
autoStartWhether to also start the installed bundles.
Returns
The number of installed bundles.

◆ installEmbeddedBundles()

std::size_t celix::installEmbeddedBundles ( celix::Framework framework,
bool  autoStart = true 
)
inline

Install the embedded bundles in the executable.

Bundles will be installed in the order they appear in the return of celix_framework_utils_listEmbeddedBundles.

If autStart is true, all embedded bundles will be installed first and then started in the same order.

Parameters
fwThe Celix framework used to install the bundles.
autoStartWhether to also start the installed bundles.
Returns
The number of installed bundles.

◆ listEmbeddedBundles()

std::vector<std::string> celix::listEmbeddedBundles ( )
inline

List the embedded bundles in the executable.

This function will check if there are embedded bundles in the executable / program by trying to lookup the symbol celix_embedded_bundles.

If present the celix_embedded_bundles should be a point to a const char* containing a , seperated list of embedded bundle urls. For example:

const char * const celix_embedded_bundles = "embedded://bundle1,embedded://bundle2";
Returns
A vector of embedded bundle urls.

Variable Documentation

◆ AUTO_INSTALL

constexpr const char* const celix::AUTO_INSTALL = CELIX_AUTO_INSTALL
constexpr

Celix framework environment property (named "CELIX_AUTO_INSTALL") which specified a (ordered) space separated set of bundles to install when the Celix framework is started.

The Celix framework will first install and start bundles defined in the properties CELIX_AUTO_START_0 till CELIX_AUTO_START_6 and then install (ano not start!) the bundles listed in CELIX_AUTO_INSTALL.

When the Celix framework stops the bundles are stopped in the reverse order. Started bundles in CELIX_AUTO_INSTALL are stopped first and of those bundles, the bundle mentioned last in a CELIX_AUTO_INSTALL set is stopped first. Then bundles defined in CELIX_AUTO_START_6 are stopped, followed by bundles defined in CELIX_AUTO_START_5, etc.

◆ AUTO_START_0

constexpr const char* const celix::AUTO_START_0 = CELIX_AUTO_START_0
constexpr

Celix framework environment property (named "CELIX_AUTO_START_0") which specified a (ordered) space separated set of bundles to load and auto start when the Celix framework is started.

The Celix framework will first start bundles in for AUTO_START_0 and lastly start bundles in AUTO_START_6. Bundles which are also started in the order they appear in the AUTO_START set; first bundles mentioned is started first. When the Celix framework stops the bundles are stopped in the reverse order. Bundles in AUTO_START_6 are stopped first and of those bundles, the bundle mentioned last in a AUTO_START set is stopped first.

◆ AUTO_START_1

constexpr const char* const celix::AUTO_START_1 = CELIX_AUTO_START_1
constexpr

◆ AUTO_START_2

constexpr const char* const celix::AUTO_START_2 = CELIX_AUTO_START_2
constexpr

◆ AUTO_START_3

constexpr const char* const celix::AUTO_START_3 = CELIX_AUTO_START_3
constexpr

◆ AUTO_START_4

constexpr const char* const celix::AUTO_START_4 = CELIX_AUTO_START_4
constexpr

◆ AUTO_START_5

constexpr const char* const celix::AUTO_START_5 = CELIX_AUTO_START_5
constexpr

◆ AUTO_START_6

constexpr const char* const celix::AUTO_START_6 = CELIX_AUTO_START_6
constexpr

◆ BUNDLES_PATH_NAME

constexpr const char* const celix::BUNDLES_PATH_NAME = CELIX_BUNDLES_PATH_NAME
constexpr

Celix framework environment property (named "CELIX_BUNDLES_PATH") which specified a ; separated list of bundles path used when installing bundles with relative paths.

Default value is "bundles".

If a Celix framework tries to install a bundle using a relative path it will use the CELIX_BUNDLES_PATH to find the bundle files. This can be seen as a LD_LIBRARY_PATH for bundles.

◆ FRAMEWORK_BUNDLE_ID

constexpr long celix::FRAMEWORK_BUNDLE_ID = CELIX_FRAMEWORK_BUNDLE_ID
constexpr

The bundle id (value 0) used to identify the Celix framework.

◆ FRAMEWORK_CACHE_DIR

constexpr const char* const celix::FRAMEWORK_CACHE_DIR = CELIX_FRAMEWORK_FRAMEWORK_CACHE_DIR
constexpr

Celix framework environment property (named "CELIX_FRAMEWORK_CACHE_DIR") specifying the cache directory used for the bundle caches.

If not specified ".cache" is used.

◆ FRAMEWORK_CONDITION_SERVICES_ENABLED

constexpr const char* const celix::FRAMEWORK_CONDITION_SERVICES_ENABLED = CELIX_FRAMEWORK_CONDITION_SERVICES_ENABLED
constexpr

Celix framework environment property (named "CELIX_FRAMEWORK_CONDITION_SERVICES_ENABLED") to configure whether framework condition services are enabled or not. Default is true. Should be a boolean value.

◆ FRAMEWORK_STATIC_EVENT_QUEUE_SIZE

constexpr const char* const celix::FRAMEWORK_STATIC_EVENT_QUEUE_SIZE = CELIX_FRAMEWORK_STATIC_EVENT_QUEUE_SIZE
constexpr

Celix framework environment property (named "CELIX_FRAMEWORK_STATIC_EVENT_QUEUE_SIZE") which configures the static event size queue used by the Celix framework.

The Celix framework handle service events in a event thread. This thread uses a static allocated event queue with a fixed size and dynamic event queue if the static event queue is full. The decrease the memory footprint a smaller static event queue size can be used and to improve performance during heavy load a bigger static event queue size can be used.

Default is CELIX_FRAMEWORK_DEFAULT_STATIC_EVENT_QUEUE_SIZE which is 1024, but can be override with a compiler define (same name).

◆ FRAMEWORK_STORAGE

constexpr const char* const celix::FRAMEWORK_STORAGE = CELIX_FRAMEWORK_FRAMEWORK_STORAGE
constexpr

◆ FRAMEWORK_UUID

constexpr const char* const celix::FRAMEWORK_UUID = CELIX_FRAMEWORK_FRAMEWORK_UUID
constexpr

Celix framework environment property (named "org.osgi.framework.uuid") specifying the UUID for the framework UUID.

The framework UUID is used to uniquely identify a single framework. If no framework uuid is provided random uuid will be generated during startup.

Note
The Celix framework expects framework UUIDs to be unique per process.

◆ LOAD_BUNDLES_WITH_NODELETE

constexpr const char* const celix::LOAD_BUNDLES_WITH_NODELETE = CELIX_LOAD_BUNDLES_WITH_NODELETE
constexpr

Celix framework environment property (named "CELIX_LOAD_BUNDLES_WITH_NODELETE") which configures if library loaded from bundles should be opened with the RTLD_NODELETE flag.

The default value is false.

If the value is "true" the RTLD_NODELETE flag will be used to load the shared libraries of bundles. This can be useful for debugging bundles.

◆ SERVICE_BUNDLE_ID

constexpr const char* const celix::SERVICE_BUNDLE_ID = CELIX_FRAMEWORK_SERVICE_BUNDLE_ID
constexpr

Service property (named service.bundleid) identifying the bundle id of the bundle registering the service.

This property is set by the Celix framework when a service is registered. The value of this property must be of type Long.

◆ SERVICE_ID

constexpr const char* const celix::SERVICE_ID = CELIX_FRAMEWORK_SERVICE_ID
constexpr

Service property (named "service.id") identifying a service's registration number (of type long).

The value of this property is assigned by the Celix framework when a service is registered. The Celix framework assigns a unique value that is larger than all previously assigned values since the Celix framework was started.

◆ SERVICE_NAME

constexpr const char* const celix::SERVICE_NAME = CELIX_FRAMEWORK_SERVICE_NAME
constexpr

Service property (named "objectClass") identifying the service name under which a service was registered in the Celix framework.

This property is set by the Celix framework when a service is registered.

◆ SERVICE_RANKING

constexpr const char* const celix::SERVICE_RANKING = CELIX_FRAMEWORK_SERVICE_RANKING
constexpr

Service property (named "service.ranking") identifying a service's ranking number (of type long).

This property may be supplied in the properties passed to the BundleContext::registerService method. The service ranking is used by the Framework to order services for the service trackers. Services with the highest ranking are first in the tracked services set and highest ranking service is used when setting a service (tracking a single service).

If services have the same service ranking, the oldest service precedes the older services (so lower service id before higher service id).

The default ranking is 0. A service with a ranking of LONG_MAX is very likely to be returned as the default service, whereas a service with a ranking of LONG_MIN is very unlikely to be returned.

◆ SERVICE_SCOPE

constexpr const char* const celix::SERVICE_SCOPE = CELIX_FRAMEWORK_SERVICE_SCOPE
constexpr

Service property (named service.scope) identifying a service's scope.

This property is set by the Framework when a service is registered. If the registered object implements service factory, then the value of this service property will be CELIX_FRAMEWORK_SERVICE_SCOPE_BUNDLE. Otherwise, the value of this service property will be CELIX_FRAMEWORK_SERVICE_SCOPE_SINGLETON.

Warning
Note that the scope "prototype" is not supported in Celix.

◆ SERVICE_SCOPE_BUNDLE

constexpr const char* const celix::SERVICE_SCOPE_BUNDLE = CELIX_FRAMEWORK_SERVICE_SCOPE_BUNDLE
constexpr

Service scope is bundle. Each bundle using the service receives a customized service object.

◆ SERVICE_SCOPE_SINGLETON

constexpr const char* const celix::SERVICE_SCOPE_SINGLETON = CELIX_FRAMEWORK_SERVICE_SCOPE_SINGLETON
constexpr

Service scope is singleton. All bundles using the service receive the same service object.

◆ SERVICE_VERSION

constexpr const char* const celix::SERVICE_VERSION = CELIX_FRAMEWORK_SERVICE_VERSION
constexpr

Service property (named "service.version") specifying the optional version of a service.

A version can be specified with major, minor and micro element in the form of <major>.<minor>.<micro>. Examples:

  • 1.0.0
  • 2.1.2

Version can be filter with a filter range when using and/or tracking services. A filter range is specified using Maven-style version range:

  • [1,2) (version 1.0.0 (inclusive) until, but not including version 2.0.0 (exclusive)
  • 1.1.3, 1.5