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

Fields

Modifier and Type	Field and Description
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

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
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_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 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:

• BUNDLE_IN_ERROR_LOCATION_ITEM
• COMPLETED_ITEM
• ERROR_ITEM
• REMAINING_LOCATION_ITEM
• SUCCESS_ITEM

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:

• COMPLETED_ITEM
• SUCCESS_ITEM

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