Eclipse PDE
Release 3.6

org.eclipse.pde.core.project
Interface IBundleProjectDescription


public interface IBundleProjectDescription

Describes a project representing an OSGi bundle. Used to create or modify artifacts associated with a bundle project. A bundle project description can be created for an IProject via IBundleProjectService.getDescription(IProject).

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

Field Summary
static String PLUGIN_NATURE
          Constant for the PDE Plug-in project nature, value is "org.eclipse.pde.PluginNature".
static String VERSION_3_0
          Identifies bundles developed for Eclipse 3.0, value is "3.0".
static String VERSION_3_1
          Identifies bundles developed for Eclipse 3.1, value is "3.1".
static String VERSION_3_2
          Identifies bundles developed for Eclipse 3.2, value is "3.2".
static String VERSION_3_3
          Identifies bundles developed for Eclipse 3.3, value is "3.3".
static String VERSION_3_4
          Identifies bundles developed for Eclipse 3.4, value is "3.4".
static String VERSION_3_5
          Identifies bundles developed for Eclipse 3.5, value is "3.5".
static String VERSION_3_6
          Identifies bundles developed for Eclipse 3.6, value is "3.6".
 
Method Summary
 void apply(IProgressMonitor monitor)
          Creates or modifies a bundle project and associated artifacts based current settings.
 String getActivationPolicy()
          Returns this bundle's activation policy or null if unspecified.
 String getActivator()
          Returns the value of the Bundle-Activator header for the described bundle, or null if none.
 IPath[] getBinIncludes()
          Returns the file and folder entries to be included on the bin.includes entry of the build.properties file of the described bundle project.
 IBundleClasspathEntry[] getBundleClasspath()
          Returns the entries on the Bundle-Classpath header of the described bundle, or null if unspecified.
 String getBundleName()
          Returns the value of the Bundle-Name header for the described bundle or null if unspecified.
 IPath getBundleRoot()
          Returns the location within the project that is the root of the bundle related artifacts, or null to indicate the default location (project folder).
 String getBundleVendor()
          Returns the value of the Bundle-Vendor header for the described bundle or null if unspecified.
 Version getBundleVersion()
          Returns the value of the Bundle-Version header for the described bundle.
 IPath getDefaultOutputFolder()
          Returns a project relative path for the described bundle's default output folder used on the Java build path, or null to indicate the default output location is used.
 String[] getExecutionEnvironments()
          Returns the required execution environments for the described bundle, or null if unspecified.
 String getExportWizardId()
          Returns the identifier of the org.eclipse.ui.exportWizards extension used in the manifest editor for exporting the project associated with these settings, or null if the default export wizard should be used.
 String getHeader(String header)
          Returns the value of the specified header from the bundle manifest, or null if unspecified.
 IHostDescription getHost()
          Returns the host bundle for the described fragment, or null if this description does not describe a fragment.
 String[] getLaunchShortcuts()
          Returns identifiers of org.eclipse.debug.ui.launchShortcuts referenced by org.eclipse.pde.ui.launchShortcuts extensions that will be displayed in the manifest editor for the project associated with these settings, or null if default shortcuts are being used.
 IPath getLocalization()
          Returns the value of the Bundle-Localization header for the described bundle or null if unspecified.
 URI getLocationURI()
          Returns the location URI for the described project.
 String[] getNatureIds()
          Returns the list of natures associated with the described project.
 IPackageExportDescription[] getPackageExports()
          Returns the value of the Export-Package header or null if unspecified.
 IPackageImportDescription[] getPackageImports()
          Returns the value of the Import-Package header or null if unspecified.
 IProject getProject()
          Returns the project associated with the described bundle.
 IRequiredBundleDescription[] getRequiredBundles()
          Returns the value of the Require-Bundle header or null if unspecified.
 String getSymbolicName()
          Returns the symbolic name of the described bundle or null if unspecified.
 String getTargetVersion()
          Returns the version of Eclipse the described bundle is targeted for, or null if unspecified.
 boolean hasNature(String natureId)
          Returns whether the project nature specified by the given nature extension id has been added to the described project.
 boolean isEquinox()
          Returns whether the described bundle is targeted for the Equinox OSGi framework.
 boolean isExtensionRegistry()
          Returns whether this bundle supports extension points and extensions via IExtensionRegistry support.
 boolean isSingleton()
          Returns whether the described bundle is a singleton.
 void setActivationPolicy(String policy)
          Sets this bundle's activation policy.
 void setActivator(String className)
          Sets the value of the Bundle-Activator header for the described bundle, or null if none.
 void setBinIncludes(IPath[] paths)
          Sets file and folder entries on the bin.includes entry of the build.properties file of the described bundle project.
 void setBundleClassath(IBundleClasspathEntry[] entries)
          Sets the entries for the Bundle-Classpath header of the described bundle, or null if unspecified.
 void setBundleName(String name)
          Sets the value of the Bundle-Name header for the described bundle.
 void setBundleRoot(IPath path)
          Sets the location within the project where the root of the bundle and its associated artifacts will reside, or null to indicate the default bundle root location should be used (project folder).
 void setBundleVendor(String name)
          Sets the value of the Bundle-Vendor header for the described bundle.
 void setBundleVersion(Version version)
          Sets the value of the Bundle-Version header for the described bundle.
 void setDefaultOutputFolder(IPath output)
          Sets a project relative path for the default output folder used on the Java build path for the described bundle.
 void setEquinox(boolean equinox)
          Sets whether the described bundle is targeted for the Equinox OSGi framework.
 void setExecutionEnvironments(String[] environments)
          Sets the required execution environments for the described bundle, possible null.
 void setExportWizardId(String id)
          Sets the identifier of the org.eclipse.ui.exportWizards extension used in the manifest editor for exporting the project associated with these settings, or null if the default export wizard should be used.
 void setExtensionRegistry(boolean supportExtensions)
          Sets whether this bundle supports extension points and extensions via IExtensionRegistry support.
 void setHeader(String header, String value)
          Sets the value of the specified header in the bundle manifest to the given value or removes the header if the value is null.
 void setHost(IHostDescription host)
          Sets the the Fragment-Host header for the described fragment.
 void setLaunchShortcuts(String[] ids)
          Sets the identifiers of org.eclipse.debug.ui.launchShortcuts referenced by org.eclipse.pde.ui.launchShortcuts extensions to be displayed in the manifest editor for the project associated with these settings, or null to indicate default shortcuts should be used.
 void setLocalization(IPath path)
          Sets the value of the Bundle-Localization header for the described bundle.
 void setLocationURI(URI location)
          Sets the location for the described project.
 void setNatureIds(String[] natures)
          Sets the list of natures associated with the described project.
 void setPackageExports(IPackageExportDescription[] exports)
          Sets the value of the Export-Package header for the described bundle.
 void setPackageImports(IPackageImportDescription[] imports)
          Sets the value of the Import-Package header for the described bundle.
 void setRequiredBundles(IRequiredBundleDescription[] bundles)
          Sets the value of the Require-Bundle header for the described bundle.
 void setSingleton(boolean singleton)
          Sets whether the described bundle is a singleton.
 void setSymbolicName(String name)
          Sets the symbolic name of the described bundle.
 void setTargetVersion(String version)
          Sets the version of Eclipse the described bundle is to targeted for.
 

