JPF Tools Reference

Most JPF tools are implemented as special purpose Java classes and wrapped as Ant tasks for ease of use. To make JPF specific tasks available in your build file insert following declaration in the beginning of Ant build script:
<typedef resource="org/java/plugin/tools/ant/jpf-tasks.properties" />
Note that jpf-tool.jar library should be available in classpath (you may use nested <classpath> element in <typedef> tag).

Integrity Check Tool
Documentation Tool
Plug-in Archive Tool
Single File Plug-in Tool
Manifest Info Tool
Version Update Tool
Classpath Tool
Sorting Tool

Integrity Check Tool  

The tool is implemented as Ant task (jpf-check) and allows to check integrity of plug-ins collection.

Attribute	Description	Required
basedir	Directory to resolve relative links. By default is equal to project base directory ${basedir}.	No
verbose	If "true", more detailed report will be generated. Default is "false".	No
includes	comma- or space-separated list of patterns of plug-in manifest files that must be included. All files are included when omitted.	No
includesfile	The name of a file. Each line of this file is taken to be an include pattern.	No
excludes	Comma- or space-separated list of patterns of plug-in manifest files that must be excluded. No files (except default excludes) are excluded when omitted.	No
excludesfile	The name of a file. Each line of this file is taken to be an exclude pattern.	No
defaultexcludes	Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted.	No
whitelist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be included in processing. All plug-ins are included when file omitted.	No
blacklist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be excluded from processing. No plug-ins are excluded when file omitted.	No
usepathresolver	If "true", JPF will try to resolve URL's specified in manifests to check existence of plug-in resources. Default is "false".	No

Parameters specified as nested elements

fileset

Ant's FileSets can be used to select plug-in manifest files for plug-ins to be checked.

Example

<!-- Define custom JPF specific Ant tasks -->
<typedef resource="org/java/plugin/tools/ant/jpf-tasks.properties" />
<!-- Call "jpf-check" task to check plug-ins integrity -->
<jpf-check
	basedir="${basedir}/plugins"
	includes="*/plugin.xml,*/plugin-fragment.xml"
	verbose="true"
	usepathresolver="true"/>

Documentation Tool  

The javadoc-like tool to generate documentation for plug-ins. The tool implemented as special utility class and wrapped with Ant task (jpf-doc) for ease of use.

Note: documentation design looks not very good now, but this is just design problem, not the documentation engine! Good HTML design contributions are welcome!

Attribute	Description	Required
basedir	Directory to resolve relative links. By default is equal to project base directory ${basedir}.	No
verbose	If "true", more detailed report will be generated. Default is "false".	No
includes	comma- or space-separated list of patterns of plug-in manifest files that must be included. All files are included when omitted.	No
includesfile	The name of a file. Each line of this file is taken to be an include pattern.	No
excludes	Comma- or space-separated list of patterns of plug-in manifest files that must be excluded. No files (except default excludes) are excluded when omitted.	No
excludesfile	The name of a file. Each line of this file is taken to be an exclude pattern.	No
defaultexcludes	Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted.	No
whitelist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be included in processing. All plug-ins are included when file omitted.	No
blacklist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be excluded from processing. No plug-ins are excluded when file omitted.	No
destdir	Base directory for generated documentation files.	Yes
overview	Documentation overview HTML file.	No
encoding	Source files encoding name (templates, overview etc.) Default is system encoding.	No
docencoding	Output files encoding name. Default is UTF-8.	No
stylesheetfile	CSS style sheet to use. Predefined style will be used if no file specified.	No
templates	path to template files (should be available in classpath). Predefined templates set will be used if not specified.	No

Parameters specified as nested elements

fileset

Ant's FileSets can be used to select plug-in manifest files, documentation should be generated for.

Example

<!-- Define custom JPF specific Ant tasks -->
<typedef resource="org/java/plugin/tools/ant/jpf-tasks.properties" />
<!-- Call "jpf-doc" task to generate plug-ins documentation -->
<jpf-doc
	basedir="${basedir}/plugins"
	includes="*/plugin.xml,*/plugin-fragment.xml"
	destdir="${build.home}/docs"/>

