org.at4j.tar
Class TarFile

java.lang.Object
  org.at4j.tar.TarFile

All Implemented Interfaces:

Map<AbsoluteLocation,TarEntry>, Archive<TarEntry,TarDirectoryEntry>

public class TarFile
extends Object
implements Archive<TarEntry,TarDirectoryEntry>

A TarFile is an Archive containing TarEntry:s loaded from a file. Tar entries may be files, directories or symbolic links. They contain metadata about the file system entity that was used to create the tar entry such as its time of last modification and its owner user and group id:s.

The Tar file format is fairly simple, but it has evolved through a few versions since it was first defined. The following formats are supported by this object:

• Unix v7 version – the original Tar file format. It supports path names up to 99 characters long and only numerical group and user id:s. Represented by TarEntry objects.
• POSIX 1003.1-1988 (ustar) version – supports path names up to 255 characters long and text user and group id:s. Represented by UstarEntry objects.
• Gnu Tar version – supports path names of unlimited length and text user and group id:s. Special features such as sparse archive files are not supported. Represented by UstarEntry objects.
• POSIX 1003.1-2001 (pax) version – supports path names of unlimited length, text user and group id:s and any number of metadata variables (PAX variables) for each entry. Represented by PaxEntry objects.

The entries in a Tar archive are positioned in a directory hierarchy. Parent directories of entries may be absent. In that case they are represented by TarDirectoryEntry objects using default directory settings.

If the file used to create this object is in a locking FileSystem, it is locked for reading by this object until it is close():d.

A TarFile object should be safe to use concurrently from several parallel threads without any external synchronization.

Note on character encodings: By default, metadata about Tar entries is encoded using the default character encoding of the platform where the tar file is created. This makes it necessary for those reading Tar files to know which character encoding that was used when the archive was created. This is often, but not always, Codepage 437 on Windows or UTF-8 on Unix. The only exception to this rule is the Pax variables that are always encoded using UTF-8. If Tar entries in a Pax compatible archive contains non-ASCII characters, the Tar entry path is (often) stored in the Pax header, making the archive portable between different platforms.

The Tar file format is described well in the Gnu Tar manual.

This object has a main method that, when run, prints out the contents of a Tar file passed to it as an argument.

Since:

1.0

Author:

Karl Gustafsson

See Also:

TarExtractor

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

TarFile(RandomlyAccessibleFile f)
Create a new Tar file archive object that reads data from the supplied file.

TarFile(RandomlyAccessibleFile f, Charset entryNameCharset)
Create a new Tar file archive object that reads data from the supplied file.

Method Summary

protected void	assertNotClosed() This method throws an IllegalStateException if this object has been closed.
void	clear()
void	close() Close this Tar file.
boolean	containsKey(Object key) Does the Tar archive contain the specified key (which should be an AbsoluteLocation object)?
boolean	containsValue(Object value) Does the Tar archive contain the specified value (which should be some kind of TarEntry object)?
Set<Map.Entry<AbsoluteLocation,TarEntry>>	entrySet() Get a read only set containing the entries in the Tar archive.
protected void	finalize()
TarEntry	get(Object key) Get the TarEntry stored at the specified absolute location in the Tar file.
TarDirectoryEntry	getRootEntry() Get the root directory entry for the Tar file.
boolean	isEmpty() This method always returns false since a Tar archive always has its root directory entry.
Set<AbsoluteLocation>	keySet() Get a read only set containing all the AbsoluteLocation:s where Tar entries are stored in the Tar file.
static void	main(String[] args)
TarEntry	put(AbsoluteLocation key, TarEntry value)
void	putAll(Map<? extends AbsoluteLocation,? extends TarEntry> m)
TarEntry	remove(Object key)
int	size() Get the number of Tar entries in the archive.
Collection<TarEntry>	values() Get a read only collection containing all TarEntry objects in the Tar file.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode

Constructor Detail

TarFile

public TarFile(RandomlyAccessibleFile f)

Create a new Tar file archive object that reads data from the supplied file. File names and other text information in the Tar file is interpreted using the platform's default charset.

If the file is in a locking FileSystem, it is locked for reading by this method. The read lock is released when this object is close():d. If this method returns with an error, the file is not locked.

Parameters:

f - The Tar file.

See Also:

TarFile(RandomlyAccessibleFile, Charset)

TarFile

public TarFile(RandomlyAccessibleFile f,
               Charset entryNameCharset)

Create a new Tar file archive object that reads data from the supplied file. Entry names and other text information in the Tar file is interpreted using the supplied charset.

If the file is in a locking FileSystem, it is locked for reading by this method. The read lock is released when this object is close():d. If this method returns with an error, the file is not locked.

Parameters:

f - The Tar file.

entryNameCharset - The charset to use for interpreting text metadata in the Tar file.

