cppmicroservices-ds - Man Page

struct BundleDTO

#include <cppmicroservices/servicecomponent/runtime/dto/BundleDTO.hpp>

A representation of a bundle.

Public Members

unsigned long id

The bundle's unique identifier.

SEE ALSO:

Bundle::GetBundleId()

unsigned long lastModified

The time when the bundle was last modified.

SEE ALSO:

Bundle::GetLastModified()

uint32_t state

The bundle's state.

SEE ALSO:

Bundle::GetState()

std::string symbolicName

The bundle's symbolic name.

SEE ALSO:

Bundle::GetSymbolicName()

std::string version

The bundle's version.

SEE ALSO:

Bundle::GetVersion()

enum class ComponentState : uint8_t

Values:

enumerator UNSATISFIED_REFERENCE

The component configuration is unsatisfied due to an unsatisfied reference.

enumerator SATISFIED

The component configuration is satisfied.

Any services declared by the component description are registered.

enumerator ACTIVE

The component configuration is active.

This is the normal operational state of a component configuration.

struct ComponentConfigurationDTO

#include <cppmicroservices/servicecomponent/runtime/dto/ComponentConfigurationDTO.hpp>

A representation of an actual instance of a declared component description parameterized by component properties.

Public Members

ComponentDescriptionDTO description

The representation of the component configuration's component description.

ComponentState state

The current state of the component configuration.

This is one of ComponentState::UNSATISFIED_REFERENCE, ComponentState::SATISFIED or ComponentState::ACTIVE.

unsigned long id

The id of the component configuration.

The id is a non-persistent, unique value assigned at runtime. The id is also available as the component.id component property. The value of this field is unspecified if the state of this component configuration is unsatisfied.

std::unordered_map<std::string, cppmicroservices::Any> properties

The component properties for the component configuration.

SEE ALSO:

ComponentContext::GetProperties()

std::vector<SatisfiedReferenceDTO> satisfiedReferences

The satisfied references.

Each SatisfiedReferenceDTO in the vector represents a satisfied reference of the component configuration. The vector must be empty if the component configuration has no satisfied references.

std::vector<UnsatisfiedReferenceDTO> unsatisfiedReferences

The unsatisfied references.

Each UnsatisfiedReferenceDTO in the vector represents an unsatisfied reference of the component configuration. The vector must be empty if the component configuration has no unsatisfied references.

const std::string SERVICE_COMPONENT

Manifest key specifying the Service Component descriptions.

The attribute value may be retrieved from the cppmicroservices::AnyMap object returned by the Bundle::GetHeaders method.

const std::string COMPONENT_NAME

A component property for a component configuration that contains the name of the component as specified in the name attribute of the component element.

The value of this property must be of type std::string.

const std::string COMPONENT_ID

A component property that contains the generated id for a component configuration.

The value of this property must be of type unsigned long.

The value of this property is assigned by Service Component Runtime when a component configuration is created. Service Component Runtime assigns a unique value that is larger than all previously assigned values since Service Component Runtime was started. These values are NOT persistent across restarts of Service Component Runtime.

const std::string COMPONENT_FACTORY

A service registration property for a Component Factory that contains the value of the  attribute.

The value of this property must be of type .

const std::string REFERENCE_TARGET_SUFFIX

The suffix for reference target properties.

These properties contain the filter to select the target services for a reference. The value of this property must be of type std::string.

const std::string REFERENCE_SCOPE_PROTOTYPE_REQUIRED

Reference scope is prototype_required.

The reference is satisfied only if the service is registered with PROTOTYPE scope. Each component instance receives a distinct service object.

const std::string CONFIG_POLICY_IGNORE

Constants used for ComponentMetadata configurationPolicy attribute.

class ComponentContext

#include <cppmicroservices/servicecomponent/ComponentContext.hpp>

A Component Context object is used by a component instance to interact with its execution context including locating services by reference name.

Each component instance has a unique Component Context.

A component instance may obtain its Component Context object through its activate, modified, and deactivate methods.

Public Functions

virtual ~ComponentContext() noexcept

virtual std::unordered_map<std::string, cppmicroservices::Any> GetProperties() const = 0

Returns the component properties for this Component Context.

Returns

The properties for this Component Context.

virtual cppmicroservices::BundleContext GetBundleContext() const = 0

