net.sf.sevenzipjbinding
Class SevenZip

java.lang.Object
  net.sf.sevenzipjbinding.SevenZip

public class SevenZip
extends java.lang.Object

7-Zip-JBinding main class.

• Finds and initializes 7-Zip-JBinding native library
• Opens existing archives and returns implementation of IInArchive
• Create new archives by providing different implementations of the IOutArchive

Initialization of the native library

Typically the library doesn't need an explicit initialization. The first call to an open/create archive method will try to initialize the native library by calling initSevenZipFromPlatformJAR() method. This initialization process requires a platform jar to be in a class path. The automatic initialization starts before the first access to an archive, if native library wasn't already initialized manually with one of the initSevenZip... methods. If manual or automatic initialization failed, no further automatic initialization attempts will be made. The initialization status and error messages can be obtained by following methods:

• isInitializedSuccessfully() - get initialization status
• isAutoInitializationWillOccur() - determine, if an initialization attempt was made
• getLastInitializationException() - get last thrown initialization exception

The platform jar is a additional jar file sevenzipjbinding-Platform.jar with one or more native libraries for respective one or more platforms. Here is some examples of 7-Zip-JBinding platform jar files.

• sevenzipjbinding-Linux-i386.jar with native library for exact one platform: Linux, 32 bit
• sevenzipjbinding-AllWindows.jar with native libraries for two platforms: Windows 32 and 64 bit
• sevenzipjbinding-AllPlatforms.jar with native libraries for all available platforms

The single and multiple platform jar files can be determined by counting dashes in the filename. Single platform jar files always contain two dashes in their names.

Here is a schema of the different initialization processes:

• Initialization using platform jar
  • First, the list of the available native libraries is loaded from the /sevenzipjbinding-platforms.properties file on the class path by calling getPlatformList() method. The list is cached in a static variable.
  • The platform is chosen by calling getPlatformBestMatch method. If the list of available platforms contains exact one platform the platform will be always the best match. If more that one platforms are available to choose from, the system properties os.arch and os.name (first part) are used to make the choice.
  • The list of the native libraries is determined by reading /ChosenPlatform/sevenzipjbinding-lib.properties on the class path. The list contains names and hashes of the dynamic libraries located in the /ChosenPlatform/ directory in the same jar.
  • The dynamic libraries for the chosen platform are copied to the unique temporary directory using "build-ref" postfix. If not passed as a parameter for one of initSevenZipFromPlatformJAR(...) methods, the temporary directory is determined using system property java.io.tmpdir.
  • The dynamic libraries are reused, if the files are already present in the temporary directory and the hash sums are verified
  • The dynamic libraries are loaded into JVM using System.load(String) method.
  • 7-Zip-JBinding native initialization method called to complete initialization process.
• Manual initialization
  • User loads 7-Zip-JBinding native dynamic libraries manually into JVM using System.load(String) or System.loadLibrary(String)
  • User calls initLoadedLibraries() method to initialize manually loaded native library

By default the initialization occurred within the AccessController.doPrivileged(java.security.PrivilegedAction) block. This can be overruled by setting sevenzip.no_doprivileged_initialization system property. For example:

java -Dsevenzip.no_doprivileged_initialization=1 ...

Temporary artifacts

During automatic initialization of the 7-Zip-JBinding the native libraries from the platform jar must be extracted to the disk in order to be loaded into the JVM. Since the count of the native libraries (depending on the platform) can be greater than one, a temporary sub-directory is created to hold those native libraries. The path to the directory for the temporary artifacts will determined according to following rules (see createOrVerifyTmpDir method):

• If path specified directly using tmpDirectory parameter of initSevenZipFromPlatformJAR(File) or initSevenZipFromPlatformJAR(String, File) it will be used
• If no path specified directly, the system property java.io.tmpdir get used
• If the system property java.io.tmpdir isn't set, an exception get raised

The list of the temporary created artifact can be obtained with getTemporaryArtifacts(). By default, 7-Zip-JBinding doesn't delete those artifacts trying to reduce subsequent initialization overhead. If 7-Zip-JBinding finds the native libraries within the temporary directory, it uses those without further verification. In order to allow smoothly updates, the temporary sub-directory with the native libraries named with a unique build reference number. If 7-Zip-JBinding get updated, a new temporary sub-directory get created and the new native libraries will be copied and used.

Opening existing archives

