org.knopflerfish.ant.taskdefs.bundle
Class BundleInfoTask

java.lang.Object
  org.apache.tools.ant.ProjectComponent
      org.apache.tools.ant.Task
          org.knopflerfish.ant.taskdefs.bundle.BundleInfoTask

All Implemented Interfaces:

java.lang.Cloneable

public class BundleInfoTask
extends org.apache.tools.ant.Task

Task that analyzes sets of class files and jar files that will be the contents of some bundle. The output is the set of packages to be exported and imported by the bundle. Also tries to find any class implementing org.osgi.framework.BundleActivator.

The set of files to analyze are specified as nested ant file sets.

Parameters

Attribute	Description	Required
imports	Name of property that will receive a comma-separated list of all used packages. If set to empty string, no property will be set. Note: Some default packages are always added. These defaults can be set using the defaultimports parameter.	No. Default value is ""
exports	Name of property that will receive a comma-separated list of all defined packages. If set to empty string, no property will be set.	No. Default value is ""
activator	Name of property that will receive name of class which implements org.osgi.framework.BundleActivator If set to empty string, no property will be set. If set to non-empty, and multiple activators are found, or an activator not equal to any previous content in the named property is found - a warning will be logged.	No. Default value is ""
stdimports	Comma-separated list of package name prefixes for referenced packages that shall not be included in the Import-Package manifest attribute. Example of packages to list in this attribute are non-standard packages obtained via boot-delegation, packages exported by a required bundle, packages referenced to by code in nested jar-files that are never used. The default value, "java.", is added to any given list since packages starting with "java.*" shall never be imported. They are always made available to the bundle by delegation to the parent classloader.	No. Default value is "java."
defaultimports	Comma-separated list of packages that will be unconditionally added to the derived set of packages that the bundle needs to import.	No. Default value is ""
extraimports	Comma-separated list of package names that must be present in the import list even though they are not explicitly referenced from the bundles code. E.g., packages from which all classes are loaded using reflection.	No. Default value is ""
importsOnly	If set to true then do not update Export-Package manifest header.	No. Default value is "false".
implicitImports	Flag for ensuring that each exported packages is included in the import package list. If set to "true", the task will add all packages mentioned in the property named by exports to the list of imported packages in the property named by imports if not already present. When this task adds an import declaration for an exported package the import entry will be given a version range starting with the version from the export statement and up to the next major version (exclusive). If some other version range is needed an explicit import with that range should be added to the bundle manifest template. This emulates the implicit import behavior present in OSGi R1-R3.	No. Default value is "true"
serviceComponent	The value of the Service-Component manifest header. If set to non-empty, leave the value of the activator property untouched and do not complain if there are no class that implements BundleActivator in the bundle. A bundle using declarative services does not need a bundle activator but it may have one anyhow.	No. Default value is ""
fragmentHost	The value of the Fragment-Host manifest header. If set to non-empty (i.e., this is a fragment bundle), leave the value of the activator property untouched and do not complain if there are no class that implements BundleActivator in the bundle.	No. Default value is ""
manifestVersion	The value of the Bundle-ManifestVersion manifest header. If set to "2" and the uses attribute is also true then a "uses" directive is computed and added to each package in the Export-Package header generated by this task.	No. Default value is "1" (pre OSGi R4 bundle).
uses	If set to true then add / update uses directive in the value of the Export-Package manifest header. Note that uses-directives are not added for pre OSGi R4 bundle. That is for bundle with manifestVersion less than "2".	No. Default value is "true".
failOnExports	If an error is detected in the given export package header and this attribute is set to true then a build failure is trigger.	No. Default value is "true"
failOnImports	If an error is detected in the given import package header and this attribute is set to true then a build failure is trigger.	No. Default value is "true"
failOnActivator	If an error is detected in the given bundle activator header and this attribute is set to true then a build failure is trigger.	No. Default value is "true"
failOnClassPath	If a non-existing entry is detected in the given bundle classpath header and this attribute is set to true then a build failure is trigger.	No. Default value is "true"
addPackageinfoPackages	If set to true then add packages that contains a packageinfo file, even if the package is empty.	No. Default value is "false"

Parameters specified as nested elements

The set of provided packages (classes) is the union of the packages found via <exports>, <exportsBundleClasspath> and <impls>, <implsBundleClasspath> resource collections. The import-package header is derived (checked against) the set of provided packages.

exports

(optional)

Nested <exports>-elements are filesets that will be analyzed to determine the set of provided Java packages to be exported by the bundle.

Unsupported file types matched by the file set are ignored.

exportsBundleClasspath

(optional)

Nested <exportsBundleClasspath>-elements are instances of BundleClasspathTask that will derive a list of file sets to be analyzed to determine the set of provided Java packages to be exported by the bundle.

Unsupported file types matched by the file set are ignored.

impls

(optional)

Nested <impls>-elements are filesets that will be analyzed to determine the set of private Java packages provided by the bundle.

Unsupported file types matched by the file set are ignored.

implsBundleClasspath

(optional)

