// Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root. package com.yahoo.jdisc.application; import org.osgi.framework.Bundle; import org.osgi.framework.BundleContext; import org.osgi.framework.BundleException; import java.util.Collection; import java.util.List; /** * This is an abstraction of the OSGi framework that hides the actual implementation details. If you need access to * this interface, simply inject it into your Application. In most cases, however, you are better of injecting a * {@link BundleInstaller} since that provides common convenience methods. * * @author Simon Thoresen Hult * @author gjoranv */ public interface OsgiFramework { /** *
Installs a bundle from the specified location. The specified location identifier will be used as the identity
* of the bundle. If a bundle containing the same location identifier is already installed, the Bundle
* object for that bundle is returned. All bundles listed in the {@link OsgiHeader#PREINSTALL_BUNDLE} manifest
* header are also installed. The bundle at index 0 of the returned list matches the bundleLocation
* argument.
NOTE: When this method installs more than one bundle, AND one of those bundles throw an * exception during installation, the bundles installed prior to throwing the exception will remain installed. To * enable the caller to recover from such a situation, this method wraps any thrown exception within a {@link * BundleInstallationException} that contains the list of successfully installed bundles.
* *It would be preferable if this method was exception-safe (that it would roll-back all installed bundles in the
* case of an exception), but that can not be implemented thread-safely since an Application
may choose to
* install bundles concurrently through any available BundleContext
.
privileged
tells the framework whether or not
* privileges are available, and is checked against the {@link OsgiHeader#PRIVILEGED_ACTIVATOR} header of each
* Bundle being started. Any bundle that is a fragment is silently ignored.
*
* @param bundles the bundles to start
* @param privileged whether or not privileges are available
* @throws BundleException if a bundle could not be started. This could be because a code dependency could not
* be resolved or the specified BundleActivator could not be loaded or threw an
* exception.
* @throws SecurityException if the caller does not have the appropriate permissions
* @throws IllegalStateException if this bundle has been uninstalled or this bundle tries to change its own state
*/
void startBundles(Listnull
if it has no valid
* BundleContext.
*
* @return a BundleContext
for the system bundle, or null
* @throws SecurityException if the caller does not have the appropriate permissions
*/
BundleContext bundleContext();
/**
* Returns an iterable collection of all installed bundles. This method returns a list of all bundles installed
* in the OSGi environment at the time of the call to this method. However, since the OsgiFramework is a very
* dynamic environment, bundles can be installed or uninstalled at anytime.
*
* @return an iterable collection of Bundle objects, one object per installed bundle
*/
List