Example 2 - Dictionary Service BundleΒΆ
This example creates a bundle that implements a service. Implementing a
service is a two-step process, first we must define the interface of the
service and then we must define an implementation of the service
interface. In this particular example, we will create a dictionary
service that we can use to check if a word exists, which indicates if
the word is spelled correctly or not. First, we will start by defining a
simple dictionary service interface in a file called
dictionaryservice/IDictionaryService.h
:
#include "cppmicroservices/ServiceInterface.h"
#include <string>
#ifdef US_BUILD_SHARED_LIBS
# ifdef Tutorial_dictionaryservice_EXPORTS
# define DICTIONARYSERVICE_EXPORT US_ABI_EXPORT
# else
# define DICTIONARYSERVICE_EXPORT US_ABI_IMPORT
# endif
#else
# define DICTIONARYSERVICE_EXPORT US_ABI_EXPORT
#endif
/**
* A simple service interface that defines a dictionary service.
* A dictionary service simply verifies the existence of a word.
**/
struct DICTIONARYSERVICE_EXPORT IDictionaryService
{
// Out-of-line virtual desctructor for proper dynamic cast
// support with older versions of gcc.
virtual ~IDictionaryService();
/**
* Check for the existence of a word.
* @param word the word to be checked.
* @return true if the word is in the dictionary,
* false otherwise.
**/
virtual bool CheckWord(const std::string& word) = 0;
};
The service interface is quite simple, with only one method that needs
to be implemented. Because we provide an empty out-of-line destructor
(defined in the file IDictionaryService.cpp
) we must export the
service interface by using the bundle specific
DICTIONARYSERVICE_EXPORT
macro.
In the following source code, the bundle uses its bundle context to
register the dictionary service. We implement the dictionary service as
an inner class of the bundle activator class, but we could have also put
it in a separate file. The source code for our bundle is as follows in a
file called dictionaryservice/Activator.cpp
:
#include "IDictionaryService.h"
#include "cppmicroservices/BundleActivator.h"
#include "cppmicroservices/BundleContext.h"
#include "cppmicroservices/ServiceProperties.h"
#include <memory>
#include <set>
using namespace cppmicroservices;
namespace {
/**
* This class implements a bundle activator that uses the bundle
* context to register an English language dictionary service
* with the C++ Micro Services registry during static initialization
* of the bundle. The dictionary service interface is
* defined in a separate file and is implemented by a nested class.
*/
class US_ABI_LOCAL Activator : public BundleActivator
{
private:
/**
* A private inner class that implements a dictionary service;
* see IDictionaryService for details of the service.
*/
class DictionaryImpl : public IDictionaryService
{
// The set of words contained in the dictionary.
std::set<std::string> m_dictionary;
public:
DictionaryImpl()
{
m_dictionary.insert("welcome");
m_dictionary.insert("to");
m_dictionary.insert("the");
m_dictionary.insert("micro");
m_dictionary.insert("services");
m_dictionary.insert("tutorial");
}
/**
* Implements IDictionaryService::CheckWord(). Determines
* if the passed in word is contained in the dictionary.
* @param word the word to be checked.
* @return true if the word is in the dictionary,
* false otherwise.
**/
bool CheckWord(const std::string& word)
{
std::string lword(word);
std::transform(lword.begin(), lword.end(), lword.begin(), ::tolower);
return m_dictionary.find(lword) != m_dictionary.end();
}
};
public:
/**
* Implements BundleActivator::Start(). Registers an
* instance of a dictionary service using the bundle context;
* attaches properties to the service that can be queried
* when performing a service look-up.
* @param context the context for the bundle.
*/
void Start(BundleContext context)
{
std::shared_ptr<DictionaryImpl> dictionaryService =
std::make_shared<DictionaryImpl>();
ServiceProperties props;
props["Language"] = std::string("English");
context.RegisterService<IDictionaryService>(dictionaryService, props);
}
/**
* Implements BundleActivator::Stop(). Does nothing since
* the C++ Micro Services library will automatically unregister any registered services.
* @param context the context for the bundle.
*/
void Stop(BundleContext /*context*/)
{
// NOTE: The service is automatically unregistered
}
};
}
CPPMICROSERVICES_EXPORT_BUNDLE_ACTIVATOR(Activator)
Note that we do not need to unregister the service in the Stop()
method,
because the C++ Micro Services library will automatically do so for us.
The dictionary service that we have implemented is very simple; its
dictionary is a set of only five words, so this solution is not optimal
and is only intended for educational purposes.
Note
In this example, the service interface and implementation are both contained in one bundle which exports the interface class. However, service implementations almost never need to be exported and in many use cases it is beneficial to provide the service interface and its implementation(s) in separate bundles. In such a scenario, clients of a service will only have a link-time dependency on the shared library providing the service interface (because of the out-of-line destructor) but not on any bundles containing service implementations.
We must create a manifest.json
file that contains the
meta-data for our bundle; the manifest file contains the following:
{
"bundle.symbolic_name" : "dictionaryservice",
"bundle.activator" : true
}
For an introduction how to compile our source code, see Example 1 - Service Event Listener.
After running the usTutorialDriver
program we should make sure that
the bundle from Example 1 is active. We can use the status
shell
command to get a list of all bundles, their state, and their bundle
identifier number. If the Example 1 bundle is not active, we should
start the bundle using the start
command and the bundle’s identifier
number or symbolic name that is displayed by the status
command. Now
we can start our dictionary service bundle by typing the
start dictionaryservice
command:
CppMicroServices-build> bin/usTutorialDriver
> status
Id | Symbolic Name | State
-----------------------------------
0 | system_bundle | ACTIVE
1 | eventlistener | INSTALLED
2 | dictionaryservice | INSTALLED
3 | frenchdictionary | INSTALLED
4 | dictionaryclient | INSTALLED
5 | dictionaryclient2 | INSTALLED
6 | dictionaryclient3 | INSTALLED
7 | spellcheckservice | INSTALLED
8 | spellcheckclient | INSTALLED
> start eventlistener
Starting to listen for service events.
> start dictionaryservice
Ex1: Service of type IDictionaryService registered.
> status
Id | Symbolic Name | State
-----------------------------------
0 | system_bundle | ACTIVE
1 | eventlistener | ACTIVE
2 | dictionaryservice | ACTIVE
3 | frenchdictionary | INSTALLED
4 | dictionaryclient | INSTALLED
5 | dictionaryclient2 | INSTALLED
6 | dictionaryclient3 | INSTALLED
7 | spellcheckservice | INSTALLED
8 | spellcheckclient | INSTALLED
>
To stop the bundle, use the stop 2
command. If the bundle
from Example 1 is still
active, then we should see it print out the details of the service event
it receives when our new bundle registers its dictionary service. Using
the usTutorialDriver
commands stop
and start
we can stop and
start it at will, respectively. Each time we start and stop our
dictionary service bundle, we should see the details of the associated
service event printed from the bundle from Example 1. In
Example 3, we will create a client for our dictionary
service. To exit usTutorialDriver
, we use the shutdown
command.