de.schlichtherle.truezip.zip
Class ExtraField

java.lang.Object
  de.schlichtherle.truezip.zip.ExtraField

Direct Known Subclasses:

DefaultExtraField

@NotThreadSafe
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
abstract class ExtraField
extends Object

Abstract base class for an Extra Field in a Local or Central Header of a ZIP archive. It defines the common properties of all Extra Fields and how to serialize/deserialize them to/from byte arrays.

Author:

Christian Schlichtherle

ZIP64_HEADER_ID

public static final int ZIP64_HEADER_ID

The Header ID of a ZIP64 Extended Information Extra Field.

See Also:

Constant Field Values

registry

private static final Map<Integer,Class<? extends ExtraField>> registry

ExtraField

ExtraField()

register

public static void register(Class<? extends ExtraField> c)

Registers a concrete implementation of this abstract base class for use with the static factory method create(int).

Parameters:

c - the implementation class of this abstract base class.

Throws:

NullPointerException - if c is null.

IllegalArgumentException - if c cannot get instantiated, is not a subclass of ExtraField or its Header ID is out of range. A more descriptive exception may be associated to it as its cause.

See Also:

create(int)

create

public static ExtraField create(int headerID)

A static factory method which creates a new Extra Field based on the given Header ID. The returned Extra Field still requires proper initialization, for example by calling readFrom(byte[], int, int).

Parameters:

headerID - An unsigned short integer (two bytes) which indicates the type of the returned Extra Field.

Returns:

A new Extra Field - never null!

Throws:

IllegalArgumentException - If headerID is out of range.

See Also:

register(java.lang.Class)

getHeaderID

public abstract int getHeaderID()

Returns the Header ID (type) of this Extra Field. The Header ID is an unsigned short integer (two bytes) which must be constant during the life cycle of this object.

getDataSize

abstract int getDataSize()

Returns the Data Size of this Extra Field. The Data Size is an unsigned short integer (two bytes) which indicates the length of the Data Block in bytes and does not include its own size in this Extra Field. This property may be initialized by calling readFrom(byte[], int, int).

Returns:

The size of the Data Block in bytes or 0 if unknown.

See Also:

getDataBlock()

getDataBlock

final byte[] getDataBlock()

Returns a protective copy of the Data Block. null is never returned.

See Also:

getDataSize()

readFrom

abstract void readFrom(byte[] data,
                       int off,
                       int size)

Initializes this Extra Field by deserializing a Data Block of size bytes from the byte array data at the zero based offset off. Upon return, this Extra Field shall not access data subsequently and getDataSize() must equal size.

Parameters:

data - The byte array to read the Data Block from.

off - The zero based offset in the byte array where the first byte of the Data Block is read from.

size - The length of the Data Block in bytes.

Throws:

IndexOutOfBoundsException - If the byte array data does not hold at least size bytes at the zero based offset off.

RuntimeException - If size is illegal or the deserialized Data Block contains illegal data.

See Also:

getDataSize()

writeTo

abstract void writeTo(byte[] data,
                      int off)

Serializes a Data Block of getDataSize() bytes to the byte array data at the zero based offset off. Upon return, this Extra Field shall not access data subsequently.

Parameters:

data - The byte array to write the Data Block to.

off - The zero based offset in the byte array where the first byte of the Data Block is written to.

Throws:

IndexOutOfBoundsException - If the byte array data does not hold at least getDataSize() bytes at the zero based offset off.

See Also:

getDataSize()