OSGi™ Enterprise
Release 5

org.osgi.jmx.framework
Interface FrameworkMBean


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.

ThreadSafe

Field Summary
static javax.management.openmbean.CompositeType BATCH_ACTION_RESULT_TYPE
          The Composite Type for a batch action result.
static javax.management.openmbean.CompositeType BATCH_INSTALL_RESULT_TYPE
          The Composite Type which represents the result of a batch install operation.
static javax.management.openmbean.CompositeType BATCH_RESOLVE_RESULT_TYPE
          The Composite Type which represents the result of a batch resolve operation.
static java.lang.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 java.lang.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 java.lang.String ERROR
          The key ERROR, used in ERROR_ITEM.
static Item ERROR_ITEM
          The item containing the error message of the batch operation.
static java.lang.String OBJECTNAME
          The Object Name prefix for this mbean.
static java.lang.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 java.lang.String SUCCESS
          The SUCCESS, used in SUCCESS_ITEM.
static Item SUCCESS_ITEM
          The item that indicates if this operation was successful.
 
Method Summary
 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
 java.lang.String getProperty(java.lang.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(java.lang.String location)
          Install the bundle indicated by the bundleLocations
 long installBundleFromURL(java.lang.String location, java.lang.String url)
          Install the bundle indicated by the bundleLocations
 javax.management.openmbean.CompositeData installBundles(java.lang.String[] locations)
          Batch install the bundles indicated by the list of bundleLocationUrls
 javax.management.openmbean.CompositeData installBundlesFromURL(java.lang.String[] locations, java.lang.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)
          Force the update, replacement or removal of the packages identified by the specified bundle and wait until completed.
 void refreshBundles(long[] bundleIdentifiers)
          Force the update, replacement or removal of the packages identified by the list of bundles.
 javax.management.openmbean.CompositeData refreshBundlesAndWait(long[] bundleIdentifiers)
          Force the update, replacement or removal of the packages identified by the list of bundles and wait until completed.
 javax.management.openmbean.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
 javax.management.openmbean.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
 javax.management.openmbean.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
 javax.management.openmbean.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
 javax.management.openmbean.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, java.lang.String url)
          Update the bundle identified by the bundle identifier
 javax.management.openmbean.CompositeData updateBundles(long[] bundleIdentifiers)
          Batch update the bundles indicated by the list of bundle identifier.
 javax.management.openmbean.CompositeData updateBundlesFromURL(long[] bundleIdentifiers, java.lang.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 java.lang.String OBJECTNAME
The Object Name prefix for this mbean. The full object name also contains the framework name and uuid as properties.

See Also:
Constant Field Values

SUCCESS

static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 javax.management.openmbean.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_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 javax.management.openmbean.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:


BATCH_RESOLVE_RESULT_TYPE

static final javax.management.openmbean.CompositeType BATCH_RESOLVE_RESULT_TYPE
The Composite Type which represents the result of a batch resolve operation. It is used in refreshBundlesAndWait(long[]) and resolve(long[]). This Composite Type consists of the following items:

Method Detail

getDependencyClosure

long[] getDependencyClosure(long[] bundles)
                            throws java.io.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:
java.io.IOException - if the operation failed
java.lang.IllegalArgumentException - if a bundle indicated does not exist

getFrameworkStartLevel

int getFrameworkStartLevel()
                           throws java.io.IOException
Retrieve the framework start level

Returns:
the framework start level
Throws:
java.io.IOException - if the operation failed

getInitialBundleStartLevel

int getInitialBundleStartLevel()
                               throws java.io.IOException
Answer the initial start level assigned to a bundle when it is first started

Returns:
the start level
Throws:
java.io.IOException - if the operation failed

getProperty

java.lang.String getProperty(java.lang.String key)
                             throws java.io.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:
java.io.IOException - if the operation failed

getRemovalPendingBundles

long[] getRemovalPendingBundles()
                                throws java.io.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:
java.io.IOException - if the operation failed

installBundle

long installBundle(java.lang.String location)
                   throws java.io.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:
java.io.IOException - if the operation does not succeed

installBundleFromURL

long installBundleFromURL(java.lang.String location,
                          java.lang.String url)
                          throws java.io.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:
java.io.IOException - if the operation does not succeed

installBundles

javax.management.openmbean.CompositeData installBundles(java.lang.String[] locations)
                                                        throws java.io.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:
java.io.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

javax.management.openmbean.CompositeData installBundlesFromURL(java.lang.String[] locations,
                                                               java.lang.String[] urls)
                                                               throws java.io.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:
java.io.IOException - if the operation does not succeed
See Also:
for the precise specification of the CompositeData type representing the returned result.

refreshBundle

void refreshBundle(long bundleIdentifier)
                   throws java.io.IOException
Force the update, replacement or removal of the packages identified by the specified bundle.

Parameters:
bundleIdentifier - the bundle identifier
Throws:
java.io.IOException - if the operation failed
java.lang.IllegalArgumentException - if the bundle indicated does not exist

refreshBundleAndWait

boolean refreshBundleAndWait(long bundleIdentifier)
                             throws java.io.IOException
Force the update, replacement or removal of the packages identified by the specified bundle and wait until completed.

Parameters:
bundleIdentifier - the bundle identifier
Returns:
whether the bundle was successfully resolved after being refreshed.
Throws:
java.io.IOException - if the operation failed
java.lang.IllegalArgumentException - if the bundle indicated does not exist

refreshBundles

void refreshBundles(long[] bundleIdentifiers)
                    throws java.io.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:
java.io.IOException - if the operation failed
java.lang.IllegalArgumentException - if a bundle indicated does not exist

refreshBundlesAndWait

javax.management.openmbean.CompositeData refreshBundlesAndWait(long[] bundleIdentifiers)
                                                               throws java.io.IOException
Force the update, replacement or removal of the packages identified by the list of bundles and wait until completed.

Parameters:
bundleIdentifiers - The identifiers of the bundles to refresh, or null for all bundles with packages pending removal.
Returns:
the result of the refresh operation
Throws:
java.io.IOException - if the operation failed
java.lang.IllegalArgumentException - if a bundle indicated does not exist
See Also:
for the precise specification of the CompositeData type representing the returned result.

resolveBundle

boolean resolveBundle(long bundleIdentifier)
                      throws java.io.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:
java.io.IOException - if the operation does not succeed
java.lang.IllegalArgumentException - if the bundle indicated does not exist

resolveBundles

boolean resolveBundles(long[] bundleIdentifiers)
                       throws java.io.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:
java.io.IOException - if the operation does not succeed
java.lang.IllegalArgumentException - if a bundle indicated does not exist

resolve

javax.management.openmbean.CompositeData resolve(long[] bundleIdentifiers)
                                                 throws java.io.IOException
Same as resolveBundles(long[]) but with a more detailed return type.

Parameters:
bundleIdentifiers - The identifiers of the bundles to resolve, or null to resolve all unresolved bundles.
Returns:
the resulting state from executing the operation
Throws:
java.io.IOException - if the operation failed
java.lang.IllegalArgumentException - if a bundle indicated does not exist
See Also:
for the precise specification of the CompositeData type representing the returned result.

restartFramework

void restartFramework()
                      throws java.io.IOException
Restart the framework by updating the system bundle

Throws:
java.io.IOException - if the operation failed

setBundleStartLevel

void setBundleStartLevel(long bundleIdentifier,
                         int newlevel)
                         throws java.io.IOException
Set the start level for the bundle identifier

Parameters:
bundleIdentifier - the bundle identifier
newlevel - the new start level for the bundle
Throws:
java.io.IOException - if the operation failed

setBundleStartLevels

javax.management.openmbean.CompositeData setBundleStartLevels(long[] bundleIdentifiers,
                                                              int[] newlevels)
                                                              throws java.io.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:
java.io.IOException - if the operation failed
See Also:
for the precise specification of the CompositeData type representing the returned result.

setFrameworkStartLevel

void setFrameworkStartLevel(int newlevel)
                            throws java.io.IOException
Set the start level for the framework

Parameters:
newlevel - the new start level
Throws:
java.io.IOException - if the operation failed

setInitialBundleStartLevel

void setInitialBundleStartLevel(int newlevel)
                                throws java.io.IOException
Set the initial start level assigned to a bundle when it is first started

Parameters:
newlevel - the new start level
Throws:
java.io.IOException - if the operation failed

shutdownFramework

void shutdownFramework()
                       throws java.io.IOException
Shutdown the framework by stopping the system bundle

Throws:
java.io.IOException - if the operation failed

startBundle

void startBundle(long bundleIdentifier)
                 throws java.io.IOException
Start the bundle indicated by the bundle identifier

Parameters:
bundleIdentifier - the bundle identifier
Throws:
java.io.IOException - if the operation does not succeed
java.lang.IllegalArgumentException - if the bundle indicated does not exist

startBundles

javax.management.openmbean.CompositeData startBundles(long[] bundleIdentifiers)
                                                      throws java.io.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:
java.io.IOException - if the operation does not succeed
See Also:
for the precise specification of the CompositeData type representing the returned result.

stopBundle

void stopBundle(long bundleIdentifier)
                throws java.io.IOException
Stop the bundle indicated by the bundle identifier

Parameters:
bundleIdentifier - the bundle identifier
Throws:
java.io.IOException - if the operation does not succeed
java.lang.IllegalArgumentException - if the bundle indicated does not exist

stopBundles

javax.management.openmbean.CompositeData stopBundles(long[] bundleIdentifiers)
                                                     throws java.io.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:
java.io.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 java.io.IOException
Uninstall the bundle indicated by the bundle identifier

Parameters:
bundleIdentifier - the bundle identifier
Throws:
java.io.IOException - if the operation does not succeed
java.lang.IllegalArgumentException - if the bundle indicated does not exist

uninstallBundles

javax.management.openmbean.CompositeData uninstallBundles(long[] bundleIdentifiers)
                                                          throws java.io.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:
java.io.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 java.io.IOException
Update the bundle indicated by the bundle identifier

Parameters:
bundleIdentifier - the bundle identifier
Throws:
java.io.IOException - if the operation does not succeed
java.lang.IllegalArgumentException - if the bundle indicated does not exist

updateBundleFromURL

void updateBundleFromURL(long bundleIdentifier,
                         java.lang.String url)
                         throws java.io.IOException
Update the bundle identified by the bundle identifier

Parameters:
bundleIdentifier - the bundle identifier
url - the URL to use to update the bundle
Throws:
java.io.IOException - if the operation does not succeed
java.lang.IllegalArgumentException - if the bundle indicated does not exist

updateBundles

javax.management.openmbean.CompositeData updateBundles(long[] bundleIdentifiers)
                                                       throws java.io.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:
java.io.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

javax.management.openmbean.CompositeData updateBundlesFromURL(long[] bundleIdentifiers,
                                                              java.lang.String[] urls)
                                                              throws java.io.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:
java.io.IOException - if the operation does not succeed
java.lang.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 java.io.IOException
Update the framework by updating the system bundle.

Throws:
java.io.IOException - if the operation failed

OSGi™ Enterprise
Release 5

Copyright © OSGi Alliance (2000, 2012). All Rights Reserved. Licensed under the OSGi Specification License, Version 2.0