org.eclipse.osgi.service.resolver
Interface State


public interface State

The state of a system as reported by a resolver. This includes all bundles presented to the resolver relative to this state (i.e., both resolved and unresolved).

Clients may implement this interface.

Since:
3.1

Method Summary
 boolean addBundle(BundleDescription description)
          Adds the given bundle to this state.
 void addResolverError(BundleDescription bundle, int type, java.lang.String data, VersionConstraint unsatisfied)
          Adds a new ResolverError for the specified bundle.
 StateDelta compare(State baseState)
          Returns a delta describing the differences between this state and the given state.
 BundleDescription getBundle(long id)
          Returns the bundle descriptor for the bundle with the given id.
 BundleDescription getBundle(java.lang.String symbolicName, Version version)
          Returns the bundle descriptor for the bundle with the given name and version.
 BundleDescription getBundleByLocation(java.lang.String location)
          Returns the bundle descriptor for the bundle with the given location identifier. null is returned if no such bundle is found in this state.
 BundleDescription[] getBundles()
          Returns descriptions for all bundles known to this state.
 BundleDescription[] getBundles(java.lang.String symbolicName)
          Returns all bundle descriptions with the given bundle symbolic name.
 StateDelta getChanges()
          Returns the delta representing the changes from the time this state was first captured until now.
 ExportPackageDescription[] getExportedPackages()
          Returns all exported packages in this state, according to the OSGi rules for resolution.
 StateObjectFactory getFactory()
          Returns the factory that created this state.
 long getHighestBundleId()
          Returns the highest bundle ID.
 java.util.Dictionary[] getPlatformProperties()
          Returns the list of platform properties currently set for this state.
 BundleDescription[] getResolvedBundles()
          Returns descriptions for all bundles currently resolved in this state.
 Resolver getResolver()
          Returns the resolver associated with this state.
 ResolverError[] getResolverErrors(BundleDescription bundle)
          Returns all ResolverErrors for the given bundle
 StateHelper getStateHelper()
          Returns a state helper object.
 ExportPackageDescription[] getSystemPackages()
          Returns the list of system packages which are exported by the system bundle.
 long getTimeStamp()
          Returns the timestamp for this state.
 boolean isEmpty()
          Returns whether this state is empty.
 boolean isResolved()
          Returns true if there have been no modifications to this state since the last time resolve() was called.
 ExportPackageDescription linkDynamicImport(BundleDescription importingBundle, java.lang.String requestedPackage)
          Attempts to find an ExportPackageDescription that will satisfy a dynamic import for the specified requestedPackage for the specified importingBundle.
 boolean removeBundle(BundleDescription bundle)
          Removes the given bundle description.
 BundleDescription removeBundle(long bundleId)
          Removes a bundle description with the given bundle id.
 void removeBundleComplete(BundleDescription bundle)
          Sets the given removal pending bundle to removal complete for this state.
 void removeResolverErrors(BundleDescription bundle)
          Removes all ResolverErrors for the specified bundle.
 StateDelta resolve()
          Same as State.resolve(true);
 StateDelta resolve(boolean incremental)
          Resolves the constraints contained in this state using the resolver currently associated with the state and returns a delta describing the changes in resolved states and dependencies in the state.
 StateDelta resolve(BundleDescription[] discard)
          Resolves the constraints contained in this state using the resolver currently associated with the state in a incremental, "least-perturbing" mode, and returns a delta describing the changes in resolved states and dependencies in the state.
 void resolveBundle(BundleDescription bundle, boolean status, BundleDescription[] hosts, ExportPackageDescription[] selectedExports, BundleDescription[] resolvedRequires, ExportPackageDescription[] resolvedImports)
          Sets whether or not the given bundle is selected in this state.
 void resolveConstraint(VersionConstraint constraint, BaseDescription supplier)
          Resolves the given version constraint with the given supplier.
 void setOverrides(java.lang.Object value)
          Sets the version overrides which are to be applied during the resolutoin of this state.
 boolean setPlatformProperties(java.util.Dictionary platformProperties)
          Sets the platform properties of the state.
 boolean setPlatformProperties(java.util.Dictionary[] platformProperties)
          Sets the platform properties of the state to a list of platform properties.
 void setResolver(Resolver value)
          Sets the resolver associated with this state.
 void setTimeStamp(long newTimeStamp)
          Sets the timestamp for this state
 boolean updateBundle(BundleDescription newDescription)
          Updates an existing bundle description with the given description.
 

