co.paralleluniverse.capsule

Class Jar

java.lang.Object

co.paralleluniverse.capsule.Jar

public class Jar
extends Object

A JAR file that can be easily modified. This class is not thread-safe.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Jar.Filter

Constructor Summary

Constructors

Constructor and Description
Jar() Creates a new, empty, JAR
Jar(File jar) Reads in the JAR from the given File.
Jar(InputStream jar) Reads in the JAR from the given InputStream.
Jar(Jar jar) Creates a copy
Jar(Path jar) Reads in the JAR from the given Path.
Jar(String jar) Reads in the JAR from the given path.

Method Summary

Modifier and Type	Method and Description
Jar	addClass(Class<?> clazz) Adds a class entry to this JAR.
Jar	addEntries(Path path, Path dirOrZip) Adds a directory (with all its subdirectories) or the contents of a zip/JAR to this JAR.
Jar	addEntries(Path path, Path dirOrZip, Jar.Filter filter) Adds a directory (with all its subdirectories) or the contents of a zip/JAR to this JAR.
Jar	addEntries(Path path, ZipInputStream zip) Adds the contents of the zip/JAR contained in the given byte array to this JAR.
Jar	addEntries(Path path, ZipInputStream zip, Jar.Filter filter) Adds the contents of the zip/JAR contained in the given byte array to this JAR.
Jar	addEntries(String path, Path dirOrZip) Adds a directory (with all its subdirectories) or the contents of a zip/JAR to this JAR.
Jar	addEntries(String path, Path dirOrZip, Jar.Filter filter) Adds a directory (with all its subdirectories) or the contents of a zip/JAR to this JAR.
Jar	addEntry(Path path, InputStream is) Adds an entry to this JAR.
Jar	addEntry(Path path, Path file) Adds an entry to this JAR.
Jar	addEntry(Path path, String file) Adds an entry to this JAR.
Jar	addEntry(String path, byte[] content) Adds an entry to this JAR.
Jar	addEntry(String path, File file) Adds an entry to this JAR.
Jar	addEntry(String path, InputStream is) Adds an entry to this JAR.
Jar	addEntry(String path, String file) Adds an entry to this JAR.
Jar	addPackageOf(Class<?> clazz) Adds the contents of a Java package to this JAR.
Jar	addPackageOf(Class<?> clazz, Jar.Filter filter) Adds the contents of a Java package to this JAR.
Jar	close()
String	getAttribute(String name) Returns an attribute's value from this JAR's manifest's main section.
String	getAttribute(String section, String name) Returns an attribute's value from a non-main section of this JAR's manifest.
List<String>	getListAttribute(String name) Returns an attribute's list value from this JAR's manifest's main section.
List<String>	getListAttribute(String section, String name) Returns an attribute's list value from a non-main section of this JAR's manifest.
Manifest	getManifest() Returns the manifest of this JAR.
Map<String,String>	getMapAttribute(String name, String defaultValue) Returns an attribute's map value from this JAR's manifest's main section.
Map<String,String>	getMapAttribute(String section, String name, String defaultValue) Returns an attribute's map value from a non-main section of this JAR's manifest.
static Jar.Filter	matches(String regex)
static Jar.Filter	notMatches(String regex)
Jar	setAttribute(String name, String value) Sets an attribute in the main section of the manifest.
Jar	setAttribute(String section, String name, String value) Sets an attribute in a non-main section of the manifest.
Jar	setJarPrefix(Path file) Sets a file whose contents will be prepended to the JAR file's data.
Jar	setJarPrefix(String value) Sets a string that will be prepended to the JAR file's data.
Jar	setListAttribute(String name, Collection<?> values) Sets an attribute in the main section of the manifest to a list.
Jar	setListAttribute(String section, String name, Collection<?> values) Sets an attribute in a non-main section of the manifest to a list.
Jar	setMapAttribute(String name, Map<String,?> values) Sets an attribute in the main section of the manifest to a map.
Jar	setMapAttribute(String section, String name, Map<String,?> values) Sets an attribute in a non-main section of the manifest to a map.
Jar	setOutput(File out) Same as setOutputStream(new FileOutputStream(out)).
Jar	setOutput(Path out) Same as setOutputStream(Files.newOutputStream(out)).
Jar	setOutputStream(OutputStream os) Sets an OutputStream to which the JAR will be written.
Jar	setPacker(Pack200.Packer packer) Sets a Pack200 packer to use when writing the JAR.
Jar	setReallyExecutable(boolean value) If set to true true, a header will be added to the JAR file when written, that will make the JAR an executable file in POSIX environments.
byte[]	toByteArray() Returns this JAR file as an array of bytes.
static InputStream	toInputStream(String str, Charset charset) Turns a String into an InputStream containing the string's encoded characters.
File	write(File file) Writes this JAR to a file.
Path	write(Path path) Writes this JAR to a file.
void	write(String file) Writes this JAR to a file.
<T extends OutputStream> T	write(T os) Writes this JAR to an output stream, and closes the stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