Plug-in Archive Tool  

Tool implemented as special utility class and wrapped with Ant tasks (jpf-pack and jpf-unpack) for ease of use. Plug-in archive is specially prepared ZIP format file that holds all packed plug-ins and special descriptor for quick extracting plug-ins meta-data without need of unpacking the whole archive file.

Plug-ins archiving task (jpf-pack).

Attribute	Description	Required
basedir	Directory to resolve relative links. By default is equal to project base directory ${basedir}.	No
verbose	If "true", more detailed report will be generated. Default is "false".	No
includes	comma- or space-separated list of patterns of plug-in manifest files that must be included. All files are included when omitted.	No
includesfile	The name of a file. Each line of this file is taken to be an include pattern.	No
excludes	Comma- or space-separated list of patterns of plug-in manifest files that must be excluded. No files (except default excludes) are excluded when omitted.	No
excludesfile	The name of a file. Each line of this file is taken to be an exclude pattern.	No
defaultexcludes	Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted.	No
whitelist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be included in processing. All plug-ins are included when file omitted.	No
blacklist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be excluded from processing. No plug-ins are excluded when file omitted.	No
destfile	Target archive file.	Yes

Plug-ins un-archiving task (jpf-unpack).

Attribute	Description	Required
basedir	Directory to resolve relative links. By default is equal to project base directory ${basedir}.	No
verbose	If "true", more detailed report will be generated. Default is "false".	No
includes	comma- or space-separated list of patterns of plug-in manifest files that must be included. All files are included when omitted.	No
includesfile	The name of a file. Each line of this file is taken to be an include pattern.	No
excludes	Comma- or space-separated list of patterns of plug-in manifest files that must be excluded. No files (except default excludes) are excluded when omitted.	No
excludesfile	The name of a file. Each line of this file is taken to be an exclude pattern.	No
defaultexcludes	Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted.	No
whitelist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be included in processing. All plug-ins are included when file omitted.	No
blacklist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be excluded from processing. No plug-ins are excluded when file omitted.	No
srcfile	Archive file to be unpacked.	Yes
destdir	Folder where to extract archived plug-ins.	Yes

Parameters specified as nested elements

fileset

Ant's FileSets can be used to select plug-in manifest files, documentation should be generated for.

Example

<!-- Define custom JPF specific Ant tasks -->
<typedef resource="org/java/plugin/tools/ant/jpf-tasks.properties" />
<!-- Call "jpf-pack" task to pack plug-ins into archive -->
<jpf-pack
	basedir="${basedir}/plugins"
	includes="*/plugin.xml,*/plugin-fragment.xml"
	destfile="${build.home}/all-plugins.zip"/>
<!-- Call "jpf-unpack" task to extract plug-ins from archive -->
<jpf-unpack
	srcfile="${build.home}/all-plugins.zip"
	destdir="${build.home}/all-plugins-extracted"/>

Single File Plug-in Tool  

The tool is implemented as Ant task (jpf-zip) and allows to process plug-ins collection packaging every plug-in and plug-in fragment into single ZIP file. ZIP file names compozed according to the following scheme: <plugin-ID>-<plugin-version>.zip

Attribute	Description	Required
basedir	Directory to resolve relative links. By default is equal to project base directory ${basedir}.	No
destdir	Directory to store generated ZIP files.	Yes
verbose	If "true", more detailed report will be generated. Default is "false".	No
includes	comma- or space-separated list of patterns of plug-in manifest files that must be included. All files are included when omitted.	No
includesfile	The name of a file. Each line of this file is taken to be an include pattern.	No
excludes	Comma- or space-separated list of patterns of plug-in manifest files that must be excluded. No files (except default excludes) are excluded when omitted.	No
excludesfile	The name of a file. Each line of this file is taken to be an exclude pattern.	No
defaultexcludes	Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted.	No
whitelist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be included in processing. All plug-ins are included when file omitted.	No
blacklist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be excluded from processing. No plug-ins are excluded when file omitted.	No
usepathresolver	If "true", JPF will try to resolve URL's specified in manifests to check existence of plug-in resources. Default is "false".	No