Returns the BundleContext of the bundle which contains this component.

Returns

The BundleContext of the bundle containing this component.

virtual cppmicroservices::Bundle GetUsingBundle() const = 0

If the component instance is registered as a service using the servicescope="bundle" or servicescope="prototype" attribute, then this method returns the bundle using the service provided by the component instance.

This method will return an invalid Bundle if: .INDENT 7.0

·

The component instance is not a service, then no bundle can be using it as a service.

·

The component instance is a service but did not specify the servicescope="bundle" or servicescope="prototype" attribute, then all bundles using the service provided by the component instance will share the same component instance.

·

The service provided by the component instance is not currently being used by any bundle.

Returns

The bundle using the component instance as a service or an invalid bundle.

virtual void EnableComponent(std::string const &name) = 0

Enables the specified component name.

The specified component name must be in the same bundle as this component.

This method must return after changing the enabled state of the specified component name. Any actions that result from this, such as activating or deactivating a component configuration, must occur asynchronously to this method call.

Parameters

name -- The name of a component or empty string to indicate all components in the bundle.

virtual void DisableComponent(std::string const &name) = 0

Disables the specified component name.

The specified component name must be in the same bundle as this component.

This method must return after changing the enabled state of the specified component name. Any actions that result from this, such as activating or deactivating a component configuration, must occur asynchronously to this method call.

Parameters

name -- The name of a component.

virtual cppmicroservices::ServiceReferenceBase GetServiceReference() const = 0

If the component instance is registered as a service using the service element, then this method returns the service reference of the service provided by this component instance.

This method will return an invalid ServiceReference object if the component instance is not registered as a service.

Returns

The ServiceReference object for the component instance or invalid object if the component instance is not registered as a service.

template<class T> inline std::shared_ptr<T> LocateService(std::string const &refName) const

Returns the service object for the specified reference name and type.

If the cardinality of the reference is 0..n or 1..n and multiple services are bound to the reference, the service with the highest ranking (as specified in its Constants::SERVICE_RANKING property) is returned. If there is a tie in ranking, the service with the lowest service id (as specified in its Constants::SERVICE_ID property); that is, the service that was registered first is returned.

Parameters

refName -- The name of a reference as specified in a reference element in this component's description.

Throws

ComponentException -- If Service Component Runtime catches an exception while activating the bound service.

Returns

A service object for the referenced service or nullptr if the reference cardinality is 0..1 or 0..n and no bound service is available.

template<class T> inline std::vector<std::shared_ptr<T>> LocateServices(std::string const &refName) const

Returns the service objects for the specified reference name and type.

Parameters

refName -- The name of a reference as specified in a reference element in this component's description.

Throws

ComponentException -- If Service Component Runtime catches an exception while activating a bound service.

Returns

A vector of service objects for the referenced service or empty vector if the reference cardinality is 0..1 or 0..n and no bound service is available. If the reference cardinality is 0..1 or 1..1 and a bound service is available, the vector will have exactly one element.

Protected Functions

struct ComponentDescriptionDTO

#include <cppmicroservices/servicecomponent/runtime/dto/ComponentDescriptionDTO.hpp>

A representation of a declared component description.

Public Members

std::string name

The name of the component.

This is declared in the name attribute of the component element. This must be the default name if the component description does not declare a name.

cppmicroservices::framework::dto::BundleDTO bundle

The bundle declaring the component description.

std::string scope

The service scope.

This is declared in the scope attribute of the service element. This must be empty string if the component description does not declare any service interfaces.

std::string implementationClass

The fully qualified name of the implementation class.

This is declared in the implementation-class element.

bool defaultEnabled

The initial enabled state.

This is declared in the enabled attribute of the component element.

bool immediate

The immediate state.

This is declared in the immediate attribute of the component element.

std::vector<std::string> serviceInterfaces

The fully qualified names of the service interfaces.

These are declared in the interface attribute of the provide elements. The vector must be empty if the component description does not declare any service interfaces.

std::unordered_map<std::string, cppmicroservices::Any> properties

The declared component properties.

These are declared in the property and properties elements.

std::vector<ReferenceDTO> references

The referenced services.

These are declared in the reference elements. The vector must be empty if the component description does not declare references to any services.

std::string activate

The name of the activate method.

This is declared in the activate attribute of the component element. This must be the default value which is "Activate", if the component description does not declare an activate method name.

