/*
* Copyright (c) OSGi Alliance (2001, 2013). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.framework.wiring;
import java.util.Collection;
import org.osgi.annotation.versioning.ProviderType;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleReference;
import org.osgi.framework.FrameworkListener;
import org.osgi.resource.Requirement;
/**
* Query and modify wiring information for the framework. The framework wiring
* object for the framework can be obtained by calling
* {@link Bundle#adapt(Class) bundle.adapt(FrameworkWiring.class)} on the system
* bundle. Only the system bundle can be adapted to a FrameworkWiring object.
*
* <p>
* The system bundle associated with this FrameworkWiring object can be obtained
* by calling {@link BundleReference#getBundle()}.
*
* @ThreadSafe
* @author $Id: 1ab9112badc94f802ccda966f7b73584f2a5c412 $
*/
@ProviderType
public interface FrameworkWiring extends BundleReference {
/**
* Refreshes the specified bundles. This forces the update (replacement) or
* removal of packages exported by the specified bundles.
*
* <p>
* The technique by which the framework refreshes bundles may vary among
* different framework implementations. A permissible implementation is to
* stop and restart the framework.
*
* <p>
* This method returns to the caller immediately and then performs the
* following steps on a separate thread:
*
* <ol>
* <li>Compute the {@link #getDependencyClosure(Collection) dependency
* closure} of the specified bundles. If no bundles are specified, compute
* the dependency closure of the {@link #getRemovalPendingBundles() removal
* pending} bundles.</li>
* <li>Each bundle in the dependency closure that is in the {@code ACTIVE}
* state will be stopped as described in the {@code Bundle.stop} method.</li>
* <li>Each bundle in the dependency closure that is in the {@code RESOLVED}
* state is unresolved and thus moved to the {@code INSTALLED} state. The
* effect of this step is that bundles in the dependency closure are no
* longer {@code RESOLVED}.</li>
* <li>Each bundle in the dependency closure that is in the
* {@code UNINSTALLED} state is removed from the dependency closure and is
* now completely removed from the Framework.</li>
* <li>Each bundle in the dependency closure that was in the {@code ACTIVE}
* state prior to Step 2 is started as described in the {@code Bundle.start}
* method, causing all bundles required for the restart to be resolved. It
* is possible that, as a result of the previous steps, packages that were
* previously exported no longer are. Therefore, some bundles may be
* unresolvable until bundles satisfying the dependencies have been
* installed in the Framework.</li>
* </ol>
*
* <p>
* For any exceptions that are thrown during any of these steps, a framework
* event of type {@code FrameworkEvent.ERROR} is fired containing the
* exception. The source bundle for these events should be the specific
* bundle to which the exception is related. If no specific bundle can be
* associated with the exception then the System Bundle must be used as the
* source bundle for the event. All framework events fired by this method
* are also delivered to the specified {@code FrameworkListener}s in the
* order they are specified.
*
* <p>
* When this process completes after the bundles are refreshed, the
* Framework will fire a Framework event of type
* {@code FrameworkEvent.PACKAGES_REFRESHED} to announce it has completed
* the bundle refresh. The specified {@code FrameworkListener}s are notified
* in the order specified. Each specified {@code FrameworkListener} will be
* called with a Framework event of type
* {@code FrameworkEvent.PACKAGES_REFRESHED}.
*
* @param bundles The bundles to be refreshed, or {@code null} to refresh
* the {@link #getRemovalPendingBundles() removal pending} bundles.
* @param listeners Zero or more listeners to be notified when the bundle
* refresh has been completed. The specified listeners do not need to
* be otherwise registered with the framework. If a specified
* listener is already registered with the framework, it will be
* notified twice.
* @throws IllegalArgumentException If the specified {@code Bundle}s were
* not created by the same framework instance associated with this
* FrameworkWiring.
* @throws SecurityException If the caller does not have
* {@code AdminPermission[System Bundle,RESOLVE]} and the Java
* runtime environment supports permissions.
*/
void refreshBundles(Collection<Bundle> bundles, FrameworkListener... listeners);
/**
* Resolves the specified bundles. The Framework must attempt to resolve the
* specified bundles that are unresolved. Additional bundles that are not
* included in the specified bundles may be resolved as a result of calling
* this method. A permissible implementation of this method is to attempt to
* resolve all unresolved bundles installed in the framework.
*
* <p>
* If no bundles are specified, then the Framework will attempt to resolve
* all unresolved bundles. This method must not cause any bundle to be
* refreshed, stopped, or started. This method will not return until the
* operation has completed.
*
* @param bundles The bundles to resolve or {@code null} to resolve all
* unresolved bundles installed in the Framework.
* @return {@code true} if all specified bundles are resolved; {@code false}
* otherwise.
* @throws IllegalArgumentException If the specified {@code Bundle}s were
* not created by the same framework instance associated with this
* FrameworkWiring.
* @throws SecurityException If the caller does not have
* {@code AdminPermission[System Bundle,RESOLVE]} and the Java
* runtime environment supports permissions.
*/
boolean resolveBundles(Collection<Bundle> bundles);
/**
* Returns the bundles that have {@link BundleWiring#isCurrent()
* non-current}, {@link BundleWiring#isInUse() in use} bundle wirings. This
* is typically the bundles which have been updated or uninstalled since the
* last call to {@link #refreshBundles(Collection, FrameworkListener...)}.
*
* @return A collection containing a snapshot of the {@code Bundle}s which
* have non-current, in use {@code BundleWiring}s, or an empty
* collection if there are no such bundles.
*/
Collection<Bundle> getRemovalPendingBundles();
/**
* Returns the dependency closure for the specified bundles.
*
* <p>
* 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 {@code UNINSTALLED} bundles that are
* {@link #getRemovalPendingBundles() removal pending}.
*
* @param bundles The initial bundles for which to generate the dependency
* closure.
* @return A collection containing a snapshot of the dependency closure of
* the specified bundles, or an empty collection if there were no
* specified bundles.
* @throws IllegalArgumentException If the specified {@code Bundle}s were
* not created by the same framework instance associated with this
* FrameworkWiring.
*/
Collection<Bundle> getDependencyClosure(Collection<Bundle> bundles);
/**
* Find bundle capabilities that match the given requirement.
*
* <p>
* The returned collection contains {@link BundleCapability} objects where
* the revision must be the {@link BundleCapability#getRevision() declaring
* revision} of the capability and the revision must either be the current
* bundle revision or an {@link BundleWiring#isInUse() in use} bundle
* revision.
*
* <p>
* Each returned capability must match the given requirement. This means
* that the filter in the requirement must match as well as any namespace
* specific directives. For example, the mandatory attributes for the
* osgi.wiring.package namespace.
*
* <p>
* The returned collection has not been filtered to remove capabilities that
* are non-effective, substituted or for which the providing bundle does not
* have permission to provide. No resolve hooks are called to filter
* matching capabilities.
*
* @param requirement The requirement to find matching bundle capabilities.
* Must not be {@code null}.
* @return A collection of {@link BundleCapability} objects that match the
* specified requirement.
* @since 1.2
*/
Collection<BundleCapability> findProviders(Requirement requirement);
}