/*
 * 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);
}