# 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

Fields
Modifier and Type
Field
Description
`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).
`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).

## Method Summary

Modifier and Type
Method
Description
`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(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`
`getTarget(IFile file)`
Returns a handle to a target definition backed by the underlying file.
`ITargetHandle[]`
`getTargets(IProgressMonitor monitor)`
Returns handles to all target definitions known in the workspace.
`ITargetDefinition`
`getWorkspaceTargetDefinition()`
Returns a `ITargetDefinition` that corresponds to the active target platform.
`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(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`
`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`
`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 Details

### 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 Details

### 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.

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

### getWorkspaceTargetDefinition

ITargetDefinition getWorkspaceTargetDefinition() throws CoreException
Returns a `ITargetDefinition` that corresponds to the active target platform. Will return an empty target definition if no target platform has been specified. Will return a target definition based on deprecated preference settings if no target definition has been created before. Will throw a `CoreException` if the backing target file does not exist or if there is a problem reading it.

The returned target definition may have been resolved previously, but this is not guaranteed. It is recommended clients use this method over `getWorkspaceTargetHandle()`.

Returns:
  a target definition corresponding to the active target platform
Throws:
  `CoreException` - if an error occurs loading the workspace target definition
Since:
  3.10 Added in the Luna 4.4 release

### 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:

- STATUS_MISSING_FROM_STATE
- STATUS_MISSING_FROM_TARGET_DEFINITION

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