Method Detail

addBundle

boolean addBundle(BundleDescription description)
Adds the given bundle to this state.

Parameters:
description - the description to add
Returns:
a boolean indicating whether the bundle was successfully added

compare

StateDelta compare(State baseState)
                   throws BundleException
Returns a delta describing the differences between this state and the given state. The given state is taken as the base so the absence of a bundle in this state is reported as a deletion, etc.

Note that the generated StateDelta will contain BundleDeltas with one of the following types: BundleDelta.ADDED, BundleDelta.REMOVED and BundleDelta.UPDATED

Parameters:
baseState - the base state
Returns:
a delta describing differences between this and the base state state
Throws:
BundleException

removeBundle

BundleDescription removeBundle(long bundleId)
Removes a bundle description with the given bundle id.

Parameters:
bundleId - the id of the bundle description to be removed
Returns:
the removed bundle description, or null, if a bundle with the given id does not exist in this state

removeBundle

boolean removeBundle(BundleDescription bundle)
Removes the given bundle description.

Parameters:
bundle - the bundle description to be removed
Returns:
true, if if the bundle description was removed, false otherwise

updateBundle

boolean updateBundle(BundleDescription newDescription)
Updates an existing bundle description with the given description.

Parameters:
newDescription - the bundle description to replace an existing one
Returns:
true, if if the bundle description was updated, false otherwise

getChanges

StateDelta getChanges()
Returns the delta representing the changes from the time this state was first captured until now.

Returns:
the state delta

getBundles

BundleDescription[] getBundles()
Returns descriptions for all bundles known to this state.

Returns:
the descriptions for all bundles known to this state.

getBundle

BundleDescription getBundle(long id)
Returns the bundle descriptor for the bundle with the given id. null is returned if no such bundle is found in this state.

Returns:
the descriptor for the identified bundle
See Also:
BundleDescription.getBundleId()

getBundle

BundleDescription getBundle(java.lang.String symbolicName,
                            Version version)
Returns the bundle descriptor for the bundle with the given name and version. A null value is returned if no such bundle is found in this state. A resolved bundle is always preferably returned over an unresolved bundle. If multiple bundles with the same resolution state are available, the bundle with the highest version number is returned if the version is null.

Parameters:
symbolicName - symbolic name of the bundle to query
version - version of the bundle to query. null matches any bundle
Returns:
the descriptor for the identified bundle

getBundleByLocation

BundleDescription getBundleByLocation(java.lang.String location)
Returns the bundle descriptor for the bundle with the given location identifier. null is returned if no such bundle is found in this state.

Parameters:
location - location identifier of the bundle to query
Returns:
the descriptor for the identified bundle

getTimeStamp

long getTimeStamp()
Returns the timestamp for this state. This correlates this timestamp to the system state. For example, if the system state timestamp is 4 but then some bundles are installed, the system state timestamp is updated. By comparing 4 to the current system state timestamp it is possible to detect if the states are out of sync.

Returns:
the timestamp of this state

setTimeStamp

void setTimeStamp(long newTimeStamp)
Sets the timestamp for this state

Parameters:
newTimeStamp - the new timestamp for this state

isResolved

boolean isResolved()
Returns true if there have been no modifications to this state since the last time resolve() was called.

Returns:
whether or not this state has changed since last resolved.

resolveConstraint

void resolveConstraint(VersionConstraint constraint,
                       BaseDescription supplier)
Resolves the given version constraint with the given supplier. The given constraint object is destructively modified to reflect its new resolved state. Note that a constraint can be unresolved by passing null for the supplier.

This method is intended to be used by resolvers in the process of determining which constraints are satisfied by which components.

