com.hunnysoft.jmime
Class AppleFile

java.lang.Object
  com.hunnysoft.jmime.AppleFile

public class AppleFile

extends java.lang.Object

Class for packing and unpacking AppleSingle and AppleDouble data.

AppleFile packs or unpacks file data to or from AppleSingle or AppleDouble format. The AppleSingle format allows a file's contents to be packed together with related file information, such as file dates, resources, icons, and so forth, into a single file. The AppleDouble format is similar, but different in that the file's contents are stored in one file, and the remaining file information (dates, resources, icons, and so forth) is stored in a separate AppleDouble header file.

In the MIME world, AppleSingle and AppleDouble are the preferred ways to transfer Macintosh files, with AppleDouble preferred over AppleSingle where possible. In actual practice, the BinHex format is common (most likely due to the fact that most Macintosh archives store files in BinHex format). The use of AppleSingle and AppleDouble in MIME is described in RFC 1740 and is referred to as MacMIME. MacMIME is an official Internet standards track protocol.

To use AppleFile for packing file data to the AppleDouble header format, first call setFormat(AppleFile.APPLE_DOUBLE_HEADER) to set the format type to AppleDouble header, then call one or more of the following methods to set the file data: setFileName(), setCreateTime(), setModifyTime(), setBackupTime(), setAccessTime() setResourceFork(). Next, call the pack() method to pack all the file information into a single buffer. Finally, call packedData() to get the packed AppleDouble header data.

To use AppleFile for packing file data to the AppleSingle format, first call setFormat(AppleFile.APPLE_SINGLE) to set the format type to AppleSingle, then call one or more of the following methods to set the file data: setFileName(), setCreateTime(), setModifyTime(), setBackupTime(), setAccessTime() setResourceFork(), setDataFork(). Next, call the pack() method to pack all the file information into a single buffer. Finally, call packedData() to get the packed AppleSingle data.

To use AppleFile to unpack AppleSingle or AppleDouble file data, first call setPackedData() to set the packed data into the AppleFile object. Then call the unpack() method to unpack the file data. Finally, call format(), fileName(), createTime(), and other methods to get the file data.

Note: The definitive reference for AppleSingle and AppleDouble is AppleSingle/AppleDouble Formats: Developer's Note, available from Apple Computer.

Field Summary

static int	APPLE_DOUBLE_HEADER
static int	APPLE_SINGLE
static int	BAD_MAGIC_NUMBER
static int	CORRUPT_DATA
static int	NO_ERROR
static int	TOO_SHORT
static int	WRONG_VERSION

Constructor Summary

AppleFile()
Default constructor.

Method Summary

int	accessTime() Gets the access time.
static int	appleFileTimeToUnixTime(int afTime) Converts from AppleFile time to Unix time.
int	backupTime() Gets the backup time.
int	createTime() Gets the create time.
ByteString	dataFork() Gets the data fork.
ByteString	fileName() Gets the file name.
int	format() Gets the format type.
boolean	hasDataFork() Returns true if the AppleFile data contains a data fork entry.
boolean	hasFileName() Returns true if the AppleFile data contains a file name.
boolean	hasFileTimes() Returns true if the AppleFile data contains a file times entry.
boolean	hasResourceFork() Returns true if the AppleFile data contains a Macintosh resource fork entry.
int	modifyTime() Gets the modify time.
void	pack() Packs the file data into a single buffer.
ByteString	packedData() Gets the buffer of packed file data.
ByteString	resourceFork() Gets the resource fork.
void	setAccessTime(int time) Sets the access time.
void	setBackupTime(int time) Sets the backup time.
void	setCreateTime(int time) Sets the create time.
void	setDataFork(ByteString bytes) Sets the data fork.
void	setFileName(ByteString name) Sets the file name.
void	setFormat(int formatType) Sets the format type.
void	setModifyTime(int time) Sets the modify time.
void	setPackedData(ByteString str) Sets the buffer of packed file data.
void	setResourceFork(ByteString bytes) Sets the resource fork.
static int	unixTimeToAppleFileTime(int unixTime) Converts from Unix time to AppleFile time.
void	unpack() Unpacks the packed file data.

Methods inherited from class java.lang.Object

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

Field Detail

NO_ERROR

public static final int NO_ERROR

See Also:

Constant Field Values

TOO_SHORT

public static final int TOO_SHORT

See Also:

Constant Field Values

BAD_MAGIC_NUMBER

public static final int BAD_MAGIC_NUMBER

See Also:

Constant Field Values

WRONG_VERSION

public static final int WRONG_VERSION

See Also:

Constant Field Values

CORRUPT_DATA

public static final int CORRUPT_DATA

See Also:

Constant Field Values

APPLE_SINGLE

public static final int APPLE_SINGLE

See Also:

Constant Field Values

APPLE_DOUBLE_HEADER

public static final int APPLE_DOUBLE_HEADER

See Also:

Constant Field Values

Constructor Detail

AppleFile

public AppleFile()

Default constructor.

Method Detail

format

public int format()

Gets the format type.

The format type can be AppleFile.APPLE_SINGLE or AppleFile.APPLE_DOUBLE_HEADER.

When using AppleFile to unpack file data, the format type is determined by interpreting a magic number in the packed data.

The AppleDouble header and AppleSingle formats are almost identical. They are different in two ways: the magic number is different, and an AppleDouble header is not permitted to contain a data fork.

Returns:

AppleFile.APPLE_SINGLE or AppleFile.APPLE_DOUBLE_HEADER

setFormat

public void setFormat(int formatType)

Sets the format type.

When using AppleFile to pack file data, you should set a format type of AppleFile.APPLE_SINGLE or AppleFile.APPLE_DOUBLE_HEADER. When using AppleFile to unpack file data, the format type is determined by interpreting a magic number in the packed data.

The AppleDouble header and AppleSingle formats are almost identical. They are different in two ways: the magic number is different, and an AppleDouble header is not permitted to contain a data fork.

Parameters:

formatType - AppleFile.APPLE_SINGLE or AppleFile.APPLE_DOUBLE_HEADER

hasFileName

public boolean hasFileName()

Returns true if the AppleFile data contains a file name.

If the AppleFile data contains a file name, you may get the file name by calling fileName().

Returns:

true if the AppleFile data contains a file name

fileName

public ByteString fileName()

Gets the file name.

This method always returns a valid reference -- it never returns null. If there is no file name, the method returns a zero-length ByteString.

Returns:

file name

setFileName

public void setFileName(ByteString name)

Sets the file name.

Parameters:

name - file name

hasFileTimes

public boolean hasFileTimes()

Returns true if the AppleFile data contains a file times entry.

If the AppleFile data contains a file times entry, you may get the file times by calling createTime(), modifyTime(), backupTime(), and accessTime().

If a file times entry is present, that does not mean that all the times (create time, modify time, backup time, and access time) are valid. An invalid time is indicated by a value of Integer.MIN_VALUE.

Returns:

true if the AppleFile data contains a file times entry

createTime

public int createTime()

Gets the create time.

The create time is the time that the file was created.

A file time's value represents the number of seconds before or after 1 Jan 2000 00:00:00 UTC. The value 0 represents 1 Jan 2000 00:00:00 UTC; a negative time represents the number of seconds until 1 Jan 2000 00:00:00 UTC; and a positive value represents the number of seconds after 1 Jan 2000 00:00:00 UTC. The value Integer.MIN_VALUE is a special value that indicates an invalid value.

You may use the methods unixTimeToAppleFileTime() and appleFileTimeToUnixTime() to convert between the apple file time representation (signed number of seconds since 1 Jan 2000) and the Unix time representation (unsigned number of seconds since 1 Jan 1970).

Returns:

the file create time

setCreateTime

public void setCreateTime(int time)

Sets the create time.

The create time is the time that the file was created.

Parameters:

time - the file create time

modifyTime

public int modifyTime()

Gets the modify time.

The modify time is the time the file was last modified.

A file time's value represents the number of seconds before or after 1 Jan 2000 00:00:00 UTC. The value 0 represents 1 Jan 2000 00:00:00 UTC; a negative time represents the number of seconds until 1 Jan 2000 00:00:00 UTC; and a positive value represents the number of seconds after 1 Jan 2000 00:00:00 UTC. The value Integer.MIN_VALUE is a special value that indicates an invalid value.

You may use the methods unixTimeToAppleFileTime() and appleFileTimeToUnixTime() to convert between the apple file time representation (signed number of seconds since 1 Jan 2000) and the Unix time representation (unsigned number of seconds since 1 Jan 1970).

Returns:

the file modify time

setModifyTime

public void setModifyTime(int time)

Sets the modify time.

The modify time is the time the file was last modified.

Parameters:

time - the file modify time

backupTime

public int backupTime()

Gets the backup time.

The backup time is the time the file was last saved to a backup medium.

A file time's value represents the number of seconds before or after 1 Jan 2000 00:00:00 UTC. The value 0 represents 1 Jan 2000 00:00:00 UTC; a negative time represents the number of seconds until 1 Jan 2000 00:00:00 UTC; and a positive value represents the number of seconds after 1 Jan 2000 00:00:00 UTC. The value Integer.MIN_VALUE is a special value that indicates an invalid value.

You may use the methods unixTimeToAppleFileTime() and appleFileTimeToUnixTime() to convert between the apple file time representation (signed number of seconds since 1 Jan 2000) and the Unix time representation (unsigned number of seconds since 1 Jan 1970).

Returns:

the file backup time

setBackupTime

public void setBackupTime(int time)

Sets the backup time.

The backup time is the time the file was last saved to a backup medium.

Parameters:

time - the file backup time

accessTime

public int accessTime()

Gets the access time.

The access time is the time the file was last accessed.

A file time's value represents the number of seconds before or after 1 Jan 2000 00:00:00 UTC. The value 0 represents 1 Jan 2000 00:00:00 UTC; a negative time represents the number of seconds until 1 Jan 2000 00:00:00 UTC; and a positive value represents the number of seconds after 1 Jan 2000 00:00:00 UTC. The value Integer.MIN_VALUE is a special value that indicates an invalid value.

You may use the methods unixTimeToAppleFileTime() and appleFileTimeToUnixTime() to convert between the apple file time representation (signed number of seconds since 1 Jan 2000) and the Unix time representation (unsigned number of seconds since 1 Jan 1970).

Returns:

the file access time

setAccessTime

public void setAccessTime(int time)

Sets the access time.

The access time is the time the file was last accessed.

Parameters:

time - the file access time

hasDataFork

public boolean hasDataFork()

Returns true if the AppleFile data contains a data fork entry.

If it does contain a data fork, you may get the data fork by calling dataFork().

An AppleDouble header does not contain a data fork entry.

Returns:

true if the AppleFile data contains a data fork entry

dataFork

public ByteString dataFork()

Gets the data fork.

The data fork contains the file's "data," such as the text in a text file, or the image data in a GIF file. In contrast, the resource fork contains resources that are used only by the Macintosh operating system (font information, code, icons, and so forth). An AppleDouble header does not contain a data fork entry.

This method always returns a valid reference -- it never returns null. If there is no file name, the method returns a zero-length ByteString.

Returns:

the bytes of the data fork

setDataFork

public void setDataFork(ByteString bytes)

Sets the data fork.

The data fork contains the file's "data," such as the text in a text file, or the image data in a GIF file. In contrast, the resource fork contains resources that are used only by the Macintosh operating system (font information, code, icons, and so forth). An AppleDouble header does not contain a data fork entry.

Parameters:

bytes - the bytes of the data fork

hasResourceFork

public boolean hasResourceFork()

Returns true if the AppleFile data contains a Macintosh resource fork entry.

If it does contain a resource fork, you may get the resource fork by calling resourceFork().

Returns:

true if the AppleFile data contains a resource fork entry

resourceFork

public ByteString resourceFork()

Gets the resource fork.

The resource fork contains resources that are used only by the Macintosh operating system (font information, code, icons, and so forth).

This method always returns a valid reference -- it never returns null. If there is no file name, the method returns a zero-length ByteString.

Returns:

the bytes of the resource fork

setResourceFork

public void setResourceFork(ByteString bytes)

Sets the resource fork.

The resource fork contains resources that are used only by the Macintosh operating system (font information, code, icons, and so forth).

Parameters:

bytes - the bytes of the resource fork

packedData

public ByteString packedData()

Gets the buffer of packed file data.

This method always returns a valid reference -- it never returns null. If there is no file name, the method returns a zero-length ByteString.

Returns:

the packed file data

setPackedData

public void setPackedData(ByteString str)

Sets the buffer of packed file data.

Parameters:

str - packed file data

pack

public void pack()

Packs the file data into a single buffer.

After calling pack(), you may get the packed data by calling packedData().

unpack

public void unpack()
            throws DecodeException

Unpacks the packed file data.

Before calling unpack(), you should call setPackedData() to set the buffer of packed file data. After calling unpack(), you may call other methods to retrieve the unpacked file information.

If an error occurs while unpacking, the method throws a DecodeException.

Returns:

0 on success; error code on failure

Throws:

DecodeException - -- if there is an error unpacking the data

unixTimeToAppleFileTime

public static int unixTimeToAppleFileTime(int unixTime)

Converts from Unix time to AppleFile time.

An Apple file time is defined to be the signed number of seconds before or after 1 Jan 2000 00:00:00 UTC. The value 0 represents 1 Jan 2000 00:00:00 UTC; a negative time represents the number of seconds until 1 Jan 2000 00:00:00 UTC; and a positive value represents the number of seconds after 1 Jan 2000 00:00:00 UTC. A Unix time is the number of seconds since 1 Jan 1970 00:00:00 UTC.

Parameters:

unixTime - a UNIX time

Returns:

an AppleFile time

appleFileTimeToUnixTime

public static int appleFileTimeToUnixTime(int afTime)

Converts from AppleFile time to Unix time.

An Apple file time is defined to be the signed number of seconds before or after 1 Jan 2000 00:00:00 UTC. The value 0 represents 1 Jan 2000 00:00:00 UTC; a negative time represents the number of seconds until 1 Jan 2000 00:00:00 UTC; and a positive value represents the number of seconds after 1 Jan 2000 00:00:00 UTC. A Unix time is the number of seconds since 1 Jan 1970 00:00:00 UTC.

Parameters:

afTime - an AppleFile time

Returns:

a UNIX time