See Also:

TarFile(RandomlyAccessibleFile)

Method Detail

assertNotClosed

protected void assertNotClosed()
                        throws IllegalStateException

This method throws an IllegalStateException if this object has been closed.

Throws:

IllegalStateException - If this object has been closed.

getRootEntry

public TarDirectoryEntry getRootEntry()

Get the root directory entry for the Tar file. The root directory entry is the entry that has the absolute location / in the Tar file.

This entry is never present in the Tar file itself, so the returned object is always a TarDirectoryEntry (and not some subclass of that object).

Specified by:

getRootEntry in interface Archive<TarEntry,TarDirectoryEntry>

Returns:

The Tar archive's root directory entry.

clear

public void clear()
           throws UnsupportedOperationException

Specified by:

clear in interface Map<AbsoluteLocation,TarEntry>

Throws:

UnsupportedOperationException - Always.

containsKey

public boolean containsKey(Object key)
                    throws IllegalStateException

Does the Tar archive contain the specified key (which should be an AbsoluteLocation object)?

Specified by:

containsKey in interface Map<AbsoluteLocation,TarEntry>

Parameters:

key - The key to search for.

Returns:

true if the supplied key is present in the Tar file.

Throws:

IllegalStateException - If the Tar file has been closed.

containsValue

public boolean containsValue(Object value)
                      throws IllegalStateException

Does the Tar archive contain the specified value (which should be some kind of TarEntry object)?

Specified by:

containsValue in interface Map<AbsoluteLocation,TarEntry>

Parameters:

value - The value to search for.

Returns:

true if the Tar file contains the specified value.

Throws:

IllegalStateException - If the Tar file has been closed.

entrySet

public Set<Map.Entry<AbsoluteLocation,TarEntry>> entrySet()
                                                   throws IllegalStateException

Get a read only set containing the entries in the Tar archive.

Specified by:

entrySet in interface Map<AbsoluteLocation,TarEntry>

Returns:

A read only set containing the Tar archive's entries.

Throws:

IllegalStateException - If the Tar archive has been closed.

get

public TarEntry get(Object key)
             throws IllegalStateException

Get the TarEntry stored at the specified absolute location in the Tar file.

Specified by:

get in interface Map<AbsoluteLocation,TarEntry>

Parameters:

key - The AbsoluteLocation where the Tar entry is stored.

Returns:

The Tar entry or null if no Tar entry is stored at the specified location.

Throws:

IllegalStateException - If the Tar archive has been closed.

isEmpty

public boolean isEmpty()
                throws IllegalStateException

This method always returns false since a Tar archive always has its root directory entry.

Specified by:

isEmpty in interface Map<AbsoluteLocation,TarEntry>

Returns:

false, always.

Throws:

IllegalStateException - If the Tar archive has been closed.

keySet

public Set<AbsoluteLocation> keySet()
                             throws IllegalStateException

Get a read only set containing all the AbsoluteLocation:s where Tar entries are stored in the Tar file.

Specified by:

keySet in interface Map<AbsoluteLocation,TarEntry>

Returns:

A read only set containing all Tar entry positions.

Throws:

IllegalStateException - If the Tar archive has been closed.

put

public TarEntry put(AbsoluteLocation key,
                    TarEntry value)
             throws UnsupportedOperationException

Specified by:

put in interface Map<AbsoluteLocation,TarEntry>

Throws:

UnsupportedOperationException - Always.

putAll

public void putAll(Map<? extends AbsoluteLocation,? extends TarEntry> m)
            throws UnsupportedOperationException

Specified by:

putAll in interface Map<AbsoluteLocation,TarEntry>

Throws:

UnsupportedOperationException - Always.

remove

public TarEntry remove(Object key)
                throws UnsupportedOperationException

Specified by:

remove in interface Map<AbsoluteLocation,TarEntry>

Throws:

UnsupportedOperationException - Always.

size

public int size()
         throws IllegalStateException

Get the number of Tar entries in the archive.

Specified by:

size in interface Map<AbsoluteLocation,TarEntry>

Returns:

The number of Tar entries in the archive.

Throws:

IllegalStateException - If the Tar archive has been closed.

values

public Collection<TarEntry> values()
                            throws IllegalStateException

Get a read only collection containing all TarEntry objects in the Tar file.

Specified by:

values in interface Map<AbsoluteLocation,TarEntry>

Returns:

A read only collection containing all Tar entries.

Throws:

IllegalStateException - If the Tar archive has been closed.

close

public void close()

Close this Tar file. This closes all open streams on file entries in the Tar file and releases the read lock on the Tar file.

This method can safely be called several times.

Specified by:

close in interface Archive<TarEntry,TarDirectoryEntry>

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

main

public static void main(String[] args)