Poco::OSP

class Bundle

Library: OSP
Package: Bundle
Header: Poco/OSP/Bundle.h

Description

This class represents a Bundle in OSP.

For every bundle directory or file found in the OSP bundle repository, a Bundle object is created. The bundle class stores the state of the Bundle and gives access to the bundle's manifest, configuration properties and resources.

The Bundle class also manages localized resources.

Inheritance

Direct Base Classes: Poco::RefCountedObject

All Base Classes: Poco::RefCountedObject

Member Summary

Member Functions: activator, activatorClass, activatorLibrary, addExtensionBundle, addProperties, addResolvedDependency, clearResolvedDependencies, copyright, events, extendedBundle, getLocalizedResource, getResource, id, isActive, isExtensionBundle, isResolved, isStarted, language, lazyStart, loadManifest, loadProperties, manifest, moduleProviders, name, path, preventUninstall, properties, providedModules, removeExtensionBundle, requiredBundles, requiredModules, resolve, resolvedDependencies, runLevel, sealed, setActivator, start, state, stateString, stop, storage, symbolicName, uninstall, vendor, version

Inherited Functions: duplicate, referenceCount, release

Nested Classes

struct ModuleProvider

 more...

struct ResolvedDependency

 more...

Types Aliases

ConstPtr

using ConstPtr = const Ptr;

Dependencies

using Dependencies = BundleManifest::Dependencies;

Dependency

using Dependency = BundleManifest::Dependency;

Module

using Module = BundleManifest::Module;

ModuleProviders

using ModuleProviders = std::vector < ModuleProvider >;

Modules

using Modules = BundleManifest::Modules;

Ptr

using Ptr = Poco::AutoPtr < Bundle >;

ResolvedDependencies

using ResolvedDependencies = std::vector < ResolvedDependency >;

Enumerations

State

BUNDLE_INSTALLED

BUNDLE_UNINSTALLED

BUNDLE_RESOLVED

BUNDLE_STARTING

BUNDLE_ACTIVE

BUNDLE_STOPPING

Constructors

Bundle protected

Bundle(
    int id,
    BundleLoader & loader,
    BundleStorage::Ptr pStorage,
    const LanguageTag & language
);

Creates the Bundle and reads the manifest using the given BundleStorage object.

The bundle takes ownership of the BundleStorage object.

Destructor

~Bundle protected virtual

~Bundle();

Destroys the Bundle.

Member Functions

activator inline

BundleActivator * activator() const;

If the bundle is active and has an activator, returns a pointer to the bundle's activator. Otherwise, returns NULL.

activatorClass inline

const std::string & activatorClass() const;

Returns the class name of the bundle's activator, or an empty string if the manifest does not specify an activator.

activatorLibrary inline

const std::string & activatorLibrary() const;

Returns the name of the library containing the bundle's activator class, or an empty string if the manifest does not specify an activator library.

copyright inline

const std::string & copyright() const;

Returns the bundle's copyright information, or an empty string if no copyright information has been specified in the pManifest->

If the copyright string contains a reference to a property, (${<property>}) the reference is expanded first.

extendedBundle

Bundle::Ptr extendedBundle() const;

If the bundle is an extension bundle, returns the extended bundle, or in other words, the bundle that this bundle extends.

Returns a null pointer if the bundle is not an extension bundle, or the extended bundle has not been loaded.

getLocalizedResource

std::istream * getLocalizedResource(
    const std::string & name
) const;

Creates and returns an input stream for reading the bundle's localized resource with the given name.

Resources are ordinary files stored within the bundle's directory or archive file.

Returns NULL if the resource does not exist.

The caller gets ownership of the input stream and must delete it when it's no longer needed.

getLocalizedResource

std::istream * getLocalizedResource(
    const std::string & name,
    const LanguageTag & language
) const;

Creates and returns an input stream for reading the bundle's localized (for the given language) resource with the given name.

Resources are ordinary files stored within the bundle's directory or archive file.

Returns NULL if the resource does not exist.

The caller gets ownership of the input stream and must delete it when it's no longer needed.

getResource

std::istream * getResource(
    const std::string & name
) const;

Creates and returns an input stream for reading the bundle's (non-localized) resource with the given name.

Resources are ordinary files stored within the bundle's directory or archive file.

Returns NULL if the resource does not exist.

The caller gets ownership of the input stream and must delete it when it's no longer needed.

id inline

int id() const;

Returns the internal ID of the bundle.

Note that internal IDs are only valid during the runtime of an OSP-based application and may change between restarts.

Bundle IDs are guaranteed to be unique within the scope of a BundleLoader. No assumptions shall be made that bundle IDs are given out in a certain order or that they are strictly consecutive.

isActive inline

bool isActive() const;

Returns true if and only if the bundle's state is BUNDLE_ACTIVE.

isExtensionBundle

bool isExtensionBundle() const;

Returns true if and only if the bundle is an extension bundle.

An extension bundle will "donate" all of its resources to the bundle it extends. This means that all properties defined in the extension bundle will become properties of the extended bundle. Also, all resources of the extension bundle will become available through getResource() and getLocalizedResource() on the extended bundle.

isResolved inline

bool isResolved() const;

Returns true if and only if the bundle has been successfully resolved.

In other words, the bundle's state must be one of BUNDLE_RESOLVED, BUNDLE_STARTING, BUNDLE_ACTIVE, BUNDLE_STOPPED.

isStarted inline

bool isStarted() const;

Returns true if and only if the bundle's state is BUNDLE_STARTING, BUNDLE_ACTIVE or BUNDLE_STOPPING.