Jar

public Jar()

Creates a new, empty, JAR

Jar

public Jar(InputStream jar)
    throws IOException

Reads in the JAR from the given InputStream. Modifications will not be made to the original JAR file, but to a new copy, which is then written with write().

Throws:

IOException

Jar

public Jar(Path jar)
    throws IOException

Reads in the JAR from the given Path. Modifications will not be made to the original JAR file, but to a new copy, which is then written with write().

Throws:

IOException

Jar

public Jar(File jar)
    throws IOException

Reads in the JAR from the given File. Modifications will not be made to the original JAR file, but to a new copy, which is then written with write().

Throws:

IOException

Jar

public Jar(String jar)
    throws IOException

Reads in the JAR from the given path. Modifications will not be made to the original JAR file, but to a new copy, which is then written with write().

Throws:

IOException

Jar

public Jar(Jar jar)

Creates a copy

Method Detail

getManifest

public Manifest getManifest()

Returns the manifest of this JAR. Modifications to the manifest will be reflected in the written JAR, provided they are done before any entries are added with addEntry().

setAttribute

public final Jar setAttribute(String name,
                              String value)

Sets an attribute in the main section of the manifest.

Parameters:

name - the attribute's name

value - the attribute's value

Returns:

this

Throws:

IllegalStateException - if entries have been added or the JAR has been written prior to calling this methods.

setAttribute

public final Jar setAttribute(String section,
                              String name,
                              String value)

Sets an attribute in a non-main section of the manifest.

Parameters:

section - the section's name

name - the attribute's name

value - the attribute's value

Returns:

this

Throws:

IllegalStateException - if entries have been added or the JAR has been written prior to calling this methods.

setListAttribute

public Jar setListAttribute(String name,
                            Collection<?> values)

Sets an attribute in the main section of the manifest to a list. The list elements will be joined with a single whitespace character.

Parameters:

name - the attribute's name

values - the attribute's value

Returns:

this

Throws:

IllegalStateException - if entries have been added or the JAR has been written prior to calling this methods.

setListAttribute

public Jar setListAttribute(String section,
                            String name,
                            Collection<?> values)

Sets an attribute in a non-main section of the manifest to a list. The list elements will be joined with a single whitespace character.

Parameters:

section - the section's name

name - the attribute's name

values - the attribute's value

Returns:

this

Throws:

IllegalStateException - if entries have been added or the JAR has been written prior to calling this methods.

setMapAttribute

public Jar setMapAttribute(String name,
                           Map<String,?> values)

Sets an attribute in the main section of the manifest to a map. The map entries will be joined with a single whitespace character, and each key-value pair will be joined with a '='.

Parameters:

name - the attribute's name

values - the attribute's value

Returns:

this

Throws:

IllegalStateException - if entries have been added or the JAR has been written prior to calling this methods.

setMapAttribute

public Jar setMapAttribute(String section,
                           String name,
                           Map<String,?> values)

Sets an attribute in a non-main section of the manifest to a map. The map entries will be joined with a single whitespace character, and each key-value pair will be joined with a '='.

Parameters:

section - the section's name

name - the attribute's name

values - the attribute's value

Returns:

this

Throws:

IllegalStateException - if entries have been added or the JAR has been written prior to calling this methods.

getAttribute

public String getAttribute(String name)

Returns an attribute's value from this JAR's manifest's main section.

Parameters:

name - the attribute's name

getAttribute

public String getAttribute(String section,
                           String name)

Returns an attribute's value from a non-main section of this JAR's manifest.

Parameters:

section - the manifest's section

name - the attribute's name

getListAttribute

public List<String> getListAttribute(String name)

Returns an attribute's list value from this JAR's manifest's main section. The attributes string value will be split on whitespace into the returned list. The returned list may be safely modified.