Parameters:
constraint - the version constraint to update
supplier - the supplier which satisfies the constraint. May be null if the constraint is to be unresolved.
Throws:
java.lang.IllegalStateException - if this is not done during a call to resolve

resolveBundle

void resolveBundle(BundleDescription bundle,
                   boolean status,
                   BundleDescription[] hosts,
                   ExportPackageDescription[] selectedExports,
                   BundleDescription[] resolvedRequires,
                   ExportPackageDescription[] resolvedImports)
Sets whether or not the given bundle is selected in this state.

This method is intended to be used by resolvers in the process of determining which constraints are satisfied by which components.

Parameters:
bundle - the bundle to update
status - whether or not the given bundle is resolved, if false the other parameters are ignored
hosts - the host for the resolve fragment, can be null
selectedExports - the selected exported packages for this resolved bundle, can be null
resolvedRequires - the BundleDescriptions that resolve the required bundles for this bundle, can be null
resolvedImports - the exported packages that resolve the imports for this bundle, can be null
Throws:
java.lang.IllegalStateException - if this is not done during a call to resolve

removeBundleComplete

void removeBundleComplete(BundleDescription bundle)
Sets the given removal pending bundle to removal complete for this state.

This method is intended to be used by resolvers in the process of resolving bundles.

Parameters:
bundle - the bundle to set a removal complete.
Throws:
java.lang.IllegalStateException - if this is not done during a call to resolve

addResolverError

void addResolverError(BundleDescription bundle,
                      int type,
                      java.lang.String data,
                      VersionConstraint unsatisfied)
Adds a new ResolverError for the specified bundle.

This method is intended to be used by resolvers in the process of resolving.

Parameters:
bundle - the bundle to add a new ResolverError for
type - the type of ResolverError to add
data - the data for the ResolverError
unsatisfied - the unsatisfied constraint or null if the resolver error was not caused by an unsatisfied constraint.
Throws:
java.lang.IllegalStateException - if this is not done during a call to resolve
Since:
3.2

removeResolverErrors

void removeResolverErrors(BundleDescription bundle)
Removes all ResolverErrors for the specified bundle.

This method is intended to be used by resolvers in the process of resolving.

Parameters:
bundle - the bundle to remove all ResolverErrors for
Throws:
java.lang.IllegalStateException - if this is not done during a call to resolve
Since:
3.2

getResolverErrors

ResolverError[] getResolverErrors(BundleDescription bundle)
Returns all ResolverErrors for the given bundle

Parameters:
bundle - the bundle to get all ResolverErrors for
Returns:
all ResolverErrors for the given bundle
Since:
3.2

getResolver

Resolver getResolver()
Returns the resolver associated with this state. 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.

Returns:
the resolver for this state. null is returned if the state does not have a resolver

setResolver

void setResolver(Resolver value)
Sets the resolver associated with this state. 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 state and the given resovler are properly linked, the following expression must be included in this method if the given resolver (value) is not identical to the result of this.getResolver().

  if (this.getResolver() != value) value.setState(this);
 


resolve

StateDelta resolve(boolean incremental)
Resolves the constraints contained in this state using the resolver currently associated with the state and returns a delta describing the changes in resolved states and dependencies in the state.

Note that this method is typically implemented using

  this.getResolver().resolve();
 
