Knopflerfish OSGi 5.2.0

org.knopflerfish.ant.taskdefs.bundle
Class BundleInfoTask

java.lang.Object
  extended by org.apache.tools.ant.ProjectComponent
      extended by org.apache.tools.ant.Task
          extended by 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.

Knopflerfish OSGi 5.2.0