com.ca.commons.cbutil
Class CBJarResource

java.lang.Object
  |
  +--com.ca.commons.cbutil.CBJarResource

public final class CBJarResource

extends java.lang.Object

CBJarResources: CBJarResources maps all resources included in a Zip or Jar file. Additionaly, it provides methods to extract them as byte arrays, images, or input streams.

This class makes no distinction between jar and zip files, and makes no use of any jar manifest file, should it exist.

Field Summary

protected java.util.Hashtable	contents The contents of the zip file are cached the first time they are used, to speed any subsequent access of the same resource.
protected java.util.Hashtable	entries When the CBJarResource object is created, the referenced zip file's catalogue is read.
protected java.util.zip.ZipFile	zipFile The actual zip or jar file
protected java.lang.String	zipFileName The name of this object's jar/zip file

Constructor Summary

CBJarResource(java.lang.String zipFileName)
creates a CBJarResources.

CBJarResource(java.lang.String zipFileName, boolean Debug)
creates a CBJarResources.

Method Summary

protected java.lang.String	dumpZipEntry(java.util.zip.ZipEntry ze) Dumps a zip entry into a string.
protected void	finalize()
java.awt.Image	getImage(java.lang.String imageName, java.awt.Toolkit imageCreator) Returns an Image from a zip file.
java.io.InputStream	getInputStream(java.lang.String resourceName) Allows a zipped file to be accessed with a (uncompressed) input stream, not unlike a normal FileInputStream.
java.lang.String[]	getPrefixedResources(java.lang.String prefix) Returns the *names* only of any resources with a particular prefix (such as 'images/').
protected byte[]	getRawResource(java.lang.String name) Extracts a file from a jar or zip, returning it as a raw byte array.
byte[]	getResource(java.lang.String name) Extracts a jar resource as a blob.
java.lang.String	getZipFileName() Returns the raw name of the zip/jar file.
boolean	hasResource(java.lang.String name) returns whether a particular resource exists in the archive.
protected void	init() initializes internal hash tables with Jar file resources.
static void	main(java.lang.String[] args) Is a test driver.
protected byte[]	readZipEntryData(java.io.InputStream is, java.util.zip.ZipEntry ze) Reads a specific zip entry from the input stream...
java.lang.String	toString() Prints a simple identifying string for debugging purposes.

Methods inherited from class java.lang.Object

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

Field Detail

contents

protected java.util.Hashtable contents

The contents of the zip file are cached the first time they are used, to speed any subsequent access of the same resource.

entries

protected java.util.Hashtable entries

When the CBJarResource object is created, the referenced zip file's catalogue is read. Later, individual zipped files are read using this cache of catalogue entries.

zipFileName

protected java.lang.String zipFileName

The name of this object's jar/zip file

zipFile

protected java.util.zip.ZipFile zipFile

The actual zip or jar file

Constructor Detail

CBJarResource

public CBJarResource(java.lang.String zipFileName)

creates a CBJarResources. It extracts all resources from a Jar into an internal hashtable, keyed by resource names.

Parameters:

zipFileName - a jar or zip file

CBJarResource

public CBJarResource(java.lang.String zipFileName,
                     boolean Debug)

creates a CBJarResources. It extracts all resources from a Jar into an internal hashtable, keyed by resource names.

Parameters:

zipFileName - a jar or zip file

Method Detail

getZipFileName

public java.lang.String getZipFileName()

Returns the raw name of the zip/jar file.

toString

public java.lang.String toString()

Prints a simple identifying string for debugging purposes.

Overrides:

toString in class java.lang.Object

hasResource

public boolean hasResource(java.lang.String name)

returns whether a particular resource exists in the archive. These names are preloaded into a hashtable, so this should be a lightweight operation.

Parameters:

name - the name of the resource (e.g. a class com/ca/od/util/CBJarResources, or an image file myimages/winona.gif)

getResource

public byte[] getResource(java.lang.String name)
                   throws java.util.zip.ZipException

Extracts a jar resource as a blob. Note that this basic method throws no exceptions, but simply returns null on failure.

Parameters:

name - a resource name.

java.util.zip.ZipException

getRawResource

protected byte[] getRawResource(java.lang.String name)
                         throws java.util.zip.ZipException

Extracts a file from a jar or zip, returning it as a raw byte array.

java.util.zip.ZipException

getImage

public java.awt.Image getImage(java.lang.String imageName,
                               java.awt.Toolkit imageCreator)
                        throws java.util.zip.ZipException

Returns an Image from a zip file.

Parameters:

imageName - the name of the image (including path) as saved in the zip file

imageCreator - a java.awt.Component used to get a Toolkit to construct the Image.

Returns:

a usable java.awt.Image file.

java.util.zip.ZipException

getInputStream

public java.io.InputStream getInputStream(java.lang.String resourceName)
                                   throws java.util.zip.ZipException

Allows a zipped file to be accessed with a (uncompressed) input stream, not unlike a normal FileInputStream.

Parameters:

resourceName - the fully qualified name of the object (i.e. with the path of the file as it exists in the zip file)

java.util.zip.ZipException

init

protected void init()

initializes internal hash tables with Jar file resources.

readZipEntryData

protected byte[] readZipEntryData(java.io.InputStream is,
                                  java.util.zip.ZipEntry ze)
                           throws java.io.IOException

Reads a specific zip entry from the input stream...

Parameters:

is - the decrypted (important!) input stream to construct an object out of. May be a ZipInputStream, but remember that ZipInputStream is *not* idempotent (i.e. don't call it on itself!). For the record, ZipFile.getInputStream() is a decrypted stream.

ze - the single zip entry to extract from the file.

java.io.IOException

dumpZipEntry

protected java.lang.String dumpZipEntry(java.util.zip.ZipEntry ze)

Dumps a zip entry into a string.

Parameters:

ze - a ZipEntry

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException

Is a test driver. Given a jar file and a resource name, it trys to extract the resource and then tells us whether it could or not. Example Let's say you have a JAR file which jarred up a bunch of gif image files. Now, by using CBJarResources, you could extract, create, and display those images on-the-fly.

     ...
     CBJarResources JR=new CBJarResources("GifBundle.jar");
     Image image=Toolkit.createImage(JR.getResource("logo.gif");
     Image logo=Toolkit.getDefaultToolkit().createImage(
                   JR.getResources("logo.gif")
                   );
     ...
 

java.io.IOException

finalize

protected void finalize()

Overrides:

finalize in class java.lang.Object

getPrefixedResources

public java.lang.String[] getPrefixedResources(java.lang.String prefix)

Returns the *names* only of any resources with a particular prefix (such as 'images/'). This is similar the wildcard search 'prefix*', but no actual '*' character is used. The search is case insensitive.