and is the preferred path for invoking resolution. In particular, states should refuse to perform updates (@see #select() and #resolveConstraint()) if they are not currently involved in a resolution cycle.

Note the given state is destructively modified to reflect the results of resolution.

Parameters:
incremental - a flag controlling whether resolution should be incremental
Returns:
a delta describing the changes in resolved state and interconnections

resolve

StateDelta resolve()
Same as State.resolve(true);


resolve

StateDelta resolve(BundleDescription[] discard)
Resolves the constraints contained in this state using the resolver currently associated with the state in a incremental, "least-perturbing" mode, and returns a delta describing the changes in resolved states and dependencies in the state.

Parameters:
discard - an array containing descriptions for bundles whose current resolution state should be forgotten. If null then all the current removal pending BundleDescriptions are refreshed.
Returns:
a delta describing the changes in resolved state and interconnections

setOverrides

void setOverrides(java.lang.Object value)
Sets the version overrides which are to be applied during the resolutoin of this state. Version overrides allow external forces to refine/override the version constraints setup by the components in the state.

Parameters:
value -

getResolvedBundles

BundleDescription[] getResolvedBundles()
Returns descriptions for all bundles currently resolved in this state.

Returns:
the descriptions for all bundles currently resolved in this state.

isEmpty

boolean isEmpty()
Returns whether this state is empty.

Returns:
true if this state is empty, false otherwise

getExportedPackages

ExportPackageDescription[] getExportedPackages()
Returns all exported packages in this state, according to the OSGi rules for resolution.

See Also:
PackageAdmin.getExportedPackages(Bundle)

getBundles

BundleDescription[] getBundles(java.lang.String symbolicName)
Returns all bundle descriptions with the given bundle symbolic name.

Parameters:
symbolicName - symbolic name of the bundles to query
Returns:
the descriptors for all bundles known to this state with the specified symbolic name.

getFactory

StateObjectFactory getFactory()
Returns the factory that created this state.

Returns:
the state object factory that created this state

linkDynamicImport

ExportPackageDescription linkDynamicImport(BundleDescription importingBundle,
                                           java.lang.String requestedPackage)
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.

Parameters:
importingBundle - the BundleDescription that is requesting a dynamic package
requestedPackage - the name of the package that is being requested
Returns:
the ExportPackageDescription that satisfies the dynamic import request; a value of null is returned if none is available.

setPlatformProperties

boolean setPlatformProperties(java.util.Dictionary platformProperties)
Sets the platform properties of the state. The platform properties are used to match platform filters that are specified in Eclipse-PlatformFilter bundle manifest header. The following propreties are supported by the state:

osgi.nl - the platform language setting
osgi.os - the platform operating system
osgi.arch - the platform architecture
osgi.ws - the platform windowing system
org.osgi.framework.system.packages - the packages exported by the system bundle
osgi.resolverMode - the resolver mode. A value of "strict" will set the resolver mode to strict.
org.osgi.framework.executionenvironment - the comma separated list of supported execution environments

The values used for the supported properties can be String type to specify a single value for the property or they can by String[] to specify a list of values for the property.

Parameters:
platformProperties - the platform properties of the state
Returns:
false if the platformProperties specified do not change any of the supported properties already set. If any of the supported property values are changed as a result of calling this method then true is returned.

setPlatformProperties

boolean setPlatformProperties(java.util.Dictionary[] platformProperties)
Sets the platform properties of the state to a list of platform properties. The platform properties are used to match platform filters that are specified in Eclipse-PlatformFilter bundle manifest header.

Parameters:
platformProperties - a set of platform properties for the state
Returns:
false if the platformProperties specified do not change any of the supported properties already set. If any of the supported property values are changed as a result of calling this method then true is returned.
See Also:
for a list of supported properties.

getPlatformProperties

java.util.Dictionary[] getPlatformProperties()
Returns the list of platform properties currently set for this state.

Returns:
the list of platform properties currently set for this state.

getSystemPackages

ExportPackageDescription[] getSystemPackages()
Returns the list of system packages which are exported by the system bundle. The list of system packages is set by the org.osgi.framework.system.packages value in the platform properties for this state.

Returns:
the list of system packages
See Also:
setPlatformProperties(Dictionary)

getStateHelper

StateHelper getStateHelper()
Returns a state helper object. State helpers provide convenience methods for manipulating states.

A possible implementation for this method would provide the same single StateHelper instance to all clients.

Returns:
a state helper
Since:
3.2
See Also:
StateHelper

getHighestBundleId

long getHighestBundleId()
Returns the highest bundle ID. The value -1 is returned if no bundles exist in this state.

Note that this method returns the highest bundle ID the ever existed in this this state object. This bundle may have been removed from the state.

Returns:
the highest bundle ID.
Since:
3.3