org.osgi.jmx.framework

Interface FrameworkMBean

All Known Implementing Classes:

Framework

public interface FrameworkMBean

The FrameworkMbean provides mechanisms to exert control over the framework. For many operations, it provides a batch mechanism to avoid excessive message passing when interacting remotely.

Version:

$Revision: 1460851 $

Field Summary

Fields

Modifier and Type	Field and Description
static CompositeType	BATCH_ACTION_RESULT_TYPE The Composite Type for a batch action result.
static CompositeType	BATCH_INSTALL_RESULT_TYPE The Composite Type which represents the result of a batch install operation.
static CompositeType	BATCH_RESOLVE_RESULT_TYPE The Composite Type which represents the result of a batch resolve operation.
static String	BUNDLE_IN_ERROR The key for BUNDLE_IN_ERROR.
static Item	BUNDLE_IN_ERROR_ID_ITEM The item containing the bundle which caused the error during the batch operation.
static Item	BUNDLE_IN_ERROR_LOCATION_ITEM The item containing the bundle which caused the error during the batch operation.
static String	COMPLETED The key COMPLETED, used in COMPLETED_ITEM.
static Item	COMPLETED_ITEM The item containing the list of bundles completing the batch operation.
static String	ERROR The key ERROR, used in ERROR_ITEM.
static Item	ERROR_ITEM The item containing the error message of the batch operation.
static String	OBJECTNAME The fully qualified object name of this mbean.
static String	REMAINING The key REMAINING, used in REMAINING_ID_ITEM and REMAINING_LOCATION_ITEM.
static Item	REMAINING_ID_ITEM The item containing the list of remaining bundles unprocessed by the failing batch operation.
static Item	REMAINING_LOCATION_ITEM The item containing the list of remaining bundles unprocessed by the failing batch operation.
static String	SUCCESS The SUCCESS, used in SUCCESS_ITEM.
static Item	SUCCESS_ITEM The item that indicates if this operation was successful.

Method Summary

Methods

Modifier and Type	Method and Description
long[]	getDependencyClosure(long[] bundles) Returns the dependency closure for the specified bundles.
int	getFrameworkStartLevel() Retrieve the framework start level
int	getInitialBundleStartLevel() Answer the initial start level assigned to a bundle when it is first started
String	getProperty(String key) Returns the value of the specified property.
long[]	getRemovalPendingBundles() Returns the bundles IDs that have non-current, in use bundle wirings.
long	installBundle(String location) Install the bundle indicated by the bundleLocations
long	installBundleFromURL(String location, String url) Install the bundle indicated by the bundleLocations
CompositeData	installBundles(String[] locations) Batch install the bundles indicated by the list of bundleLocationUrls
CompositeData	installBundlesFromURL(String[] locations, String[] urls) Batch install the bundles indicated by the list of bundleLocationUrls
void	refreshBundle(long bundleIdentifier) Force the update, replacement or removal of the packages identified by the specified bundle.
boolean	refreshBundleAndWait(long bundleIdentifier)
void	refreshBundles(long[] bundleIdentifiers) Force the update, replacement or removal of the packages identified by the list of bundles.
CompositeData	refreshBundlesAndWait(long[] bundleIdentifiers)
CompositeData	resolve(long[] bundleIdentifiers) Same as resolveBundles(long[]) but with a more detailed return type.
boolean	resolveBundle(long bundleIdentifier) Resolve the bundle indicated by the unique symbolic name and version
boolean	resolveBundles(long[] bundleIdentifiers) Batch resolve the bundles indicated by the list of bundle identifiers
void	restartFramework() Restart the framework by updating the system bundle
void	setBundleStartLevel(long bundleIdentifier, int newlevel) Set the start level for the bundle identifier
CompositeData	setBundleStartLevels(long[] bundleIdentifiers, int[] newlevels) Set the start levels for the list of bundles.
void	setFrameworkStartLevel(int newlevel) Set the start level for the framework
void	setInitialBundleStartLevel(int newlevel) Set the initial start level assigned to a bundle when it is first started
void	shutdownFramework() Shutdown the framework by stopping the system bundle
void	startBundle(long bundleIdentifier) Start the bundle indicated by the bundle identifier
CompositeData	startBundles(long[] bundleIdentifiers) Batch start the bundles indicated by the list of bundle identifier
void	stopBundle(long bundleIdentifier) Stop the bundle indicated by the bundle identifier
CompositeData	stopBundles(long[] bundleIdentifiers) Batch stop the bundles indicated by the list of bundle identifier
void	uninstallBundle(long bundleIdentifier) Uninstall the bundle indicated by the bundle identifier
CompositeData	uninstallBundles(long[] bundleIdentifiers) Batch uninstall the bundles indicated by the list of bundle identifiers
void	updateBundle(long bundleIdentifier) Update the bundle indicated by the bundle identifier
void	updateBundleFromURL(long bundleIdentifier, String url) Update the bundle identified by the bundle identifier
CompositeData	updateBundles(long[] bundleIdentifiers) Batch update the bundles indicated by the list of bundle identifier.
CompositeData	updateBundlesFromURL(long[] bundleIdentifiers, String[] urls) Update the bundle uniquely identified by the bundle symbolic name and version using the contents of the supplied urls.
void	updateFramework() Update the framework by updating the system bundle.

