Represents a CppMicroServices module. More...

Inheritance diagram for Module:

Public Member Functions
	Module (const Module &)=delete

Module &	operator= (const Module &)=delete

virtual	~Module ()

bool	IsLoaded () const
	Returns this module's current state. More...

ModuleContext *	GetModuleContext () const
	Returns this module's ModuleContext. More...

long	GetModuleId () const
	Returns this module's unique identifier. More...

virtual std::string	GetLocation () const
	Returns this module's location. More...

std::string	GetName () const
	Returns the name of this module as specified by the US_CREATE_MODULE CMake macro. More...

ModuleVersion	GetVersion () const
	Returns the version of this module as specified by the US_INITIALIZE_MODULE CMake macro. More...

Any	GetProperty (const std::string &key) const
	Returns the value of the specified property for this module. More...

std::vector< std::string >	GetPropertyKeys () const
	Returns a list of top-level property keys for this module. More...

std::vector< ServiceReferenceU >	GetRegisteredServices () const
	Returns this module's ServiceReference list for all services it has registered or an empty list if this module has no registered services. More...

std::vector< ServiceReferenceU >	GetServicesInUse () const
	Returns this module's ServiceReference list for all services it is using or returns an empty list if this module is not using any services. More...

ModuleResource	GetResource (const std::string &path) const
	Returns the resource at the specified `path` in this module. More...

std::vector< ModuleResource >	FindResources (const std::string &path, const std::string &filePattern, bool recurse) const
	Returns resources in this module. More...

virtual void	Start ()
	Start this bundle. More...

virtual void	Stop ()
	Stop this bundle. More...

virtual void	Uninstall ()
	Uninstalls this bundle. More...

Static Public Member Functions
static const std::string &	PROP_ID ()
	Returns the property key for looking up this module's id. More...

static const std::string &	PROP_NAME ()
	Returns the property key for looking up this module's name. More...

static const std::string &	PROP_LOCATION ()
	Returns the property key for looking up this module's location in the file system. More...

static const std::string &	PROP_VERSION ()
	Returns the property key with a value of `module.version` for looking up this module's version identifier. More...

static const std::string &	PROP_VENDOR ()
	Returns the property key with a value of `module.vendor` for looking up this module's vendor information. More...

static const std::string &	PROP_DESCRIPTION ()
	Returns the property key with a value of `module.description` for looking up this module's description. More...

static const std::string &	PROP_AUTOLOAD_DIR ()
	Returns the property key with a value of `module.autoload_dir` for looking up this module's auto-load directory. More...

static const std::string &	PROP_AUTOLOADED_MODULES ()
	Returns the property key with a value of `module.autoloaded_modules` for looking up this module's auto-load modules. More...

Detailed Description

Represents a CppMicroServices module.

A Module object is the access point to a CppMicroServices module. Each CppMicroServices module has an associated Module object.

A module has unique identity, a long, chosen by the framework. This identity does not change during the lifecycle of a module.

A module can be in one of four states:

INSTALLED
LOADED
UNLOADED
UNINSTALLED

You can determine whether a bundle is loaded or not by using IsLoaded().

A module can only execute code when its state is LOADED. An UNLOADED module is a zombie and can only be reached because it was loaded before. However, unloaded modules can be loaded again.

The framework is the only entity that is allowed to create Module objects.

Remarks: This class is thread safe.

Constructor & Destructor Documentation

Module::Module ( const Module & )

delete

virtual Module::~Module ( )

virtual

Member Function Documentation

std::vector<ModuleResource> Module::FindResources	(	const std::string &	path,
		const std::string &	filePattern,
		bool	recurse
	)		const

Returns resources in this module.

This method is intended to be used to obtain configuration, setup, localization and other information from this module.

This method can either return only resources in the specified path or recurse into subdirectories returning resources in the directory tree beginning at the specified path.

Examples:

  ModuleContext* moduleContext = GetModuleContext();
  Module* module = moduleContext->GetModule();
  // List all XML files in the config directory
  std::vector<ModuleResource> xmlFiles = module->FindResources("config", "*.xml", false);
  // Find the resource named vertex_shader.txt starting at the root directory
  std::vector<ModuleResource> shaders = module->FindResources("", "vertex_shader.txt", true);