std::string deactivate

The name of the deactivate method.

This is declared in the deactivate attribute of the component element. This must be the default value which is "Deactivate", if the component description does not declare a deactivate method name.

std::string modified

The name of the modified method.

This is declared in the modified attribute of the component element. This must be the default value which is "Modified", if the component description does not declare a modified method name.

class ComponentException : public std::runtime_error

#include <cppmicroservices/servicecomponent/ComponentException.hpp>

Exception which may be thrown by Service Component Runtime.

Public Functions

explicit ComponentException(std::string const &message)

Construct a new ComponentException with the specified message.

Parameters

message -- The message for the exception.

explicit ComponentException(char const *message)

virtual ~ComponentException() noexcept

struct ReferenceDTO

#include <cppmicroservices/servicecomponent/runtime/dto/ReferenceDTO.hpp>

A representation of a declared reference to a service.

Public Members

std::string name

The name of the reference.

This is declared in the name attribute of the reference element. This must be the default name if the component description does not declare a name for the reference.

std::string interfaceName

The service interface of the reference.

This is declared in the interface attribute of the reference element.

std::string cardinality

The cardinality of the reference.

This is declared in the cardinality attribute of the reference element. This must be the default cardinality if the component description does not declare a cardinality for the reference.

std::string policy

The policy of the reference.

This is declared in the policy attribute of the reference element. This must be the default policy if the component description does not declare a policy for the reference.

std::string policyOption

The policy option of the reference.

This is declared in the policy-option attribute of the reference element. This must be the default policy option if the component description does not declare a policy option for the reference.

std::string target

The target of the reference.

This is declared in the target attribute of the reference element. This must be an empty string if the component description does not declare a target for the reference.

std::string bind

The name of the bind method of the reference.

This is declared in the bind attribute of the reference element. This must be an empty string if the component description does not declare a bind method for the reference.

std::string unbind

The name of the unbind method of the reference.

This is declared in the unbind attribute of the reference element. This must be an empty string if the component description does not declare an unbind method for the reference.

std::string updated

The name of the updated method of the reference.

This is declared in the updated attribute of the reference element. This must be an empty string if the component description does not declare an updated method for the reference.

std::string scope

The scope of the reference.

This is declared in the scope attribute of the reference element. This must be the default scope if the component description does not declare a scope for the reference.

struct SatisfiedReferenceDTO

#include <cppmicroservices/servicecomponent/runtime/dto/SatisfiedReferenceDTO.hpp>

A representation of a satisfied reference.

Public Members

std::string name

The name of the declared reference.

This is declared in the name attribute of the reference element of the component description.

SEE ALSO:

ReferenceDTO::name

std::string target

The target property of the satisfied reference.

This is the value of the component property whose name is the concatenation of the declared reference name and ".target". This must be empty string if no target property is set for the reference.

std::vector<cppmicroservices::framework::dto::ServiceReferenceDTO> boundServices

The bound services.

Each ServiceReferenceDTO in the vector represents a service bound to the satisfied reference. The vector must be empty if there are no bound services.

class ServiceComponentRuntime

#include <cppmicroservices/servicecomponent/runtime/ServiceComponentRuntime.hpp>

The ServiceComponentRuntime service represents the Declarative Services actor, known as Service Component Runtime (SCR), that manages the service components and their life cycle.

The ServiceComponentRuntime service allows introspection of the components managed by Service Component Runtime.

This service differentiates between a ComponentDescriptionDTO and a ComponentConfigurationDTO. A ComponentDescriptionDTO is a representation of a declared component description. A ComponentConfigurationDTO is a representation of an actual instance of a declared component description parameterized by component properties.

Public Functions

virtual ~ServiceComponentRuntime() noexcept

virtual std::vector<dto::ComponentDescriptionDTO> GetComponentDescriptionDTOs(std::vector<cppmicroservices::Bundle> const &bundles = {}) const = 0

Returns the component descriptions declared by the specified active bundles.

Only component descriptions from active bundles are returned. If the specified bundles have no declared components or are not active, an empty collection is returned.

Parameters

bundles -- The bundles whose declared component descriptions are to be returned. Specifying no bundles, or the equivalent of an empty Bundle vector, will return the declared component descriptions from all active bundles.

Returns

