Eclipse PDE
Release 3.8

org.eclipse.pde.core.target
Interface ITargetPlatformService


public interface ITargetPlatformService

A service to manage target platform definitions available to the workspace.

Since:
3.8
Restriction:
This interface is not intended to be implemented by clients.

Field Summary
static int STATUS_MISSING_FROM_TARGET_DEFINITION
          Status code indicating that a bundle in the current target platform state is not contained in a target definition (a bundle has been deleted from the file system that the target platform does not know about).
static int STATUS_MISSING_FROM_TARGET_PLATFORM
          Status code indicating that a bundle in a target definition is not contained in the current target platform state (a bundle has been added to the file system that the target platform does not know about).
 
Method Summary
 IStatus compareWithTargetPlatform(ITargetDefinition target)
          Returns a status describing whether the given target definition is synchronized with workspace's target platform state.
 void copyTargetDefinition(ITargetDefinition from, ITargetDefinition to)
          Copies all attributes from one target definition to another.
 void deleteTarget(ITargetHandle handle)
          Deletes the target definition associated with the given handle.
 ITargetHandle getTarget(IFile file)
          Returns a handle to a target definition backed by the underlying file.
 ITargetHandle getTarget(String memento)
          Creates and returns a target handle from the given memento.
 ITargetHandle getTarget(URI uri)
          Returns a handle to a target definition backed by the underlying URI.
 ITargetHandle[] getTargets(IProgressMonitor monitor)
          Returns handles to all target definitions known in the workspace.
 ITargetHandle getWorkspaceTargetHandle()
          Returns a handle to the target definition that corresponds to the active target platform or null if none.
 void loadTargetDefinition(ITargetDefinition definition, String targetExtensionId)
          Sets the content of the given target definition based on the target file supplied by an org.eclipse.pde.core.targets extension with the specified identifier.
 ITargetDefinition newDefaultTarget()
          Returns a new target definition with default settings.
 ITargetLocation newDirectoryLocation(String path)
          Creates and returns a target location that contains all bundles in the specified directory which may contain string substitution variables.
 ITargetLocation newFeatureLocation(String home, String featureId, String version)
          Creates and returns a target location that contains all bundles referenced by the feature at the specified location.
 ITargetLocation newIULocation(IInstallableUnit[] units, URI[] repositories, int resolutionFlags)
          Creates and returns a target location that contains all bundles contained in the specified installable units (IU's) in the given repositories.
 ITargetLocation newIULocation(String[] unitIds, String[] versions, URI[] repositories, int resolutionFlags)
          Creates and returns a target location that contains all bundles contained in the specified installable units (IU's) in the given repositories.
 ITargetLocation newProfileLocation(String home, String configurationLocation)
          Creates and returns a target location that contains all bundles installed in a profile at the specified location with the specified configuration area.
 ITargetDefinition newTarget()
          Returns a new target definition to be stored with local metadata.
 void saveTargetDefinition(ITargetDefinition definition)
          Persists the given target definition.
 

Field Detail

STATUS_MISSING_FROM_TARGET_PLATFORM

static final int STATUS_MISSING_FROM_TARGET_PLATFORM
Status code indicating that a bundle in a target definition is not contained in the current target platform state (a bundle has been added to the file system that the target platform does not know about).

See Also:
Constant Field Values

STATUS_MISSING_FROM_TARGET_DEFINITION

static final int STATUS_MISSING_FROM_TARGET_DEFINITION
Status code indicating that a bundle in the current target platform state is not contained in a target definition (a bundle has been deleted from the file system that the target platform does not know about).

See Also:
Constant Field Values
Method Detail

getTargets

ITargetHandle[] getTargets(IProgressMonitor monitor)
Returns handles to all target definitions known in the workspace.

Returns:
handles to all target definitions known in the workspace

getTarget

ITargetHandle getTarget(IFile file)
Returns a handle to a target definition backed by the underlying file. The target definition may or may not exist. If the file does not exist then this is a new target definition which becomes one of the known workspace target definitions when it is saved.

Parameters:
file - target definition file that may or may not exist
Returns:
target handle

getTarget

ITargetHandle getTarget(URI uri)
Returns a handle to a target definition backed by the underlying URI. The target definition may or may not exist. If the URI is valid then this is a new target definition which becomes one of the known external target definitions.

Parameters:
uri - target definition URI that may or may not exist
Returns:
target handle

newTarget

ITargetDefinition newTarget()
Returns a new target definition to be stored with local metadata. The target becomes one of the known workspace target definitions when it is saved.

Returns:
new empty target definition

saveTargetDefinition

void saveTargetDefinition(ITargetDefinition definition)
                          throws CoreException
Persists the given target definition. The target becomes one of known workspace target definitions when it is saved.

The target is persisted in a location determined by its handle. A handle may refer to an IFile or a workspace metadata location. Any existing target definition at the same location is overwritten.

Parameters:
definition - definition to persist
Throws:
CoreException - if unable to persist the definition

deleteTarget

void deleteTarget(ITargetHandle handle)
                  throws CoreException
Deletes the target definition associated with the given handle.

Parameters:
handle - target handle
Throws:
CoreException - if the associated target does not exist or deletion fails

getTarget

ITargetHandle getTarget(String memento)
                        throws CoreException
Creates and returns a target handle from the given memento. The memento must have been generated from ITargetHandle.getMemento().

Parameters:
memento - a target handle memento
Returns:
target handle
Throws:
CoreException - if the target handle format is invalid

newDirectoryLocation

ITargetLocation newDirectoryLocation(String path)
Creates and returns a target location that contains all bundles in the specified directory which may contain string substitution variables.

Parameters:
path - absolute path in the local file system, may contain string variables
Returns:
target location

newProfileLocation

ITargetLocation newProfileLocation(String home,
                                   String configurationLocation)
Creates and returns a target location that contains all bundles installed in a profile at the specified location with the specified configuration area. If a configuration area is not specified the default location is used. The specified home location and configuration location may contain string substitution variables.

Parameters:
home - absolute path in the local file system to the root of an installed profile which may contain string substitution variables
configurationLocation - absolute path in the local file system to the configuration area for the specified installation which may contain string substitution variables or null to use the default location
Returns:
target location

newIULocation

ITargetLocation newIULocation(IInstallableUnit[] units,
                              URI[] repositories,
                              int resolutionFlags)
Creates and returns a target location that contains all bundles contained in the specified installable units (IU's) in the given repositories. If repositories are not specified default repositories are searched (based on user preferences).

Parameters:
units - installable units
repositories - URI's describing repository locations or null to use default repositories
resolutionFlags - bitmask of flags to control IU resolution, possible flags are IUBundleContainer.INCLUDE_ALL_ENVIRONMENTS, IUBundleContainer.INCLUDE_REQUIRED, IUBundleContainer.INCLUDE_SOURCE, IUBundleContainer.INCLUDE_CONFIGURE_PHASE
Returns:
target location

newIULocation

ITargetLocation newIULocation(String[] unitIds,
                              String[] versions,
                              URI[] repositories,
                              int resolutionFlags)
Creates and returns a target location that contains all bundles contained in the specified installable units (IU's) in the given repositories. If repositories are not specified default repositories are searched (based on user preferences).

Parameters:
unitIds - installable unit identifiers
versions - version identifiers
repositories - URI's describing repository locations or null to use default repositories
resolutionFlags - bitmask of flags to control IU resolution, possible flags are IUBundleContainer.INCLUDE_ALL_ENVIRONMENTS, IUBundleContainer.INCLUDE_REQUIRED, IUBundleContainer.INCLUDE_SOURCE, IUBundleContainer.INCLUDE_CONFIGURE_PHASE
Returns:
target location

newFeatureLocation

ITargetLocation newFeatureLocation(String home,
                                   String featureId,
                                   String version)
Creates and returns a target location that contains all bundles referenced by the feature at the specified location. The location is the directory that defines the feature.

Parameters:
home - installation location containing a features directory which may contain string substitution variables
featureId - feature symbolic name
version - feature version identifier or null to use most recent available
Returns:
target location

getWorkspaceTargetHandle

ITargetHandle getWorkspaceTargetHandle()
                                       throws CoreException
Returns a handle to the target definition that corresponds to the active target platform or null if none. If the plug-in registry has not been initialized, this method will initialize it so the workspace target can be set.

Returns:
handle to workspace target platform or null if none
Throws:
CoreException - if an error occurs generating the handle

compareWithTargetPlatform

IStatus compareWithTargetPlatform(ITargetDefinition target)
                                  throws CoreException
Returns a status describing whether the given target definition is synchronized with workspace's target platform state. It is possible that bundles could have been added/removed from the underlying target location storage making the current target platform state out of synch with the contents of the a definition. The given target definition must already be resolved or this method will return null.

An OK status is returned when in synch. A multi-status is returned when there are synchronization issues. Null is returned if the target has not been resolved. Each status contains one of the following codes and the name of the associated bundle as a message:

Parameters:
target - resolved target definition to compare with target platform state
Returns:
status describing whether the target is in synch with target platform state
Throws:
CoreException - if comparison fails

copyTargetDefinition

void copyTargetDefinition(ITargetDefinition from,
                          ITargetDefinition to)
                          throws CoreException
Copies all attributes from one target definition to another.

Parameters:
from - attributes are copied from this definition
to - attributes are copied to this definition
Throws:
CoreException - in copy fails

loadTargetDefinition

void loadTargetDefinition(ITargetDefinition definition,
                          String targetExtensionId)
                          throws CoreException
Sets the content of the given target definition based on the target file supplied by an org.eclipse.pde.core.targets extension with the specified identifier.

Parameters:
definition - target definition to load
targetExtensionId - identifier of a targets extension
Throws:
CoreException - if the extension is not found or an error occurs reading the target file or loading the target definition

newDefaultTarget

ITargetDefinition newDefaultTarget()
Returns a new target definition with default settings. The default target contains all plug-ins and features from the running host. It uses an explicit configuration area if not equal to the default location.

Returns:
a new target definition with default settings

Eclipse PDE
Release 3.8

Guidelines for using Eclipse APIs.

Copyright (c) 2000, 2013 IBM Corporation and others. All rights reserved.