bundles/org.eclipse.osgi/core/adaptor/org/eclipse/osgi/service/resolver/StateHelper.java - equinox/rt.equinox.framework - Git at Google

 /*******************************************************************************
  * Copyright (c) 2004, 2009 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.osgi.service.resolver;

 /**
  * A helper class that provides convenience methods for manipulating
  * state objects. <code>PlatformAdmin</code> provides an access point
  * for a state helper.
  * <p>
  * This interface is not intended to be implemented by clients.
  * </p>
  * @since 3.1
  * @see PlatformAdmin#getStateHelper
  * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface StateHelper {
 	/**
 	 * Indicates that access is encouraged to an <code>ExportPackageDescription</code>.
 	 */
 	public static int ACCESS_ENCOURAGED = 0x01;
 	/**
 	 * Indicates that access is discouraged to an <code>ExportPackageDescription</code>.
 	 */
 	public static int ACCESS_DISCOURAGED = 0x02;

 	/**
 	 * An option to include packages available from the execution environment when
 	 * getting the visible packages of a bundle.  For example, when running on a
 	 * J2SE 1.4 VM the system bundle will export the javax.xml.parsers package as part of the
 	 * execution environment.  When this option is used then any packages from the execution
 	 * environment which the bundle is wired to will be included.
 	 * @see StateHelper#getVisiblePackages(BundleDescription, int)
 	 */
 	public static int VISIBLE_INCLUDE_EE_PACKAGES = 0x01;

 	/**
 	 * An option to get all visible packages that a host bundle is currently wired to.  This
 	 * includes packages wired to as a result of a dynamic import and packages wired to as a
 	 * result of additional constraints specified by a fragment bundle.  Using this option
 	 * with a fragment will cause an empty array to be returned.
 	 * @see StateHelper#getVisiblePackages(BundleDescription, int)
 	 * @since 3.6
 	 */
 	public static int VISIBLE_INCLUDE_ALL_HOST_WIRES = 0x02;

 	/**
 	 * Returns all bundles in the state depending on the given bundles. The given bundles
 	 * appear in the returned array.
 	 *
 	 * @param bundles the initial set of bundles
 	 * @return an array containing bundle descriptions for the given roots and all
 	 * bundles in the state that depend on them
 	 */
 	public BundleDescription[] getDependentBundles(BundleDescription[] bundles);

 	/**
 	 * Returns all the prerequisite bundles in the state for the given bundles.  The given
 	 * bundles appear in the returned array.
 	 * @param bundles the inital set of bundles
 	 * @return an array containing bundle descriptions for the given leaves and their
 	 * prerequisite bundles in the state.
 	 * @since 3.2
 	 */
 	public BundleDescription[] getPrerequisites(BundleDescription[] bundles);

 	/**
 	 * Returns all unsatisfied constraints in the given bundle. Returns an
 	 * empty array if no unsatisfied constraints can be found.
 	 * <p>
 	 * Note that a bundle may have no unsatisfied constraints and still not be
 	 * resolved.
 	 * </p>
 	 *
 	 * @param bundle the bundle to examine
 	 * @return an array containing all unsatisfied constraints for the given bundle
 	 */
 	public VersionConstraint[] getUnsatisfiedConstraints(BundleDescription bundle);

 	/**
 	 * Returns all unsatisfied constraints in the given bundles that have no possible supplier.
 	 * Returns an empty array if no unsatisfied leaf constraints can be found.
 	 * <p>
 	 * The returned constraints include only the unsatisfied constraints in the given
 	 * state that have no possible supplier (leaf constraints).  There may
 	 * be additional unsatisfied constraints in the given bundles but these will have at
 	 * least one possible supplier.  In this case the possible supplier of the constraint
 	 * is not resolved for some reason.  For example, a given state only has Bundles X and Y
 	 * installed and Bundles X and Y have the following constraints:
 	 * </p>
 	 * <pre>
 	 * Bundle X requires Bundle Y
 	 * Bundle Y requires Bundle Z</pre>
 	 * <p>
 	 * In this case Bundle Y has an unsatisfied constraint leaf on Bundle Z.  This will
 	 * cause Bundle X's constraint on Bundle Y to be unsatisfied as well because the
 	 * bundles are involved in a dependency chain.  Bundle X's constraint on Bundle Y is
 	 * not considered a leaf because there is a possible supplier Y in the given state.
 	 * </p>
 	 * <p>
 	 * Note that a bundle may have no unsatisfied constraints and still not be
 	 * resolved.
 	 * </p>
 	 *
 	 * @param bundles the bundles to examine
 	 * @return an array containing all unsatisfied leaf constraints for the given bundles
 	 * @since 3.2
 	 */
 	public VersionConstraint[] getUnsatisfiedLeaves(BundleDescription[] bundles);

 	/**
 	 * Returns whether the given package specification constraint is resolvable.
 	 * A package specification constraint may be
 	 * resolvable but not resolved, which means that the bundle that provides
 	 * it has not been resolved for some other reason (e.g. another constraint
 	 * could not be resolved, another version has been picked, etc).
 	 *
 	 * @param specification the package specification constraint to be examined
 	 * @return <code>true</code> if the constraint can be resolved,
 	 * <code>false</code> otherwise
 	 */
 	public boolean isResolvable(ImportPackageSpecification specification);

 	/**
 	 * Returns whether the given bundle specification constraint is resolvable.
 	 * A bundle specification constraint may be
 	 * resolvable but not resolved, which means that the bundle that provides
 	 * it has not been resolved for some other reason (e.g. another constraint
 	 * could not be resolved, another version has been picked, etc).
 	 *
 	 * @param specification the bundle specification constraint to be examined
 	 * @return <code>true</code> if the constraint can be resolved,
 	 * <code>false</code> otherwise
 	 */
 	public boolean isResolvable(BundleSpecification specification);

 	/**
 	 * Returns whether the given host specification constraint is resolvable.
 	 * A host specification constraint may be
 	 * resolvable but not resolved, which means that the bundle that provides
 	 * it has not been resolved for some other reason (e.g. another constraint
 	 * could not be resolved, another version has been picked, etc).
 	 *
 	 * @param specification the host specification constraint to be examined
 	 * @return <code>true</code> if the constraint can be resolved,
 	 * <code>false</code> otherwise
 	 */
 	public boolean isResolvable(HostSpecification specification);

 	/**
 	 * Sorts the given array of <strong>resolved</strong> bundles in pre-requisite order. If A
 	 * requires B, A appears after B.
 	 * Fragments will appear after all of their hosts. Constraints contributed by fragments will
 	 * be treated as if contributed by theirs hosts, affecting their position. This is true even if
 	 * the fragment does not appear in the given bundle array.
 	 * <p>
 	 * Unresolved bundles are ignored.
 	 * </p>
 	 *
 	 * @param toSort an array of bundles to be sorted
 	 * @return any cycles found
 	 */
 	public Object[][] sortBundles(BundleDescription[] toSort);

 	/**
 	 * Returns a list of all packages that the specified bundle has access to which are
 	 * exported by other bundles.
 	 * <p>
 	 * Same as calling getVisiblePackages(bundle, 0)
 	 * </p>
 	 * @param bundle a bundle to get the list of packages for.
 	 * @return a list of all packages that the specified bundle has access to which are
 	 * exported by other bundles.
 	 */
 	public ExportPackageDescription[] getVisiblePackages(BundleDescription bundle);

 	/**
 	 * Returns a list of all packages that the specified bundle has access to which are
 	 * exported by other bundles.  This takes into account all constraint specifications
 	 * (Import-Package, Require-Bundle etc).  A deep dependency search is done for all
 	 * packages which are available through the required bundles and any bundles which
 	 * are reexported.  This method also takes into account all directives
 	 * which may be specified on the constraint specifications (e.g. uses, x-friends etc.)
 	 *
 	 * @param bundle a bundle to get the list of packages for.
 	 * @param options the options for selecting the visible packages
 	 * @return a list of all packages that the specified bundle has access to which are
 	 * exported by other bundles.
 	 * @see StateHelper#VISIBLE_INCLUDE_EE_PACKAGES
 	 * @see StateHelper#VISIBLE_INCLUDE_ALL_HOST_WIRES
 	 * @since 3.3
 	 */
 	public ExportPackageDescription[] getVisiblePackages(BundleDescription bundle, int options);

 	/**
 	 * Returns the access code that the specified <code>BundleDescription</code> has to the
 	 * specified <code>ExportPackageDescription</code>.
 	 * @param bundle the bundle to find the access code for
 	 * @param export the export to find the access code for
 	 * @return the access code to the export.
 	 * @see StateHelper#ACCESS_ENCOURAGED
 	 * @see StateHelper#ACCESS_DISCOURAGED
 	 */
 	public int getAccessCode(BundleDescription bundle, ExportPackageDescription export);
 }
	/*******************************************************************************
	* Copyright (c) 2004, 2009 IBM Corporation and others.
	* All rights reserved. This program and the accompanying materials
	* are made available under the terms of the Eclipse Public License v1.0
	* which accompanies this distribution, and is available at
	* http://www.eclipse.org/legal/epl-v10.html
	*
	* Contributors:
	* IBM Corporation - initial API and implementation
	*******************************************************************************/
	package org.eclipse.osgi.service.resolver;

	/**
	* A helper class that provides convenience methods for manipulating
	* state objects. <code>PlatformAdmin</code> provides an access point
	* for a state helper.
	* <p>
	* This interface is not intended to be implemented by clients.
	* </p>
	* @since 3.1
	* @see PlatformAdmin#getStateHelper
	* @noimplement This interface is not intended to be implemented by clients.
	*/
	public interface StateHelper {
	/**
	* Indicates that access is encouraged to an <code>ExportPackageDescription</code>.
	*/
	public static int ACCESS_ENCOURAGED = 0x01;
	/**
	* Indicates that access is discouraged to an <code>ExportPackageDescription</code>.
	*/
	public static int ACCESS_DISCOURAGED = 0x02;

	/**
	* An option to include packages available from the execution environment when
	* getting the visible packages of a bundle. For example, when running on a
	* J2SE 1.4 VM the system bundle will export the javax.xml.parsers package as part of the
	* execution environment. When this option is used then any packages from the execution
	* environment which the bundle is wired to will be included.
	* @see StateHelper#getVisiblePackages(BundleDescription, int)
	*/
	public static int VISIBLE_INCLUDE_EE_PACKAGES = 0x01;

	/**
	* An option to get all visible packages that a host bundle is currently wired to. This
	* includes packages wired to as a result of a dynamic import and packages wired to as a
	* result of additional constraints specified by a fragment bundle. Using this option
	* with a fragment will cause an empty array to be returned.
	* @see StateHelper#getVisiblePackages(BundleDescription, int)
	* @since 3.6
	*/
	public static int VISIBLE_INCLUDE_ALL_HOST_WIRES = 0x02;

	/**
	* Returns all bundles in the state depending on the given bundles. The given bundles
	* appear in the returned array.
	*
	* @param bundles the initial set of bundles
	* @return an array containing bundle descriptions for the given roots and all
	* bundles in the state that depend on them
	*/
	public BundleDescription[] getDependentBundles(BundleDescription[] bundles);

	/**
	* Returns all the prerequisite bundles in the state for the given bundles. The given
	* bundles appear in the returned array.
	* @param bundles the inital set of bundles
	* @return an array containing bundle descriptions for the given leaves and their
	* prerequisite bundles in the state.
	* @since 3.2
	*/
	public BundleDescription[] getPrerequisites(BundleDescription[] bundles);

	/**
	* Returns all unsatisfied constraints in the given bundle. Returns an
	* empty array if no unsatisfied constraints can be found.
	* <p>
	* Note that a bundle may have no unsatisfied constraints and still not be
	* resolved.
	* </p>
	*
	* @param bundle the bundle to examine
	* @return an array containing all unsatisfied constraints for the given bundle
	*/
	public VersionConstraint[] getUnsatisfiedConstraints(BundleDescription bundle);

	/**
	* Returns all unsatisfied constraints in the given bundles that have no possible supplier.
	* Returns an empty array if no unsatisfied leaf constraints can be found.
	* <p>
	* The returned constraints include only the unsatisfied constraints in the given
	* state that have no possible supplier (leaf constraints). There may
	* be additional unsatisfied constraints in the given bundles but these will have at
	* least one possible supplier. In this case the possible supplier of the constraint
	* is not resolved for some reason. For example, a given state only has Bundles X and Y
	* installed and Bundles X and Y have the following constraints:
	* </p>
	* <pre>
	* Bundle X requires Bundle Y
	* Bundle Y requires Bundle Z</pre>
	* <p>
	* In this case Bundle Y has an unsatisfied constraint leaf on Bundle Z. This will
	* cause Bundle X's constraint on Bundle Y to be unsatisfied as well because the
	* bundles are involved in a dependency chain. Bundle X's constraint on Bundle Y is
	* not considered a leaf because there is a possible supplier Y in the given state.
	* </p>
	* <p>
	* Note that a bundle may have no unsatisfied constraints and still not be
	* resolved.
	* </p>
	*
	* @param bundles the bundles to examine
	* @return an array containing all unsatisfied leaf constraints for the given bundles
	* @since 3.2
	*/
	public VersionConstraint[] getUnsatisfiedLeaves(BundleDescription[] bundles);

	/**
	* Returns whether the given package specification constraint is resolvable.
	* A package specification constraint may be
	* resolvable but not resolved, which means that the bundle that provides
	* it has not been resolved for some other reason (e.g. another constraint
	* could not be resolved, another version has been picked, etc).
	*
	* @param specification the package specification constraint to be examined
	* @return <code>true</code> if the constraint can be resolved,
	* <code>false</code> otherwise
	*/
	public boolean isResolvable(ImportPackageSpecification specification);

	/**
	* Returns whether the given bundle specification constraint is resolvable.
	* A bundle specification constraint may be
	* resolvable but not resolved, which means that the bundle that provides
	* it has not been resolved for some other reason (e.g. another constraint
	* could not be resolved, another version has been picked, etc).
	*
	* @param specification the bundle specification constraint to be examined
	* @return <code>true</code> if the constraint can be resolved,
	* <code>false</code> otherwise
	*/
	public boolean isResolvable(BundleSpecification specification);

	/**
	* Returns whether the given host specification constraint is resolvable.
	* A host specification constraint may be
	* resolvable but not resolved, which means that the bundle that provides
	* it has not been resolved for some other reason (e.g. another constraint
	* could not be resolved, another version has been picked, etc).
	*
	* @param specification the host specification constraint to be examined
	* @return <code>true</code> if the constraint can be resolved,
	* <code>false</code> otherwise
	*/
	public boolean isResolvable(HostSpecification specification);

	/**
	* Sorts the given array of <strong>resolved</strong> bundles in pre-requisite order. If A
	* requires B, A appears after B.
	* Fragments will appear after all of their hosts. Constraints contributed by fragments will
	* be treated as if contributed by theirs hosts, affecting their position. This is true even if
	* the fragment does not appear in the given bundle array.
	* <p>
	* Unresolved bundles are ignored.
	* </p>
	*
	* @param toSort an array of bundles to be sorted
	* @return any cycles found
	*/
	public Object[][] sortBundles(BundleDescription[] toSort);

	/**
	* Returns a list of all packages that the specified bundle has access to which are
	* exported by other bundles.
	* <p>
	* Same as calling getVisiblePackages(bundle, 0)
	* </p>
	* @param bundle a bundle to get the list of packages for.
	* @return a list of all packages that the specified bundle has access to which are
	* exported by other bundles.
	*/
	public ExportPackageDescription[] getVisiblePackages(BundleDescription bundle);

	/**
	* Returns a list of all packages that the specified bundle has access to which are
	* exported by other bundles. This takes into account all constraint specifications
	* (Import-Package, Require-Bundle etc). A deep dependency search is done for all
	* packages which are available through the required bundles and any bundles which
	* are reexported. This method also takes into account all directives
	* which may be specified on the constraint specifications (e.g. uses, x-friends etc.)
	*
	* @param bundle a bundle to get the list of packages for.
	* @param options the options for selecting the visible packages
	* @return a list of all packages that the specified bundle has access to which are
	* exported by other bundles.
	* @see StateHelper#VISIBLE_INCLUDE_EE_PACKAGES
	* @see StateHelper#VISIBLE_INCLUDE_ALL_HOST_WIRES
	* @since 3.3
	*/
	public ExportPackageDescription[] getVisiblePackages(BundleDescription bundle, int options);

	/**
	* Returns the access code that the specified <code>BundleDescription</code> has to the
	* specified <code>ExportPackageDescription</code>.
	* @param bundle the bundle to find the access code for
	* @param export the export to find the access code for
	* @return the access code to the export.
	* @see StateHelper#ACCESS_ENCOURAGED
	* @see StateHelper#ACCESS_DISCOURAGED
	*/
	public int getAccessCode(BundleDescription bundle, ExportPackageDescription export);
	}