com.pegacat.vcf.utility
Class PluginResource

java.lang.Object
  |
  +--com.pegacat.vcf.utility.PluginResource

public final class PluginResource
extends java.lang.Object

PluginResource: PluginResources maps resources in a zip or jar file. It provides methods to extract these as byte arrays, images, or input streams.

No distinction is made between jar and zip files, and any jar manifest file is unused.

XXX a half-hearted effort has been made to make this also work with non-zipped loose files that are just in the normal file directory structure. This is untested though...


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 PluginResource 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
PluginResource(java.lang.String zipFileName)
          creates a PluginResource.
PluginResource(java.lang.String zipFileName, boolean Debug)
          creates a PluginResources.
 
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 PluginResource 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

PluginResource

public PluginResource(java.lang.String zipFileName)
creates a PluginResource. It extracts all resources from a Jar into an internal hashtable, keyed by resource names.
Parameters:
zipFileName - a jar or zip file. May be null, if just the file system is being used.

PluginResource

public PluginResource(java.lang.String zipFileName,
                      boolean Debug)
creates a PluginResources. It extracts all resources from a Jar into an internal hashtable, keyed by resource names.
Parameters:
zipFileName - a jar or zip file. Null, if just the file system is being used.
debug - whether to dump the list of files found in the zip file.
Method Detail

getZipFileName

public java.lang.String getZipFileName()
Returns the raw name of the zip/jar file.
Parameters:
the - name of the zip file, e.g. 'help/local/fnord.zip'. may be null, if only the file system is being used.

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/PluginResources, 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.

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.

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.

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)

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.

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 PluginResources, you could extract, create, and display those images on-the-fly.
     ...
     PluginResources JR=new PluginResources("GifBundle.jar");
     Image image=Toolkit.createImage(JR.getResource("logo.gif");
     Image logo=Toolkit.getDefaultToolkit().createImage(
                   JR.getResources("logo.gif")
                   );
     ...
 

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.

This method currently does not support searching raw files on disk (i.e. not using a zip file).