Interface Framework
-
- All Superinterfaces:
Bundle
public interface Framework extends Bundle
A Framework instance. A Framework is also known as a System Bundle.Framework instances are created using a
FrameworkFactory
. The methods of this interface can be used to manage and control the created framework instance.- Version:
- $Revision: 6542 $
-
-
Field Summary
-
Fields inherited from interface org.osgi.framework.Bundle
ACTIVE, INSTALLED, RESOLVED, SIGNERS_ALL, SIGNERS_TRUSTED, START_ACTIVATION_POLICY, START_TRANSIENT, STARTING, STOP_TRANSIENT, STOPPING, UNINSTALLED
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description long
getBundleId()
Returns the Framework unique identifier.java.lang.String
getLocation()
Returns the Framework location identifier.java.lang.String
getSymbolicName()
Returns the symbolic name of this Framework.void
init()
Initialize this Framework.void
start()
Start this Framework.void
start(int options)
Start this Framework.void
stop()
Stop this Framework.void
stop(int options)
Stop this Framework.void
uninstall()
The Framework cannot be uninstalled.void
update()
Stop and restart this Framework.void
update(java.io.InputStream in)
Stop and restart this Framework.FrameworkEvent
waitForStop(long timeout)
Wait until this Framework has completely stopped.-
Methods inherited from interface org.osgi.framework.Bundle
findEntries, getBundleContext, getEntry, getEntryPaths, getHeaders, getHeaders, getLastModified, getRegisteredServices, getResource, getResources, getServicesInUse, getSignerCertificates, getState, getVersion, hasPermission, loadClass
-
-
-
-
Method Detail
-
init
void init() throws BundleException
Initialize this Framework. After calling this method, this Framework must:- Be in the
Bundle.STARTING
state. - Have a valid Bundle Context.
- Be at start level 0.
- Have event handling enabled.
- Have reified Bundle objects for all installed bundles.
- Have registered any framework services. For example,
PackageAdmin
,ConditionalPermissionAdmin
,StartLevel
.
This Framework will not actually be started until
start
is called.This method does nothing if called when this Framework is in the
Bundle.STARTING
,Bundle.ACTIVE
orBundle.STOPPING
states.- Throws:
BundleException
- If this Framework could not be initialized.java.lang.SecurityException
- If the Java Runtime Environment supports permissions and the caller does not have the appropriateAdminPermission[this,EXECUTE]
or if there is a security manager already installed and theConstants.FRAMEWORK_SECURITY
configuration property is set.
- Be in the
-
waitForStop
FrameworkEvent waitForStop(long timeout) throws java.lang.InterruptedException
Wait until this Framework has completely stopped. Thestop
andupdate
methods on a Framework performs an asynchronous stop of the Framework. This method can be used to wait until the asynchronous stop of this Framework has completed. This method will only wait if called when this Framework is in theBundle.STARTING
,Bundle.ACTIVE
, orBundle.STOPPING
states. Otherwise it will return immediately.A Framework Event is returned to indicate why this Framework has stopped.
- Parameters:
timeout
- Maximum number of milliseconds to wait until this Framework has completely stopped. A value of zero will wait indefinitely.- Returns:
- A Framework Event indicating the reason this method returned. The
following
FrameworkEvent
types may be returned by this method.STOPPED
- This Framework has been stopped.STOPPED_UPDATE
- This Framework has been updated which has shutdown and will now restart.-
STOPPED_BOOTCLASSPATH_MODIFIED
- This Framework has been stopped and a bootclasspath extension bundle has been installed or updated. The VM must be restarted in order for the changed boot class path to take affect. ERROR
- The Framework encountered an error while shutting down or an error has occurred which forced the framework to shutdown.-
WAIT_TIMEDOUT
- This method has timed out and returned before this Framework has stopped.
- Throws:
java.lang.InterruptedException
- If another thread interrupted the current thread before or while the current thread was waiting for this Framework to completely stop. The interrupted status of the current thread is cleared when this exception is thrown.java.lang.IllegalArgumentException
- If the value of timeout is negative.
-
start
void start() throws BundleException
Start this Framework.The following steps are taken to start this Framework:
- If this Framework is not in the
Bundle.STARTING
state,initialize
this Framework. - All installed bundles must be started in accordance with each
bundle's persistent autostart setting. This means some bundles
will not be started, some will be started with eager activation
and some will be started with their declared activation policy. If
this Framework implements the optional Start Level Service
Specification, then the start level of this Framework is moved to the
start level specified by the
beginning start level
framework property, as described in the Start Level Service Specification. If this framework property is not specified, then the start level of this Framework is moved to start level one (1). Any exceptions that occur during bundle starting must be wrapped in aBundleException
and then published as a framework event of typeFrameworkEvent.ERROR
- This Framework's state is set to
Bundle.ACTIVE
. - A framework event of type
FrameworkEvent.STARTED
is fired
- Specified by:
start
in interfaceBundle
- Throws:
BundleException
- If this Framework could not be started.java.lang.SecurityException
- If the caller does not have the appropriateAdminPermission[this,EXECUTE]
, and the Java Runtime Environment supports permissions.- See Also:
- "Start Level Service Specification"
- If this Framework is not in the
-
start
void start(int options) throws BundleException
Start this Framework.Calling this method is the same as calling
start()
. There are no start options for the Framework.- Specified by:
start
in interfaceBundle
- Parameters:
options
- Ignored. There are no start options for the Framework.- Throws:
BundleException
- If this Framework could not be started.java.lang.SecurityException
- If the caller does not have the appropriateAdminPermission[this,EXECUTE]
, and the Java Runtime Environment supports permissions.- See Also:
start()
-
stop
void stop() throws BundleException
Stop this Framework.The method returns immediately to the caller after initiating the following steps to be taken on another thread.
- This Framework's state is set to
Bundle.STOPPING
. - All installed bundles must be stopped without changing each bundle's
persistent autostart setting. If this Framework implements the
optional Start Level Service Specification, then the start level
of this Framework is moved to start level zero (0), as described in the
Start Level Service Specification. Any exceptions that occur
during bundle stopping must be wrapped in a
BundleException
and then published as a framework event of typeFrameworkEvent.ERROR
- Unregister all services registered by this Framework.
- Event handling is disabled.
- This Framework's state is set to
Bundle.RESOLVED
. - All resources held by this Framework are released. This includes threads, bundle class loaders, open files, etc.
- Notify all threads that are waiting at
waitForStop
that the stop operation has completed.
After being stopped, this Framework may be discarded, initialized or started.
- Specified by:
stop
in interfaceBundle
- Throws:
BundleException
- If stopping this Framework could not be initiated.java.lang.SecurityException
- If the caller does not have the appropriateAdminPermission[this,EXECUTE]
, and the Java Runtime Environment supports permissions.- See Also:
- "Start Level Service Specification"
- This Framework's state is set to
-
stop
void stop(int options) throws BundleException
Stop this Framework.Calling this method is the same as calling
stop()
. There are no stop options for the Framework.- Specified by:
stop
in interfaceBundle
- Parameters:
options
- Ignored. There are no stop options for the Framework.- Throws:
BundleException
- If stopping this Framework could not be initiated.java.lang.SecurityException
- If the caller does not have the appropriateAdminPermission[this,EXECUTE]
, and the Java Runtime Environment supports permissions.- See Also:
stop()
-
uninstall
void uninstall() throws BundleException
The Framework cannot be uninstalled.This method always throws a BundleException.
- Specified by:
uninstall
in interfaceBundle
- Throws:
BundleException
- This Framework cannot be uninstalled.java.lang.SecurityException
- If the caller does not have the appropriateAdminPermission[this,LIFECYCLE]
, and the Java Runtime Environment supports permissions.- See Also:
Bundle.stop()
-
update
void update() throws BundleException
Stop and restart this Framework.The method returns immediately to the caller after initiating the following steps to be taken on another thread.
- Specified by:
update
in interfaceBundle
- Throws:
BundleException
- If stopping and restarting this Framework could not be initiated.java.lang.SecurityException
- If the caller does not have the appropriateAdminPermission[this,LIFECYCLE]
, and the Java Runtime Environment supports permissions.- See Also:
Bundle.update(InputStream)
-
update
void update(java.io.InputStream in) throws BundleException
Stop and restart this Framework.Calling this method is the same as calling
update()
except that any provided InputStream is immediately closed.- Specified by:
update
in interfaceBundle
- Parameters:
in
- Any provided InputStream is immediately closed before returning from this method and otherwise ignored.- Throws:
BundleException
- If stopping and restarting this Framework could not be initiated.java.lang.SecurityException
- If the caller does not have the appropriateAdminPermission[this,LIFECYCLE]
, and the Java Runtime Environment supports permissions.- See Also:
Bundle.stop()
,Bundle.start()
-
getBundleId
long getBundleId()
Returns the Framework unique identifier. This Framework is assigned the unique identifier zero (0) since this Framework is also a System Bundle.- Specified by:
getBundleId
in interfaceBundle
- Returns:
- 0.
- See Also:
Bundle.getBundleId()
-
getLocation
java.lang.String getLocation()
Returns the Framework location identifier. This Framework is assigned the unique location "System Bundle
" since this Framework is also a System Bundle.- Specified by:
getLocation
in interfaceBundle
- Returns:
- The string "
System Bundle
". - Throws:
java.lang.SecurityException
- If the caller does not have the appropriateAdminPermission[this,METADATA]
, and the Java Runtime Environment supports permissions.- See Also:
Bundle.getLocation()
,Constants.SYSTEM_BUNDLE_LOCATION
-
getSymbolicName
java.lang.String getSymbolicName()
Returns the symbolic name of this Framework. The symbolic name is unique for the implementation of the framework. However, the symbolic name "system.bundle
" must be recognized as an alias to the implementation-defined symbolic name since this Framework is also a System Bundle.- Specified by:
getSymbolicName
in interfaceBundle
- Returns:
- The symbolic name of this Framework.
- See Also:
Bundle.getSymbolicName()
,Constants.SYSTEM_BUNDLE_SYMBOLICNAME
-
-