Field Detail

VERSION_3_0

static final String VERSION_3_0
Identifies bundles developed for Eclipse 3.0, value is "3.0".

See Also:
Constant Field Values

VERSION_3_1

static final String VERSION_3_1
Identifies bundles developed for Eclipse 3.1, value is "3.1".

See Also:
Constant Field Values

VERSION_3_2

static final String VERSION_3_2
Identifies bundles developed for Eclipse 3.2, value is "3.2".

See Also:
Constant Field Values

VERSION_3_3

static final String VERSION_3_3
Identifies bundles developed for Eclipse 3.3, value is "3.3".

See Also:
Constant Field Values

VERSION_3_4

static final String VERSION_3_4
Identifies bundles developed for Eclipse 3.4, value is "3.4".

See Also:
Constant Field Values

VERSION_3_5

static final String VERSION_3_5
Identifies bundles developed for Eclipse 3.5, value is "3.5".

See Also:
Constant Field Values

VERSION_3_6

static final String VERSION_3_6
Identifies bundles developed for Eclipse 3.6, value is "3.6".

See Also:
Constant Field Values

PLUGIN_NATURE

static final String PLUGIN_NATURE
Constant for the PDE Plug-in project nature, value is "org.eclipse.pde.PluginNature".

See Also:
Constant Field Values
Method Detail

apply

void apply(IProgressMonitor monitor)
           throws CoreException
Creates or modifies a bundle project and associated artifacts based current settings.

Parameters:
monitor - progress monitor or null
Throws:
CoreException - if project creation or modification fails

setSymbolicName

void setSymbolicName(String name)
Sets the symbolic name of the described bundle.

A symbolic name must be specified.

Parameters:
name - bundle symbolic name

getSymbolicName

