net.sf.sevenzipjbinding
Class SevenZip

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

public class SevenZip
extends java.lang.Object

7-Zip-JBinding main class.

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:
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. 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:
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):
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

Creating new archives

There are two ways to create a new archive: For more information see IOutCreateArchive.

Updating existing archives

In order to update an existing archive three simple steps are necessary: 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