This section gives you a quick tour of the most important concepts in order to get you started with developing bundles and publishing and consuming services.
We will define a service interface, service implementation, and service consumer. A simple executable then shows how to install and start these bundles.
The complete source code for this example can be found at /doc/src/examples/getting_started. It works for both shared and static builds, but only the more commonly used shared build mode is discussed in detail below.
These examples come with a complete CMakeLists.txt file showing the main usage scenarios of the provided CMake helper functions
<cmake-support>. The script requires the CppMicroServices package:
examples/getting_started/CMakeLists.txt
Services implement one or more service interfaces. An interface can be any C++ class, but typically contains only pure virtual functions. For our example, we create a separate library containing a service interface that allows us to retrieve the number of elapsed milliseconds since the POSIX epoch:
examples/getting_started/service_time/ServiceTime.h
The CMake code does not require C++ Micro Services specific additions:
examples/getting_started/CMakeLists.txt
A bundle is the logical set of C++ Micro Services specific initialization code, metadata stored in a manifest.json resource <concept-resources> file, and other resources and code. Multiple bundles can be part of the same or different (shared or static) library or executable. To create the bundle initialization code, you can either use the usFunctionGenerateBundleInit CMake function or the CPPMICROSERVICES_INITIALIZE_BUNDLE macro directly.
In order to publish and consume a service, we need a BundleContext
<cppmicroservices::BundleContext> instance, through which a bundle accesses the C++ Micro Services API. Each bundle is associated with a distinct bundle context that is accessible from anywhere in the bundle via the GetBundleContext() <cppmicroservices::GetBundleContext> function:
#include <cppmicroservices/GetBundleContext.h>
void Dummy()
{
auto context = cppmicroservices::GetBundleContext();
}Please note that trying to use GetBundleContext() without proper initialization code in the using library will lead to compile or runtime errors.
Publishing a service is done by calling the BundleContext::RegisterService
<cppmicroservices::BundleContext::RegisterService> function. The following code for the service_time_systemclock bundle implements the ServiceTime interface as a service:
examples/getting_started/service_time_systemclock/ServiceTimeImpl.cpp
A std::shared_ptr holding the service object is passed as the an argument to the RegisterService<>() function within a bundle activator <cppmicroservices::BundleActivator>. The service is registered as long as it is explicitly unregistered or the bundle is stopped. The bundle activator is optional, but if it is declared, its BundleActivator::Start(BundleContext) <cppmicroservices::BundleActivator::Start> and BundleActivator::Stop(BundleContext) <cppmicroservices::BundleActivator::Stop> functions are called when the bundle is started <cppmicroservices::Bundle::Start> or stopped <cppmicroservices::Bundle::Stop>, respectively.
The CMake code for creating our bundle looks like this:
examples/getting_started/CMakeLists.txt
In addition to the generated bundle initialization code, we need to specify a unique bundle name by using the US_BUNDLE_NAME compile definition as shown above.
We also need to provide the manifest.json file, which is added as a resource and contains the following JSON data:
examples/getting_started/service_time_systemclock/manifest.json
Because our bundle provides an activator, we also need to state its existence by setting the bundle.activator key to true. The last two elements are purely informational and not used directly.
The process to consume a service is very similar to the process for publishing a service, except that consumers need to handle some additional error cases.
Again, we use a bundle activator to execute code on bundle start that retrieves and consumes a ServiceTime service:
examples/getting_started/service_time_consumer/ServiceTimeConsumer.cpp
Because the C++ Micro Services is a dynamic environment, a particular service might not be available yet. Therefore, we first need to check the validity of some returned objects.
The above code would be sufficient only in the simplest use cases. To avoid bundle start ordering problems (e.g. one bundle assuming the existence of a service published by another bundle), a ServiceTracker <cppmicroservices::ServiceTracker> should be used instead. Such a tracker allows bundles to react on service events and in turn be more robust.
The CMake code for creating a library containing the bundle is very similar to the code for the publishing bundle and thus not included here.
The two bundles above are embedded in separate libraries and need to be installed into a Framework <cppmicroservices::Framework> and started. This is done by a small example program:
examples/getting_started/main.cpp
The program expects a list of file system paths pointing to installable libraries. It will first construct a new Framework instance and then install <cppmicroservices::BundleContext::InstallBundles> the given libraries. Next, it will start all available bundles.
When the Framework instance is destroyed, it will automatically shut itself down, essentially stopping all active bundles.
A more detailed tutorial <tutorial> demonstrating some more advanced features is also available.