The methods for the opening archive files are

• openInArchive(ArchiveFormat, IInStream) - simple open archive method.
• openInArchive(ArchiveFormat, IInStream, IArchiveOpenCallback) - generic open archive method. It's possible to open all kinds of archives providing call back object that implements following interfaces
  • IArchiveOpenCallback - base interface. Must be implemented by all call back classes
  • ICryptoGetTextPassword - (optional) Provides password encrypted index
  • IArchiveOpenVolumeCallback - (optional) Provides information about volumes in multipart archives. Currently used only for multipart RAR archives. For opening multipart 7z archives use VolumedArchiveInStream.
• openInArchive(ArchiveFormat, IInStream, String) a shortcut method for opening password protected archives with an encrypted index.

Creating new archives

There are two ways to create a new archive:

• Use openOutArchive(ArchiveFormat) method. It will return an instance of the IOutCreateArchive<IOutItemAllFormats> interface allowing creation of an archive of any supported archive format. To get all currently supported formats see the 'compression' column of the ArchiveFormat -JavaDoc.
• Use one of the SevenZip.openOutArchiveXxx methods, that provide implementations of corresponding archive format specific interfaces. Those interfaces contain all supported configuration methods for selected archive format and are more convenient in cases, where only one archive format should be supported.

For more information see IOutCreateArchive.

Updating existing archives

In order to update an existing archive three simple steps are necessary:

• Open the existing archive need to be modified (getting an instance of the IInArchive interface)
• Call IInArchive.getConnectedOutArchive() to get connected instance of the IOutUpdateArchive interface
• Call IOutUpdateArchive.updateItems(ISequentialOutStream, int, IOutCreateCallback) to start the archive update operation

During update operation user may copy item properties or item properties and content from the existing archive significantly improving performance comparing to extract and re-compress alternative.

For more information see IOutUpdateArchive.

Since:

4.65-1

Author:

Boris Brodski

Nested Class Summary

static class

SevenZip.Version Version information about 7-Zip.

Method Summary

static java.lang.Throwable	getLastInitializationException() Returns last native library initialization exception, if occurs.
static java.lang.String	getPlatformBestMatch() Return best match for the current platform out of available platforms availablePlatform
static java.util.List<java.lang.String>	getPlatformList() Load list of the available platforms out of sevenzipjbinding-Platform.jar on the class path.
static java.lang.String	getSevenZipJBindingVersion() Return version of the 7-Zip-JBinding.
static SevenZip.Version	getSevenZipVersion() Return information about native 7-Zip engine.
static java.io.File[]	getTemporaryArtifacts() Returns list of the temporary created artifacts (one directory and one or more files within this directory).
static java.lang.String	getUsedPlatform() Return the platform used for the initialization.
static void	initLoadedLibraries() Initialize 7-Zip-JBinding native library without loading libraries in JVM first.
static void	initSevenZipFromPlatformJAR() Initialize native SevenZipJBinding library assuming sevenzipjbinding-Platform.jar on the class path.
static void	initSevenZipFromPlatformJAR(java.io.File tmpDirectory) Initialize native SevenZipJBinding library assuming sevenzipjbinding-Platform.jar on the class path.
static void	initSevenZipFromPlatformJAR(java.lang.String platform) Initialize native SevenZipJBinding library assuming sevenzipjbinding-Platform.jar on the class path.
static void	initSevenZipFromPlatformJAR(java.lang.String platform, java.io.File tmpDirectory) Initialize native SevenZipJBinding library assuming sevenzipjbinding-Platform.jar on the class path.
static boolean	isAutoInitializationWillOccur() Returns weather automatic initialization will occur or not.
static boolean	isInitializedSuccessfully() Tests native library initialization status of SevenZipJBinding.
static IInArchive	openInArchive(ArchiveFormat archiveFormat, IInStream inStream) Open archive of type archiveFormat from the input stream inStream.
static IInArchive	openInArchive(ArchiveFormat archiveFormat, IInStream inStream, IArchiveOpenCallback archiveOpenCallback) Open archive of type archiveFormat from the input stream inStream using 'archive open call back' listener archiveOpenCallback.
static IInArchive	openInArchive(ArchiveFormat archiveFormat, IInStream inStream, java.lang.String passwordForOpen) Open archive of type archiveFormat from the input stream inStream using 'archive open call-back' listener archiveOpenCallback.
static IOutCreateArchive<IOutItemAllFormats>	openOutArchive(ArchiveFormat archiveFormat) Create a new archive of type archiveFormat.
static IOutCreateArchive7z	openOutArchive7z() Create a new 7z archive.
static IOutCreateArchiveBZip2	openOutArchiveBZip2() Create a new BZip2 archive.
static IOutCreateArchiveGZip	openOutArchiveGZip() Create a new GZip archive.
static IOutCreateArchiveTar	openOutArchiveTar() Create a new 7z archive.
static IOutCreateArchiveZip	openOutArchiveZip() Create a new Zip archive.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isInitializedSuccessfully