String getSymbolicName()
Returns the symbolic name of the described bundle or null if unspecified.

Returns:
bundle symbolic name or null

setLocationURI

void setLocationURI(URI location)
Sets the location for the described project. If null is specified, the default location is used.

Setting the location on a description for a project which already exists has no effect; the new project location is ignored when the description is applied to the already existing project. This method is intended for use on descriptions for new projects.

This operation maps the root folder of the project to the exact location provided. For example, if the location for project named "P" is set to the URI file://c:/my_plugins/Project1, the file resource at workspace path /P/index.html would be stored in the local file system at file://c:/my_plugins/Project1/index.html.

Parameters:
location - the location for the described project or null
See Also:
getLocationURI(), IProjectDescription.setLocationURI(URI)

getLocationURI

URI getLocationURI()
Returns the location URI for the described project. null is returned if the default location should be used.

Returns:
the location for the described project or null
See Also:
setLocationURI(URI)

setBundleName

void setBundleName(String name)
Sets the value of the Bundle-Name header for the described bundle. When null, the bundle name defaults to the bundle symbolic name.

Parameters:
name - bundle name

getBundleName

String getBundleName()
Returns the value of the Bundle-Name header for the described bundle or null if unspecified.

For new projects, the bundle name defaults to the bundle symbolic name.

Returns:
bundle name or null

setBundleVendor

void setBundleVendor(String name)
Sets the value of the Bundle-Vendor header for the described bundle.

Parameters:
name - bundle vendor name

getBundleVendor

String getBundleVendor()
Returns the value of the Bundle-Vendor header for the described bundle or null if unspecified.

Returns:
bundle vendor name or null

setBundleVersion

void setBundleVersion(Version version)
Sets the value of the Bundle-Version header for the described bundle. When null, the bundle version defaults to 1.0.0.qualifier.

Parameters:
version - bundle version

getBundleVersion

Version getBundleVersion()
Returns the value of the Bundle-Version header for the described bundle.

For new projects, the bundle version is 1.0.0.qualifier unless otherwise specified.

Returns:
bundle version or null if unspecified

setSingleton

void setSingleton(boolean singleton)
Sets whether the described bundle is a singleton.

Parameters:
singleton - whether the described bundle is a singleton

isSingleton

boolean isSingleton()
Returns whether the described bundle is a singleton.

A bundle description for a new project is not a singleton, by default.

Returns:
whether the described bundle is a singleton

setLocalization

void setLocalization(IPath path)
Sets the value of the Bundle-Localization header for the described bundle.

Parameters:
path - bundle root relative path or null

getLocalization

IPath getLocalization()
Returns the value of the Bundle-Localization header for the described bundle or null if unspecified.

Returns:
bundle relative path or null

getNatureIds

String[] getNatureIds()
Returns the list of natures associated with the described project. Returns an empty array if there are no natures on this description.

Returns:
the list of natures for the described project
See Also:
setNatureIds(String[]), IProjectDescription.setNatureIds(String[])

setNatureIds

void setNatureIds(String[] natures)
Sets the list of natures associated with the described project. A project created with this description will have these natures added to it in the given order when this description is applied.

When creating a new project, plug-in and Java natures (PLUGIN_NATURE and JavaCore.NATURE_ID) will be added by default when unspecified.

Parameters:
natures - the list of natures
See Also:
getNatureIds(), IProjectDescription.getNatureIds()

hasNature

boolean hasNature(String natureId)
Returns whether the project nature specified by the given nature extension id has been added to the described project.

Parameters:
natureId - the nature extension identifier
Returns:
true if the described project has the given nature
See Also:
IProjectDescription.hasNature(String)

setHost

void setHost(IHostDescription host)
Sets the the Fragment-Host header for the described fragment. When a non-null value is specified, this bundle description describes a fragment.

Parameters:
host - host specification or null

getHost

IHostDescription getHost()
Returns the host bundle for the described fragment, or null if this description does not describe a fragment.

Returns:
host specification or null

setDefaultOutputFolder

void setDefaultOutputFolder(IPath output)
Sets a project relative path for the default output folder used on the Java build path for the described bundle. null indicates the Java project's default output location should be used.

Parameters:
output - project relative path to default output location or null

getDefaultOutputFolder

IPath getDefaultOutputFolder()
Returns a project relative path for the described bundle's default output folder used on the Java build path, or null to indicate the default output location is used.

Returns:
default project relative output folder path or null

setExecutionEnvironments

void setExecutionEnvironments(String[] environments)
Sets the required execution environments for the described bundle, possible null. When more than one environment specified, the first will be used to configure compiler compliance and build path settings.

