dsto.dfc.tools
Class JarX

java.lang.Object
  extended by dsto.dfc.tools.JarX

public class JarX
extends Object

A JAR file generator tool that operates by taking a one or more 'root' resource patterns (eg the main class of an application or a set of library package names) and generates a JAR containing the root resources plus any referenced resources.

NOTE: All resources must be named using the resource syntax: ie most importantly classes are NOT referenced by their logical class name. For example, the logical class name com.frobsoft.stuff.Widget should be referred to by the resource name "com/frobsoft/stuff/Widget.class".

TODO:

Version:
$Revision$
Author:
Matthew Phillips
See Also:
for a Ant build task that uses JarX.

Constructor Summary
JarX(File archiveFile)
          Create an instance of JarX writing to a ZIP archive.
JarX(File archiveFile, boolean useJarFormat)
          Create an instance of JarX writing to a ZIP or JAR archive.
 
Method Summary
 void addExcludeMatchers(List newExcludes)
          Add a list of ResourceMatcher's to the excludes list.
 void addExcludeMatchers(ResourceMatcher[] newExcludes)
          Convenience version of addExcludeMatchers.
 void addExcludeRegexps(List newExcludes)
          Add a set of regular expression rules to the exclude set.
 void addExcludeRegexps(String[] newExcludes)
          Convenience version of addExcludes.
 void addExcludes(List newExcludes)
          Add simple string or wildcard rules to the exclude set.
 void addExcludes(String[] newExcludes)
          Convenience version of addExcludes.
protected  void addResource(String resourceName, byte[] resourceData)
          Add a resource, and all the resources it references in the case of classes, to the archive.
protected  void addResourceFromClasspath(String resourceName)
          Add a resource (via addResource()) found by searching the classpath.
protected  void addResourceFromFile(String resourceName, File file)
          Add a resource stored in a file (via addResource()).
protected  void addResourceFromZip(String resourceName, ZipFile zipFile)
          Add a resource stored in a ZIP archive (via addResource()).
 void addRootMatchers(List newResourceMatchers)
          Add a list of ResourceMatcher's to the root resources list.
 void addRootMatchers(ResourceMatcher[] newResourceMatchers)
          Convenience version of addRootMatchers.
 void addRootRegexps(List regexps)
          Add a list of regular expressions to the root resources list.
 void addRootRegexps(String[] regexps)
          Convenience version of addRootRegexps.
 void addRoots(List newRoots)
          Add a list of resource names as roots of the resource tree to archive.
 void addRoots(String[] newRoots)
          Convenience version of addRoots.
static String classToResourceName(String className)
          Generate the resource name for a logical class name.
 void clearExcludes()
          Clear the exclude rule set.
protected  void closeOpenZips()
          Close any ZIP archives opened via findOrOpenZip().
 void dispose()
           
protected static void error(String message)
          Log an error.
protected  String[] findClassResources(String className, byte[] classData)
          Return a list of resources referenced by a class.
protected  ZipFile findOrOpenZip(String zipFileName)
          Find an already opened ZIP archive (cached in openZips) or open it.
static String[] getSystemClassPath()
          Get the JVM system class path as an array of String's.
protected  boolean isResourceExcludedByMatch(String resourceName)
          Test if a resource is matched by the excludes set.
protected  boolean isResourceIncludedByMatch(String resourceName)
          Tests if a resource is in the root include set by matching a pettern.
protected  boolean isResourceIncludedByName(String resourceName)
          Tests if a resource is in the root include set directly by name.
protected  boolean isResourceStored(String resourceName)
          Test if a resource has been stored in the archive.
protected static boolean isSystemClass(String className)
          Test if a given class name is a 'system' class, ie a class provided by the JRE or a core extension.
protected  boolean isZipArchive(String path)
          Test if a path name refers to a ZIP archive.
protected static void log(String message)
          Log a message.
protected  byte[] readResourceData(String path, String resourceName)
          Read the data associated with a resource from either a ZIP archive or a file.
protected  byte[] readResourceDataFromFile(String resourceName, File resourceFile)
          Read resource data from a file.
protected  byte[] readResourceDataFromZip(String resourceName, ZipFile zipFile)
          Read resource data from a ZIP archive.
 void run()
          Start archive creation.
protected  void runDirect()
          Run the archive operation in 'direct' mode: scan each root resource in roots and add it via addResourceFromClasspath().
protected  void runFullScan()
          Run the archive operation in 'full scan' mode: scan all resources in the classpath looking for resource names that match those in roots and rootMatchers.
protected  void scanArchive(String archivePath)
          Scan a ZIP archive for resources that match those in the root set.
