Class PluginBundle
- java.lang.Object
-
- ca.cgjennings.apps.arkham.plugins.PluginBundle
-
public class PluginBundle extends java.lang.Object
A plug-in bundle is a file that stores the code and resources required by a plug-in. ThePluginBundle
class encapsulates operations that can be performed on such a bundle without actually linking it to the application. (The distinction is important because linking a plug-in bundle to the application also typically locks the bundle file until the application terminates.)A plug-in bundle is essentially a ZIP archive, with the following restrictions and exceptions:
- All file names in the archive are encoded in UTF-8.
- The following byte sequence may occur before the normal start of the file: 0x07, 0x88, 0x53, 0x45; in this case the bundle is called Web-safe.
- The archive must contain a file named eons-plugin
in its root folder. This file must follow the format for a plug-in root file.
(Strictly speaking, a root file is optional for library bundles, but highly
recommended.) See
PluginRoot
.
Web-safe bundles: Unless a server is properly configured to recognize the standard plug-in file extensions and MIME types, the user's browser (Internet Explorer in particular) may detect its type on the fly and convert the file extension to .zip without informing the user. This makes it difficult for users to install the plug-in, since they must both recognize the problem and know the correct extension to use. A Web-safe bundle gets around this by adding a few bytes to the start of the file, which prevents it from being detected as a ZIP archive. However, a Web-safe bundle cannot be linked to the application without first converting it back to the standard format. Most of the methods in this class will transparently convert a Web-safe bundle to a standard bundle; see the specific method descriptions for details.
Obsolete Formats: Some alpha and beta releases of Strange Eons supported bundles that used other archive formats. These bundles are no longer supported, and attempting to create a
PluginBundle
instance for such files, or to determine their format, will throw an exception. Bundles stored in these obsolete formats would now typically be converted into published bundles (see below).Published Bundles: This class does not handle bundles that have been published. Published bundles are the network transport format used by the
Catalog
system. They have been reorganized and compressed using a special multistep process that greatly reduces download size. Published bundle files can be identified by an additional file extension. This extension always starts with "p"; typically ".plzm" or ".pbz". For example, myplugin.seplugin.pbz is the name of a published version of myplugin.seplugin. Published bundles must be converted back to the regular bundle format before they can be used with this class.- Since:
- 2.1
- Author:
- Chris Jennings
- See Also:
PluginRoot
,BundleInstaller
-
-
Field Summary
Fields Modifier and Type Field Description static int
FORMAT_INVALID
The file is not a valid plug-in bundle.static int
FORMAT_PLAIN
The bundle format is a plain ZIP-compatible archive bundle.static int
FORMAT_WRAPPED
The bundle format is a "Web-safe" wrapped bundle.static int
TYPE_EXTENSION
The file appears to be an extension plug-in bundle (based on the file extension).static int
TYPE_LIBRARY
The file appears to be a library bundle (based on the file extension).static int
TYPE_PLUGIN
The file appears to be a plug-in bundle (based on the file extension).static int
TYPE_THEME
The file appears to be a theme (based on the file extension).static int
TYPE_UNKNOWN
The file type is unknown (based on the file extension).
-
Constructor Summary
Constructors Constructor Description PluginBundle(java.io.File file)
Creates a new plug-in bundle instance for a file.PluginBundle(java.lang.String file)
Creates a new plug-in bundle from a file path stored in a string.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description PluginBundle
copy(java.io.File destination)
Writes a copy of the plug-in bundle todestination
.java.io.File
createUncompressedArchive()
Copies the bundle content into a ZIP archive with no file compression (all files in the archive areSTORE
d).void
dispose()
Performs cleanup when a plug-in bundle instance is no longer required.java.net.URL
getBaseURL()
Returns aURL
that can be used as a base URL to access the archived contents of this bundle without linking it against the application.static int
getBundleFormat(java.io.File file)
Returns the storage format of an arbitrary bundle file, which will be one ofFORMAT_PLAIN
,FORMAT_WRAPPED
, orFORMAT_INVALID
.static int
getBundleType(java.lang.Object file)
Returns the apparent type of an arbitrary bundle file, based on the file name's extension.java.io.File
getFile()
Returns the file represented by this plug-in bundle.int
getFormat()
Returns the storage format of this bundle, eitherFORMAT_PLAIN
orFORMAT_WRAPPED
.static ThemedIcon
getIcon(java.lang.Object file, boolean smallIcon)
Returns a large or small icon that can be used to represent a plug-in bundle in message dialogs, etc.java.io.File
getPlainFile()
Returns a file that contains the contents of this bundle inFORMAT_PLAIN
.PluginRoot
getPluginRoot()
Returns aPluginRoot
for the root file in this bundle, ornull
if the plug-in does not have a root file.int
getType()
Returns the apparent type of this bundle file, based on the file name's extension.java.util.zip.ZipFile
getZipFile()
Returns aZipFile
that represents the archived contents of this bundle.java.lang.String
toString()
Returns a string representation of this bundle instance, including the class name, file name, and bundle format.void
wrap()
Convert the plug-in bundle file into a wrapped version, replacing the original file.
-
-
-
Field Detail
-
FORMAT_PLAIN
public static final int FORMAT_PLAIN
The bundle format is a plain ZIP-compatible archive bundle.- See Also:
- Constant Field Values
-
FORMAT_WRAPPED
public static final int FORMAT_WRAPPED
The bundle format is a "Web-safe" wrapped bundle.- See Also:
- Constant Field Values
-
FORMAT_INVALID
public static final int FORMAT_INVALID
The file is not a valid plug-in bundle.- See Also:
- Constant Field Values
-
TYPE_LIBRARY
public static final int TYPE_LIBRARY
The file appears to be a library bundle (based on the file extension).- See Also:
- Constant Field Values
-
TYPE_THEME
public static final int TYPE_THEME
The file appears to be a theme (based on the file extension).- See Also:
- Constant Field Values
-
TYPE_EXTENSION
public static final int TYPE_EXTENSION
The file appears to be an extension plug-in bundle (based on the file extension).- See Also:
- Constant Field Values
-
TYPE_PLUGIN
public static final int TYPE_PLUGIN
The file appears to be a plug-in bundle (based on the file extension).- See Also:
- Constant Field Values
-
TYPE_UNKNOWN
public static final int TYPE_UNKNOWN
The file type is unknown (based on the file extension).- See Also:
- Constant Field Values
-
-
Constructor Detail
-
PluginBundle
public PluginBundle(java.lang.String file) throws java.io.IOException
Creates a new plug-in bundle from a file path stored in a string. This convenience constructor is equivalent toPluginBundle( new java.io.File( file ) )
.- Parameters:
file
- the path and name of the bundle file- Throws:
java.io.IOException
- if an error occurs while accessing the bundle or it is not a plug-in bundle
-
PluginBundle
public PluginBundle(java.io.File file) throws java.io.IOException
Creates a new plug-in bundle instance for a file.- Parameters:
file
- the file that represents a plug-in bundle- Throws:
java.io.IOException
- if an error occurs while accessing the bundle or it is not a plug-in bundle
-
-
Method Detail
-
getPluginRoot
public PluginRoot getPluginRoot() throws java.io.IOException
Returns aPluginRoot
for the root file in this bundle, ornull
if the plug-in does not have a root file. (A plug-in bundle with no root file is invalid unless it is a library bundle.) If the bundle format is notFORMAT_PLAIN
, then it will first be converted into a plain bundle as if by callingthis.copy( this.getFile() )
.- Returns:
- the content of the bundle's root file, or
null
- Throws:
java.io.IOException
- if an I/O exception occurs while reading the root file
-
getFile
public java.io.File getFile()
Returns the file represented by this plug-in bundle. This is always the original file that was used in the constructor.- Returns:
- the original plug-in bundle file
-
getPlainFile
public java.io.File getPlainFile() throws java.io.IOException
Returns a file that contains the contents of this bundle inFORMAT_PLAIN
. If the original bundle was already plain, then this is equivalent to callinggetFile()
. Otherwise, a temporary file will be created inFORMAT_PLAIN
and returned. (Repeated calls will return the same file unlessdispose()
is called in the meantime.)- Returns:
- an plain version of the bundle file
- Throws:
java.io.IOException
- if the file is wrapped and an exception occurs while unwrapping to a temporary file
-
getZipFile
public java.util.zip.ZipFile getZipFile() throws java.io.IOException
Returns aZipFile
that represents the archived contents of this bundle.- Returns:
- a
ZipFile
that can be used to access the plug-in bundle's content - Throws:
java.io.IOException
-
getBaseURL
public java.net.URL getBaseURL() throws java.io.IOException
Returns aURL
that can be used as a base URL to access the archived contents of this bundle without linking it against the application.- Returns:
- a
JarFile
URL for the plug-in bundle's content - Throws:
java.io.IOException
- if an I/O error occurs
-
copy
public PluginBundle copy(java.io.File destination) throws java.io.IOException
Writes a copy of the plug-in bundle todestination
. The copy of the bundle will always be inFORMAT_PLAIN
, but is otherwise identical to the original bundle. The newly created bundle is returned as aPluginBundle
.It is valid to use the file containing this bundle as the destination. In this case,
this
is returned if the bundle is already unwrapped. If the bundle is wrapped, it is unwrapped in place, replacing the original file. In this case, this bundle's state is updated to reflect the new status of the file.- Parameters:
destination
- theFile
to write the copy to- Returns:
- a
PluginBundle
representing the destination - Throws:
java.io.IOException
- if an I/O error occurs during the copy
-
wrap
public void wrap() throws java.io.IOException
Convert the plug-in bundle file into a wrapped version, replacing the original file. If the file is already wrapped, this method does nothing.- Throws:
java.io.IOException
- if an I/O error occurs while wapping
-
createUncompressedArchive
public java.io.File createUncompressedArchive() throws java.io.IOException
Copies the bundle content into a ZIP archive with no file compression (all files in the archive areSTORE
d). There are two primary reasons for wanting an uncompressed archive:- When the plug-in will actually be run from the bundle in question (i.e., when installing the bundle): after an initial access, the file content will generally be found in the file system cache, so the decompression overhead is not compensating for slow I/O operations.
- When the bundle file is going to be compressed again, such as when creating an archive of plug-in bundles for distribution. Compressing already compressed data generally achieves worse compression ratios than only compressing once.
- Returns:
- a new temporary file containing the uncompressed archive file
- Throws:
java.io.IOException
- if an error occurs while creating the flat file
-
getFormat
public int getFormat()
Returns the storage format of this bundle, eitherFORMAT_PLAIN
orFORMAT_WRAPPED
.Note that if the file has been modified outside of this class between the time this object was constructed and the the time this method is called, this value may be out of date.
- Returns:
- the storage format of this bundle
-
getType
public int getType()
Returns the apparent type of this bundle file, based on the file name's extension. This will be one ofTYPE_LIBRARY
,TYPE_THEME
,TYPE_EXTENSION
,TYPE_PLUGIN
, orTYPE_UNKNOWN
.- Returns:
- a type ID that matches the apparent type of this bundle
- Throws:
java.lang.NullPointerException
- if the file isnull
-
getBundleType
public static int getBundleType(java.lang.Object file)
Returns the apparent type of an arbitrary bundle file, based on the file name's extension. The passed-in value can be any object; the object's string value is used. This will be one ofTYPE_LIBRARY
,TYPE_THEME
,TYPE_EXTENSION
,TYPE_PLUGIN
, orTYPE_UNKNOWN
.- Parameters:
file
- this object's string value will be treated as a file name that will be used to return a more specific icon- Returns:
- a type ID that matches the apparent type of the file
- Throws:
java.lang.NullPointerException
- if the file isnull
-
getIcon
public static ThemedIcon getIcon(java.lang.Object file, boolean smallIcon)
Returns a large or small icon that can be used to represent a plug-in bundle in message dialogs, etc. A valid icon is returned even if file isnull
. However, if a valid plug-in file is named, the returned icon may more accurately reflect the file's contents.- Parameters:
file
- this object's string value will be treated as a file name that will be used to return a more specific iconsmallIcon
- if true, returns a small icon- Returns:
- an icon that represents the type of the bundle implied by
file
-
getBundleFormat
public static int getBundleFormat(java.io.File file) throws java.io.IOException
Returns the storage format of an arbitrary bundle file, which will be one ofFORMAT_PLAIN
,FORMAT_WRAPPED
, orFORMAT_INVALID
.- Parameters:
file
- the file to determine the format of- Returns:
- a format ID that matches the bundle format of the file
- Throws:
java.io.IOException
- if an I/O error occurs while determining the formatjava.lang.NullPointerException
- if the file isnull
-
dispose
public void dispose()
Performs cleanup when a plug-in bundle instance is no longer required. If a temporary copy of the bundle file was created inFORMAT_PLAIN
, calling this method will delete the temporary file. If this method is not called, the temporary file will be deleted when the application terminates. It is safe to continue using this instance after callingdispose()
, though potentially inefficient.Note: In no event will calling this method delete the original file. Only temporary files created during processing will be affected.
-
toString
public java.lang.String toString()
Returns a string representation of this bundle instance, including the class name, file name, and bundle format.- Overrides:
toString
in classjava.lang.Object
- Returns:
- a string representation of this bundle
-
-