Nested <implsBundleClasspath>-elements are instances of BundleClasspathTask that will derive a list of file sets are to be analyzed to determine the set of private Java packages provided by the bundle.

Unsupported file types matched by the file set are ignored.

Examples

Check all imports and activator in implementation classes

This example assumes all implementation classes are in the package test.impl.*

  <bundleinfo  activator = "bmfa.Bundle-Activator"
               imports   = "impl.import.package">
   <impls dir="classes" includes="test/impl/*"/>
  </bundleinfo>
  <echo message="imports   = ${impl.import.package}"/>
  <echo message="activator = ${bmfa.Bundle-Activator}"/>
 

Check all imports and exports in API classes

This example assumes all API classes are in the package test.*

  <bundleinfo  exports  = "api.export.package"
               imports  = "api.import.package">
   <exports dir="classes" includes="test/*"/>
   <impls   dir="classes" includes="test/impl/*"/>
  </bundleinfo>
  <echo message="imports  = ${api.import.package}"/>
  <echo message="exports  = ${api.export.package}"/>
 

Field Summary

static java.util.Set<java.lang.String>	ANALYZE_SUFFIXES
static org.apache.tools.ant.types.resources.selectors.ResourceSelector	analyzeRestriction A resource selector that selects files to be analyzed.

Fields inherited from class org.apache.tools.ant.Task

target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

description, location, project

Constructor Summary

BundleInfoTask()

Method Summary

void	addConfiguredExports(org.apache.tools.ant.types.FileSet set) Add a file set with classes that shall be exported.
void	addConfiguredExportsBundleClasspath(BundleClasspathTask bcpt) Add file sets for classes exported from the bundle classpath.
void	addConfiguredImpls(org.apache.tools.ant.types.FileSet set) Add a file set with classes that are private to the bundles.
void	addConfiguredImplsBundleClasspath(BundleClasspathTask bcpt) Add file sets for private classes on the bundle classpath.
protected void	analyze(org.apache.tools.ant.types.Resource res) Analyze a resource by checking its suffix and delegate to analyzeClass(Resource) or analyzePackageinfo(Resource).
protected void	analyzeClass(org.apache.tools.ant.types.Resource res)
protected void	analyzePackageinfo(org.apache.tools.ant.types.Resource res)
protected java.lang.String	buildExportPackagesValue(java.util.Set<java.lang.String> exportPackages) Return the value of the Export-Package based on the analysis.
void	execute() Analyze all resources in the exports and impls resource collections to determine the set of Java packages provided by this bundle.
protected boolean	isImported(java.lang.String className)
protected boolean	isStdImport(java.lang.String name) Check if package is included in the prefix list of packages that does not need to be in the Import-Package list.
void	setActivator(java.lang.String propName) Set property receiving any BundleActivator class.
void	setAddPackageinfoPackages(boolean addPackageinfoPackages) If set to true then add packages that contains a packageinfo file, even if the package is empty.
void	setDefaultImports(java.lang.String packageList) Set default import set.
void	setExports(java.lang.String propName) Set property receiving list of exported packages.
void	setExtraImports(java.lang.String packageList) Set the extra imports set.
void	setFailOnActivator(boolean b)
void	setFailOnClassPath(boolean b)
void	setFailOnExports(boolean b)
void	setFailOnImports(boolean b)
void	setFragmentHost(java.lang.String fragmentHost) Set value of the Fragment-Host manifest header.
void	setImplicitImports(java.lang.String s)
void	setImports(java.lang.String s) Set property receiving list of imported packages.
void	setImportsOnly(boolean importsOnly) If set to true then do not update Export-Package manifest header.
void	setManifestVersion(java.lang.String manifestVersion) Set value of the Bundle-ManifestVersion manifest header.
void	setPrintClasses(java.lang.String s)
void	setServiceComponent(java.lang.String serviceComponent) Set name value of the Service-Component manifest header.
void	setStdImports(java.lang.String packageList) Set set of packages always imported.
void	setUses(boolean uses) Shall uses directives be added to the Export-Package header or not.
static java.lang.String	toDefaultVersionRange(java.lang.String version) Given an OSGi version number on the form Major.Minor.Micro.Qualifier return a version range of the form "[Major.Minor.Micro.Qualifier,Major)".
protected static java.lang.String	toString(java.util.Set<java.lang.String> set, java.lang.String separator) Convert Set elements to a string.
protected java.lang.String	validateExportPackagesValue(java.lang.String oldExportsVal) Validate a given Export-Package header value.

Methods inherited from class org.apache.tools.ant.Task

bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ANALYZE_SUFFIXES

public static final java.util.Set<java.lang.String> ANALYZE_SUFFIXES

analyzeRestriction

public static final org.apache.tools.ant.types.resources.selectors.ResourceSelector analyzeRestriction

A resource selector that selects files to be analyzed. I.e., it selects .class-files and packageinfo-files.

Constructor Detail

BundleInfoTask

public BundleInfoTask()

Method Detail

setImports

public void setImports(java.lang.String s)

Set property receiving list of imported packages.

setPrintClasses

public void setPrintClasses(java.lang.String s)

setFailOnExports