protected  void scanDirectory(File directory, String resourcePath)
          Scan a directory and all its subdirectories for resources that match those in the root set.
 void setAutoFindResources(boolean newValue)
          Set to true if JarX should include resources guessed by looking at calls to Class.getResource().
 void setClassPath(String[] newClassPath)
          Set the path used to find resources.
 void setMainClassName(String mainClassName)
          Set the name (not the resource name) of the class to specify as the main application in the JAR manifest (the "Main-Class" attribute).
 void setManifestFile(File newManifestFile)
          Set the file to use as the base of the JAR manifest.
protected  void setupDefaultExcludes()
           
 void setUseJarFormat(boolean useJarFormat)
          Set whether to generate a JAR-compatible archive (generate a manifest and use a java.util.JarOutputStream).
protected  boolean shouldIncludeImportedResource(String resourceName)
          Test if a resource imported by another resource should be included using the rules: (a) resource must not be a system class and (b) resource must either be included directly by name OR not be excluded by a pattern.
protected  boolean shouldIncludeResource(String resourceName)
          Test if a resource found by scanning the classpath should be included using the rules: (a) resource must not be a system class and (b) resource must EITHER be included directly by name OR matched by a pattern and not excluded by a pattern (ie exclude patterns override include patterns, but not inclusion directly by name).
protected  boolean shouldStoreResource(String resourceName)
          Test if a resource should be stored ie (a) is not already stored (b) is included in the root resource set and (c) is not in the excludes set.
protected  void storeResource(String resourceName, byte[] resourceData)
          Store a resource in the output archive.
protected static void warn(String message)
          Log a warning.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JarX

public JarX(File archiveFile)
Create an instance of JarX writing to a ZIP archive.

Parameters:
archiveFile - The file to write the ZIP archive to.

JarX

public JarX(File archiveFile,
            boolean useJarFormat)
Create an instance of JarX writing to a ZIP or JAR archive.

Parameters:
archiveFile - The file to write the ZIP archive to.
useJarFormat - True if the archive should be JAR-compatible.
See Also:
setUseJarFormat(boolean)
Method Detail

getSystemClassPath

public static String[] getSystemClassPath()
Get the JVM system class path as an array of String's.


classToResourceName

public static String classToResourceName(String className)
Generate the resource name for a logical class name.

Parameters:
className - The name of a class eg "com.frobsoft.Widget".
Returns:
The resource name of the class eg "com/frobsoft/Widget.class".

setUseJarFormat

public void setUseJarFormat(boolean useJarFormat)
Set whether to generate a JAR-compatible archive (generate a manifest and use a java.util.JarOutputStream).

See Also:
setManifestFile(java.io.File), setMainClassName(java.lang.String)

setManifestFile

public void setManifestFile(File newManifestFile)
Set the file to use as the base of the JAR manifest. Implicitly sets useJarFormat to true.

See Also:
setUseJarFormat(boolean)

setMainClassName

public void setMainClassName(String mainClassName)
Set the name (not the resource name) of the class to specify as the main application in the JAR manifest (the "Main-Class" attribute). This class should define a 'static void main (String [])' method. Implicitly sets useJarFormat to true and adds the class to the root resource set if not already added.

Example: setMainClassName ("com.frobsoft.Main").

See Also:
setUseJarFormat(boolean)

setClassPath

public void setClassPath(String[] newClassPath)
Set the path used to find resources.

Parameters:
newClassPath - The new class path. Must contain either directory paths or ZIP/JAR file names.

clearExcludes

public void clearExcludes()
Clear the exclude rule set.

See Also:
addExcludes(java.util.List)

addExcludes

public void addExcludes(String[] newExcludes)
Convenience version of addExcludes.

Parameters:
newExcludes - An array of exclude expressions.
See Also:
for full description.

addExcludes