Field Detail

OBJECTNAME

static final String OBJECTNAME

The fully qualified object name of this mbean.

See Also:

Constant Field Values

SUCCESS

static final String SUCCESS

The SUCCESS, used in SUCCESS_ITEM.

See Also:

Constant Field Values

SUCCESS_ITEM

static final Item SUCCESS_ITEM

The item that indicates if this operation was successful. The key is SUCCESS and the type is SimpleType.BOOLEAN. It is used in BATCH_ACTION_RESULT_TYPE and BATCH_INSTALL_RESULT_TYPE.

ERROR

static final String ERROR

The key ERROR, used in ERROR_ITEM.

See Also:

Constant Field Values

ERROR_ITEM

static final Item ERROR_ITEM

The item containing the error message of the batch operation. The key is ERROR and the type is SimpleType.STRING. It is used in BATCH_ACTION_RESULT_TYPE and BATCH_INSTALL_RESULT_TYPE.

COMPLETED

static final String COMPLETED

The key COMPLETED, used in COMPLETED_ITEM.

See Also:

Constant Field Values

COMPLETED_ITEM

static final Item COMPLETED_ITEM

The item containing the list of bundles completing the batch operation. The key is COMPLETED and the type is JmxConstants.LONG_ARRAY_TYPE. It is used in BATCH_ACTION_RESULT_TYPE and BATCH_INSTALL_RESULT_TYPE.

BUNDLE_IN_ERROR

static final String BUNDLE_IN_ERROR

The key for BUNDLE_IN_ERROR. This key is used with two different items: BUNDLE_IN_ERROR_ID_ITEM and BUNDLE_IN_ERROR_LOCATION_ITEM that each have a different type for this key. It is used in BATCH_ACTION_RESULT_TYPE and BATCH_INSTALL_RESULT_TYPE.

See Also:

Constant Field Values

BUNDLE_IN_ERROR_ID_ITEM

static final Item BUNDLE_IN_ERROR_ID_ITEM

The item containing the bundle which caused the error during the batch operation. This item describes the bundle in error as an id. The key is BUNDLE_IN_ERROR and the type is SimpleType.LONG. It is used in BATCH_ACTION_RESULT_TYPE.

See Also:

BUNDLE_IN_ERROR_LOCATION_ITEM for the item that has a location for the bundle in error.

REMAINING

static final String REMAINING

The key REMAINING, used in REMAINING_ID_ITEM and REMAINING_LOCATION_ITEM.

See Also:

Constant Field Values

REMAINING_ID_ITEM

static final Item REMAINING_ID_ITEM

The item containing the list of remaining bundles unprocessed by the failing batch operation. The key is REMAINING and the type is JmxConstants.LONG_ARRAY_TYPE. It is used in BATCH_ACTION_RESULT_TYPE and BATCH_INSTALL_RESULT_TYPE.

BATCH_ACTION_RESULT_TYPE

static final CompositeType BATCH_ACTION_RESULT_TYPE

The Composite Type for a batch action result. refreshBundle(long) and refreshBundles(long[]). Notice that a batch action result returns uses an id for the BUNDLE_IN_ERROR while the BATCH_INSTALL_RESULT_TYPE uses a location. This Composite Type consists of the following items:

• BUNDLE_IN_ERROR_ID_ITEM
• COMPLETED_ITEM
• ERROR_ITEM
• REMAINING_ID_ITEM
• SUCCESS_ITEM

BUNDLE_IN_ERROR_LOCATION_ITEM

static final Item BUNDLE_IN_ERROR_LOCATION_ITEM

The item containing the bundle which caused the error during the batch operation. This item describes the bundle in error as a location. The key is BUNDLE_IN_ERROR and the type is SimpleType.STRING. It is used in BATCH_INSTALL_RESULT_TYPE.

See Also:

BUNDLE_IN_ERROR_ID_ITEM for the item that has the id for the bundle in error.

REMAINING_LOCATION_ITEM

static final Item REMAINING_LOCATION_ITEM

The item containing the list of remaining bundles unprocessed by the failing batch operation. The key is REMAINING and the type is JmxConstants.STRING_ARRAY_TYPE. It is used in BATCH_ACTION_RESULT_TYPE and BATCH_INSTALL_RESULT_TYPE.

BATCH_INSTALL_RESULT_TYPE

static final CompositeType BATCH_INSTALL_RESULT_TYPE

The Composite Type which represents the result of a batch install operation. It is used in installBundles(String[]) and installBundlesFromURL(String[], String[]). This Composite Type consists of the following items:

• BUNDLE_IN_ERROR_LOCATION_ITEM
• COMPLETED_ITEM
• ERROR_ITEM
• P
• SUCCESS_ITEM

BATCH_RESOLVE_RESULT_TYPE

static final CompositeType BATCH_RESOLVE_RESULT_TYPE

The Composite Type which represents the result of a batch resolve operation. It is used in #refreshBundlesAndWait(String[]). This Composite Type consists of the following items:

• COMPLETED_ITEM
• SUCCESS_ITEM

Method Detail

getDependencyClosure

long[] getDependencyClosure(long[] bundles)
                            throws IOException

Returns the dependency closure for the specified bundles.

A graph of bundles is computed starting with the specified bundles. The graph is expanded by adding any bundle that is either wired to a package that is currently exported by a bundle in the graph or requires a bundle in the graph. The graph is fully constructed when there is no bundle outside the graph that is wired to a bundle in the graph. The graph may contain UNINSTALLED bundles that are removal pending.

Parameters:

bundles - The initial bundles IDs for which to generate the dependency closure.

Returns:

A bundle ID array containing a snapshot of the dependency closure of the specified bundles, or an empty array if there were no specified bundles.

Throws:

IOException - if the operation failed

getFrameworkStartLevel

int getFrameworkStartLevel()
                           throws IOException

Retrieve the framework start level

Returns:

the framework start level

Throws:

IOException - if the operation failed

getInitialBundleStartLevel

int getInitialBundleStartLevel()
                               throws IOException

Answer the initial start level assigned to a bundle when it is first started

Returns:

the start level

Throws:

IOException - if the operation failed

getProperty

String getProperty(String key)
                   throws IOException

Returns the value of the specified property. If the key is not found in the Framework properties, the system properties are then searched. The method returns null if the property is not found.

Parameters:

key - The name of the requested property.

Returns:

The value of the requested property, or null if the property is undefined.

Throws:

IOException - if the operation failed

getRemovalPendingBundles

long[] getRemovalPendingBundles()
                                throws IOException

Returns the bundles IDs that have non-current, in use bundle wirings. This is typically the bundles which have been updated or uninstalled since the last call to refreshBundles(long[]).

Returns:

A bundle ID array containing a snapshot of the bundles which have non-current, in use bundle wirings, or an empty array if there are no such bundles.

Throws:

IOException - if the operation failed

installBundle

long installBundle(String location)
                   throws IOException

Install the bundle indicated by the bundleLocations

Parameters:

location - the location of the bundle to install

Returns:

the bundle id the installed bundle

Throws:

IOException - if the operation does not succeed

installBundleFromURL

long installBundleFromURL(String location,
                        String url)
                          throws IOException

Install the bundle indicated by the bundleLocations

Parameters:

location - the location to assign to the bundle