The declared component descriptions of the specified active bundles. An empty collection is returned if there are no component descriptions for the specified active bundles.

virtual dto::ComponentDescriptionDTO GetComponentDescriptionDTO(cppmicroservices::Bundle const &bundle, std::string const &name) const = 0

Returns the ComponentDescriptionDTO declared with the specified name by the specified bundle.

Only component descriptions from active bundles are returned. An empty object is returned if no such component is declared by the given bundle or the bundle is not active.

Parameters

• bundle -- The bundle declaring the component description.
• name -- The name of the component description.

Returns

The declared component description or empty object if the specified bundle is not active or does not declare a component description with the specified name.

virtual std::vector<dto::ComponentConfigurationDTO> GetComponentConfigurationDTOs(dto::ComponentDescriptionDTO const &description) const = 0

Returns the component configurations for the specified component description.

Parameters

description -- The component description.

Returns

A vector containing a snapshot of the current component configurations for the specified component description. An empty vector is returned if there are none.

virtual bool IsComponentEnabled(dto::ComponentDescriptionDTO const &description) const = 0

Returns whether the specified component description is currently enabled.

The enabled state of a component description is initially set by the enabled attribute of the component description.

SEE ALSO:

EnableComponent

SEE ALSO:

DisableComponent

SEE ALSO:

ComponentContext#DisableComponent(std::string)

SEE ALSO:

ComponentContext#EnableComponent(std::string)

Parameters

description -- The component description.

Returns

true if the specified component description is currently enabled. Otherwise, false.

virtual std::shared_future<void> EnableComponent(dto::ComponentDescriptionDTO const &description) = 0

Enables the specified component description.

If the specified component description is currently enabled, this method has no effect.

This method must return after changing the enabled state of the specified component description. Any actions that result from this, such as activating or deactivating a component configuration, must occur asynchronously to this method call.

Remark

The shared_future<void> returned can contain a { cppmicroservices::SecurityException if enabling the component caused the bundle's shared library to be loaded and the bundle failed a security check.

SEE ALSO:

IsComponentEnabled

Parameters

description -- The component description to enable.

Returns

A future that will be ready when the actions that result from changing the enabled state of the specified component have completed.

virtual std::shared_future<void> DisableComponent(dto::ComponentDescriptionDTO const &description) = 0

Disables the specified component description.

If the specified component description is currently disabled, this method has no effect.

This method must return after changing the enabled state of the specified component description. Any actions that result from this, such as activating or deactivating a component configuration, must occur asynchronously to this method call.

SEE ALSO:

IsComponentEnabled

Parameters

description -- The component description to disable.

Returns

A future that will be ready when the actions that result from changing the enabled state of the specified component have completed.

struct ServiceReferenceDTO

#include <cppmicroservices/servicecomponent/runtime/dto/ServiceReferenceDTO.hpp>

A representation of a satisfied reference.

Public Members

unsigned long id

The id of the service.

SEE ALSO:

Constants::SERVICE_ID

unsigned long bundle

The id of the bundle that registered the service.

SEE ALSO:

ServiceReference::GetBundle()

std::unordered_map<std::string, cppmicroservices::Any> properties

The properties for the service.

The value type must be a numerical type, Boolean, String or a container of any of the former.

SEE ALSO:

ServiceReference#GetProperty(String)

std::vector<unsigned long> usingBundles

The ids of the bundles that are using the service.

SEE ALSO:

ServiceReference::GetUsingBundles()

struct UnsatisfiedReferenceDTO

#include <cppmicroservices/servicecomponent/runtime/dto/UnsatisfiedReferenceDTO.hpp>

A representation of an unsatisfied reference.

Public Members

std::string name

The name of the declared reference.

This is declared in the name attribute of the reference element of the component description.

SEE ALSO:

ReferenceDTO::name

std::string target

The target property of the unsatisfied reference.

This is the value of the component property whose name is the concatenation of the declared reference name and ".target". This must be empty string if no target property is set for the reference.

std::vector<cppmicroservices::framework::dto::ServiceReferenceDTO> targetServices

The target services.

Each ServiceReferenceDTO in the vector represents a target service for the reference. The vector must be empty if there are no target services. The upper bound on the number of target services in the vector is the upper bound on the cardinality of the reference.

CppMicroServices Team

2017-2023, CppMicroServices Contributors