The bundle context is used to interact with the Celix framework. More...

#include <BundleContext.h>

Public Member Functions
	BundleContext (celix_bundle_context_t *_cCtx)

template<typename I , typename Implementer >
ServiceRegistrationBuilder< I >	registerService (std::shared_ptr< Implementer > implementer, std::string_view name={})
	Register a service in the Celix framework using a fluent builder API. More...

template<typename I , typename Implementer >
ServiceRegistrationBuilder< I >	registerUnmanagedService (Implementer *svc, std::string_view name={})
	Register a (unmanaged) service in the Celix framework using a fluent builder API. More...

template<typename I >
UseServiceBuilder< I >	useService (std::string_view name={})
	Use a service registered in the Celix framework using a fluent builder API. More...

template<typename I >
UseServiceBuilder< I >	useServices (std::string_view name={})
	Use services registered in the Celix framework using a fluent builder API. More...

template<typename I >
long	findService (std::string_view filter={}, std::string_view versionRange={})
	Finds the highest ranking service using the optional provided (LDAP) filter and version range. More...

long	findServiceWithName (std::string_view name, std::string_view filter={}, std::string_view versionRange={})
	Finds the highest ranking service using the provided service name and the optional (LDAP) filter and version range. More...

template<typename I >
std::vector< long >	findServices (std::string_view filter={}, std::string_view versionRange={})
	Finds all services matching the optional provided (LDAP) filter and version range. More...

std::vector< long >	findServicesWithName (std::string_view name, std::string_view filter={}, std::string_view versionRange={})
	Finds all service matching the provided service name and the optional (LDAP) filter and version range. More...

template<typename I >
ServiceTrackerBuilder< I >	trackServices (std::string_view name={})
	Track services in the Celix framework using a fluent builder API. More...

ServiceTrackerBuilder< void >	trackAnyServices ()
	Track services in the Celix framework using a fluent builder API. More...

BundleTrackerBuilder	trackBundles ()
	Track bundles in the Celix framework using a fluent builder API. More...

template<typename I >
MetaTrackerBuilder	trackServiceTrackers (std::string_view name={})
	Track service trackers in the Celix framework using a fluent builder API. More...

MetaTrackerBuilder	trackAnyServiceTrackers ()
	Track service trackers in the Celix framework using a fluent builder API. More...

ScheduledEventBuilder	scheduledEvent ()
	Schedule a callback to be called after the given initial delay and/or interval using a fluent builder API. More...

long	installBundle (std::string_view bndLocation, bool autoStart=true)
	Install and optional start a bundle. More...

bool	uninstallBundle (long bndId)
	Uninstall the bundle with the provided bundle id. More...

bool	startBundle (long bndId)
	Start the bundle with the provided bundle id. More...

bool	stopBundle (long bndId)
	Stop the bundle with the provided bundle id. More...

bool	updateBundle (long bndId, std::string_view updatedBundleUrl={})
	Update the bundle with the provided bundle id async. More...

std::vector< long >	listBundleIds () const
	List the installed and started bundle ids. The bundle ids does not include the framework bundle (bundle id CELIX_FRAMEWORK_BUNDLE_ID). More...

std::vector< long >	listInstalledBundleIds ()
	List the installed bundle ids. The bundle ids does not include the framework bundle (bundle id CELIX_FRAMEWORK_BUNDLE_ID). More...

std::string	getConfigProperty (std::string_view name, std::string_view defaultValue) const
	Gets the config property for the provided name. More...

long	getConfigPropertyAsLong (std::string_view name, long defaultValue) const
	Gets the config property for the provided name and returns it as a long. More...

double	getConfigPropertyAsDouble (std::string_view name, double defaultValue) const
	Gets the config property for the provided name and returns it as a double. More...

long	getConfigPropertyAsBool (std::string_view name, bool defaultValue) const
	Gets the config property for the provided name and returns it as a bool. More...

const Bundle &	getBundle () const
	Get the bundle of this bundle context. More...

long	getBundleId () const
	Get the bundle id for the bundle of this bundle context. More...

std::shared_ptr< Framework >	getFramework () const
	Get the Celix framework for this bundle context. More...

std::shared_ptr< dm::DependencyManager >	getDependencyManager () const
	Get the Celix dependency manager for this bundle context. More...