public static boolean isInitializedSuccessfully()

Tests native library initialization status of SevenZipJBinding. Use getLastInitializationException() method to get more information in case of initialization failure.

Returns:

true 7-Zip-JBinding native library was initialized successfully. Native library wasn't initialized successfully (yet).

See Also:

getLastInitializationException(), isAutoInitializationWillOccur()

getLastInitializationException

public static java.lang.Throwable getLastInitializationException()

Returns last native library initialization exception, if occurs.

Returns:

null - no initialization exception occurred (yet), else initialization exception

See Also:

isInitializedSuccessfully()

isAutoInitializationWillOccur

public static boolean isAutoInitializationWillOccur()

Returns weather automatic initialization will occur or not. Automatic initialization starts before opening an archive, if native library wasn't already initialized manually with one of the initSevenZip... methods. If manual or automatic initialization failed, no further automatic initialization attempts will be made.

Returns:

true automatic initialization will occur, false automatic initialization will not occur

See Also:

isInitializedSuccessfully(), getLastInitializationException()

getUsedPlatform

public static java.lang.String getUsedPlatform()

Return the platform used for the initialization. The Platform is one element out of the list of available platforms returned by getPlatformList().

Returns:

the platform used for the initialization or null if initialization wasn't performed yet.

See Also:

getPlatformList()

getPlatformList

public static java.util.List<java.lang.String> getPlatformList()
                                                        throws SevenZipNativeInitializationException

Load list of the available platforms out of sevenzipjbinding-Platform.jar on the class path.

Returns:

list of the available platforms

Throws:

SevenZipNativeInitializationException - indicated problems finding or parsing platform property file

getTemporaryArtifacts

public static java.io.File[] getTemporaryArtifacts()

Returns list of the temporary created artifacts (one directory and one or more files within this directory). The directory is always the last element in the array.

Returns:

array of Files.

initSevenZipFromPlatformJAR

public static void initSevenZipFromPlatformJAR()
                                        throws SevenZipNativeInitializationException

Initialize native SevenZipJBinding library assuming sevenzipjbinding-Platform.jar on the class path. The platform depended library will be extracted from the jar file and copied to the temporary directory. Then it will be loaded into JVM using System.load(String) method. Finally the library specific native initialization method will be called. Please see JavaDoc of SevenZip for detailed information.

If libraries for more that one platform exists, the choice will be made by calling getPlatformBestMatch() method. Use initSevenZipFromPlatformJAR(String) to set platform manually.

Throws:

SevenZipNativeInitializationException - indicated problems finding a native library, coping it into the temporary directory or loading it.

See Also:

SevenZip, initSevenZipFromPlatformJAR(File), initSevenZipFromPlatformJAR(String), initSevenZipFromPlatformJAR(String, File)

initSevenZipFromPlatformJAR

public static void initSevenZipFromPlatformJAR(java.io.File tmpDirectory)
                                        throws SevenZipNativeInitializationException

Initialize native SevenZipJBinding library assuming sevenzipjbinding-Platform.jar on the class path. The platform depended library will be extracted from the jar file and copied to the temporary directory. Then it will be loaded into JVM using System.load(String) method. Finally the library specific native initialization method will be called. Please see JavaDoc of SevenZip for detailed information.

If libraries for more that one platform exists, the choice will be made by calling getPlatformBestMatch() method. Use initSevenZipFromPlatformJAR(String) to set platform manually.

Parameters:

tmpDirectory - temporary directory to copy native libraries to. This directory must be writable and contain at least 2 MB free space.

Throws:

SevenZipNativeInitializationException - indicated problems finding a native library, coping it into the temporary directory or loading it.

See Also:

SevenZip, initSevenZipFromPlatformJAR(), initSevenZipFromPlatformJAR(String), initSevenZipFromPlatformJAR(String, File)