Parameters:
environments - execution environment identifiers or null

getExecutionEnvironments

String[] getExecutionEnvironments()
Returns the required execution environments for the described bundle, or null if unspecified. When more than one environment is specified, the first will be used to configure compiler compliance and build path settings.

Returns:
execution environment identifiers or null

setBundleClassath

void setBundleClassath(IBundleClasspathEntry[] entries)
Sets the entries for the Bundle-Classpath header of the described bundle, or null if unspecified. Specifies the relationship between source and/or binary folders with bundle classpath entries. When null is specified, no Bundle-Classpath header will be produced.

Parameters:
entries - Bundle-Classpath header entries or null

getBundleClasspath

IBundleClasspathEntry[] getBundleClasspath()
Returns the entries on the Bundle-Classpath header of the described bundle, or null if unspecified.

Returns:
bundle class path entries or null if unspecified
See Also:
setBundleClassath(IBundleClasspathEntry[])

setActivator

void setActivator(String className)
Sets the value of the Bundle-Activator header for the described bundle, or null if none.

Parameters:
className - activator class name or null

getActivator

String getActivator()
Returns the value of the Bundle-Activator header for the described bundle, or null if none.

Returns:
bundle activator class name or null

setTargetVersion

void setTargetVersion(String version)
Sets the version of Eclipse the described bundle is to targeted for. This effects the values generated for Equinox specific headers. Has no effect when isEquinox() is false. When isEquinox() is true, and a target version is unspecified, the newest available target version of Eclipse is used.

Parameters:
version - one of the version constant values defined by this class or null
See Also:
setEquinox(boolean)

getTargetVersion

String getTargetVersion()
Returns the version of Eclipse the described bundle is targeted for, or null if unspecified. When unspecified, the project is targeted to the newest available version of Eclipse when isEquinox() is true.

Returns:
target version or null

setEquinox

void setEquinox(boolean equinox)
Sets whether the described bundle is targeted for the Equinox OSGi framework.

An Equniox specific lazy-start header will be generated in the associated manifest when true based on the target version and activation policy. For new projects the value is false, by default.

This following headers are affected when true, based on the getTargetVersion() and getActivationPolicy(). The headers are removed when getActivationPolicy() is unspecified (null).

Parameters:
equinox - whether targeted for the Equinox OSGi framework
See Also:
getTargetVersion()

isEquinox

boolean isEquinox()
Returns whether the described bundle is targeted for the Equinox OSGi framework. Effects the Equinox lazy-start header generated in the manifest.

Returns:
whether the described bundle is targeted for the Equinox OSGi framework

setActivationPolicy

void setActivationPolicy(String policy)
Sets this bundle's activation policy. Legal values are Constants.ACTIVATION_LAZY or null (unspecified). Any other values are ignored (equivalent to null). When unspecified, a corresponding header is not generated. By default the value is unspecified for newly created projects.

An Equniox specific lazy-start header will be generated in the associated manifest based on the getTargetVersion() and the specified policy. The headers are removed when the policy is unspecified (null).

Parameters:
policy - activation policy or null
See Also:
getTargetVersion()

getActivationPolicy

String getActivationPolicy()
Returns this bundle's activation policy or null if unspecified.

Returns:
activation policy or null

setExtensionRegistry

void setExtensionRegistry(boolean supportExtensions)
Sets whether this bundle supports extension points and extensions via IExtensionRegistry support. By default, this value is false for new projects.

Parameters:
supportExtensions - whether extension points and extensions are supported

isExtensionRegistry

boolean isExtensionRegistry()
Returns whether this bundle supports extension points and extensions via IExtensionRegistry support. By default, this value is false for new projects.

Returns:
whether extension points and extensions are supported

setRequiredBundles

void setRequiredBundles(IRequiredBundleDescription[] bundles)
Sets the value of the Require-Bundle header for the described bundle.

Parameters:
bundles - required bundle descriptions or null if none

getRequiredBundles

IRequiredBundleDescription[] getRequiredBundles()
Returns the value of the Require-Bundle header or null if unspecified.

Returns:
required bundle descriptions or null

setPackageImports

void setPackageImports(IPackageImportDescription[] imports)
Sets the value of the Import-Package header for the described bundle.

Parameters:
imports - package import descriptions or null if none

getPackageImports

IPackageImportDescription[] getPackageImports()
Returns the value of the Import-Package header or null if unspecified.

Returns:
package import descriptions or null

setPackageExports

void setPackageExports(IPackageExportDescription[] exports)
Sets the value of the Export-Package header for the described bundle.

