net.sf.sevenzipjbinding
Class SevenZip

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

public class SevenZip
extends java.lang.Object

7-Zip-JBinding entry point class. Finds and initializes 7-Zip-JBinding native library. Opens archives and returns implementation of ISevenZipInArchive

Initialization of the native library

Typically the library doesn't need an explicit initialization. The first call to an open 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 available native libraries is read out of the /sevenzipjbinding-platforms.properties file in 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 is always considered 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 in the class path. The list contains names of the dynamic libraries situated in the /ChosenPlatform/ directory in the same jar.
  • The dynamic libraries for the chosen platform are copied (if not already) 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 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 initialization phase 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(File):

• 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 get copied and used.

Opening archives

The methods for opening archive files (read-only):

• 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 archives with an encrypted index.

Version:

4.65-1

Author:

Boris Brodski

Method Summary

static java.lang.Throwable	getLastInitializationException() Returns last native library initialization exception, if occurs.
static java.util.List<java.lang.String>	getPlatformList() Load list of the available platforms out of sevenzipjbinding-Platform.jar in the class path.
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 ISevenZipInArchive	openInArchive(ArchiveFormat archiveFormat, IInStream inStream) Open archive of type archiveFormat from the input stream inStream.
static ISevenZipInArchive	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 ISevenZipInArchive	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.

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 in 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

openInArchive

public static ISevenZipInArchive 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 ISevenZipInArchive which represents opened archive.

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding intern error occur. Check exception message for more information.

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

See Also:

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

openInArchive

public static ISevenZipInArchive 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 ISevenZipInArchive which represents opened archive.

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding intern error occur. Check exception message for more information.

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

See Also:

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

openInArchive

public static ISevenZipInArchive 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 ISevenZipInArchive which represents opened archive.

Throws:

SevenZipException - 7-Zip or 7-Zip-JBinding intern error occur. Check exception message for more information.

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

See Also:

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