org.eclipse.osgi.service.resolver.Resolver Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.osgi Show documentation
This is org.eclipse.osgi jar used by Scout SDK
There is a newer version: 3.11.0.v20160603-1336
/*******************************************************************************
 * Copyright (c) 2003, 2012 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;

import java.util.Comparator;
import java.util.Dictionary;

/**
 * An implementation of a resolver which resolves the constraints of the bundles
 * in a system.
 * 
 * Clients may implement this interface.
 * 
 * @since 3.1
 */
public interface Resolver {

	/**
	 * Resolves the state associated with this resolver and returns an array of
	 * bundle deltas describing the changes.. The state and version bindings
	 * for the various bundles and packages in this state are updated and a
	 * array containing bundle deltas describing the changes returned.
	 * 
	 * This method is intended to be called only by State objects in response
	 * to a user invocation of State.resolve(). States will typically refuse to
	 * update their constituents (see State.resolveBundle() and
	 * State.resolveConstraint()) if their resolve method is not currently
	 * being invoked.
	 * 
	 * 
	 * Note the given state is destructively modified to reflect the results of
	 * resolution.
	 * 
	 * @param discard the list of bundles to discard the resolve status and 
	 * reresolve.  A null value indicates that all currently unresolved
	 * bundles in the state should be resolved.
	 * @param platformProperties the platform properties used to match platform filters
	 * against.  A null value indicates that the system properties should
	 * be used to match against
	 */
	public void resolve(BundleDescription[] discard, Dictionary[] platformProperties);

	/**
	 * Flushes this resolver of any stored/cached data it may be keeping to
	 * facilitate incremental processing on its associated state. This is
	 * typicaly used when switching the resolver's state object.
	 */
	public void flush();

	/**
	 * Returns the state associated with this resolver. A state can work with
	 * at most one resolver at any given time. Similarly, a resolver can work
	 * with at most one state at a time.
	 * 
	 * @return the state for this resolver. null is returned if the resolver
	 * does not have a state
	 */
	public State getState();

	/**
	 * Sets the state associated with this resolver. A state can work with at
	 * most one resolver at any given time. Similarly, a resolver can work with
	 * at most one state at a time.
	 * 
	 * To ensure that this resolver and the given state are properly linked,
	 * the following expression must be included in this method if the given
	 * state (value) is not identical to the result of this.getState().
	 * 
	 * 
	 * 	 *  if (this.getState() != value) value.setResolver(this);
	 * 
	 */
	public void setState(State value);

	/**
	 * Notifies the resolver a bundle has been added to the state.
	 * @param bundle
	 */
	public void bundleAdded(BundleDescription bundle);

	/**
	 * Notifies the resolver a bundle has been removed from the state.
	 * @param bundle the bundle description to remove
	 * @param pending indicates if the bundle to be remove has current dependents and
	 * will pend complete removal until the bundle has been re-resolved.
	 */
	public void bundleRemoved(BundleDescription bundle, boolean pending);

	/**
	 * Notifies the resolver a bundle has been updated in the state.
	 * @param newDescription the new description
	 * @param existingDescription the existing description
	 * @param pending indicates if the bundle to be updated has current dependents and
	 * will pend complete removal until the bundle has been re-resolved.
	 */
	public void bundleUpdated(BundleDescription newDescription, BundleDescription existingDescription, boolean pending);

	/**
	 * Attempts to find an ExportPackageDescription that will satisfy a dynamic import
	 * for the specified requestedPackage for the specified importingBundle.  If no
	 * ExportPackageDescription is available that satisfies a dynamic import for the 
	 * importingBundle then null is returned.
	 * @param importingBundle the BundleDescription that is requesting a dynamic package
	 * @param requestedPackage the name of the package that is being requested
	 * @return the ExportPackageDescription that satisfies the dynamic import request; 
	 * a value of null is returned if none is available.
	 */
	public ExportPackageDescription resolveDynamicImport(BundleDescription importingBundle, String requestedPackage);

	/**
	 * Sets the selection policy for this resolver.  A selection policy is used to sort 
	 * possible suppliers of a version constraint in descending order.  That is an order
	 * which is from most desired to least desired.  The objects passed to the 
	 * selection policy {@link Comparator#compare(Object, Object)} method 
	 * will be of type {@link BaseDescription}.  The selection policy should return a 
	 * negative number, zero, or a positive number depending on if the first object is 
	 * more desired, equal amount of desire, or less desired than the second object respectively.
	 * 
	 * If no selection policy is set then a default policy will be used which sorts according
	 * to the following rules: 
	 * 

	 *  The resolution status of the bundle which supplies the base description.  Resolved bundles take priority over unresolved ones.
	 * 
 The version of the base description.  Higher versions take priority over lower versions.
	 * 
 The bundle ID which supplies the base description.  Lower IDs take priority over higher IDs. 
	 * 
	 * @param selectionPolicy the selection policy for this resolver
	 * @since 3.2
	 */
	public void setSelectionPolicy(Comparator selectionPolicy);

	/**
	 * Returns the selection policy for this resolver or null if it is not set 
	 * @return the selection policy for this resolver or null if it is not set
	 * @since 3.2 
	 */
	public Comparator getSelectionPolicy();
}