initSevenZipFromPlatformJAR

public static void initSevenZipFromPlatformJAR(java.lang.String platform,
                                               java.io.File tmpDirectory)
                                        throws SevenZipNativeInitializationException

Initialize native SevenZipJBinding library assuming sevenzipjbinding-Platform.jar on the class path. The platform depended library will be extracted from the jar file and copied to the temporary directory. Then it will be loaded into JVM using System.load(String) method. Finally the library specific native initialization method will be called. Please see JavaDoc of SevenZip for detailed information.

If libraries for more that one platform exists, the choice will be made by calling getPlatformBestMatch() method. Use initSevenZipFromPlatformJAR(String) to set platform manually.

Parameters:

tmpDirectory - temporary directory to copy native libraries to. This directory must be writable and contain at least 2 MB free space.

platform - Platform to load native library for. The platform must be one of the elements of the list of available platforms returned by getPlatformList().

Throws:

SevenZipNativeInitializationException - indicated problems finding a native library, coping it into the temporary directory or loading it.

See Also:

SevenZip, initSevenZipFromPlatformJAR(), initSevenZipFromPlatformJAR(File), initSevenZipFromPlatformJAR(String), getPlatformList()

initSevenZipFromPlatformJAR

public static void initSevenZipFromPlatformJAR(java.lang.String platform)
                                        throws SevenZipNativeInitializationException

Initialize native SevenZipJBinding library assuming sevenzipjbinding-Platform.jar on the class path. The platform depended library will be extracted from the jar file and copied to the temporary directory. Then it will be loaded into JVM using System.load(String) method. Finally the library specific native initialization method will be called. Please see JavaDoc of SevenZip for detailed information.

If libraries for more that one platform exists, the choice will be made by calling getPlatformBestMatch() method. Use initSevenZipFromPlatformJAR(String) to set platform manually.

Parameters:

platform - Platform to load native library for. The platform must be one of the elements of the list of available platforms returned by getPlatformList().

Throws:

SevenZipNativeInitializationException - indicated problems finding a native library, coping it into the temporary directory or loading it.

See Also:

SevenZip, initSevenZipFromPlatformJAR(), initSevenZipFromPlatformJAR(File), initSevenZipFromPlatformJAR(String, File), getPlatformList()

initLoadedLibraries

public static void initLoadedLibraries()
                                throws SevenZipNativeInitializationException

Initialize 7-Zip-JBinding native library without loading libraries in JVM first. Prevent automatic loading of 7-Zip-JBinding native libraries into JVM. This method will only call 7-Zip-JBinding internal initialization method, considering all needed native libraries as loaded. It method is useful, if the java application wants to load 7-Zip-JBinding native libraries manually.

Throws:

SevenZipNativeInitializationException - in case of an initialization error

openInArchive

public static IInArchive openInArchive(ArchiveFormat archiveFormat,
                                       IInStream inStream,
                                       IArchiveOpenCallback archiveOpenCallback)
                                throws SevenZipException

Open archive of type archiveFormat from the input stream inStream using 'archive open call back' listener archiveOpenCallback. To open archive from the file, use RandomAccessFileInStream.

Parameters:

archiveFormat - format of archive

inStream - input stream to open archive from

archiveOpenCallback - archive open call back listener to use. You can optionally implement ICryptoGetTextPassword to specify password to use.

Returns:

implementation of IInArchive which represents opened archive.

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding error occur. Use SevenZipException.printStackTraceExtended() to get stack traces of this SevenZipException and of the all thrown 'cause by' exceptions.

java.lang.NullPointerException - is thrown, if inStream is null

See Also:

openInArchive(ArchiveFormat, IInStream, IArchiveOpenCallback), openInArchive(ArchiveFormat, IInStream, String)

openInArchive

public static IInArchive openInArchive(ArchiveFormat archiveFormat,
                                       IInStream inStream,
                                       java.lang.String passwordForOpen)
                                throws SevenZipException

Open archive of type archiveFormat from the input stream inStream using 'archive open call-back' listener archiveOpenCallback. To open archive from the file, use RandomAccessFileInStream.

Parameters:

archiveFormat - format of archive

inStream - input stream to open archive from

passwordForOpen - password to use. Warning: this password will not be used to extract item from archive but only to open archive. (7-zip format supports encrypted filename)