Parameters specified as nested elements

fileset

Ant's FileSets can be used to select plug-in manifest files for plug-ins to be processed.

Example

<!-- Define custom JPF specific Ant tasks -->
<typedef resource="org/java/plugin/tools/ant/jpf-tasks.properties" />
<!-- Call "jpf-zip" task to process plug-ins packaging every plug-in as
  single ZIP file -->
<jpf-zip
	basedir="${build.home}/plugins"
	includes="*/*.xml"
	destdir="${build.home}/plugins"/>

Manifest Info Tool  

Simple (but quite useful :) task (jpf-info) to read some data from plug-in manifest into project properties. This task is modeled after similar purpose method in plug-in resgistry and covers the same properties as corresponding manifest info interface

Attribute	Description	Required
manifest	Plug-in or plug-in fragment file to read data from.	Yes
propertyid	Name of the property where to put plug-in or plug-in fragment ID.	No
propertyversion	Name of the property where to put plug-in or plug-in fragment version. If no version specified in manifest, the empty string will be used.	No
propertyvendor	Name of the property where to put plug-in or plug-in fragment vendor.	No
propertypluginid	Name of the property where to put plug-in ID (applicable for plug-in fragment manifest only).	No
propertypluginversion	Name of the property where to put plug-in version (applicable for plug-in fragment manifest only). If no version specified in manifest, the empty string will be used.	No
propertymatchingrule	Name of the property where to put plug-in fragment matchin rule (applicable for plug-in fragment manifest only).	No

Example

<!-- Define custom JPF specific Ant tasks -->
<typedef resource="org/java/plugin/tools/ant/jpf-tasks.properties" />
<!-- Call "jpf-info" task to read plug-in ID into "plugin.id" property
        and plug-in version into "plugin.version" property -->
<jpf-info
	manifest="${basedir}/plugin.xml"
	propertyid="plugin.id"
	propertyversion="plugin.version"/>

Version Update Tool  

Task (jpf-version) to automatically updade plug-in versions and version references. This task upgrades vesions build number and optionally version name (see Version class documentation) if plug-in has modified since previous task run. Actual version numbers and timestamps are stored in simple text file in Java properties format.

Attribute	Description	Required
basedir	Directory to resolve relative links. By default is equal to project base directory ${basedir}. The folder should contain non-ziped plain folders with plug-ins and plug-in fragments. Note that this task will modify manifests in this folder (leaving manifest file timestamps unchanged).	No
versionsfile	File where to store versions related data. If not exist, will be created automatically.	Yes
alterreferences	If "true", version references should be upgraded also. Default is "false".	No
timestampversion	If "true", the plug-in timestamp will be included into version name field. Default is "false".	No
verbose	If "true", more detailed report will be generated. Default is "false".	No
includes	comma- or space-separated list of patterns of plug-in manifest files that must be included. All files are included when omitted.	No
includesfile	The name of a file. Each line of this file is taken to be an include pattern.	No
excludes	Comma- or space-separated list of patterns of plug-in manifest files that must be excluded. No files (except default excludes) are excluded when omitted.	No
excludesfile	The name of a file. Each line of this file is taken to be an exclude pattern.	No
defaultexcludes	Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted.	No
whitelist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be included in processing. All plug-ins are included when file omitted.	No
blacklist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be excluded from processing. No plug-ins are excluded when file omitted.	No

Parameters specified as nested elements

fileset

Ant's FileSets can be used to select plug-in manifest files for plug-ins to be processed.

Example

<!-- Define custom JPF specific Ant tasks -->
<typedef resource="org/java/plugin/tools/ant/jpf-tasks.properties" />
<!-- Call "jpf-version" task to update versions of modified plug-ins -->
<jpf-version
	basedir="${build.home}/plugins"
	includes="*/plugin.xml,*/plugin-fragment.xml"
	versionsfile="${basedir}/plugins/versions.properties"
	timestampversion="true"/>