Parameters:

name - the attribute's name

getListAttribute

public List<String> getListAttribute(String section,
                                     String name)

Returns an attribute's list value from a non-main section of this JAR's manifest. The attributes string value will be split on whitespace into the returned list. The returned list may be safely modified.

Parameters:

section - the manifest's section

name - the attribute's name

getMapAttribute

public Map<String,String> getMapAttribute(String name,
                                          String defaultValue)

Returns an attribute's map value from this JAR's manifest's main section. The attributes string value will be split on whitespace into map entries, and each entry will be split on '=' to get the key-value pair. The returned map may be safely modified.

Parameters:

name - the attribute's name

getMapAttribute

public Map<String,String> getMapAttribute(String section,
                                          String name,
                                          String defaultValue)

Returns an attribute's map value from a non-main section of this JAR's manifest. The attributes string value will be split on whitespace into map entries, and each entry will be split on '=' to get the key-value pair. The returned map may be safely modified.

Parameters:

section - the manifest's section

name - the attribute's name

addEntry

public Jar addEntry(String path,
                    InputStream is)
             throws IOException

Adds an entry to this JAR.

Parameters:

path - the entry's path within the JAR

is - the entry's content

Returns:

this

Throws:

IOException

addEntry

public Jar addEntry(String path,
                    byte[] content)
             throws IOException

Adds an entry to this JAR.

Parameters:

path - the entry's path within the JAR

content - the entry's content

Returns:

this

Throws:

IOException

addEntry

public Jar addEntry(Path path,
                    InputStream is)
             throws IOException

Adds an entry to this JAR.

Parameters:

path - the entry's path within the JAR

is - the entry's content

Returns:

this

Throws:

IOException

addEntry

public Jar addEntry(Path path,
                    Path file)
             throws IOException

Adds an entry to this JAR.

Parameters:

path - the entry's path within the JAR

file - the file to add as an entry

Returns:

this

Throws:

IOException

addEntry

public Jar addEntry(Path path,
                    String file)
             throws IOException

Adds an entry to this JAR.

Parameters:

path - the entry's path within the JAR

file - the path of the file to add as an entry

Returns:

this

Throws:

IOException

addEntry

public Jar addEntry(String path,
                    File file)
             throws IOException

Adds an entry to this JAR.

Parameters:

path - the entry's path within the JAR

file - the file to add as an entry

Returns:

this

Throws:

IOException

addEntry

public Jar addEntry(String path,
                    String file)
             throws IOException

Adds an entry to this JAR.

Parameters:

path - the entry's path within the JAR

file - the path of the file to add as an entry

Returns:

this

Throws:

IOException

addClass

public Jar addClass(Class<?> clazz)
             throws IOException

Adds a class entry to this JAR.

Parameters:

clazz - the class to add to the JAR.

Returns:

this

Throws:

IOException

addEntries

public Jar addEntries(Path path,
                      Path dirOrZip,
                      Jar.Filter filter)
               throws IOException

Adds a directory (with all its subdirectories) or the contents of a zip/JAR to this JAR.

Parameters:

path - the path within the JAR where the root of the directory will be placed, or null for the JAR's root

dirOrZip - the directory to add as an entry or a zip/JAR file whose contents will be extracted and added as entries

filter - a filter to select particular classes

Returns:

this

Throws:

IOException

addEntries

public Jar addEntries(Path path,
                      Path dirOrZip)
               throws IOException

Adds a directory (with all its subdirectories) or the contents of a zip/JAR to this JAR.

Parameters:

path - the path within the JAR where the root of the directory will be placed, or null for the JAR's root

dirOrZip - the directory to add as an entry or a zip/JAR file whose contents will be extracted and added as entries

Returns:

this

Throws:

IOException

addEntries

public Jar addEntries(String path,
                      Path dirOrZip,
                      Jar.Filter filter)
               throws IOException

Adds a directory (with all its subdirectories) or the contents of a zip/JAR to this JAR.

Parameters:

path - the path within the JAR where the root of the directory/zip will be placed, or null for the JAR's root

dirOrZip - the directory to add as an entry or a zip/JAR file whose contents will be extracted and added as entries

filter - a filter to select particular classes

Returns:

this

Throws:

IOException

addEntries

public Jar addEntries(String path,
                      Path dirOrZip)
               throws IOException

Adds a directory (with all its subdirectories) or the contents of a zip/JAR to this JAR.