Returns:

implementation of IInArchive which represents opened archive.

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding error occur. Use SevenZipException.printStackTraceExtended() to get stack traces of this SevenZipException and of the all thrown 'cause by' exceptions.

java.lang.NullPointerException - is thrown, if inStream is null

See Also:

openInArchive(ArchiveFormat, IInStream), openInArchive(ArchiveFormat, IInStream, IArchiveOpenCallback)

openInArchive

public static IInArchive openInArchive(ArchiveFormat archiveFormat,
                                       IInStream inStream)
                                throws SevenZipException

Open archive of type archiveFormat from the input stream inStream. To open archive from the file, use RandomAccessFileInStream.

Parameters:

archiveFormat - (optional) format of archive. If null archive format will be auto-detected.

inStream - input stream to open archive from

Returns:

implementation of IInArchive which represents opened archive.

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding error occur. Use SevenZipException.printStackTraceExtended() to get stack traces of this SevenZipException and of the all thrown 'cause by' exceptions.

java.lang.NullPointerException - is thrown, if inStream is null

See Also:

openInArchive(ArchiveFormat, IInStream), openInArchive(ArchiveFormat, IInStream, String)

getPlatformBestMatch

public static java.lang.String getPlatformBestMatch()
                                             throws SevenZipNativeInitializationException

Return best match for the current platform out of available platforms availablePlatform

Returns:

platform

Throws:

SevenZipNativeInitializationException - is no platform could be chosen

See Also:

getPlatformList()

getSevenZipVersion

public static SevenZip.Version getSevenZipVersion()

Return information about native 7-Zip engine.

Returns:

Version

getSevenZipJBindingVersion

public static java.lang.String getSevenZipJBindingVersion()

Return version of the 7-Zip-JBinding.

Returns:

version of the 7-Zip-JBinding

openOutArchiveZip

public static IOutCreateArchiveZip openOutArchiveZip()
                                              throws SevenZipException

Create a new Zip archive.

Returns:

an out-archive object initialized to create the new Zip archive

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding error occur. Use SevenZipException.printStackTraceExtended() to get stack traces of this SevenZipException and of the all thrown 'cause by' exceptions.

See Also:

IOutCreateArchiveZip

openOutArchive7z

public static IOutCreateArchive7z openOutArchive7z()
                                            throws SevenZipException

Create a new 7z archive.

Returns:

an out-archive object initialized to create the new 7z archive

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding error occur. Use SevenZipException.printStackTraceExtended() to get stack traces of this SevenZipException and of the all thrown 'cause by' exceptions.

See Also:

IOutCreateArchive7z

openOutArchiveTar

public static IOutCreateArchiveTar openOutArchiveTar()
                                              throws SevenZipException

Create a new 7z archive.

Returns:

an out-archive object initialized to create the new 7z archive

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding error occur. Use SevenZipException.printStackTraceExtended() to get stack traces of this SevenZipException and of the all thrown 'cause by' exceptions.

See Also:

IOutCreateArchiveTar

openOutArchiveBZip2

public static IOutCreateArchiveBZip2 openOutArchiveBZip2()
                                                  throws SevenZipException

Create a new BZip2 archive.

Returns:

an out-archive object initialized to create the new BZip2 archive

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding error occur. Use SevenZipException.printStackTraceExtended() to get stack traces of this SevenZipException and of the all thrown 'cause by' exceptions.

See Also:

IOutCreateArchiveBZip2

openOutArchiveGZip

public static IOutCreateArchiveGZip openOutArchiveGZip()
                                                throws SevenZipException

Create a new GZip archive.

Returns:

an out-archive object initialized to create the new GZip archive

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding error occur. Use SevenZipException.printStackTraceExtended() to get stack traces of this SevenZipException and of the all thrown 'cause by' exceptions.

See Also:

IOutCreateArchiveGZip

openOutArchive

public static IOutCreateArchive<IOutItemAllFormats> openOutArchive(ArchiveFormat archiveFormat)
                                                            throws SevenZipException

Create a new archive of type archiveFormat.

Parameters:

archiveFormat - archive format of the new archive

Returns:

an out-archive object initialized to create the new archive

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding error occur. Use SevenZipException.printStackTraceExtended() to get stack traces of this SevenZipException and of the all thrown 'cause by' exceptions.

See Also:

IOutCreateArchiveZip