Class Poco::OSP::Bundle

File Information

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

struct ResolvedDependency

Types Aliases

ConstPtr

using ConstPtr = const Ptr;

Enumerations

State

Constructors

Bundle

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

~Bundle();

Destroys the Bundle.

Member Functions

activator

BundleActivator * activator() const;

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

activatorClass

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

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

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

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

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

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

bool isStarted() const;

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

language

const LanguageTag & language() const;

Returns the language used for localization.

lazyStart

bool lazyStart() const;

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

manifest

const BundleManifest & manifest() const;

Returns a reference to the BundleManifest object.

moduleProviders

const ModuleProviders & moduleProviders() const;

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

name

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

std::string path() const;

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

preventUninstall

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

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

const Modules & providedModules() const;

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

requiredBundles

const Dependencies & requiredBundles() const;

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

requiredModules

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

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

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

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

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.