Framework
Date: 2016-06-24

org.osgi.framework.launch

## Interface Framework

- All Superinterfaces:
    Bundle, java.lang.Comparable<Bundle>

      @ProviderType
      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.

- - ### 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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `<A> A` | `adapt(java.lang.Class<A> type)` Adapt this Framework to the specified type.
    `java.util.Enumeration<java.net.URL>` | `findEntries(java.lang.String path, java.lang.String filePattern, boolean recurse)` Returns `null` as a framework implementation does not have a proper bundle from which to return entries.
    `long` | `getBundleId()` Returns the Framework unique identifier.
    `java.net.URL` | `getEntry(java.lang.String path)` Returns `null` as a framework implementation does not have a proper bundle from which to return an entry.
    `java.util.Enumeration<java.lang.String>` | `getEntryPaths(java.lang.String path)` Returns `null` as a framework implementation does not have a proper bundle from which to return entry paths.
    `long` | `getLastModified()` Returns the time when the set of bundles in this framework was last modified.
    `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` | `init(FrameworkListener... listeners)` 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

      `getBundleContext, getDataFile, getHeaders, getHeaders, getRegisteredServices, getResource, getResources, getServicesInUse, getSignerCertificates, getState, getVersion, hasPermission, loadClass`

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

- - ### Method Detail

    - #### init

          void init()
                    throws BundleException

      Initialize this Framework.

      This method performs the same function as calling `init(FrameworkListener...)` with no framework listeners.

      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 appropriate `AdminPermission[this,EXECUTE]` or if there is a security manager already installed and the `Constants.FRAMEWORK_SECURITY` configuration property is set.
      See Also:
        `init(FrameworkListener...)`

    - #### init

          void init(FrameworkListener... listeners)
                    throws BundleException

      Initialize this Framework. After calling this method, this Framework must:
      - Have generated a new `framework UUID`.
      - 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, `ConditionalPermissionAdmin`.
      - Be `adaptable` to the OSGi defined types to which a system bundle can be adapted.
      - Have called the `start` method of the extension bundle activator for all resolved extension bundles.

      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` or `Bundle.STOPPING` states.

      All framework events fired by this method method are also delivered to the specified FrameworkListeners in the order they are specified before returning from this method. After returning from this method the specified listeners are no longer notified of framework events.

      Parameters:
        `listeners` - Zero or more listeners to be notified when framework events occur while initializing the framework. The specified listeners do not need to be otherwise registered with the framework. If a specified listener is registered with the framework, it will be notified twice for each framework event.
      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 appropriate `AdminPermission[this,EXECUTE]` or if there is a security manager already installed and the `Constants.FRAMEWORK_SECURITY` configuration property is set.
      Since:
        1.2

    - #### waitForStop

          FrameworkEvent waitForStop(long timeout)
                                     throws java.lang.InterruptedException

      Wait until this Framework has completely stopped. The `stop` and `update` 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 the `Bundle.STARTING`, `Bundle.ACTIVE`, or `Bundle.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 effect.
        - `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:

      1. If this Framework is not in the `Bundle.STARTING` state, `initialize` this Framework.
      2. 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. 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 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 a `BundleException` and then published as a framework event of type `FrameworkEvent.ERROR`
      3. This Framework's state is set to `Bundle.ACTIVE`.
      4. A framework event of type `FrameworkEvent.STARTED` is fired
      Specified by:
        `start` in interface `Bundle`
      Throws:
        `BundleException` - If this Framework could not be started.
        `java.lang.SecurityException` - If the caller does not have the appropriate `AdminPermission[this,EXECUTE]`, and the Java Runtime Environment supports permissions.
      See Also:
        "Start Level Specification"

    - #### 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 interface `Bundle`
      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 appropriate `AdminPermission[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.

      1. This Framework's state is set to `Bundle.STOPPING`.
      2. All installed bundles must be stopped without changing each bundle's persistent autostart setting. The start level of this Framework is moved to start level zero (0), as described in the Start Level Specification. Any exceptions that occur during bundle stopping must be wrapped in a `BundleException` and then published as a framework event of type `FrameworkEvent.ERROR`
      3. Unregister all services registered by this Framework.
      4. Event handling is disabled.
      5. This Framework's state is set to `Bundle.RESOLVED`.
      6. All resources held by this Framework are released. This includes threads, bundle class loaders, open files, etc.
      7. 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 interface `Bundle`
      Throws:
        `BundleException` - If stopping this Framework could not be initiated.
        `java.lang.SecurityException` - If the caller does not have the appropriate `AdminPermission[this,EXECUTE]`, and the Java Runtime Environment supports permissions.
      See Also:
        "Start Level Specification"

    - #### 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 interface `Bundle`
      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 appropriate `AdminPermission[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 interface `Bundle`
      Throws:
        `BundleException` - This Framework cannot be uninstalled.
        `java.lang.SecurityException` - If the caller does not have the appropriate `AdminPermission[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.

      1. Perform the steps in the `stop()` method to stop this Framework.
      2. Perform the steps in the `start()` method to start this Framework.
      Specified by:
        `update` in interface `Bundle`
      Throws:
        `BundleException` - If stopping and restarting this Framework could not be initiated.
        `java.lang.SecurityException` - If the caller does not have the appropriate `AdminPermission[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 interface `Bundle`
      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 appropriate `AdminPermission[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 interface `Bundle`
      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 interface `Bundle`
      Returns:
        The string "`System Bundle`".
      Throws:
        `java.lang.SecurityException` - If the caller does not have the appropriate `AdminPermission[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 interface `Bundle`
      Returns:
        The symbolic name of this Framework.
      See Also:
        `Bundle.getSymbolicName()`, `Constants.SYSTEM_BUNDLE_SYMBOLICNAME`

    - #### getEntryPaths

          java.util.Enumeration<java.lang.String> getEntryPaths(java.lang.String path)

      Returns `null` as a framework implementation does not have a proper bundle from which to return entry paths.
      Specified by:
        `getEntryPaths` in interface `Bundle`
      Parameters:
        `path` - Ignored.
      Returns:
        `null` as a framework implementation does not have a proper bundle from which to return entry paths.

    - #### getEntry

          java.net.URL getEntry(java.lang.String path)

      Returns `null` as a framework implementation does not have a proper bundle from which to return an entry.
      Specified by:
        `getEntry` in interface `Bundle`
      Parameters:
        `path` - Ignored.
      Returns:
        `null` as a framework implementation does not have a proper bundle from which to return an entry.

    - #### getLastModified

          long getLastModified()

      Returns the time when the set of bundles in this framework was last modified. The set of bundles is considered to be modified when a bundle is installed, updated or uninstalled.

      The time value is the number of milliseconds since January 1, 1970, 00:00:00 UTC.

      Specified by:
        `getLastModified` in interface `Bundle`
      Returns:
        The time when the set of bundles in this framework was last modified.

    - #### findEntries

          java.util.Enumeration<java.net.URL> findEntries(java.lang.String path,
                                                        java.lang.String filePattern,
                                                        boolean recurse)

      Returns `null` as a framework implementation does not have a proper bundle from which to return entries.
      Specified by:
        `findEntries` in interface `Bundle`
      Parameters:
        `path` - Ignored.
        `filePattern` - Ignored.
        `recurse` - Ignored.
      Returns:
        `null` as a framework implementation does not have a proper bundle from which to return entries.

    - #### adapt

          <A> A adapt(java.lang.Class<A> type)

      Adapt this Framework to the specified type.

      Adapting this Framework to the specified type may require certain checks, including security checks, to succeed. If a check does not succeed, then this Framework cannot be adapted and `null` is returned. If this Framework is not `initialized`, then `null` is returned if the specified type is one of the OSGi defined types to which a system bundle can be adapted.

      Specified by:
        `adapt` in interface `Bundle`
      Type Parameters:
        `A` - The type to which this Framework is to be adapted.
      Parameters:
        `type` - Class object for the type to which this Framework is to be adapted.
      Returns:
        The object, of the specified type, to which this Framework has been adapted or `null` if this Framework cannot be adapted