CkTar Java Programming
Reference Documentation
CkTar
API for creating and extracting TAR archives. Also supports creating and extracting .tar.gz (.tgz), .tar.bz2, and .tar.Z (compressed TAR archives, also known as compressed tarball archives). Can read/write the following TAR formats: (1) GNU tar 1.13.x format, (2) PAX -- POSIX 1003.1-2001 format, (3) USTAR -- POSIX 1003.1-1988 format.
Object Creation
CkTar obj = new CkTar();
Properties
// str is a CkString object (output)
get_Charset( str )
// newVal is a string (input)
put_Charset( newVal )
Character encoding to be used when interpreting filenames within .tar archives for untar operations. The default is "utf-8", and this is typically not changed. (The WriteTar methods always uses utf-8 to store filenames within the TAR archive.)
// Returns an integer value
get_DirMode( )
// newVal is an integer (input)
put_DirMode( newVal )
The directory permissions to used in WriteTar* methods. The default is octal 0755. This is the value to be stored in the "mode" field of each TAR header for a directory entries.
// str is a CkString object (output)
get_DirPrefix( str )
// newVal is a string (input)
put_DirPrefix( newVal )
To be documented soon...
// Returns an integer value
get_FileMode( )
// newVal is an integer (input)
put_FileMode( newVal )
The file permissions to used in WriteTar* methods. The default is octal 0644. This is the value to be stored in the "mode" field of each TAR header for a file entries.
// Returns an integer value
get_GroupId( )
// newVal is an integer (input)
put_GroupId( newVal )
The default numerical GID to be stored in each TAR header when writing TAR archives. The default value is 1000.
// str is a CkString object (output)
get_GroupName( str )
// newVal is a string (input)
put_GroupName( newVal )
The default group name to be stored in each TAR header when writing TAR archives. The default value is the logged-on username of the application's process.
// Returns an integer value
get_HeartbeatMs( )
// newVal is an integer (input)
put_HeartbeatMs( newVal )
This is the number of milliseconds between each AbortCheck event callback. The AbortCheck callback allows an application to abort any TAR operation prior to completion. If HeartbeatMs is 0, no AbortCheck event callbacks will occur.
// str is a CkString object (output)
LastErrorHtml( str )
Error information in HTML format for the last method called.
// str is a CkString object (output)
LastErrorText( str )
To be documented soon.Error information in plain-text format for the last method called.
// str is a CkString object (output)
LastErrorXml( str )
To be documented soon.Error information in XML format for the last method called.
// Returns a boolean value
get_NoAbsolutePaths( )
// newVal is a boolean (input)
put_NoAbsolutePaths( newVal )
If true, then absolute paths are converted to relative paths by removing the leading "/" or "\" character when untarring. This protects your system from unknowingly untarring files into important system directories, such as C:\Windows\system32. The default value is true.
// Returns an integer value
get_NumDirRoots( )
The total number of directory roots set by calling AddDirRoot (i.e. the number of times AddDirRoot was called by the application). A TAR archive is created by calling AddDirRoot for one or more directory tree roots, followed by a single call to WriteTar (or WriteTarBz2, WriteTarGz, WriteTarZ). This allows for TAR archives containing multiple directory trees to be created.
// Returns an integer value
get_ScriptFileMode( )
// newVal is an integer (input)
put_ScriptFileMode( newVal )
The file permissions to used in WriteTar* methods for shell script files (.sh, .csh, .bash, .bsh). The default is octal 0755. This is the value to be stored in the "mode" field of each TAR header for a file entries.
// Returns a boolean value
get_UntarCaseSensitive( )
// newVal is a boolean (input)
put_UntarCaseSensitive( newVal )
Determines whether pattern matching is case-sensitive if the UntarMatchPattern is used. The default value is false.
// Returns a boolean value
get_UntarDebugLog( )
// newVal is a boolean (input)
put_UntarDebugLog( newVal )
Similar to the VerboseLogging property. If set to true, then information about each file/directory extracted in an untar method call is logged to LastErrorText (or LastErrorXml / LastErrorHtml). The default value is false.
// Returns a boolean value
get_UntarDiscardPaths( )
// newVal is a boolean (input)
put_UntarDiscardPaths( newVal )
If true, then discard all path information when untarring. This causes all files to be untarred into a single directory. The default value is false.
// str is a CkString object (output)
get_UntarFromDir( str )
// newVal is a string (input)
put_UntarFromDir( newVal )
The directory path where files are extracted when untarring. The default value is ".", meaning that the current working directory of the calling process is used. If UntarDiscardPaths is set, then all files are untarred into this directory. Otherwise, the untar operation will re-create a directory tree rooted in this directory.
// str is a CkString object (output)
get_UntarMatchPattern( str )
// newVal is a string (input)
put_UntarMatchPattern( newVal )
Used to untar only files and directories that match this pattern. The asterisk character represents 0 or more of any character. For example, setting this pattern to "*.txt" causes all .txt files to be extracted. The default value is an empty string, indicating that all files are to be extracted.
// Returns an integer value
get_UntarMaxCount( )
// newVal is an integer (input)
put_UntarMaxCount( newVal )
Limits the number of files extracted during an untar to this count. The default value is 0 to indicate no maximum. To untar a single file, one might set the UntarMatchPattern such that it will match only the file to be extracted, and also set UntarMaxCount equal to 1. This causes an untar to scan the TAR archive until it finds the matching file, extract it, and then return.
// Returns an integer value
get_UserId( )
// newVal is an integer (input)
put_UserId( newVal )
The default numerical UID to be stored in each TAR header when writing TAR archives. The default value is 1000.
// str is a CkString object (output)
get_UserName( str )
// newVal is a string (input)
put_UserName( newVal )
The default user name to be stored in each TAR header when writing TAR archives. The default value is the logged-on username of the application's process.
// Returns a boolean value
get_VerboseLogging( )
// newVal is a boolean (input)
put_VerboseLogging( newVal )
If set to true, then the LastErrorText may contain more verbose logging.
// str is a CkString object (output)
get_Version( str )
The version of the TAR component/library, such as 1.0.0.
// str is a CkString object (output)
get_WriteFormat( str )
// newVal is a string (input)
put_WriteFormat( newVal )
The TAR format to use when writing a TAR archive. Valid values are "gnu", "pax", and "ustar". The default value is "gnu".
Methods
// dirPath is a string (input)
// Returns a boolean value
AddDirRoot( dirPath )
Adds a directory tree to be included in the next call to one of the WriteTar* methods. To include multiple directory trees in a .tar, call AddDirRoot multiple times followed by a single call to WriteTar. Returns true for success, false for failure.
// index is an integer (input)
// outStr is a CkString object (output)
// Returns a boolean value
GetDirRoot( index, outStr )
Returns the value of the Nth directory root. For example, if an application calls AddDirRoot twice, then the NumDirRoots property would have a value of 2, and GetDirRoot(0) would return the path passed to AddDirRoot in the 1st call, and GetDirRoot(1) would return the directory path in the 2nd call to AddDirRoot. Returns true for success, false for failure.
// tarFilename is a string (input)
// outStr is a CkString object (output)
// Returns a boolean value
ListXml( tarFilename, outStr )
Scans a TAR archive and returns XML detailing the files and directories found within the TAR. Returns true for success, false for failure.
// filename is a string (input)
// Returns a boolean value
SaveLastError( filename )
Saves the last error information to an XML formatted file.
// unlockCode is a string (input)
// Returns a boolean value
UnlockComponent( unlockCode )
Unlocks the component allowing for the full functionality to be used. If this method unexpectedly returns false, examine the contents of the LastErrorText property to determine the reason for failure.
// tarFilename is a string (input)
// Returns an integer value
Untar( tarFilename )
Extracts the files and directories from a TAR archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property. Returns the number of files and directories extracted, or -1 for failure. (Java) Untar a .tar Archive (Android™) Untar a .tar Archive
// tarFilename is a string (input)
// Returns a boolean value
UntarBz2( tarFilename )
Extracts the files and directories from a tar.bz2 (or tar.bzip2) archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property. Returns true for success, false for failure. (Java) Untar a .tar.bz2 Compressed Archive (Android™) Untar a .tar.bz2 Compressed Archive
// tarFileBytes is a CkByteData object (output)
// matchPattern is a string (input)
// outBytes is a CkByteData object (output)
// Returns a boolean value
UntarFirstMatchingToMemory( tarFileBytes, matchPattern, outBytes )
Memory-to-memory untar. The first file matching the UntarMatchPattern property is extracted and returned.
// tarFileBytes is a CkByteData object (output)
// Returns an integer value
UntarFromMemory( tarFileBytes )
Extracts the files and directories from an in-memory TAR archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property. Returns the number of files and directories extracted, or -1 for failure.
// tarFilename is a string (input)
// Returns a boolean value
UntarGz( tarFilename )
Extracts the files and directories from a tar.gz (or tar.gzip) archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property. Returns true for success, false for failure. (Java) Untar a .tar.gz (.tgz) Compressed Archive (Android™) Untar a .tar.gz (.tgz) Compressed Archive
// tarFilename is a string (input)
// Returns a boolean value
UntarZ( tarFilename )
Extracts the files and directories from a tar.Z archive, reconstructing the directory tree(s) in the local filesystem. The files are extracted to the directory specified by the UntarFromDir property. Returns true for success, false for failure. (Java) Untar a .tar.Z (.taz) Compressed Archive (Android™) Untar a .tar.Z (.taz) Compressed Archive
// tarFilename is a string (input)
// Returns a boolean value
VerifyTar( tarFilename )
To be documented soon...
// tarFilename is a string (input)
// Returns a boolean value
WriteTar( tarFilename )
Writes a TAR archive. The directory trees previously added by calling AddDirRoot one or more times are included in the output TAR archive. Returns true for success, false for failure. (Java) Create TAR Archive (Android™) Create TAR Archive
// outFilename is a string (input)
// Returns a boolean value
WriteTarBz2( outFilename )
Writes a .tar.bz2 compressed TAR archive. The directory trees previously added by calling AddDirRoot one or more times are included in the output file. Returns true for success, false for failure. (Java) Create TAR BZ2 Compressed Archive (.tar.bz2, .tbz, .tbz2, .tb2) (Android™) Create TAR BZ2 Compressed Archive (.tar.bz2, .tbz, .tbz2, .tb2)
// outFilename is a string (input)
// Returns a boolean value
WriteTarGz( outFilename )
Writes a .tar.gz (also known as .tgz) compressed TAR archive. The directory trees previously added by calling AddDirRoot one or more times are included in the output file. Returns true for success, false for failure. (Java) Create Compressed .tgz (.tar.gz) TAR Archive (Android™) Create Compressed .tgz (.tar.gz) TAR Archive
// Returns a string
charset( )
Character encoding to be used when interpreting filenames within .tar archives for untar operations. The default is "utf-8", and this is typically not changed. (The WriteTar methods always uses utf-8 to store filenames within the TAR archive.) Returns a null on failure
// Returns a string
dirPrefix( )
To be documented soon...
// index is an integer (input)
// Returns a string
getDirRoot( index )
Returns the value of the Nth directory root. For example, if an application calls AddDirRoot twice, then the NumDirRoots property would have a value of 2, and GetDirRoot(0) would return the path passed to AddDirRoot in the 1st call, and GetDirRoot(1) would return the directory path in the 2nd call to AddDirRoot. Returns a null on failure
// Returns a string
groupName( )
The default group name to be stored in each TAR header when writing TAR archives. The default value is the logged-on username of the application's process. Returns a null on failure
// Returns a string
lastErrorHtml( )
Error information in HTML format for the last method called.Returns a null on failure
// Returns a string
lastErrorText( )
Error information in plain-text format for the last method called.Returns a null on failure
// Returns a string
lastErrorXml( )
Error information in XML format for the last method called.Returns a null on failure
// tarFilename is a string (input)
// Returns a string
listXml( tarFilename )
Scans a TAR archive and returns XML detailing the files and directories found within the TAR. Returns a null on failure
// Returns a string
untarFromDir( )
The directory path where files are extracted when untarring. The default value is ".", meaning that the current working directory of the calling process is used. If UntarDiscardPaths is set, then all files are untarred into this directory. Otherwise, the untar operation will re-create a directory tree rooted in this directory. Returns a null on failure
// Returns a string
untarMatchPattern( )
Used to untar only files and directories that match this pattern. The asterisk character represents 0 or more of any character. For example, setting this pattern to "*.txt" causes all .txt files to be extracted. The default value is an empty string, indicating that all files are to be extracted. Returns a null on failure
// Returns a string
userName( )
The default user name to be stored in each TAR header when writing TAR archives. The default value is the logged-on username of the application's process. Returns a null on failure
// Returns a string
version( )
The version of the TAR component/library, such as 1.0.0. Returns a null on failure
// Returns a string
writeFormat( )
The TAR format to use when writing a TAR archive. Valid values are "gnu", "pax", and "ustar". The default value is "gnu". Returns a null on failure
|