Parameters:
exports - package export descriptions or null if none

getPackageExports

IPackageExportDescription[] getPackageExports()
Returns the value of the Export-Package header or null if unspecified.

Returns:
package export descriptions or null

getProject

IProject getProject()
Returns the project associated with the described bundle.

Returns:
associated project

setBinIncludes

void setBinIncludes(IPath[] paths)
Sets file and folder entries on the bin.includes entry of the build.properties file of the described bundle project.

By default, the MANIFEST/ folder and any entries on the Bundle-Classpath will be included. This sets any additional entries that are to be included.

Parameters:
paths - bundle root relative paths of files and folders to include or null if none

getBinIncludes

IPath[] getBinIncludes()
Returns the file and folder entries to be included on the bin.includes entry of the build.properties file of the described bundle project.

By default, the MANIFEST/ folder and any entries on the Bundle-Classpath will be included. This returns any additional entries that are to be included.

Returns:
bundle root relative paths of files and folders on the bin.includes entry or null

setBundleRoot

void setBundleRoot(IPath path)
Sets the location within the project where the root of the bundle and its associated artifacts will reside, or null to indicate the default bundle root location should be used (project folder).

This has no effect on existing projects. This method is intended for use on descriptions for new projects. To modify the bundle root of an existing project use IBundleProjectService.setBundleRoot(IProject, IPath).

The bundle root is the folder containing the META-INF/ folder. When a project does not yet exist, bundle files will be created relative to the bundle root. When a project already exists and the bundle root location is modified, existing bundle artifacts at the old root are not moved or modified. Instead, the modify operation will update any existing bundle files at the new root location, or create them if not yet present.

Parameters:
path - project relative path to bundle root artifacts in the project or null

getBundleRoot

IPath getBundleRoot()
Returns the location within the project that is the root of the bundle related artifacts, or null to indicate the default location (project folder).

Returns:
project relative bundle root path or null

getLaunchShortcuts

String[] getLaunchShortcuts()
Returns identifiers of org.eclipse.debug.ui.launchShortcuts referenced by org.eclipse.pde.ui.launchShortcuts extensions that will be displayed in the manifest editor for the project associated with these settings, or null if default shortcuts are being used.

Returns:
identifiers of the org.eclipse.debug.ui.launchShortcuts extensions or null

setLaunchShortcuts

void setLaunchShortcuts(String[] ids)
Sets the identifiers of org.eclipse.debug.ui.launchShortcuts referenced by org.eclipse.pde.ui.launchShortcuts extensions to be displayed in the manifest editor for the project associated with these settings, or null to indicate default shortcuts should be used.

When default shortcuts are used, all org.eclipse.pde.ui.launchShortcuts extensions are considered. When specific shortcuts are specified, the available shortcuts will be limited to those specified.

Important: When specifying shortcuts, both org.eclipse.debug.ui.launchShortcuts and org.eclipse.pde.ui.launchShortcuts must exist. Labels for shortcuts in the editor are derived from the org.eclipse.pde.ui.launchShortcuts.

Parameters:
ids - identifiers of org.eclipse.debug.ui.launchShortcuts extensions or null

getExportWizardId

String getExportWizardId()
Returns the identifier of the org.eclipse.ui.exportWizards extension used in the manifest editor for exporting the project associated with these settings, or null if the default export wizard should be used.

Returns:
identifier of an org.eclipse.ui.exportWizards extension or null

setExportWizardId

void setExportWizardId(String id)
Sets the identifier of the org.eclipse.ui.exportWizards extension used in the manifest editor for exporting the project associated with these settings, or null if the default export wizard should be used.

Parameters:
id - identifier of an org.eclipse.ui.exportWizards extension or null

setHeader

void setHeader(String header,
               String value)
Sets the value of the specified header in the bundle manifest to the given value or removes the header if the value is null.

Using this method will override the value of a header generated by other methods in this interface. For example, using the method setBundleName(String) will generate a value for the Bundle-Name header, but calling setHeader(String, String) for the Bundle-Name header will override any value set via setBundleName(String). This method is intended to be used to set the value of a header that does not have explicit API.

To include an empty header value.trim().length() must equal zero (i.e an empty string or a string of whitespace).

Parameters:
header - header name
value - header value or null to remove

getHeader

String getHeader(String header)
Returns the value of the specified header from the bundle manifest, or null if unspecified. Note that an empty string is returned for a header that has an empty value.

Parameters:
header -
Returns:
header value or null

Eclipse PDE
Release 3.6

Guidelines for using Eclipse APIs.

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