Package ca.cgjennings.apps.arkham.plugins

Class 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. The PluginBundle 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:

    1. All file names in the archive are encoded in UTF-8.
    2. 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.
    3. 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 to destination.
      java.io.File createUncompressedArchive()
      Copies the bundle content into a ZIP archive with no file compression (all files in the archive are STOREd).
      void dispose()
      Performs cleanup when a plug-in bundle instance is no longer required.
      java.net.URL getBaseURL()
      Returns a URL 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 of FORMAT_PLAIN, FORMAT_WRAPPED, or FORMAT_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, either FORMAT_PLAIN or FORMAT_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 in FORMAT_PLAIN.
      PluginRoot getPluginRoot()
      Returns a PluginRoot for the root file in this bundle, or null 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 a ZipFile 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.

      • Methods inherited from class java.lang.Object

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

    • 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 to PluginBundle( 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 a PluginRoot for the root file in this bundle, or null 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 not FORMAT_PLAIN, then it will first be converted into a plain bundle as if by calling this.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 in FORMAT_PLAIN. If the original bundle was already plain, then this is equivalent to calling getFile(). Otherwise, a temporary file will be created in FORMAT_PLAIN and returned. (Repeated calls will return the same file unless dispose() 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 a ZipFile 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 a URL 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 to destination. The copy of the bundle will always be in FORMAT_PLAIN, but is otherwise identical to the original bundle. The newly created bundle is returned as a PluginBundle.

        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 - the File 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 are STOREd). There are two primary reasons for wanting an uncompressed archive:
        1. 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.
        2. 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, either FORMAT_PLAIN or FORMAT_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 of TYPE_LIBRARY, TYPE_THEME, TYPE_EXTENSION, TYPE_PLUGIN, or TYPE_UNKNOWN.
        Returns:
        a type ID that matches the apparent type of this bundle
        Throws:
        java.lang.NullPointerException - if the file is null

      • 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 of TYPE_LIBRARY, TYPE_THEME, TYPE_EXTENSION, TYPE_PLUGIN, or TYPE_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 is null

      • 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 is null. 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 icon
        smallIcon - 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 of FORMAT_PLAIN, FORMAT_WRAPPED, or FORMAT_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 format
        java.lang.NullPointerException - if the file is null

      • 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 in FORMAT_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 calling dispose(), 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 class java.lang.Object
        Returns:
        a string representation of this bundle