org.pantsbuild.tools.jar

Class JarBuilder

java.lang.Object

org.pantsbuild.tools.jar.JarBuilder

All Implemented Interfaces:

Closeable, AutoCloseable

public class JarBuilder
extends Object
implements Closeable

A utility than can create or update jar archives with special handling of duplicate entries.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JarBuilder.DuplicateAction Identifies an action to take when duplicate jar entries are encountered.
static class	JarBuilder.DuplicateEntryException Indicates a duplicate jar entry is being rejected.
static class	JarBuilder.DuplicateHandler Handles duplicate jar entries by selecting an appropriate action based on the entry path.
static class	JarBuilder.DuplicatePolicy Encapsulates a policy for treatment of duplicate jar entries.
static interface	JarBuilder.Entry Represents an entry to be added to a jar.
static class	JarBuilder.IndexingException Indicates a problem indexing a pre-existing jar that will be added or updated to the target jar.
static class	JarBuilder.JarBuilderException Indicates a problem encountered when building up a jar's contents for writing out.
static class	JarBuilder.JarCreationException Indicates a problem writing out a jar.
static interface	JarBuilder.Listener An interface for those interested in the progress of writing the target jar.
static interface	JarBuilder.Source Identifies a source for jar entries.

Constructor Summary

Constructors

Constructor and Description
JarBuilder(File target) Creates a JarBuilder that will write scheduled jar additions to target upon write().
JarBuilder(File target, JarBuilder.Listener listener) Creates a JarBuilder that will write scheduled jar additions to target upon write().

Method Summary

Modifier and Type	Method and Description
JarBuilder	add(ByteSource contents, String jarPath) Schedules addition of the given contents to the entry at jarPath.
JarBuilder	addDirectory(File directory, Optional<String> jarPath) Schedules recursive addition of all files contained within directory to the resulting jar.
JarBuilder	addFile(File file, String jarPath) Schedules addition of the given file's contents to the entry at jarPath.
JarBuilder	addJar(File file) Schedules addition of the given jar's contents to the file at jarPath.
void	close()
JarBuilder	useCustomManifest(CharSequence customManifest) Registers the given Manifest to be used in the jar written out by write().
JarBuilder	useCustomManifest(File customManifest) Registers the given Manifest to be used in the jar written out by write().
JarBuilder	useCustomManifest(org.pantsbuild.tools.jar.JarBuilder.NamedByteSource customManifest) Registers the given Manifest to be used in the jar written out by write().
JarBuilder	useCustomManifest(Manifest customManifest) Registers the given Manifest to be used in the jar written out by write().
File	write() Creates a jar at the configured target path applying the scheduled additions and skipping any duplicate entries found.
File	write(boolean compress) Creates a jar at the configured target path applying the scheduled additions and skipping any duplicate entries found.
File	write(boolean compress, JarBuilder.DuplicateHandler duplicateHandler, Iterable<Pattern> skipPatterns) Creates a jar at the configured target path applying the scheduled additions per the given duplicateHandler.
File	write(boolean compress, JarBuilder.DuplicateHandler duplicateHandler, Pattern... skipPatterns) Creates a jar at the configured target path applying the scheduled additions per the given duplicateHandler.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JarBuilder

public JarBuilder(File target)

Creates a JarBuilder that will write scheduled jar additions to target upon write().

If the target exists an attempt will be made to over-write it and if it does not exist a then a new jar will be created at its path.

Parameters:

target - The target jar file to write.

JarBuilder

public JarBuilder(File target,
                  JarBuilder.Listener listener)

Creates a JarBuilder that will write scheduled jar additions to target upon write().

If the target does not exist a new jar will be created at its path.

Parameters:

target - The target jar file to write.

Method Detail

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

add

public JarBuilder add(ByteSource contents,
                      String jarPath)

Schedules addition of the given contents to the entry at jarPath. In addition, individual parent directory entries will be created when this builder is written in he spirit of mkdir -p.

Parameters:

contents - The contents of the entry to add.

jarPath - The path of the entry to add.

Returns:

This builder for chaining.