url - the URL which will supply the bytes for the bundle

Returns:

the bundle id the installed bundle

Throws:

IOException - if the operation does not succeed

installBundles

CompositeData installBundles(String[] locations)
                             throws IOException

Batch install the bundles indicated by the list of bundleLocationUrls

Parameters:

locations - the array of locations of the bundles to install

Returns:

the resulting state from executing the operation

Throws:

IOException - if the operation does not succeed

See Also:

BATCH_INSTALL_RESULT_TYPE for the precise specification of the CompositeData type representing the returned result.

installBundlesFromURL

CompositeData installBundlesFromURL(String[] locations,
                                  String[] urls)
                                    throws IOException

Batch install the bundles indicated by the list of bundleLocationUrls

Parameters:

locations - the array of locations to assign to the installed bundles

urls - the array of urls which supply the bundle bytes

Returns:

the resulting state from executing the operation

Throws:

IOException - if the operation does not succeed

See Also:

BATCH_INSTALL_RESULT_TYPE BatchBundleResult for the precise specification of the CompositeData type representing the returned result.

refreshBundle

void refreshBundle(long bundleIdentifier)
                   throws IOException

Force the update, replacement or removal of the packages identified by the specified bundle.

Parameters:

bundleIdentifier - the bundle identifier

Throws:

IOException - if the operation failed

refreshBundleAndWait

boolean refreshBundleAndWait(long bundleIdentifier)
                             throws IOException

Throws:

IOException

refreshBundles

void refreshBundles(long[] bundleIdentifiers)
                    throws IOException

Force the update, replacement or removal of the packages identified by the list of bundles.

Parameters:

bundleIdentifiers - The identifiers of the bundles to refresh, or null for all bundles with packages pending removal.

Throws:

IOException - if the operation failed

refreshBundlesAndWait

CompositeData refreshBundlesAndWait(long[] bundleIdentifiers)
                                    throws IOException

Throws:

IOException

resolveBundle

boolean resolveBundle(long bundleIdentifier)
                      throws IOException

Resolve the bundle indicated by the unique symbolic name and version

Parameters:

bundleIdentifier - the bundle identifier

Returns:

true if the bundle was resolved, false otherwise

Throws:

IOException - if the operation does not succeed

IllegalArgumentException - if the bundle indicated does not exist

resolveBundles

boolean resolveBundles(long[] bundleIdentifiers)
                       throws IOException

Batch resolve the bundles indicated by the list of bundle identifiers

Parameters:

bundleIdentifiers - The identifiers of the bundles to resolve, or null to resolve all unresolved bundles.

Returns:

true if the bundles were resolved, false otherwise

Throws:

IOException - if the operation does not succeed

resolve

CompositeData resolve(long[] bundleIdentifiers)
                      throws IOException

Same as resolveBundles(long[]) but with a more detailed return type.

Parameters:

bundleIdentifiers -

Returns:

Throws:

IOException

restartFramework

void restartFramework()
                      throws IOException

Restart the framework by updating the system bundle

Throws:

IOException - if the operation failed

setBundleStartLevel

void setBundleStartLevel(long bundleIdentifier,
                       int newlevel)
                         throws IOException

Set the start level for the bundle identifier

Parameters:

bundleIdentifier - the bundle identifier

newlevel - the new start level for the bundle

Throws:

IOException - if the operation failed

setBundleStartLevels

CompositeData setBundleStartLevels(long[] bundleIdentifiers,
                                 int[] newlevels)
                                   throws IOException

Set the start levels for the list of bundles.

Parameters:

bundleIdentifiers - the array of bundle identifiers

newlevels - the array of new start level for the bundles

Returns:

the resulting state from executing the operation

Throws:

IOException - if the operation failed

See Also:

BATCH_ACTION_RESULT_TYPE for the precise specification of the CompositeData type representing the returned result.

setFrameworkStartLevel

void setFrameworkStartLevel(int newlevel)
                            throws IOException

Set the start level for the framework

Parameters:

newlevel - the new start level

Throws:

IOException - if the operation failed

setInitialBundleStartLevel

void setInitialBundleStartLevel(int newlevel)
                                throws IOException

Set the initial start level assigned to a bundle when it is first started

Parameters:

newlevel - the new start level

Throws:

IOException - if the operation failed

shutdownFramework

void shutdownFramework()
                       throws IOException

Shutdown the framework by stopping the system bundle

Throws:

IOException - if the operation failed

startBundle

void startBundle(long bundleIdentifier)
                 throws IOException

Start the bundle indicated by the bundle identifier

Parameters:

bundleIdentifier - the bundle identifier

Throws:

IOException - if the operation does not succeed

IllegalArgumentException - if the bundle indicated does not exist

startBundles

CompositeData startBundles(long[] bundleIdentifiers)
                           throws IOException

Batch start the bundles indicated by the list of bundle identifier

Parameters:

bundleIdentifiers - the array of bundle identifiers

Returns:

the resulting state from executing the operation

Throws:

IOException - if the operation does not succeed

See Also:

BATCH_ACTION_RESULT_TYPE for the precise specification of the CompositeData type representing the returned result.

stopBundle

void stopBundle(long bundleIdentifier)
                throws IOException

Stop the bundle indicated by the bundle identifier

Parameters:

bundleIdentifier - the bundle identifier

Throws:

IOException - if the operation does not succeed

IllegalArgumentException - if the bundle indicated does not exist

stopBundles

CompositeData stopBundles(long[] bundleIdentifiers)
                          throws IOException

Batch stop the bundles indicated by the list of bundle identifier

Parameters:

bundleIdentifiers - the array of bundle identifiers

Returns:

the resulting state from executing the operation

Throws:

IOException - if the operation does not succeed

See Also:

BATCH_ACTION_RESULT_TYPE for the precise specification of the CompositeData type representing the returned result.

uninstallBundle

void uninstallBundle(long bundleIdentifier)
                     throws IOException

Uninstall the bundle indicated by the bundle identifier

Parameters:

bundleIdentifier - the bundle identifier

Throws:

IOException - if the operation does not succeed

IllegalArgumentException - if the bundle indicated does not exist

uninstallBundles

CompositeData uninstallBundles(long[] bundleIdentifiers)
                               throws IOException

Batch uninstall the bundles indicated by the list of bundle identifiers

Parameters:

bundleIdentifiers - the array of bundle identifiers

Returns:

the resulting state from executing the operation

Throws:

IOException - if the operation does not succeed

See Also:

BATCH_ACTION_RESULT_TYPE for the precise specification of the CompositeData type representing the returned result.

updateBundle

void updateBundle(long bundleIdentifier)
                  throws IOException

Update the bundle indicated by the bundle identifier

Parameters:

bundleIdentifier - the bundle identifier

Throws:

IOException - if the operation does not succeed

IllegalArgumentException - if the bundle indicated does not exist

updateBundleFromURL

void updateBundleFromURL(long bundleIdentifier,
                       String url)
                         throws IOException

Update the bundle identified by the bundle identifier

Parameters:

bundleIdentifier - the bundle identifier

url - the URL to use to update the bundle

Throws:

IOException - if the operation does not succeed

IllegalArgumentException - if the bundle indicated does not exist

updateBundles

CompositeData updateBundles(long[] bundleIdentifiers)
                            throws IOException

Batch update the bundles indicated by the list of bundle identifier.

Parameters:

bundleIdentifiers - the array of bundle identifiers

Returns:

the resulting state from executing the operation

Throws:

IOException - if the operation does not succeed

See Also:

BATCH_ACTION_RESULT_TYPE for the precise specification of the CompositeData type representing the returned result.

updateBundlesFromURL

CompositeData updateBundlesFromURL(long[] bundleIdentifiers,
                                 String[] urls)
                                   throws IOException

Update the bundle uniquely identified by the bundle symbolic name and version using the contents of the supplied urls.

Parameters:

bundleIdentifiers - the array of bundle identifiers

urls - the array of URLs to use to update the bundles

Returns:

the resulting state from executing the operation

Throws:

IOException - if the operation does not succeed

IllegalArgumentException - if the bundle indicated does not exist

See Also:

BATCH_ACTION_RESULT_TYPE for the precise specification of the CompositeData type representing the returned result.

updateFramework

void updateFramework()
                     throws IOException

Update the framework by updating the system bundle.

Throws:

IOException - if the operation failed