Knopflerfish OSGi 2.4.0

org.knopflerfish.ant.taskdefs.bundle
Class BundleLocator

java.lang.Object
  extended byorg.apache.tools.ant.ProjectComponent
      extended byorg.apache.tools.ant.Task
          extended byorg.knopflerfish.ant.taskdefs.bundle.BundleLocator
All Implemented Interfaces:
java.lang.Cloneable

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

Determines a sub-set of bundles from a given file set. The resulting set of bundles will only contain the highest version of each bundle in the original file set. The resulting set of bundles may then be used in several ways.

An OSGi version spec used below is a string on the format Major.Minor.Micro.Qualifier where major, minor and micro are integers, and all parts of the version except major are optional. See org.osgi.framework.Version for details. The version formatting used by Maven 2 is also recognized, i.e., a '‑' between the micro and qualifier fields: Major.Minor.MicroQualifier.

Given a partial bundle name and a file set with bundles, this task may be used to select the bundle with the highest version number and name that matches. E.g.,

   <bundle_locator bundleName="http" property="http.path">
     <fileset dir="${jars.dir}">
       <include name="**/*.jar"/>
     </fileset>
   </bundle_locator>
 
will set the project property http.path to the absolute path of the highest version of the bundle named http within the given file set. By setting the bundleName to http-1.N.N the task will select the highest version of the http-bundle with the restriction that the Major part of the version number of the selection must be exactly 1.

The bundle locator task can also iterate over a path and replace all non-existing file resources in it that either has a name ending with -N.N.N.jar or that is the symbolic name of a bundle with the corresponding bundle with the highest version of the matching bundle from the given file set. Non-existing path entries that does not end in .jar or .zip that does not match a symbolic bundle name will trigger a build error if failOnMissingBundles is set to true. The same applies to path entries ending with -N.N.N.jar that does not yield a match. The search may be further restricted to specific versions by replacing the N in the resource name with a specific version number.

   <bundle_locator classPathRef="bundle.path"
                   newClassPathId="bundle.path.Expanded"
                   failOnMissingBundles="true">
     <fileset dir="${jars.dir}">
       <include name="**/*.jar"/>
     </fileset>
   </bundle_locator>
 
this will build a new path added to the project with the id bundle.path.Expanded. The new path will be a copy of the original, bundle.path, but with all path elements with a name ending in -N.N.N.jar replaced with the corresponding match or removed if no match was found.

Another usage of the bundle locator task is to ensure that only the highest version of a bundle is matched by a certain pattern set.

   <bundle_locator patternSetId="my.ps.exact">
     <fileset dir="${jars.dir}">
       <patternset refid="my.ps"/>
     </fileset>
   </bundle_locator>
 
Here the original pattern set my.ps is used to find bundles in the directory jars.dir, if more than one version of a bundle matches then only the one with the highest version will be selected. A new pattern set based on the matches is created and saved in the project under the name my.ps.exact. This pattern set will contain one include pattern for each matching bundle. The value of the include pattern is the relative path of that bundle (relative to the root directory of the file set that the matching bundle originates from).

Finally this task may also be used to create a properties file suitable for using as a replacement filter that will replace bundle names on the form @name-N.N.N.jar@ or bundle symbolic names on the form @bundleSymbolicName.jar@ with the relative path within the given file set of the bundle with the given name and the highest version.

   <bundle_locator replacefilterfile="my.filter">
     <fileset dir="${jars.dir}">
       <patternset refid="my.ps"/>
     </fileset>
   </bundle_locator>
 

Parameters

Attribute Description Required
bundleName The name of the bundle to look for. There are several ways to specify the bundle name.
  • If the bundle to locate is named like name‑OSGi version spec.jar, then the value of the bundleName-attribute may be specified as name.
  • The symbolic name of the bundle.
A property with name given by the value of the attribute property with the location (absolute path) of the bundle as value is added to the project.
No. No default value.
bundleNames A comma separated list of bundle names to look for. There are several ways to specify the bundle name.
  • If a bundle to locate is named like name‑OSGi version spec.jar, then the value of the bundleName-attribute may be specified as name.
  • The symbolic name of the bundle.
The absolute path of the matching bundle will be stored in a project property named bap.bundleName.

If the attribute property is set its value will be used as prefix for the property names in stead of the default bap.

No. No default value.
property The name of a project property to be assigned the location of the matching bundle. Yes when bundleName is specified.
No default value.
classPathRef The reference name (id) of a path-structure to transform. No. No default value.
newClassPathId The transformed path-structure will be added to the current project using this name (id). Yes when classPathRef is specified.
No default value.
patternSetId Create a pattern set from the set of bundles that are selected by the nested file set(s) and add it to the project using this name (id). No. No default value.
failOnMissingBundles If an entry with a file name like bundleName-N.N.N.jar is found on the classpath to transform and there is no matching bundle in the file set then a build failure is triggered if this attribute is set to true. Same applies if the given bundleName or one of the given bundleNames does not yield a match. No.
Defaults to true.
extendedReplaceFilter If set to true then the replace filter generated by the replacefilter attribute will be extended with the following set of replacements for each matching bundle.
KeyValue
@bundleName‑N.N.N.name@
@Bundle‑SymbolicName.name@
The bundle symbolic name from the manifest. For bundles with manifest version 1 (i.e., pre OSGi R4 bundles) the bundle name.
@bundleName‑N.N.N.version@
@Bundle‑SymbolicName.version@
The bundle version from the manifest.
@bundleName‑N.N.N.location@
@Bundle‑SymbolicName.location@
The absolute path of the bundle.
No.
Defaults to false.
replacefilterfile Creates a property file suitable for use as the replacefilterfile argument in the replace-task. The generated file will contain two entries for each matching bundle.
KeyValue
@bundleName‑N.N.N.jar@
@Bundle‑SymbolicName.jar@
The relative path to the bundle from the root-directory of the file set that the matching bundle ordinates from.
No.
No default value.

Parameters specified as nested elements

fileset

(required)

The jar files to match against must be specified as a fileset.


Field Summary
 
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
BundleLocator()
           
 
Method Summary
 void addFileset(org.apache.tools.ant.types.FileSet set)
           
 void execute()
           
 void setBundleName(java.lang.String s)
           
 void setBundleNames(java.lang.String s)
           
 void setClassPathRef(org.apache.tools.ant.types.Reference r)
           
 void setExtendedReplaceFilter(boolean b)
           
 void setFailOnMissingBundles(boolean b)
           
 void setNewClassPathId(java.lang.String s)
           
 void setPatternSetId(java.lang.String s)
           
 void setProperty(java.lang.String s)
           
 void setReplacefilterfile(java.io.File f)
           
 
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
 

Constructor Detail

BundleLocator

public BundleLocator()
Method Detail

setProperty

public void setProperty(java.lang.String s)

setBundleName

public void setBundleName(java.lang.String s)

setBundleNames

public void setBundleNames(java.lang.String s)

addFileset

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

setClassPathRef

public void setClassPathRef(org.apache.tools.ant.types.Reference r)

setNewClassPathId

public void setNewClassPathId(java.lang.String s)

setPatternSetId

public void setPatternSetId(java.lang.String s)

setFailOnMissingBundles

public void setFailOnMissingBundles(boolean b)

setExtendedReplaceFilter

public void setExtendedReplaceFilter(boolean b)

setReplacefilterfile

public void setReplacefilterfile(java.io.File f)

execute

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

Knopflerfish OSGi 2.4.0