Class PluginBundlePublisher


  • public class PluginBundlePublisher
    extends java.lang.Object
    Utility methods for converting plug-in bundles to and from published catalog bundles (such as ".pbz" files). A published bundle is the network transport format used to transmit plug-in bundles from a remote catalog server to Strange Eons.

    A published bundle compresses an existing bundle with a high-efficiency compression method. For best results, the existing bundle should first be re-packed so that the underlying ZIP/JAR does not compress any entries (i.e. all entries are written with STORE). This will reduce the overall file size compared to compressing an already compressed bundle. (The project command to publish a bundle performs this step automatically.)

    Note: Previously, a two-process was used in which the original bundle (a type of JAR file) was compressed with Pack200, then the result compressed as described above. However, support for Pack200 was removed from Java. As the required tools are no longer distributed with JREs starting in Java 14, bundles published with older versions of the app can no longer be decompressed by newer versions of the app. (They can be unpacked by an older version, then the bundle installed in the newer version.)

    Since:
    3.0
    Author:
    Chris Jennings
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  PluginBundlePublisher.CompressionMethod
      An enumeration of the possible methods (algorithms) that may be used to compress plug-in bundles for network transport.
    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static void compress​(java.io.File source, java.io.File dest, PluginBundlePublisher.CompressionMethod method)
      Compresses a file using the specified compression method.
      static void decompress​(java.io.File source, java.io.File dest, PluginBundlePublisher.CompressionMethod method)
      Decompresses a file previously compressed with the specified compression method.
      static void packBundle​(java.io.File source, java.io.File dest)
      Deprecated.
      The Pack200 tools used by this method have been removed from Java.
      static java.io.File publishedBundleToPluginBundle​(java.io.File source, java.io.File dest)
      Converts a published bundle file to a standard plug-in bundle, decompressing and unpacking it with a single method call.
      static void unpackBundle​(java.io.File source, java.io.File dest)
      Deprecated.
      The Pack200 tools used by this method have been removed from Java.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • packBundle

        @Deprecated
        public static void packBundle​(java.io.File source,
                                      java.io.File dest)
                               throws java.io.IOException
        Deprecated.
        The Pack200 tools used by this method have been removed from Java. Calling this method will copy the file without changes.
        Converts a bundle into an uncompressed, packed representation format. The output file must still be compressed to complete the publication process.

        The specified bundle file is expected to use the plain format. This method does not verify the format, and the result of using a non-plain bundle is undefined.

        Parameters:
        source - the bundle file to convert
        dest - the packed file to create
        Throws:
        java.io.IOException - if an error occurs
        java.lang.NullPointerException - if either file is null
        See Also:
        unpackBundle(java.io.File, java.io.File)
      • unpackBundle

        @Deprecated
        public static void unpackBundle​(java.io.File source,
                                        java.io.File dest)
                                 throws java.io.IOException
        Deprecated.
        The Pack200 tools used by this method have been removed from Java. Calling this method on a packed file will throw an exception.
        Converts an uncompressed, packed file into a plain, uncompressed plug-in bundle that can be loaded by the Strange Eons plug-in system. A published bundle must be decompressed before it can be unpacked.
        Parameters:
        source - the packed file to convert
        dest - the bundle file to create
        Throws:
        java.io.IOException - if an error occurs
        java.lang.NullPointerException - if either file is null
        See Also:
        packBundle(java.io.File, java.io.File)
      • compress

        public static void compress​(java.io.File source,
                                    java.io.File dest,
                                    PluginBundlePublisher.CompressionMethod method)
                             throws java.io.IOException
        Compresses a file using the specified compression method. Compression is applied after packing to complete the publication process. The final output file should have the same name as the original bundle with the file extension of the compression method appended. For example, if the bundle "OmicronPlugin.seplugin" is compressed using BZip2 compression, the resulting file should be named "OmicronPlugin.seplugin.pbz".
        Parameters:
        source - the uncompressed source file
        dest - the compressed file to create
        method - the compression method to use; if null, the default method is selected
        Throws:
        java.io.IOException - if an error occurs
        java.lang.NullPointerException - if either file is null
      • decompress

        public static void decompress​(java.io.File source,
                                      java.io.File dest,
                                      PluginBundlePublisher.CompressionMethod method)
                               throws java.io.IOException
        Decompresses a file previously compressed with the specified compression method. If the method is null, then a compression method will be chosen based on the input file name. If no method can be detected from the file name, an IOException will be thrown.
        Parameters:
        source - the compressed source file
        dest - the uncompressed file to create
        method - the compression method used to compress the file, or null to choose based on the input file name
        Throws:
        java.io.IOException - if an error occurs
        java.lang.NullPointerException - if either file is null
      • publishedBundleToPluginBundle

        public static java.io.File publishedBundleToPluginBundle​(java.io.File source,
                                                                 java.io.File dest)
                                                          throws java.io.IOException
        Converts a published bundle file to a standard plug-in bundle, decompressing and unpacking it with a single method call. An optional listener can be provided that will be notified of the progress of the bundle conversion.

        The compression method is detected automatically from the file name. If the destination is null, a file in the same folder with the publication extension (such as .pbz) removed will be used. An optional listener may be supplied that will be notified of the unpacking progress.

        Parameters:
        source - the source file to convert
        dest - the destination bundle file; may be null to create a destination based on the source
        Returns:
        the name of the destination file; useful if null was specified to determine the name automatically
        Throws:
        java.lang.NullPointerException - if the source file is null
        java.io.IOException - if an I/O error occurs during unpacking