public void setFailOnExports(boolean b)

setFailOnImports

public void setFailOnImports(boolean b)

setFailOnActivator

public void setFailOnActivator(boolean b)

setFailOnClassPath

public void setFailOnClassPath(boolean b)

setImplicitImports

public void setImplicitImports(java.lang.String s)

setDefaultImports

public void setDefaultImports(java.lang.String packageList)

Set default import set.

Parameters:

packageList - Comma-separated list of package names.

setExtraImports

public void setExtraImports(java.lang.String packageList)

Set the extra imports set.

Parameters:

packageList - Comma-separated list of package names.

setExports

public void setExports(java.lang.String propName)

Set property receiving list of exported packages.

setActivator

public void setActivator(java.lang.String propName)

Set property receiving any BundleActivator class.

setServiceComponent

public void setServiceComponent(java.lang.String serviceComponent)

Set name value of the Service-Component manifest header.

setFragmentHost

public void setFragmentHost(java.lang.String fragmentHost)

Set value of the Fragment-Host manifest header.

setManifestVersion

public void setManifestVersion(java.lang.String manifestVersion)

Set value of the Bundle-ManifestVersion manifest header.

setUses

public void setUses(boolean uses)

Shall uses directives be added to the Export-Package header or not.

setStdImports

public void setStdImports(java.lang.String packageList)

Set set of packages always imported.

Parameters:

packageList - Comma-separated list of package names.

addConfiguredExports

public void addConfiguredExports(org.apache.tools.ant.types.FileSet set)

Add a file set with classes that shall be exported.

Parameters:

set - The file set with exports to add.

addConfiguredExportsBundleClasspath

public void addConfiguredExportsBundleClasspath(BundleClasspathTask bcpt)

Add file sets for classes exported from the bundle classpath.

Parameters:

bcpt - The bundle classpath that the bundle will have.

addConfiguredImpls

public void addConfiguredImpls(org.apache.tools.ant.types.FileSet set)

Add a file set with classes that are private to the bundles.

Parameters:

set - The file set with private implementations to add.

addConfiguredImplsBundleClasspath

public void addConfiguredImplsBundleClasspath(BundleClasspathTask bcpt)

Add file sets for private classes on the bundle classpath.

Parameters:

bcpt - The bundle classpath that the bundle will have.

setImportsOnly

public void setImportsOnly(boolean importsOnly)

If set to true then do not update Export-Package manifest header.

setAddPackageinfoPackages

public void setAddPackageinfoPackages(boolean addPackageinfoPackages)

If set to true then add packages that contains a packageinfo file, even if the package is empty.

execute

public void execute()
             throws org.apache.tools.ant.BuildException

Analyze all resources in the exports and impls resource collections to determine the set of Java packages provided by this bundle. Update the given properties for export- and import package accordingly.

Overrides:

execute in class org.apache.tools.ant.Task

Throws:

org.apache.tools.ant.BuildException

buildExportPackagesValue

protected java.lang.String buildExportPackagesValue(java.util.Set<java.lang.String> exportPackages)

Return the value of the Export-Package based on the analysis.

Parameters:

exportPackages - The sub-set of provided packages to be exported.

validateExportPackagesValue

protected java.lang.String validateExportPackagesValue(java.lang.String oldExportsVal)

Validate a given Export-Package header value. Check existing version parameters, add missing package versions. Check uses directives and add those that are missing.

Parameters:

oldExportsVal - the Export-Package value to validate and update.

Throws:

org.apache.tools.ant.BuildException - when conflicting version specifications are found for a package.

analyze

protected void analyze(org.apache.tools.ant.types.Resource res)
                throws org.apache.tools.ant.BuildException

Analyze a resource by checking its suffix and delegate to analyzeClass(Resource) or analyzePackageinfo(Resource).

Parameters:

res - The resource to be analyzed.

Throws:

org.apache.tools.ant.BuildException

isImported

protected boolean isImported(java.lang.String className)

isStdImport

protected boolean isStdImport(java.lang.String name)

Check if package is included in the prefix list of packages that does not need to be in the Import-Package list.

Returns:

true if name is prefixed with any of the elements in stdImports set, false otherwise.

analyzeClass

protected void analyzeClass(org.apache.tools.ant.types.Resource res)
                     throws org.apache.tools.ant.BuildException

Throws:

org.apache.tools.ant.BuildException

analyzePackageinfo

protected void analyzePackageinfo(org.apache.tools.ant.types.Resource res)
                           throws org.apache.tools.ant.BuildException

Throws:

org.apache.tools.ant.BuildException

toDefaultVersionRange

public static final java.lang.String toDefaultVersionRange(java.lang.String version)

Given an OSGi version number on the form Major.Minor.Micro.Qualifier return a version range of the form "[Major.Minor.Micro.Qualifier,Major)".

Parameters:

version - the version number to convert to a version range.

Returns:

A quoted version range string.

toString

protected static java.lang.String toString(java.util.Set<java.lang.String> set,
                                           java.lang.String separator)

Convert Set elements to a string.

Parameters:

separator - String to use as separator between elements.