language inline

const LanguageTag & language() const;

Returns the language used for localization.

lazyStart inline

bool lazyStart() const;

Returns true if lazy start has been specified for the bundle.

manifest inline

const BundleManifest & manifest() const;

Returns a reference to the BundleManifest object.

moduleProviders inline

const ModuleProviders & moduleProviders() const;

Returns a vector of all required modules, with information about the bundles providing each module.

name inline

const std::string & name() const;

Returns the bundle's name.

If the name contains a reference to a property, (${<property>}) the reference is expanded first.

path inline

std::string path() const;

Returns the path to the bundle's directory or archive file.

preventUninstall inline

bool preventUninstall() const;

Returns true if the bundle must not be uninstalled at run-time.

This is mostly useful for bundles that cannot be cleanly stopped. An example are bundles that contain third-party libraries that, once loaded, cannot be unloaded cleanly.

properties inline

const Poco::Util::AbstractConfiguration & properties() const;

Returns the bundle's properties, which are obtained from the bundle's "bundle.properties" file (and its optional localizations).

providedModules inline

const Modules & providedModules() const;

Returns a vector containing information about all modules provided by this bundle.

requiredBundles inline

const Dependencies & requiredBundles() const;

Returns a vector containing information about all bundles required by this bundle.

requiredModules inline

const Dependencies & requiredModules() const;

Returns a vector containing information about all modules required by this bundle.

resolve

void resolve();

Resolves the bundle by verifying the availability of all required bundles. The bundle must be in BUNDLE_INSTALLED state. A sucessful resolve() puts the bundle in BUNDLE_RESOLVED state.

Throws an exception if the bundle cannot be resolved.

resolvedDependencies inline

const ResolvedDependencies & resolvedDependencies() const;

Returns a vector containing information about all bundles explicitly (through Require-Bundle) or implicitly (through Require-Module) required by this bundle.

runLevel inline

const std::string & runLevel() const;

Returns the bundle's run level.

If the bundle does not specify a run level, returns the default "999-user".

sealed inline

bool sealed() const;

Returns true if the bundle is sealed and cannot be extended by an extension bundle.

start

void start();

Starts the bundle. The bundle's state must be BUNDLE_RESOLVED.

Puts the bundle in BUNDLE_STARTING state, loads the bundle's activator and invokes it, and finally puts the bundle in BUNDLE_RUNNING state.

state inline

State state() const;

Returns the current state of the bundle.

stateString

const std::string & stateString() const;

Returns the current state of the bundle as a string.

stop

void stop();

Stops the bundle. The bundle's state must be BUNDLE_ACTIVE. Puts the bundle into BUNDLE_STOPPING state, stops the bundle activator and finally puts the bundle into BUNDLE_RESOLVED state.

symbolicName inline

const std::string & symbolicName() const;

Returns the symbolic name of the bundle.

uninstall

void uninstall();

Uninstalls the bundle. The bundle must be in BUNDLE_INSTALLED or BUNDLE_RESOLVED state. The bundle is also removed from the bundle repository.

vendor inline

const std::string & vendor() const;

Returns the bundle's vendor name, or an empty string if no vendor name has been specified in the pManifest->

If the vendor string contains a reference to a property, (${<property>}) the reference is expanded first.

version inline

const Version & version() const;

Returns the bundle's version.

addExtensionBundle protected

void addExtensionBundle(
    Bundle * pExtensionBundle
);

Adds an extension bundle.

An extension bundle will "donate" all of its resources to the bundle it extends. This means that all properties defined in the extension bundle will become properties of the extended bundle. Also, all resources of the extension bundle will become available through getResource() and getLocalizedResource() on the extended bundle.

addProperties protected

void addProperties(
    const std::string & path
);

Adds the properties from the property file specified by path to the bundle's properties.

addResolvedDependency protected

void addResolvedDependency(
    const ResolvedDependency & dependency
);

Adds a dependency to the vector of resolved dependencies, unless it's already been added before.

clearResolvedDependencies protected

void clearResolvedDependencies();

Clears the vector of resolved dependencies.

events protected

BundleEvents & events();

Returns a reference to the BundleEvents object.

loadManifest protected

void loadManifest();

Loads the bundle's manifest file.

loadProperties protected

void loadProperties();

Loads the bundle's properties.

removeExtensionBundle protected

void removeExtensionBundle(
    Bundle * pExtensionBundle
);

Removes an extension bundle.

The resources and properties of the extension bundle will no longer be available to the extended bundle.

setActivator protected

void setActivator(
    BundleActivator * pActivator
);

Sets the BundleActivator.

storage protected inline

BundleStorage & storage();

Returns a reference to the BundleStorage object.

Variables

BUNDLE_ACTIVE_STRING static

static const std::string BUNDLE_ACTIVE_STRING;

BUNDLE_INSTALLED_STRING static

static const std::string BUNDLE_INSTALLED_STRING;

BUNDLE_INVALID_STRING static

static const std::string BUNDLE_INVALID_STRING;

BUNDLE_RESOLVED_STRING static

static const std::string BUNDLE_RESOLVED_STRING;

BUNDLE_STARTING_STRING static

static const std::string BUNDLE_STARTING_STRING;

BUNDLE_STOPPING_STRING static

static const std::string BUNDLE_STOPPING_STRING;

BUNDLE_UNINSTALLED_STRING static

static const std::string BUNDLE_UNINSTALLED_STRING;

MANIFEST_FILE static

static const std::string MANIFEST_FILE;

PROPERTIES_FILE static

static const std::string PROPERTIES_FILE;