Parameters:

path - the path within the JAR where the root of the directory/zip will be placed, or null for the JAR's root

dirOrZip - the directory to add as an entry or a zip/JAR file whose contents will be extracted and added as entries

Returns:

this

Throws:

IOException

addEntries

public Jar addEntries(Path path,
                      ZipInputStream zip)
               throws IOException

Adds the contents of the zip/JAR contained in the given byte array to this JAR.

Parameters:

path - the path within the JAR where the root of the zip will be placed, or null for the JAR's root

zip - the contents of the zip/JAR file

Returns:

this

Throws:

IOException

addEntries

public Jar addEntries(Path path,
                      ZipInputStream zip,
                      Jar.Filter filter)
               throws IOException

Adds the contents of the zip/JAR contained in the given byte array to this JAR.

Parameters:

path - the path within the JAR where the root of the zip will be placed, or null for the JAR's root

zip - the contents of the zip/JAR file

filter - a filter to select particular classes

Returns:

this

Throws:

IOException

addPackageOf

public Jar addPackageOf(Class<?> clazz)
                 throws IOException

Adds the contents of a Java package to this JAR.

Parameters:

clazz - A class whose package we wish to add to the JAR.

Returns:

this

Throws:

IOException

addPackageOf

public Jar addPackageOf(Class<?> clazz,
                        Jar.Filter filter)
                 throws IOException

Adds the contents of a Java package to this JAR.

Parameters:

clazz - a class whose package we wish to add to the JAR.

filter - a filter to select particular classes

Returns:

this

Throws:

IOException

setPacker

public Jar setPacker(Pack200.Packer packer)

Sets a Pack200 packer to use when writing the JAR.

Parameters:

packer -

Returns:

this

setReallyExecutable

public Jar setReallyExecutable(boolean value)

If set to true true, a header will be added to the JAR file when written, that will make the JAR an executable file in POSIX environments.

Parameters:

value -

Returns:

this

setJarPrefix

public Jar setJarPrefix(String value)

Sets a string that will be prepended to the JAR file's data.

Parameters:

value - the prefix, or null for none.

Returns:

this

setJarPrefix

public Jar setJarPrefix(Path file)

Sets a file whose contents will be prepended to the JAR file's data.

Parameters:

file - the prefix file, or null for none.

Returns:

this

setOutputStream

public Jar setOutputStream(OutputStream os)

Sets an OutputStream to which the JAR will be written. If used, this method must be called before any entries have been added or the JAR written. Calling this method prevents this object from using an internal buffer to store the JAR, and therefore, none of the other write methods can be called.

Parameters:

os - the target OutputStream of this JAR.

Returns:

this

setOutput

public Jar setOutput(Path out)
              throws IOException

Same as setOutputStream(Files.newOutputStream(out)). If used, this method must be called before any entries have been added or the JAR written. Calling this method prevents this object from using an internal buffer to store the JAR, and therefore, none of the other write methods can be called.

Parameters:

out - the target file to which this JAR will be written.

Returns:

this

Throws:

IOException

setOutput

public Jar setOutput(File out)
              throws IOException

Same as setOutputStream(new FileOutputStream(out)). If used, this method must be called before any entries have been added or the JAR written. Calling this method prevents this object from using an internal buffer to store the JAR, and therefore, none of the other write methods can be called.

Parameters:

out - the target file to which this JAR will be written.

Returns:

this

Throws:

IOException

close

public Jar close()
          throws IOException

Throws:

IOException

write

public <T extends OutputStream> T write(T os)
                                 throws IOException

Writes this JAR to an output stream, and closes the stream.

Throws:

IOException

write

public File write(File file)
           throws IOException

Writes this JAR to a file.

Throws:

IOException

write

public Path write(Path path)
           throws IOException

Writes this JAR to a file.

Throws:

IOException

write

public void write(String file)
           throws IOException

Writes this JAR to a file.

Throws:

IOException

toByteArray

public byte[] toByteArray()

Returns this JAR file as an array of bytes.

toInputStream

public static InputStream toInputStream(String str,
                                        Charset charset)

Turns a String into an InputStream containing the string's encoded characters.

Parameters:

str - the string

charset - the Charset to use when encoding the string.

Returns:

an InputStream containing the string's encoded characters.

matches

public static Jar.Filter matches(String regex)

notMatches

public static Jar.Filter notMatches(String regex)