org.knopflerfish.ant.taskdefs.bundle

Class BundleLocator

java.lang.Object

org.apache.tools.ant.ProjectComponent

org.apache.tools.ant.Task

org.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 specification 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.Micro‑Qualifier.

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.
bundlePath	Specifies a bundle search path like the one specified in xargs files by the framework property org.knopflerfish.gosg.jars. Path elements are URLs separated by ';'. Setting this property will add a file set with an includes set to ∗∗/∗.jar for each path element that is defined as a file-URL.	No. No default value.
baseDir	Path to directory to use as base-directory to complete relative file URLs in the bundlePath.	No. Defaults to the empty string, i.e., the current working directory.
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. Key Value @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. Key Value @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 originates 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

Constructors

Constructor and Description
BundleLocator()

Method Summary

Methods

Modifier and Type	Method and Description
void	addFileset(org.apache.tools.ant.types.FileSet set)
void	execute()
void	setBaseDir(java.io.File f)
void	setBundleName(java.lang.String s)
void	setBundleNames(java.lang.String s)
void	setBundlePath(java.lang.String bundlePath)
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)

setBundlePath

public void setBundlePath(java.lang.String bundlePath)
                   throws org.apache.tools.ant.BuildException

Throws:

org.apache.tools.ant.BuildException

setBaseDir

public void setBaseDir(java.io.File f)

execute

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

Overrides:

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

Throws:

org.apache.tools.ant.BuildException