JPF Tools Reference

All 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

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 Plug-ins "repository" folder. 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
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 Plug-ins "repository" folder. 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
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 Plug-ins "repository" folder. 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
destfile Target archive file. Yes
Plug-ins un-archiving task (jpf-unpack).
Attribute Description Required
basedir Plug-ins "repository" folder. 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
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 Plug-ins "repository" folder. Yes
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
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"/>

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