Classpath Tool  

Task (jpf-path) to compose plug-in(s) classpath according to manifest data (libraries and dependencies declarations).

Attribute	Description	Required
basedir	Directory to resolve relative links. By default is equal to project base directory ${basedir}.	No
pathid	Composed path-like structure ID.	One of two attriutes should be set.
pathidref	Path-like structure ID reference.
pluginid	Plug-in ID to compose classpath for.	At least one of two attriutes should be set.
pluginids	Comma separated list of plug-in ID's to compose classpath for.
followexports	If "true", libraries export rules will be taken into account. Default is "true".	No
verbose	If "true", more detailed report will be generated. Default is "false".	No
includes	comma- or space-separated list of patterns of plug-in manifest files that must be included. All files are included when omitted.	No
includesfile	The name of a file. Each line of this file is taken to be an include pattern.	No
excludes	Comma- or space-separated list of patterns of plug-in manifest files that must be excluded. No files (except default excludes) are excluded when omitted.	No
excludesfile	The name of a file. Each line of this file is taken to be an exclude pattern.	No
defaultexcludes	Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted.	No
whitelist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be included in processing. All plug-ins are included when file omitted.	No
blacklist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be excluded from processing. No plug-ins are excluded when file omitted.	No

Parameters specified as nested elements

fileset

Ant's FileSets can be used to select plug-in manifest files for plug-ins to be processed.

Example

<!-- Define custom JPF specific Ant tasks -->
<typedef resource="org/java/plugin/tools/ant/jpf-tasks.properties" />
<!-- Call "jpf-path" task to compose classpath for plug-in "my.plugin" and
  put result in path-like structure with ID "plugin.classpath". -->
<jpf-path
	basedir="${build.home}/plugins"
	includes="*/plugin.xml,*/plugin-fragment.xml"
	pathid="plugin.classpath"
	pluginid="my.plugin"/>

Sorting Tool  

Task (jpf-sort) to sort plug-in(s) in correct build order. Places result into output path-like structure.

Attribute	Description	Required
basedir	Directory to resolve relative links. By default is equal to project base directory ${basedir}.	No
pathid	Composed path-like structure ID.	One of two attriutes should be set.
pathidref	Path-like structure ID reference.
pathmode	Regulates what to place into output path. Possible values are: DIR put plug-in directory into output path BUILD put plug-in's build.xml file into output path MANIFEST put original plug-in manifest file into output path Default value is MANIFEST.	No
reverse	If "true", result entries will be placed into output path in reversed order. Default is "false".	No
verbose	If "true", more detailed report will be generated. Default is "false".	No
includes	comma- or space-separated list of patterns of plug-in manifest files that must be included. All files are included when omitted.	No
includesfile	The name of a file. Each line of this file is taken to be an include pattern.	No
excludes	Comma- or space-separated list of patterns of plug-in manifest files that must be excluded. No files (except default excludes) are excluded when omitted.	No
excludesfile	The name of a file. Each line of this file is taken to be an exclude pattern.	No
defaultexcludes	Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted.	No
whitelist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be included in processing. All plug-ins are included when file omitted.	No
blacklist	The name of a file. Each line of this file is taken to be an ID or UID of plug-in to be excluded from processing. No plug-ins are excluded when file omitted.	No

Parameters specified as nested elements

fileset

Ant's FileSets can be used to select plug-in manifest files for plug-ins to be processed.

Example

<!-- Define custom JPF specific Ant tasks -->
<typedef resource="org/java/plugin/tools/ant/jpf-tasks.properties" />
<!-- Call "jpf-sort" task to sort all plug-ins in correct build order and
  put their folders in path-like structure with ID "plugins". -->
<jpf-sort
	basedir="${build.home}/plugins"
	includes="*/plugin.xml,*/plugin-fragment.xml"
	pathid="plugins"
	pathmode="DIR"/>

Look at the source code of JPF-Demo application to get working example of tools usage.