Installs a bundle from the specified {@code InputStream} object.
If the specified {@code InputStream} is {@code null}, the Framework must create the {@code InputStream} from which to read the bundle byinterpreting, in an implementation dependent manner, the specified {@code location}.
The specified {@code location} identifier will be used as the identity ofthe bundle. Every installed bundle is uniquely identified by its location identifier which is typically in the form of a URL.
The following steps are required to install a bundle:
- If a bundle containing the same location identifier is already installed, the {@code Bundle} object for that bundle is returned.
- The bundle's content is read from the input stream. If this fails, a {@link BundleException} is thrown.
- The bundle's associated resources are allocated. The associated resources minimally consist of a unique identifier and a persistent storage area if the platform has file system support. If this step fails, a {@code BundleException} is thrown.
- The bundle's state is set to {@code INSTALLED}.
- A bundle event of type {@link BundleEvent#INSTALLED} is fired.
- The {@code Bundle} object for the newly or previously installedbundle is returned.
Postconditions, no exceptions thrown - {@code getState()} in { {@code INSTALLED}, {@code RESOLVED}}.
- Bundle has a unique ID.
Postconditions, when an exception is thrown - Bundle is not installed. If there was an existing bundle for the specified location, then that bundle must still be in the state it was prior to calling this method.
@param location The location identifier of the bundle to install.
@param input The {@code InputStream} object from which this bundle willbe read or {@code null} to indicate the Framework must create theinput stream from the specified location identifier. The input stream must always be closed when this method completes, even if an exception is thrown.
@return The {@code Bundle} object of the installed bundle.
@throws BundleException If the installation failed. BundleException typesthrown by this method include: {@link BundleException#READ_ERROR}, {@link BundleException#DUPLICATE_BUNDLE_ERROR}, {@link BundleException#MANIFEST_ERROR}, and {@link BundleException#REJECTED_BY_HOOK}.
@throws SecurityException If the caller does not have the appropriate{@code AdminPermission[installed bundle,LIFECYCLE]}, and the Java Runtime Environment supports permissions.
@throws IllegalStateException If this BundleContext is no longer valid.