celix_bundle_context_t *	getCBundleContext () const
	Get the C bundle context. More...

void	logTrace (const char *format...) __attribute__((format(printf
	Log a message to the Celix framework logger using the TRACE log level. More...

void	va_start (args, format)

	celix_bundleContext_vlog (cCtx.get(), CELIX_LOG_LEVEL_TRACE, format, args)

	va_end (args)

void	logDebug (const char *format...) __attribute__((format(printf
	Log a message to the Celix framework logger using the DEBUG log level. More...

void	va_start (args, format)

	celix_bundleContext_vlog (cCtx.get(), CELIX_LOG_LEVEL_DEBUG, format, args)

	va_end (args)

void	logInfo (const char *format...) __attribute__((format(printf
	Log a message to the Celix framework logger using the INFO log level. More...

void	va_start (args, format)

	celix_bundleContext_vlog (cCtx.get(), CELIX_LOG_LEVEL_INFO, format, args)

	va_end (args)

void	logWarn (const char *format...) __attribute__((format(printf
	Log a message to the Celix framework logger using the WARNING log level. More...

void	va_start (args, format)

	celix_bundleContext_vlog (cCtx.get(), CELIX_LOG_LEVEL_WARNING, format, args)

	va_end (args)

void	logError (const char *format...) __attribute__((format(printf
	Log a message to the Celix framework logger using the ERROR log level. More...

void	va_start (args, format)

	celix_bundleContext_vlog (cCtx.get(), CELIX_LOG_LEVEL_ERROR, format, args)

	va_end (args)

void	logFatal (const char *format...) __attribute__((format(printf
	Log a message to the Celix framework logger using the FATAL log level. More...

void	va_start (args, format)

	celix_bundleContext_vlog (cCtx.get(), CELIX_LOG_LEVEL_FATAL, format, args)

	va_end (args)

void	logTssErrors (celix_log_level_e level)
	Log celix per-thread error messages to the Celix framework logger using the provided log level. Silently ignores log level CELIX_LOG_LEVEL_DISABLED. More...

void	waitForEvents () const
	Wait until all Celix events for this bundle are completed. More...

void	waitIfAbleForEvents () const
	Wait (if not on the Celix event thread) until all Celix events for this bundle are completed. More...

void	waitForAllEvents () const
	Wait until all Celix events (for all bundles) are completed. More...

void	waitIfAbleForAllEvents () const
	Wait (if not on the Celix event thread) until all Celix events (for all bundles) are completed. More...

Detailed Description

The bundle context is used to interact with the Celix framework.

The bundle context represent a bundle and can be used to:

Register, use and track services
Install, start, stop and uninstall bundles (runtime)
log on framework level
Access bundles
Get config properties

Note: Provided std::string_view values must be null terminated strings.; Thread safe.

Constructor & Destructor Documentation

◆ BundleContext()

celix::BundleContext::BundleContext ( celix_bundle_context_t * _cCtx )

inlineexplicit

Member Function Documentation

◆ celix_bundleContext_vlog() [1/6]

celix::BundleContext::celix_bundleContext_vlog	(	cCtx.	get(),
		CELIX_LOG_LEVEL_DEBUG	,
		format	,
		args
	)

◆ celix_bundleContext_vlog() [2/6]

celix::BundleContext::celix_bundleContext_vlog	(	cCtx.	get(),
		CELIX_LOG_LEVEL_ERROR	,
		format	,
		args
	)

◆ celix_bundleContext_vlog() [3/6]

celix::BundleContext::celix_bundleContext_vlog	(	cCtx.	get(),
		CELIX_LOG_LEVEL_FATAL	,
		format	,
		args
	)

◆ celix_bundleContext_vlog() [4/6]

celix::BundleContext::celix_bundleContext_vlog	(	cCtx.	get(),
		CELIX_LOG_LEVEL_INFO	,
		format	,
		args
	)

◆ celix_bundleContext_vlog() [5/6]

celix::BundleContext::celix_bundleContext_vlog	(	cCtx.	get(),
		CELIX_LOG_LEVEL_TRACE	,
		format	,
		args
	)

◆ celix_bundleContext_vlog() [6/6]

celix::BundleContext::celix_bundleContext_vlog	(	cCtx.	get(),
		CELIX_LOG_LEVEL_WARNING	,
		format	,
		args
	)

◆ findService()

template<typename I >

long celix::BundleContext::findService	(	std::string_view	filter = `{}`,
		std::string_view	versionRange = `{}`
	)

inline

Finds the highest ranking service using the optional provided (LDAP) filter and version range.

Uses celix::typeName to defer the service name.

Template Parameters

I	the service type to found.

Parameters

filter	An optional LDAP filter.
versionRange	An optional version range.

Returns: The service id of the found service or -1 if the service was not found.

◆ findServices()

template<typename I >

std::vector<long> celix::BundleContext::findServices	(	std::string_view	filter = `{}`,
		std::string_view	versionRange = `{}`
	)

inline

Finds all services matching the optional provided (LDAP) filter and version range.

Note uses celix::typeName to defer the service name.

Template Parameters

I	the service type to found.

Parameters

filter	An optional LDAP filter.
versionRange	An optional version range.

Returns: A vector of service ids.

◆ findServicesWithName()

std::vector<long> celix::BundleContext::findServicesWithName	(	std::string_view	name,
		std::string_view	filter = `{}`,
		std::string_view	versionRange = `{}`
	)

inline

Finds all service matching the provided service name and the optional (LDAP) filter and version range.

Parameters

The	service name. (Can be empty to find service with any name).
filter	An optional LDAP filter.
versionRange	An optional version range.

Returns: A vector of service ids.

◆ findServiceWithName()

long celix::BundleContext::findServiceWithName	(	std::string_view	name,
		std::string_view	filter = `{}`,
		std::string_view	versionRange = `{}`
	)

inline

Finds the highest ranking service using the provided service name and the optional (LDAP) filter and version range.

Parameters

The	service name. (Can be empty to find service with any name).
filter	An optional LDAP filter.
versionRange	An optional version range.

Returns: The service id of the found service or -1 if the service was not found.

◆ getBundle()

const Bundle& celix::BundleContext::getBundle ( ) const

inline

Get the bundle of this bundle context.

◆ getBundleId()

long celix::BundleContext::getBundleId ( ) const

inline

Get the bundle id for the bundle of this bundle context.

◆ getCBundleContext()

celix_bundle_context_t* celix::BundleContext::getCBundleContext ( ) const

inline

Get the C bundle context.

Warning: Try not the depend on the C API from a C++ BundleContext. If features are missing these should be added to the C++ API.

◆ getConfigProperty()

std::string celix::BundleContext::getConfigProperty	(	std::string_view	name,
		std::string_view	defaultValue
	)		const

inline

Gets the config property for the provided name.

First the provided name will be used to lookup an environment variable of that name. If this is not found, the config properties of the Celix framework will be used (config.properties). Note that by design this means that environment variable can be used to override config properties.

Parameters

name	The name of the property to receive.
defaultVal	The default value to use if the property is not found.

Returns: The config property value for the provided key or the provided defaultValue is the name is not found.

◆ getConfigPropertyAsBool()

long celix::BundleContext::getConfigPropertyAsBool	(	std::string_view	name,
		bool	defaultValue
	)		const

inline

Gets the config property for the provided name and returns it as a bool.

First the provided name will be used to lookup an environment variable of that name. If no this is not found or not a valid bool, the config properties of the Celix framework will be used (config.properties). Note that by design this means that environment variable can be used to override config properties.

Valid bools are "true" and "false" (case insensitive)

Parameters

name	The name of the property to receive.
defaultVal	The default value to use if the property is not found.

Returns: The config property value (as boolean) for the provided key or the provided defaultValue is the name is not found or not a valid boolean.

◆ getConfigPropertyAsDouble()

double celix::BundleContext::getConfigPropertyAsDouble	(	std::string_view	name,
		double	defaultValue
	)		const

inline

Gets the config property for the provided name and returns it as a double.

First the provided name will be used to lookup an environment variable of that name. If no this is not found or not a valid double, the config properties of the Celix framework will be used (config.properties). Note that by design this means that environment variable can be used to override config properties.

Parameters

name	The name of the property to receive.
defaultVal	The default value to use if the property is not found.

Returns: The config property value (as double) for the provided key or the provided defaultValue is the name is not found or not a valid double.

◆ getConfigPropertyAsLong()

long celix::BundleContext::getConfigPropertyAsLong	(	std::string_view	name,
		long	defaultValue
	)		const

inline

Gets the config property for the provided name and returns it as a long.

First the provided name will be used to lookup an environment variable of that name. If no this is not found or not a valid long, the config properties of the Celix framework will be used (config.properties). Note that by design this means that environment variable can be used to override config properties.

Parameters

name	The name of the property to receive.
defaultVal	The default value to use if the property is not found.

Returns: The config property value (as long) for the provided key or the provided defaultValue is the name is not found or not a valid long.

◆ getDependencyManager()

std::shared_ptr<dm::DependencyManager> celix::BundleContext::getDependencyManager ( ) const

inline

Get the Celix dependency manager for this bundle context.

◆ getFramework()

std::shared_ptr<Framework> celix::BundleContext::getFramework ( ) const

inline

Get the Celix framework for this bundle context.

◆ installBundle()

long celix::BundleContext::installBundle	(	std::string_view	bndLocation,
		bool	autoStart = `true`
	)

inline

Install and optional start a bundle.

Will silently ignore bundle ids < 0.

Parameters

bndLocation	The bundle location to the bundle zip file.
autoStart	If the bundle should also be started.

Returns: the bundleId (>= 0) or < 0 if the bundle could not be installed and possibly started.

◆ listBundleIds()

std::vector<long> celix::BundleContext::listBundleIds ( ) const

inline

List the installed and started bundle ids. The bundle ids does not include the framework bundle (bundle id CELIX_FRAMEWORK_BUNDLE_ID).

Returns: A vector with bundle ids.

◆ listInstalledBundleIds()

std::vector<long> celix::BundleContext::listInstalledBundleIds ( )

inline

List the installed bundle ids. The bundle ids does not include the framework bundle (bundle id CELIX_FRAMEWORK_BUNDLE_ID).

Returns: A vector with bundle ids.

◆ logDebug()

void celix::BundleContext::logDebug ( const char * format... )

Log a message to the Celix framework logger using the DEBUG log level.

Note: Only supports printf style call (so use c_str() instead of std::string)

◆ logError()

void celix::BundleContext::logError ( const char * format... )

Log a message to the Celix framework logger using the ERROR log level.

Note: Only supports printf style call (so use c_str() instead of std::string)

◆ logFatal()

void celix::BundleContext::logFatal ( const char * format... )

Log a message to the Celix framework logger using the FATAL log level.

Note: Only supports printf style call (so use c_str() instead of std::string)

◆ logInfo()

void celix::BundleContext::logInfo ( const char * format... )

Log a message to the Celix framework logger using the INFO log level.

Note: Only supports printf style call (so use c_str() instead of std::string)

◆ logTrace()

void celix::BundleContext::logTrace ( const char * format... )

Log a message to the Celix framework logger using the TRACE log level.

Note: Only supports printf style call (so use c_str() instead of std::string)

◆ logTssErrors()

void celix::BundleContext::logTssErrors ( celix_log_level_e level )

inline

Log celix per-thread error messages to the Celix framework logger using the provided log level. Silently ignores log level CELIX_LOG_LEVEL_DISABLED.

◆ logWarn()

void celix::BundleContext::logWarn ( const char * format... )

Log a message to the Celix framework logger using the WARNING log level.

Note: Only supports printf style call (so use c_str() instead of std::string)

◆ registerService()

template<typename I , typename Implementer >

ServiceRegistrationBuilder<I> celix::BundleContext::registerService	(	std::shared_ptr< Implementer >	implementer,
		std::string_view	name = `{}`
	)

inline

Register a service in the Celix framework using a fluent builder API.

The service registration can be fine tuned using the returned ServiceRegistrationBuilder API.

 std::shared_ptr<celix::BundleContext> ctx = ...
 auto svcReg = ctx->registerService<IExample>(std::make_shared<ExampleImpl>())
     .setVersion("1.0.0")
     .addProperty("key1", "value1")
     .addOnRegistered([](const std::shared_ptr<celix::ServiceRegistration>& reg) {
         std::cout << "Done registering service '" << reg->getServiceName() << "' with id " << reg->getServiceId() << std::endl;
     })
     .build();

By default the service registration is configure to register and unregister the service async.

Template Parameters

I	The service type (Note should be the abstract interface, not the interface implementer)
Implementer	The service implementer.

Parameters

implementer	The service implementer.
name	The optional name of the service. If not provided celix::typeName<I> will be used to defer the service name.

Returns: A ServiceRegistrationBuilder object.

◆ registerUnmanagedService()

template<typename I , typename Implementer >

ServiceRegistrationBuilder<I> celix::BundleContext::registerUnmanagedService	(	Implementer *	svc,
		std::string_view	name = `{}`
	)

inline

Register a (unmanaged) service in the Celix framework using a fluent builder API.

Same as registerService, but then with an unmanaged service pointer. Note that the user is responsible for ensuring that the service pointer is valid as long as the service is registered in the Celix framework.

By default the service registration is configure to register the service async, but to unregister the service sync (because the svc pointer is unmanaged).

◆ scheduledEvent()

ScheduledEventBuilder celix::BundleContext::scheduledEvent ( )

inline

Schedule a callback to be called after the given initial delay and/or interval using a fluent builder API.

◆ startBundle()

bool celix::BundleContext::startBundle ( long bndId )

inline

Start the bundle with the provided bundle id.

Will silently ignore bundle ids < 0.

If this function is called on the Celix event thread, the actual starting of the bundle will be done async and on a separate thread. If this function is called from a different thread than the Celix event thread, then the function will return after the bundle start is completed.

Parameters

bndId The bundle id to start.

Returns: true if the bundle is found & correctly started or if the bundle is started async. False if not.

◆ stopBundle()

bool celix::BundleContext::stopBundle ( long bndId )

inline

Stop the bundle with the provided bundle id.

Will silently ignore bundle ids < 0.

If this function is called on the Celix event thread, the actual stopping of the bundle will be done async and on a separate thread. If this function is called from a different thread than the Celix event thread, then the function will return after the bundle stop is completed.

Parameters

bndId The bundle id to stop.

Returns: true if the bundle is found & correctly stop or if the bundle is stopped async. False if not.

◆ trackAnyServices()

ServiceTrackerBuilder<void> celix::BundleContext::trackAnyServices ( )

inline

Track services in the Celix framework using a fluent builder API.

Same as trackerService, but than for any service. Note that the service shared ptr is of the type std::shared_ptr<void>.

◆ trackAnyServiceTrackers()

MetaTrackerBuilder celix::BundleContext::trackAnyServiceTrackers ( )

inline

Track service trackers in the Celix framework using a fluent builder API.

Same as trackServiceTrackers, but than for service tracker for any service types.

◆ trackBundles()

BundleTrackerBuilder celix::BundleContext::trackBundles ( )

inline

Track bundles in the Celix framework using a fluent builder API.

The bundle tracker can be fine tuned using the returned BundleTrackerBuilder API.

 std::shared_ptr<celix::BundleContext> ctx = ...
 auto tracker = ctx->trackBundles<>()
     .addOnInstallCallback([](const celix::Bundle& bnd) {
         std::cout << "Bundle installed with id '" << bnd.getId() << std::endl;
     })
     .build();

Returns: A BundleTrackerBuilder object.

◆ trackServices()

template<typename I >

ServiceTrackerBuilder celix::BundleContext::trackServices ( std::string_view name = {} )

inline

Track services in the Celix framework using a fluent builder API.

The service tracker can be fine tuned using the returned ServiceTrackerBuilder API.

 std::shared_ptr<celix::BundleContext> ctx = ...
 auto tracker = ctx->trackServices<IExample>()
     .setFilter("(property_key=value)")
     .addAddCallback([](std::shared_ptr<IExample>, std::shared_ptr<const celix::Properties> props) {
         std::cout << "Adding service with id '" << props->get("service.id", "-1") << std::endl;
     })
     .addRemCallback([](std::shared_ptr<IExample>, std::shared_ptr<const celix::Properties> props) {
         std::cout << "Removing service with id '" << props->get("service.id", "-1") << std::endl;
     })
     .build();

Template Parameters

I	The service type to track

Parameters

name	The optional service name. If empty celix::typeName<I> will be used to defer the service name.

Returns: A ServiceTrackerBuilder object.

◆ trackServiceTrackers()

template<typename I >

MetaTrackerBuilder celix::BundleContext::trackServiceTrackers ( std::string_view name = {} )

inline

Track service trackers in the Celix framework using a fluent builder API.

The meta tracker (service tracker tracker) can be fine tuned using the returned MetaTrackerBuilder API.

 std::shared_ptr<celix::BundleContext> ctx = ...
 auto tracker = ctx->trackServiceTrackers<IExample>()
     .addOnTrackerCreatedCallback([](const ServiceTrackerInfo& info) {
         std::cout << "Tracker created for service name '" << info.serviceName << std::endl;
     })
     .addOnTrackerDestroyedCallback([](const ServiceTrackerInfo& info) {
         std::cout << "Tracker destroyed for service name '" << info.serviceName << std::endl;
     })
     .build();

Template Parameters

I	The service tracker service type to track.

Parameters

name	The optional service name. If empty celix::typeName<I> will be used to defer the service name.

Returns: A MetaTrackerBuilder object.

◆ uninstallBundle()

bool celix::BundleContext::uninstallBundle ( long bndId )

inline

Uninstall the bundle with the provided bundle id.

If needed the bundle will be stopped first. Will silently ignore bundle ids < 0.

Parameters

bndId The bundle id to uninstall.

Returns: true if the bundle is correctly uninstalled. False if not.

◆ updateBundle()

bool celix::BundleContext::updateBundle	(	long	bndId,
		std::string_view	updatedBundleUrl = `{}`
	)

inline

Update the bundle with the provided bundle id async.

This will do the following:

Stop the bundle (if needed);
Update the bundle revision if a newer bundle zip if found;
Start the bundle, if it was started.

Will silently ignore bundle ids < 0.

If this function is called on the Celix event thread, the actual updating of the bundle will be done async and on a separate thread. If this function is called from a different thread than the Celix event thread, then the function will return after the bundle update is completed.

Parameters

ctx	The bundle context
bndId	The bundle id to start.
updatedBundleUrl	The optional updated bundle url to the bundle zip file. If empty, the existing bundle url from the bundle cache will be used.

Returns: true if the bundle is found & correctly started or if the bundle is updated async. False if not.

◆ useService()

template<typename I >

UseServiceBuilder celix::BundleContext::useService ( std::string_view name = {} )

inline

Use a service registered in the Celix framework using a fluent builder API.

The service use can be fine tuned using the returned UseServiceBuilder API.

With this API a Celix service can be used by providing use functions. The use function will be executed on the Celix event thread and the Celix framework will ensure that the service cannot be removed while in use.

If there are more 1 matching service, the highest ranking service will be used. If no service can be found the use callbacks with not be called.

 std::shared_ptr<celix::BundleContext> ctx = ...
 auto callCount = ctx->useService<IExample>()
     .setTimeout(std::chrono::seconds{1})
     .addUseCallback([](IExample& service, const celix::Properties& props){
         std::cout << "Calling service with id " << props.get("service.id", "-1") << std::endl;
         service.method();
     })
     .build();

Template Parameters

I	The service type to use

Parameters

name	The optional service name to use. If not provided celix::typeName<I> will be used to defer the service name.

Returns: A UseServiceBuilder object.

◆ useServices()

template<typename I >

UseServiceBuilder celix::BundleContext::useServices ( std::string_view name = {} )

inline

Use services registered in the Celix framework using a fluent builder API.

The service use can be fine tuned using the returned UseServiceBuilder API.

With this API Celix services can be used by providing use functions. The use function will be executed on the Celix event thread and the Celix framework will ensure that the service cannot be removed while in use.

The use callbacks will be called for every matching service found.

 std::shared_ptr<celix::BundleContext> ctx = ...
 auto callCount = ctx->useServices<IExample>()
     .addUseCallback([](IExample& service, const celix::Properties& props){
         std::cout << "Calling service with id " << props.get("service.id", "-1") << std::endl;
         service.method();
     })
     .build();

Template Parameters

I	The service type to use

Parameters

name	The optional service name to use. If not provided celix::typeName<I> will be used to defer the service name.

Returns: A UseServiceBuilder object.