Parameters

path	The path name in which to look. The path is always relative to the root of this module and may begin with '/'. A path value of "/" indicates the root of this module.
filePattern	The resource name pattern for selecting entries in the specified path. The pattern is only matched against the last element of the resource path. Substring matching is supported using the wildcard charachter (''). If `filePattern` is empty, this is equivalent to "" and matches all resources.
recurse	If `true`, recurse into subdirectories. Otherwise only return resources from the specified path.

Returns: A vector of ModuleResource objects for each matching entry.

virtual std::string Module::GetLocation ( ) const

virtual

Returns this module's location.

The location is the full path to the module's shared library. This method continues to return this module's location while this module is in the UNLOADED state.

Returns: The string representation of this module's location.

Reimplemented in Framework.

ModuleContext* Module::GetModuleContext ( ) const

Returns this module's ModuleContext.

The returned ModuleContext can be used by the caller to act on behalf of this module.

If this module is not in the LOADED state, then this module has no valid ModuleContext. This method will return 0 if this module has no valid ModuleContext.

Returns: A ModuleContext for this module or 0 if this module has no valid ModuleContext.

long Module::GetModuleId ( ) const

Returns this module's unique identifier.

This module is assigned a unique identifier by the framework when it was loaded.

A module's unique identifier has the following attributes:

Is unique.
Is a long.
Its value is not reused for another module, even after a module is unloaded.
Does not change while a module remains loaded.
Does not change when a module is reloaded.

This method continues to return this module's unique identifier while this module is in the UNLOADED state.

Returns: The unique identifier of this module.

std::string Module::GetName ( ) const

Returns the name of this module as specified by the US_CREATE_MODULE CMake macro.

The module name together with a version must identify a unique module.

This method continues to return this module's name while this module is in the UNLOADED state.

Returns: The name of this module.

Any Module::GetProperty ( const std::string & key ) const

Returns the value of the specified property for this module.

If not found, the framework's properties are searched. The method returns an empty Any if the property is not found.

Parameters

key	The name of the requested property.

Returns: The value of the requested property, or an empty string if the property is undefined.

See also: GetPropertyKeys(); Module Properties

std::vector<std::string> Module::GetPropertyKeys ( ) const

Returns a list of top-level property keys for this module.

Returns: A list of available property keys.

See also: Module Properties

std::vector<ServiceReferenceU> Module::GetRegisteredServices ( ) const

Returns this module's ServiceReference list for all services it has registered or an empty list if this module has no registered services.

The list is valid at the time of the call to this method, however, as the framework is a very dynamic environment, services can be modified or unregistered at anytime.

Returns: A list of ServiceReference objects for services this module has registered.

ModuleResource Module::GetResource ( const std::string & path ) const

Returns the resource at the specified path in this module.

The specified path is always relative to the root of this module and may begin with '/'. A path value of "/" indicates the root of this module.

Parameters

path	The path name of the resource.

Returns: A ModuleResource object for the given path. If the path cannot be found in this module or the module's state is UNLOADED, an invalid ModuleResource object is returned.

std::vector<ServiceReferenceU> Module::GetServicesInUse ( ) const

Returns this module's ServiceReference list for all services it is using or returns an empty list if this module is not using any services.

A module is considered to be using a service if its use count for that service is greater than zero.

The list is valid at the time of the call to this method, however, as the framework is a very dynamic environment, services can be modified or unregistered at anytime.

Returns: A list of ServiceReference objects for all services this module is using.

ModuleVersion Module::GetVersion ( ) const

Returns the version of this module as specified by the US_INITIALIZE_MODULE CMake macro.

If this module does not have a specified version then ModuleVersion::EmptyVersion is returned.

This method continues to return this module's version while this module is in the UNLOADED state.

Returns: The version of this module.

bool Module::IsLoaded ( ) const

Returns this module's current state.

A module can be in only one state at any time.