public void addExcludes(List newExcludes)
Add simple string or wildcard rules to the exclude set. The default exclude set exludes the java and javax packages plus the sun and com.sun packages ("java/*", "javax/*", "com/sun/*". sun/*").

Parameters:
newExcludes - A list of strings to used as exclude wildcard patterns, where "*" can be used as a kleene star operator.
See Also:
- you can use regular expressions too!

addExcludeRegexps

public void addExcludeRegexps(String[] newExcludes)
                       throws IllegalArgumentException
Convenience version of addExcludes.

Parameters:
newExcludes - A list of regular expressions to add to the exclude set.
Throws:
IllegalArgumentException
See Also:
addExcludeRegexps(java.util.List)

addExcludeRegexps

public void addExcludeRegexps(List newExcludes)
                       throws IllegalArgumentException
Add a set of regular expression rules to the exclude set. The regular expressions syntax is the Perl 5 syntax supported by OROMatcher (http://jakarta.apache.org/oro/index.html).

Parameters:
newExcludes - A list of regular expression strings.
Throws:
IllegalArgumentException - if one of the regular expressions has invalid syntax.

addExcludeMatchers

public void addExcludeMatchers(ResourceMatcher[] newExcludes)
Convenience version of addExcludeMatchers.

See Also:
addExcludeMatchers(java.util.List)

addExcludeMatchers

public void addExcludeMatchers(List newExcludes)
Add a list of ResourceMatcher's to the excludes list.

Parameters:
newExcludes - A list of ResourceMatcher instances.
See Also:
ResourceMatcher, RegexpResourceMatcher, WildcardResourceMatcher

addRoots

public void addRoots(String[] newRoots)
Convenience version of addRoots.

See Also:
addRoots(java.util.List)

addRoots

public void addRoots(List newRoots)
Add a list of resource names as roots of the resource tree to archive. The resource names may contain the '*' as a wildcard (kleene star) operator.

Parameters:
newRoots - A list of resource names.
See Also:
addRootRegexps(java.util.List), WildcardResourceMatcher

addRootRegexps

public void addRootRegexps(String[] regexps)
Convenience version of addRootRegexps.

See Also:
addRootRegexps(java.util.List)

addRootRegexps

public void addRootRegexps(List regexps)
Add a list of regular expressions to the root resources list.

Parameters:
regexps - a value of type 'List'

addRootMatchers

public void addRootMatchers(ResourceMatcher[] newResourceMatchers)
Convenience version of addRootMatchers.

See Also:
addRootMatchers(java.util.List)

addRootMatchers

public void addRootMatchers(List newResourceMatchers)
Add a list of ResourceMatcher's to the root resources list.

Parameters:
newResourceMatchers - A list of ResourceMatcher instances.
See Also:
ResourceMatcher, RegexpResourceMatcher, WildcardResourceMatcher

setAutoFindResources

public void setAutoFindResources(boolean newValue)
Set to true if JarX should include resources guessed by looking at calls to Class.getResource().


run

public void run()
         throws IOException
Start archive creation.

Throws:
IOException - if an error ocurred while creating the archive.

dispose

public void dispose()

setupDefaultExcludes

protected void setupDefaultExcludes()

isResourceIncludedByName

protected boolean isResourceIncludedByName(String resourceName)
Tests if a resource is in the root include set directly by name.


isResourceIncludedByMatch

protected boolean isResourceIncludedByMatch(String resourceName)
Tests if a resource is in the root include set by matching a pettern.


isResourceExcludedByMatch

protected boolean isResourceExcludedByMatch(String resourceName)
Test if a resource is matched by the excludes set.


isResourceStored

protected boolean isResourceStored(String resourceName)
Test if a resource has been stored in the archive.


shouldStoreResource

protected boolean shouldStoreResource(String resourceName)
Test if a resource should be stored ie (a) is not already stored (b) is included in the root resource set and (c) is not in the excludes set.

Parameters:
resourceName - a value of type 'String'
Returns:
a value of type 'boolean'
See Also:
return true;#shouldIncludeResource

shouldIncludeResource

protected boolean shouldIncludeResource(String resourceName)
Test if a resource found by scanning the classpath should be included using the rules: (a) resource must not be a system class and (b) resource must EITHER be included directly by name OR matched by a pattern and not excluded by a pattern (ie exclude patterns override include patterns, but not inclusion directly by name).

Parameters:
resourceName - a value of type 'String'
Returns:
a value of type 'boolean'

shouldIncludeImportedResource

protected boolean shouldIncludeImportedResource(String resourceName)
Test if a resource imported by another resource should be included using the rules: (a) resource must not be a system class and (b) resource must either be included directly by name OR not be excluded by a pattern.

Parameters:
resourceName - a value of type 'String'
Returns:
a value of type 'boolean'

isZipArchive

protected boolean isZipArchive(String path)
Test if a path name refers to a ZIP archive. Currently returns true if the path has a '.zip' or '.jar' extension.


runDirect

protected void runDirect()
Run the archive operation in 'direct' mode: scan each root resource in roots and add it via addResourceFromClasspath(). This method should be slightly faster than that used by runFullScan() but will ignore any resources specified via patterns in in rootMatchers.

See Also:
runFullScan(), addResourceFromClasspath(java.lang.String)

runFullScan

protected void runFullScan()
Run the archive operation in 'full scan' mode: scan all resources in the classpath looking for resource names that match those in roots and rootMatchers.

See Also:
runDirect(), scanArchive(java.lang.String), scanDirectory(java.io.File, java.lang.String)

scanArchive

protected void scanArchive(String archivePath)
Scan a ZIP archive for resources that match those in the root set.

Parameters:
archivePath - The path to a ZIP-format archive file.

scanDirectory

protected void scanDirectory(File directory,
                             String resourcePath)
Scan a directory and all its subdirectories for resources that match those in the root set.

Parameters:
directory - The directory to scan.
resourcePath - The resource name of the directory (ie its relative path from the root of the scan).

addResourceFromZip

protected void addResourceFromZip(String resourceName,
                                  ZipFile zipFile)
                           throws IOException
Add a resource stored in a ZIP archive (via addResource()).

Parameters:
resourceName - The name of the resource.
zipFile - The ZIP file to read from.
Throws:
IOException - if an IO error occurs.
See Also:
addResource(java.lang.String, byte[])

addResourceFromFile

protected void addResourceFromFile(String resourceName,
                                   File file)
                            throws IOException
Add a resource stored in a file (via addResource()).

Parameters:
resourceName - The name of the resource.
file - The file to read from.
Throws:
IOException - if an IO error occurs.
See Also:
addResource(java.lang.String, byte[])

addResourceFromClasspath

protected void addResourceFromClasspath(String resourceName)
                                 throws IOException
Add a resource (via addResource()) found by searching the classpath.

Parameters:
resourceName - The resource name.
Throws:
IOException - if an IO error occurs, including if the resource is not found.
See Also:
setClassPath(java.lang.String[]), addResource(java.lang.String, byte[])

addResource

protected void addResource(String resourceName,
                           byte[] resourceData)
                    throws IOException
Add a resource, and all the resources it references in the case of classes, to the archive.

Parameters:
resourceName - The name of the resource.
resourceData - The resource data.
Throws:
IOException - if an IO exception occurs while writing the resource.
See Also:
findClassResources(java.lang.String, byte[])

readResourceData

protected byte[] readResourceData(String path,
                                  String resourceName)
                           throws IOException
Read the data associated with a resource from either a ZIP archive or a file.

Parameters:
path - The path to a ZIP archive or a file.
resourceName - The name of the resource.
Returns:
The resource data.
Throws:
IOException - if the data could not be read.
See Also:
readResourceDataFromFile(java.lang.String, java.io.File), readResourceDataFromZip(java.lang.String, java.util.zip.ZipFile)

readResourceDataFromFile

protected byte[] readResourceDataFromFile(String resourceName,
                                          File resourceFile)
                                   throws IOException
Read resource data from a file.

Parameters:
resourceName - The name of the resource.
resourceFile - The file to read from.
Returns:
The resource data.
Throws:
IOException - if the data could not be read.

readResourceDataFromZip

protected byte[] readResourceDataFromZip(String resourceName,
                                         ZipFile zipFile)
                                  throws IOException
Read resource data from a ZIP archive.

Parameters:
resourceName - The name of the resource.
zipFile - The ZIP archive to read from.
Returns:
The resource data.
Throws:
IOException - if the data could not be read.

storeResource

protected void storeResource(String resourceName,
                             byte[] resourceData)
                      throws IOException
Store a resource in the output archive.

Parameters:
resourceName - The resource name.
resourceData - The resource data.
Throws:
IOException - if an IO error occurred.

findOrOpenZip

protected ZipFile findOrOpenZip(String zipFileName)
                         throws IOException
Find an already opened ZIP archive (cached in openZips) or open it.

Parameters:
zipFileName - The file name of the ZIP archive.
Returns:
The ZIP archive opened for reading.
Throws:
IOException - if an IO error occurred.
See Also:
closeOpenZips()

closeOpenZips

protected void closeOpenZips()
Close any ZIP archives opened via findOrOpenZip().

See Also:
findOrOpenZip(java.lang.String)

error

protected static void error(String message)
Log an error.


warn

protected static void warn(String message)
Log a warning.


log

protected static void log(String message)
Log a message.


findClassResources

protected String[] findClassResources(String className,
                                      byte[] classData)
                               throws IOException
Return a list of resources referenced by a class. If autoFindResources is true, will also scan for resources referenced via calls to Class.getResource().

The logic in this method is shamelessly copied from the original in ZipLock: see class doc for author acknowledgements and contact info.

Parameters:
className - The class resource name.
classData - The class resource data.
Returns:
An array of resources used by the class.
Throws:
IOException - if an IO error occurs.

isSystemClass

protected static boolean isSystemClass(String className)
Test if a given class name is a 'system' class, ie a class provided by the JRE or a core extension.



Copyright © 2008 Commonwealth of Australia