addDirectory

public JarBuilder addDirectory(File directory,
                               Optional<String> jarPath)

Schedules recursive addition of all files contained within directory to the resulting jar. The path of each file relative to directory will be used for the corresponding jar entry path. If a jarPath is present then all subtree entries will be prefixed with it.

Parameters:

directory - An existing directory to add to the jar.

jarPath - An optional base path to graft the directory onto.

Returns:

This builder for chaining.

addFile

public JarBuilder addFile(File file,
                          String jarPath)

Schedules addition of the given file's contents to the entry at jarPath. In addition, individual parent directory entries will be created when this builder is written in the spirit of mkdir -p.

Parameters:

file - An existing file to add to the jar.

jarPath - The path of the entry to add.

Returns:

This builder for chaining.

addJar

public JarBuilder addJar(File file)

Schedules addition of the given jar's contents to the file at jarPath. Even if the jar does not contain individual parent directory entries, they will be added for each entry added.

Parameters:

file - The path of the jar to add.

Returns:

This builder for chaining.

useCustomManifest

public JarBuilder useCustomManifest(Manifest customManifest)

Registers the given Manifest to be used in the jar written out by write().

Parameters:

customManifest - The manifest to use for the built jar.

Returns:

This builder for chaining.

useCustomManifest

public JarBuilder useCustomManifest(File customManifest)

Registers the given Manifest to be used in the jar written out by write().

Parameters:

customManifest - The manifest to use for the built jar.

Returns:

This builder for chaining.

useCustomManifest

public JarBuilder useCustomManifest(CharSequence customManifest)

Registers the given Manifest to be used in the jar written out by write().

Parameters:

customManifest - The manifest to use for the built jar.

Returns:

This builder for chaining.

useCustomManifest

public JarBuilder useCustomManifest(org.pantsbuild.tools.jar.JarBuilder.NamedByteSource customManifest)

Registers the given Manifest to be used in the jar written out by write().

Parameters:

customManifest - The manifest to use for the built jar.

Returns:

This builder for chaining.

write

public File write()
           throws IOException

Creates a jar at the configured target path applying the scheduled additions and skipping any duplicate entries found. Entries will not be compressed.

Returns:

The jar file that was written.

Throws:

IOException - if there was a problem writing the jar file.

write

public File write(boolean compress)
           throws IOException

Creates a jar at the configured target path applying the scheduled additions and skipping any duplicate entries found.

Parameters:

compress - Pass true to compress all jar entries; otherwise, they will just be stored.

Returns:

The jar file that was written.

Throws:

IOException - if there was a problem writing the jar file.

write

public File write(boolean compress,
                  JarBuilder.DuplicateHandler duplicateHandler,
                  Pattern... skipPatterns)
           throws IOException

Creates a jar at the configured target path applying the scheduled additions per the given duplicateHandler.

Parameters:

compress - Pass true to compress all jar entries; otherwise, they will just be stored.

duplicateHandler - A handler for dealing with duplicate entries.

skipPatterns - An optional list of patterns that match entry paths that should be excluded.

Returns:

The jar file that was written.

Throws:

IOException - if there was a problem writing the jar file.

JarBuilder.DuplicateEntryException - if the the policy in effect for an entry is JarBuilder.DuplicateAction.THROW and that entry is a duplicate.

write

public File write(boolean compress,
                  JarBuilder.DuplicateHandler duplicateHandler,
                  Iterable<Pattern> skipPatterns)
           throws JarBuilder.DuplicateEntryException,
                  IOException

Creates a jar at the configured target path applying the scheduled additions per the given duplicateHandler.

Parameters:

compress - Pass true to compress all jar entries; otherwise, they will just be stored.

duplicateHandler - A handler for dealing with duplicate entries.

skipPatterns - An optional sequence of patterns that match entry paths that should be excluded.

Returns:

The jar file that was written.

Throws:

IOException - if there was a problem writing the jar file.

JarBuilder.DuplicateEntryException - if the the policy in effect for an entry is JarBuilder.DuplicateAction.THROW and that entry is a duplicate.