Returns: true if the module is LOADED false if it is in any other state.

Module& Module::operator= ( const Module & )

delete

static const std::string& Module::PROP_AUTOLOAD_DIR ( )

static

Returns the property key with a value of module.autoload_dir for looking up this module's auto-load directory.

The property value is of type std::string.

Returns: The auto-load directory property key.

static const std::string& Module::PROP_AUTOLOADED_MODULES ( )

static

Returns the property key with a value of module.autoloaded_modules for looking up this module's auto-load modules.

The property value is of type std::vector<std::string> and contains the file system locations for the auto-loaded modules triggered by this module.

Returns: The auto-loaded modules property key.

static const std::string& Module::PROP_DESCRIPTION ( )

static

Returns the property key with a value of module.description for looking up this module's description.

The property value is of type std::string.

Returns: The description property key.

static const std::string& Module::PROP_ID ( )

static

Returns the property key for looking up this module's id.

The property value is of type long.

Returns: The id property key.

static const std::string& Module::PROP_LOCATION ( )

static

Returns the property key for looking up this module's location in the file system.

The property value is of type std::string.

Returns: The location property key.

static const std::string& Module::PROP_NAME ( )

static

Returns the property key for looking up this module's name.

The property value is of type std::string.

Returns: The name property key.

static const std::string& Module::PROP_VENDOR ( )

static

Returns the property key with a value of module.vendor for looking up this module's vendor information.

The property value is of type std::string.

Returns: The vendor property key.

static const std::string& Module::PROP_VERSION ( )

static

Returns the property key with a value of module.version for looking up this module's version identifier.

The property value is of type std::string.

Returns: The version property key.

virtual void Module::Start ( )

virtual

Start this bundle.

The following steps are required to start this bundle:

If this bundle is in the process of being activated or deactivated then this method must wait for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a std::runtime_error exception is thrown to indicate this bundle was unable to be started.
If this bundle was already started, then this method returns immediately.
A bundle event of type BundleEvent::STARTING is fired.
The BundleActivator::Start(BundleContext) method of this bundle's BundleActivator, if one is specified, is called. If the BundleActivator is invalid or throws an exception then:
- A bundle event of type BundleEvent::STOPPING is fired.
- Any services registered by this bundle must be unregistered.
- Any services used by this bundle must be released.
- Any listeners registered by this bundle must be removed.
- A bundle event of type BundleEvent::STOPPED is fired.
- A std::runtime_error exception is then thrown.
A bundle event of type BundleEvent::STARTED is fired.

Exceptions

std::runtime_error If this bundle could not be started.

Reimplemented in Framework.

virtual void Module::Stop ( )

virtual

Stop this bundle.

The following steps are required to stop a bundle:

If this bundle is in the process of being activated or deactivated then this method must wait for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a std::runtime_error exception is thrown to indicate this bundle was unable to be stopped.
If this bundle was already stopped, then this method returns immediately.
A bundle event of type BundleEvent::STOPPING is fired.
The BundleActivator::Stop(BundleContext) method of this bundle's BundleActivator, if one is specified, is called. If that method throws an exception, this method must continue to stop this bundle and a std::runtime_error exception must be thrown after completion of the remaining steps.
Any services registered by this bundle must be unregistered.
Any services used by this bundle must be released.
Any listeners registered by this bundle must be removed.
A bundle event of type BundleEvent::STOPPED is fired.

Exceptions

std::runtime_error If the bundle failed to stop.

Reimplemented in Framework.

virtual void Module::Uninstall ( )

virtual

Uninstalls this bundle.

This method causes the Framework to notify other bundles that this bundle is being uninstalled, and then uninstalls this bundle. The Framework must remove any resources related to this bundle that it is able to remove.

The following steps are required to uninstall a bundle:

This bundle is stopped as described in the Bundle.Stop method.
A bundle event of BundleEvent::UNINSTALLED is fired.
This bundle and any persistent storage area provided for this bundle by the Framework are removed.

Exceptions

std::runtime_error If the bundle could not be uninstalled. *

Reimplemented in Framework.

CppMicroServices

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation