com.tffenterprises.music.tag.id3v2.frame
Class FrameHeader

java.lang.Object
  extended by com.tffenterprises.music.tag.id3v2.frame.FrameHeader
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
FrameHeader_2_0, FrameHeader_3_0

public abstract class FrameHeader
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

FrameHeader is a class that provides ID3v2 with an interpretation of the frame header structure. It is the base class for all versions of the ID3v2 frame header. FrameHeader features a factory class method that will return an object that implementats the appropriate version of the ID3v2 specification.

Subclasses of FrameHeader should implement two constructors accessible to FrameHeader: a default constructor and a constructor that takes a java.io.InputStream as a parameter. See the two protected constructiors defined by FrameHeader for more details on their definitions, including their exception declarations (which MUST be respected by subclasses).

Methods that a FrameHeader subclass should override are...

The methodology for ouputting the stream using FrameHeader objects hasn't been determined yet...

Version:
1.0d1 $Date: 2003/03/19 22:48:21 $
Author:
Guillaume Lessard
See Also:
Serialized Form

Field Summary
private  boolean changed
          Whether this FrameHeader object has been changed.
private static java.lang.Class[] CONSTRUCTOR_PARAMS_TYPES_ARRAY
          An array containing the Class objects which select the constructor of the FrameHeader subclass to be used.
private  int dataLength
          The Data length This may be different from the Frame length in the presence of compression, for example.
private static java.lang.String DEFAULT
          A mnemotechnic/easy parameter to pass the ResourceBundle and obtain the FrameHeader subclass implementing the newest spec.
private static java.util.ResourceBundle FRAMEHEADER_CLASS_INFO
          A resource bundle listing the subclass by version
private static java.util.Hashtable FRAMEHEADER_CLASSES
          The Hashtable which contains all the initialized class objects of our subclasses, keyed by version.
private  int frameLength
          The Frame length
private  java.lang.String id
          The Frame ID
protected static java.lang.String NULL_ID
          A string consisting of four nulls.
 
Constructor Summary
protected FrameHeader()
          Default constructor.
protected FrameHeader(java.io.InputStream in)
          Constructs a FrameHeader from an InputStream.
 
Method Summary
 boolean checkFormatMask(byte flagMask)
          Check whether a combination of bits is set in the format flags byte.
 boolean checkStatusMask(byte flagMask)
          Check whether a combination of bits is set in the status flags byte.
 java.lang.Object clone()
          Returns a clone of this Flags object.
private  byte[] decodeFrameBytesFromStream(java.io.InputStream stream)
          This is an auxiliary method to the getFrameBytesFromStream method.
 boolean equals(java.lang.Object other)
          Compares this FrameHeader object with another one.
 java.util.zip.Checksum getChecksum()
          Returns a Checksum of all this object's data.
 int getDataLength()
          Returns the length of the length of the raw data for this frame, without any encoding such as compression or unsynchronization.
 byte getFormatFlags()
          Returns this frame's format flags byte.
 byte[] getFrameBytesFromStream(java.io.InputStream in, long availableBytes)
          Extract the frame's raw data from the InputStream.
private static java.lang.Class GetFrameHeaderClass(short version)
          Returns the FrameHeader subclass to be used for the given ID3v2 version.
private static java.lang.Class GetFrameHeaderClass(java.lang.String version)
          Returns the FrameHeader subclass to be used for the given ID3v2 version.
 java.lang.String getFrameID()
          Returns the type string for this frame.
 int getFrameLength()
          Returns the frame length in bytes, if the frame was read from a stream.
static FrameHeader getNewInstance()
          Create a new FrameHeader object using the newest known version.
static FrameHeader getNewInstance(short version)
          Create a new FrameHeader object of a subclass appropriate for the version parameter.
static FrameHeader getNewInstance(short version, java.io.InputStream in)
          Create a new FrameHeader object of a subclass appropriate for the version parameter.
static FrameHeader getNewInstance(short version, java.lang.String frameID)
          Create a new FrameHeader object from an appropriate subclass, using the given frame ID and the default flags.
 byte getStatusFlags()
          Returns this frame's status flags byte.
 int hashCode()
          Returns a hash code for this FrameHeader object.
 boolean isChanged()
          Return true if this FrameHeader method has been changed.
static boolean isValidFrameID(java.lang.String frameID)
          Checks a 4-character String to see whether or not it's a valid ID3v2 frame ID.
protected  java.io.InputStream processInput(java.io.InputStream in)
          Layer input stream filters over in, and return the resulting input stream.
protected  java.io.OutputStream processOutput(java.io.OutputStream out)
          Process the OutputStream in which the frame is to be embedded.
 void setChanged(boolean changed)
          Sets or clears the "changed" bit.
protected  void setDataLength(int theLength)
          Set the data length in bytes.
 void setFormatFlags(byte flags)
          Set this frame's format flags byte.
 void setFormatMask(byte flagMask)
          Set the bits corresponding to a mask of bits in the format flags byte.
 void setFrameID(java.lang.String newID)
          Set the ID for the frame.
protected  void setFrameLength(int theLength)
          Set the frame length in bytes.
 void setStatusFlags(byte flags)
          Set this frame's status flags byte.
 void setStatusMask(byte flagMask)
          Set the bits corresponding to a mask of bits in the status flags byte.
 java.lang.String toString()
          Returns a String representation of this FrameHeader object.
 void unsetFormatMask(byte flagMask)
          Unset the bits corresponding to a mask of bits in the format flags byte.
 void unsetStatusMask(byte flagMask)
          Unset the bits corresponding to a mask of bits in the status flags byte.
 void updateChecksum(DataOutputChecksum checksum)
          Updates a Checskum with all this object's data.
 boolean usesCompression()
          Returns true if this frame used compression in the stream from which it was read.
 boolean usesDataLengthIndicator()
          Returns true if this frame encoded the length of its data in the stream from which it was read.
 boolean usesEncryption()
          Returns true if this frame was encrypted in the stream from which it was read.
 boolean usesGroupID()
          Returns true if this frame is part of a group of frames.
 boolean usesUnsynchronization()
          Returns true if this frame was unsynchronized in the stream from which it was read.
abstract  void writeTo(java.io.OutputStream os)
          Writes this FrameHeader to an OutputStream.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

FRAMEHEADER_CLASS_INFO

private static java.util.ResourceBundle FRAMEHEADER_CLASS_INFO
A resource bundle listing the subclass by version


FRAMEHEADER_CLASSES

private static java.util.Hashtable FRAMEHEADER_CLASSES
The Hashtable which contains all the initialized class objects of our subclasses, keyed by version. Subclasses get added to this Hashtable as they become needed. Lazy initialization rules.


CONSTRUCTOR_PARAMS_TYPES_ARRAY

private static final java.lang.Class[] CONSTRUCTOR_PARAMS_TYPES_ARRAY
An array containing the Class objects which select the constructor of the FrameHeader subclass to be used.


DEFAULT

private static final java.lang.String DEFAULT
A mnemotechnic/easy parameter to pass the ResourceBundle and obtain the FrameHeader subclass implementing the newest spec.

See Also:
Constant Field Values

id

private java.lang.String id
The Frame ID


frameLength

private transient int frameLength
The Frame length


dataLength

private transient int dataLength
The Data length This may be different from the Frame length in the presence of compression, for example.


changed

private transient boolean changed
Whether this FrameHeader object has been changed.


NULL_ID

protected static final java.lang.String NULL_ID
A string consisting of four nulls. There is a better way.

Constructor Detail

FrameHeader

protected FrameHeader()
Default constructor. Constructs a FrameHeader object with zeroed flags and and undefined frame ID. This constructor is used by the factory method getNewInstance(short version and throws no exceptions; the default constructors for FrameHeader subclasses shoudn't either.

This constructor should not be called by normal users of FrameHeader objects. Use the static factory method FrameHeader.getNewInstance(short version) instead.


FrameHeader

protected FrameHeader(java.io.InputStream in)
               throws PaddingException,
                      TagDataFormatException,
                      java.io.IOException
Constructs a FrameHeader from an InputStream. This constructor is used by the factory method getNewInstance(short version, java.io.InputStream in) and can throw two types of exceptions. Corresponding constructors for FrameHeader subclasses should limit themselves to declaring the same two exceptions.

This constructor should not be called by normal users of FrameHeader objects. Use the static factory method FrameHeader.getNewInstance(short version, java.io.InputStream in) instead.

Parameters:
in - An InputStream from which to read the FrameHeader information.
Throws:
PaddingException - if all bytes read as the Frame ID are nulls
java.io.IOException - if the InputStream throws one
TagDataFormatException
Method Detail

isValidFrameID

public static boolean isValidFrameID(java.lang.String frameID)
Checks a 4-character String to see whether or not it's a valid ID3v2 frame ID.

Parameters:
frameID - The frame ID string.
Returns:
true if the string is a valid frame ID, false otherwise.

getNewInstance

public static FrameHeader getNewInstance()
Create a new FrameHeader object using the newest known version.

Returns:
a new FrameHeader object using the newest known version.

getNewInstance

public static FrameHeader getNewInstance(short version)
                                  throws TagDataFormatException
Create a new FrameHeader object of a subclass appropriate for the version parameter.

Parameters:
version - the version of ID3v2 for which to get a FrameHeader object
Returns:
a new FrameHeader object of the appropriate type.
Throws:
TagDataFormatException

getNewInstance

public static FrameHeader getNewInstance(short version,
                                         java.lang.String frameID)
                                  throws TagDataFormatException
Create a new FrameHeader object from an appropriate subclass, using the given frame ID and the default flags.

Parameters:
version - the version.
frameID - the frame ID.
Returns:
a new FrameHeader object of the appropriate type.
Throws:
TagDataFormatException

getNewInstance

public static FrameHeader getNewInstance(short version,
                                         java.io.InputStream in)
                                  throws PaddingException,
                                         TagDataFormatException,
                                         java.io.IOException
Create a new FrameHeader object of a subclass appropriate for the version parameter. This newInstance() method's version parameter has the ID3v2 major version number in its high byte, and the minor version number in its low byte.

Parameters:
version - the version of ID3v2 for which to get a FrameHeader object
in - an InputStream value
Returns:
a new FrameHeader object of the appropriate type.
Throws:
PaddingException - if the bytes read as Frame ID are nulls.
java.io.IOException - if an I/O error occurs.
FrameDataFormatException - if the formatting of the stream is incorrect for this frame.
TagDataFormatException

GetFrameHeaderClass

private static java.lang.Class GetFrameHeaderClass(short version)
                                            throws TagDataFormatException
Returns the FrameHeader subclass to be used for the given ID3v2 version. This lazily initializes each of the classes, as they become necessary.

Parameters:
version - the ID3v2 version to which the subclass is to correspond.
Returns:
the FrameHeader subclass to be used for the given ID3v2 version.
Throws:
FrameDataFormatException - if the version is unsupported.
TagDataFormatException

GetFrameHeaderClass

private static java.lang.Class GetFrameHeaderClass(java.lang.String version)
Returns the FrameHeader subclass to be used for the given ID3v2 version. This lazily initializes each of the classes, as they become necessary.

Parameters:
version - the ID3v2 version to which the subclass is to correspond.
Returns:
the FrameHeader subclass to be used for the given ID3v2 version.

updateChecksum

public void updateChecksum(DataOutputChecksum checksum)
Updates a Checskum with all this object's data. This is used by the getChecksum() method, and can be used by other objects which may have this object as a data member.

Parameters:
checksum - a Checksum to be updated.

getChecksum

public final java.util.zip.Checksum getChecksum()
Returns a Checksum of all this object's data. This is used by the hashcode() method.

Returns:
a Checksum of all this object's data.

hashCode

public final int hashCode()
Returns a hash code for this FrameHeader object. Subclasses must override the getChecksum() method in order to return a good hash code.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code for this FrameHeader object.

clone

public java.lang.Object clone()
Returns a clone of this Flags object. The object returned by this implementation already has the proper type. In order for this method to work, subclasses of BaseFrame must have a default constructor accessible to this class.

Overrides:
clone in class java.lang.Object
Returns:
a clone of this Flags object.

equals

public boolean equals(java.lang.Object other)
Compares this FrameHeader object with another one.

Overrides:
equals in class java.lang.Object
Parameters:
other - The other object.
Returns:
true if the two objects are equivalent, false otherwise.

toString

public java.lang.String toString()
Returns a String representation of this FrameHeader object.

Overrides:
toString in class java.lang.Object
Returns:
a String representation of this FrameHeader object.

isChanged

public boolean isChanged()
Return true if this FrameHeader method has been changed.

Returns:
true if this FrameHeader object has been changed.

setChanged

public void setChanged(boolean changed)
Sets or clears the "changed" bit.

Parameters:
changed - true to set the changed bit, false to clear it.

getFrameID

public final java.lang.String getFrameID()
Returns the type string for this frame.

Returns:
the type string for this frame.

setFrameID

public void setFrameID(java.lang.String newID)
Set the ID for the frame.

Subclasses will probably want to override this and check for sanity.

Parameters:
newID - A string containing the new ID to use for the frame.

getFrameLength

public int getFrameLength()
Returns the frame length in bytes, if the frame was read from a stream. If the frame was not read from a stream, then this value is undefined.

Returns:
int the frame length in bytes.

setFrameLength

protected final void setFrameLength(int theLength)
Set the frame length in bytes.

Parameters:
theLength - the frame length in bytes.

getDataLength

public int getDataLength()
Returns the length of the length of the raw data for this frame, without any encoding such as compression or unsynchronization. This value will be set if the frame was read from a stream; if it was not read from a stream or file, this value is undefined.

Returns:
the data length in bytes.

setDataLength

protected final void setDataLength(int theLength)
Set the data length in bytes.

Parameters:
theLength - the data length in bytes.

getStatusFlags

public byte getStatusFlags()
Returns this frame's status flags byte. This implementation returns zero.

Returns:
this frame's status flags byte.

setStatusFlags

public void setStatusFlags(byte flags)
Set this frame's status flags byte. This implementation does nothing.

Parameters:
flags - The flags byte that is to be used from now on.

checkStatusMask

public final boolean checkStatusMask(byte flagMask)
Check whether a combination of bits is set in the status flags byte.

Parameters:
flagMask - the combination of bits to check in the status flags byte.
Returns:
whether the bits from the mask are set in the status flags byte.

setStatusMask

public final void setStatusMask(byte flagMask)
Set the bits corresponding to a mask of bits in the status flags byte.

Parameters:
flagMask - the combination of bits to set in the status flags byte.

unsetStatusMask

public final void unsetStatusMask(byte flagMask)
Unset the bits corresponding to a mask of bits in the status flags byte.

Parameters:
flagMask - the combination of bits to unset in the status flags byte.

getFormatFlags

public byte getFormatFlags()
Returns this frame's format flags byte. This implementation returns zero.

Returns:
this frame's format flags byte.

setFormatFlags

public void setFormatFlags(byte flags)
Set this frame's format flags byte. This implementation does nothing.

Parameters:
flags - The flags byte that is to be used from now on.

checkFormatMask

public final boolean checkFormatMask(byte flagMask)
Check whether a combination of bits is set in the format flags byte.

Parameters:
flagMask - the combination of bits to check in the format flags byte.
Returns:
whether the bits from the mask are set in the format flags byte.

setFormatMask

public final void setFormatMask(byte flagMask)
Set the bits corresponding to a mask of bits in the format flags byte.

Parameters:
flagMask - the combination of bits to set in the format flags byte.

unsetFormatMask

public final void unsetFormatMask(byte flagMask)
Unset the bits corresponding to a mask of bits in the format flags byte.

Parameters:
flagMask - the combination of bits to unset in the format flags byte.

usesCompression

public boolean usesCompression()
Returns true if this frame used compression in the stream from which it was read.

Returns:
true if this frame was read from compressed data.

usesGroupID

public boolean usesGroupID()
Returns true if this frame is part of a group of frames.

Returns:
true if this frame is part of a group of frames.

usesEncryption

public boolean usesEncryption()
Returns true if this frame was encrypted in the stream from which it was read.

Returns:
true if this frame was encrypted in the stream.

usesUnsynchronization

public boolean usesUnsynchronization()
Returns true if this frame was unsynchronized in the stream from which it was read.

Returns:
true if this frame was unsynchronized in the stream.

usesDataLengthIndicator

public boolean usesDataLengthIndicator()
Returns true if this frame encoded the length of its data in the stream from which it was read.

Returns:
a boolean value

getFrameBytesFromStream

public byte[] getFrameBytesFromStream(java.io.InputStream in,
                                      long availableBytes)
                               throws java.io.IOException,
                                      TagDataFormatException,
                                      FrameDataFormatException
Extract the frame's raw data from the InputStream. This method is used by Frame.FromInputStream(InputStream) during the tag parsing stage, and guarantees that barring any problems on the input stream, the frame's data bytes will be read. Subclasses should not override this method, but should override the processInput method (in which InputStream filters can be layered onto the input in order to perform some data formatting/decoding).

This implementation reads dataLength bytes from in if dataLength is set, otherwise it frameLength bytes.

Parameters:
in - The InputStream from which to extract the bytes.
Returns:
a byte array from which the frame data can be parsed.
Throws:
java.io.IOException - if the InputStream throws one, or if the Stream is unable to produce the necessary number of bytes.
FrameDataFormatException - if the frame cannot be decoded because of unknown frame flags.
TagDataFormatException

decodeFrameBytesFromStream

private byte[] decodeFrameBytesFromStream(java.io.InputStream stream)
                                   throws FrameDataFormatException
This is an auxiliary method to the getFrameBytesFromStream method. If a special InputStream is needed to decode the frame, this method will be called to do the decoding. This was done to add some logical structure to the getFrameBytesFromStream method.

Parameters:
stream - the stream from which the frame bytes will be read.
Returns:
a byte array from which the frame data can be parsed.
Throws:
FrameDataFormatException - if the data is formatted in an incorrect or incompatible manner.

writeTo

public abstract void writeTo(java.io.OutputStream os)
                      throws java.io.IOException
Writes this FrameHeader to an OutputStream. This method is used by Frame subclasses during the execution of their writeTo(OutputStream) and getBytes() methods.

The state of the object should be assumed to have preliminarily been updated with data and values obtained from the

processInput

protected java.io.InputStream processInput(java.io.InputStream in)
                                    throws FrameDataFormatException
Layer input stream filters over in, and return the resulting input stream.

Subclasses should override this method in order to do any decoding of the frame data required to make the frames parseable in "clear text".

Parameters:
in - the initial input stream.
Returns:
an input stream capable of completely decoding the frame data.
Throws:
FrameDataFormatException - if the frame cannot be decoded for any reason (most likely due to incorrect data formatting).

processOutput

protected java.io.OutputStream processOutput(java.io.OutputStream out)
                                      throws java.io.IOException
Process the OutputStream in which the frame is to be embedded. This method is called by Frame subclasses when the frame is being written to a file or stream

A FrameHeader subclass should override this method and apply whatever calculations and FilterOutputStream subclasses are necessary to output a correct stream of the frame. See the method postProcessUnsynchronization() of Flags for an example of a FilterOutputStream that can be applied through this method.

Parameters:
out - the OutputStream to which the frame will be written
Returns:
the OutputStream to which the frame will be written
Throws:
java.io.IOException - if an error occurs