com.tffenterprises.music.tag.id3v2
Class Frame

java.lang.Object
  extended by com.tffenterprises.music.tag.id3v2.Frame
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
BaseFrame, Container

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

This class is the superclass of all ID3v2 frame types. It contains factory methods to generate ID3v2 frames from streams and byte arrays, as well as accessor methods, output methods, and other methods common to all ID3v2 frames. As it is an abstract class, it cannot be instantiated on its own.

Note that all subclasses of Frame are REQUIRED, in addition to any special constructors they might have, to contain a public constructor which takes a FrameHeader object as an argument. They are also required to override the setRawData(byte[] data) method and update the internal representation of their data using its byte array argument. See setRawData(byte[] data) and BaseFrame(FrameHeader header) for further details.

Subclasses provided by TFF Enterprises (e.g. TextFrame, URLLinkFrame) are automatically used by this library. Subclasses provided by third parties must be explicitly made known to the the Frame class object, using the method RegisterFrameClass(String, Class).

Version:
1.0d1 $Date: 2004/04/25 04:02:46 $
Author:
Daniel M. Zimmerman, Guillaume Lessard
See Also:
Serialized Form

Field Summary
private static java.lang.Class[] CONSTRUCTOR_TYPES
          An array containing the Class objects which select the constructor of the Frame subclass to be used.
private static java.lang.Class FRAME_CLASS
          The Class object for this class.
private static java.util.Hashtable FRAME_CLASSES
          The Hashtable which contains all the frame IDs (types) and the frame classes with which they are associated.
private static java.util.ResourceBundle FRAME_TYPE_CLASS_MAPPINGS
          A ResourceBundle containing some mappings between frame IDs and classes.
private static java.lang.Class GENERIC_FRAME_CLASS
          The Class object for the generic frame class.
private static java.lang.Class TEXT_FRAME_CLASS
          The Class object for the generic text frame class.
 
Constructor Summary
Frame()
           
 
Method Summary
abstract  java.lang.Object clone()
          Returns a clone of this ID3v2 frame.
abstract  boolean equals(java.lang.Object other)
          Compares this ID3v2 frame with another object.
static Frame FromByteArray(short version, byte[] byteArray)
          Creates an ID3v2 frame from a byte array.
static Frame FromByteArray(short version, byte[] byteArray, int offset)
          Creates an ID3v2 frame from a byte array, starting at the specified offset.
static Frame FromInputStream(short version, java.io.InputStream inputStream, long availableBytes)
          Creates an ID3v2 frame from an InputStream.
abstract  java.util.zip.Checksum getChecksum()
          Returns a checksum updated with this frame's data.
abstract  byte getFormatFlags()
          Returns the format flags of this frame.
static java.lang.Class GetFrameClassForID(java.lang.String frameID)
          Obtain a Frame subclass to handle a particular type of ID3v2 frame.
abstract  java.lang.String getFrameID()
          Returns the frame ID of this frame.
protected abstract  FrameHeader getHeader()
          Returns the FrameHeader object that corresponds to this Frame instance.
static Frame getNewInstance(FrameHeader header)
          Create a new Frame object of an appropriate subtype, given a FrameHeader.
static Frame getNewInstance(FrameHeader header, java.lang.String theID)
          Create a new Frame object of an appropriate subtype, given a FrameHeader and a specific frame ID.
static Frame getNewInstance(java.lang.String theID)
          Create a new Frame object of an appropriate subtype, given a frame ID.
abstract  byte[] getRawData()
          Returns the raw data corresponding to this frame.
abstract  byte getStatusFlags()
          Returns the status flags of this frame.
abstract  int hashCode()
          Returns a hash code for this ID3v2 frame.
abstract  boolean isChanged()
          Returns true is this frame has been changed.
abstract  boolean isOfRepeatableType()
          Certain frame types can coexist with others of their type within a certain tag, while others must be unique.
static int MinimumLength(short version)
          A little utility to return the minimum length of a frame according to the ID3v2 version.
static java.lang.Class RegisterFrameClass(java.lang.String frameID, java.lang.Class frameClass)
          Registers a subclass for processing a particular type of ID3v2 frame.
abstract  void setChanged(boolean changed)
          Sets the changed state of this frame
abstract  void setFormatFlags(byte flags)
          Sets the format flags of this frame.
abstract  void setRawData(byte[] rawData)
          Sets the raw data corresponding to this frame, and changes the frame's internal data represntation to reflect this new raw data, i.e.
abstract  void setStatusFlags(byte flags)
          Sets the status flags of this frame.
abstract  byte[] toByteArray()
          Returns a byte array containing the representation of this frame as it should be written to an ID3v2 tag.
abstract  java.lang.String toString()
          Returns a String representation of this frame.
static java.lang.Class UnregisterFrameClass(java.lang.String frameID)
          Unregisters a subclass for processing a particular type of ID3v2 frame.
abstract  void updateChecksum(DataOutputChecksum checksum)
          Updates a checksum with this frame's data
abstract  void writeTo(java.io.OutputStream outputStream)
          Writes this tag to an output stream.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

CONSTRUCTOR_TYPES

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


FRAME_CLASSES

private static final java.util.Hashtable FRAME_CLASSES
The Hashtable which contains all the frame IDs (types) and the frame classes with which they are associated. Initialized statically.


FRAME_CLASS

private static final java.lang.Class FRAME_CLASS
The Class object for this class. This is useful to determine whether a class passed-in to get registered is a subclass of this class, as it should be.


GENERIC_FRAME_CLASS

private static final java.lang.Class GENERIC_FRAME_CLASS
The Class object for the generic frame class.


TEXT_FRAME_CLASS

private static final java.lang.Class TEXT_FRAME_CLASS
The Class object for the generic text frame class.


FRAME_TYPE_CLASS_MAPPINGS

private static java.util.ResourceBundle FRAME_TYPE_CLASS_MAPPINGS
A ResourceBundle containing some mappings between frame IDs and classes. (for when they're not obvious).

Constructor Detail

Frame

public Frame()
Method Detail

FromInputStream

public static Frame FromInputStream(short version,
                                    java.io.InputStream inputStream,
                                    long availableBytes)
                             throws PaddingException,
                                    TagDataFormatException,
                                    java.io.IOException
Creates an ID3v2 frame from an InputStream. The InputStream should be positioned at the beginning of the frame data (ie: the first byte of the frame ID). If the data is not a valid ID3v2 frame, this method returns null.

This method will in any case read all the bytes for a given frame off the stream, but does not guarantee that a valid Frame object will be returned from the bytes that were read. That is, if the method returns without throwing an exception, the stream can be expected to be at the beginning of the next frame even if no Frame was returned.

Parameters:
version - The version of the ID3v2 spec to be used for this frame.
inputStream - The InputStream to read from.
availableBytes - The number of bytes that should be considered available in the stream.
Returns:
the newly-created Frame object.
Throws:
PaddingException - if padding is encountered instead of a frame.
java.io.IOException - if there is a problem reading from the specified InputStream.
TagDataFormatException

FromByteArray

public static Frame FromByteArray(short version,
                                  byte[] byteArray)
                           throws TagDataFormatException,
                                  PaddingException
Creates an ID3v2 frame from a byte array. The first byte of the byte array should be the beginning of the frame data (i.e. the first byte of the frame ID). If the data is not a valid ID3v2 frame, this method returns null. Invoking this method is defined as equivalent to invoking Frame.FromByteArray(version, byteArray, 0).

Parameters:
version - The version of the ID3v2 spec to be used for this frame.
byteArray - The byte array.
Returns:
the newly-created Frame object.
Throws:
java.lang.IllegalArgumentException - if the byte array is null.
PaddingException - if padding is encountered instead of a frame.
TagDataFormatException

FromByteArray

public static Frame FromByteArray(short version,
                                  byte[] byteArray,
                                  int offset)
                           throws TagDataFormatException,
                                  PaddingException
Creates an ID3v2 frame from a byte array, starting at the specified offset. The specified offset should be the beginning of the frame data (ie: the first byte of the frame ID). If the data is not a valid ID3v2 frame, this method returns null.

Parameters:
version - The version of the ID3v2 spec to be used for this frame.
byteArray - The byte array.
offset - The offset.
Returns:
the newly-created Frame object.
Throws:
java.lang.IllegalArgumentException - if the byte array is null.
PaddingException - if padding is encountered instead of a frame.
TagDataFormatException

getNewInstance

public static Frame getNewInstance(FrameHeader header,
                                   java.lang.String theID)
Create a new Frame object of an appropriate subtype, given a FrameHeader and a specific frame ID.

Parameters:
header - the new Frame's FrameHeader.
theID - the new frame ID.
Returns:
a new Frame object.

getNewInstance

public static Frame getNewInstance(java.lang.String theID)
Create a new Frame object of an appropriate subtype, given a frame ID. The object will implement the latest supported ID3v2 specification.

Parameters:
theID - the new frame ID.
Returns:
a new Frame object.

getNewInstance

public static Frame getNewInstance(FrameHeader header)
Create a new Frame object of an appropriate subtype, given a FrameHeader.

Parameters:
header - the new Frame's FrameHeader.
Returns:
a new Frame object.

RegisterFrameClass

public static java.lang.Class RegisterFrameClass(java.lang.String frameID,
                                                 java.lang.Class frameClass)
                                          throws java.lang.IllegalArgumentException
Registers a subclass for processing a particular type of ID3v2 frame. This subclass will then be used automatically, each type a frame of that type is parsed. If a subclass for processing the specified type is already registered, it is replaced by the new subclass.

Parameters:
frameID - The frame ID (4-letter String identifying the frame type).
frameClass - The Class to be used to process frames of the type corresponding to this ID.
Returns:
the previous Class which had previously registered to process frames with this ID, or null if there was none.
Throws:
java.lang.IllegalArgumentException - if the specified frame ID does not conform to the ID3v2 specification, or if the specified class is not a subclass of Frame, or if either parameter is null.

UnregisterFrameClass

public static java.lang.Class UnregisterFrameClass(java.lang.String frameID)
Unregisters a subclass for processing a particular type of ID3v2 frame. If no subclass has been registered for that type of frame, this method silently does nothing.

Parameters:
frameID - The frame ID (4-letter String identifying the frame type).
Returns:
the previous Class which was to be used to process frames with this ID, or null if no Class had previously been registered for this ID.

GetFrameClassForID

public static java.lang.Class GetFrameClassForID(java.lang.String frameID)
Obtain a Frame subclass to handle a particular type of ID3v2 frame. If no subclass is found, this will return the GenericFrame class, or an exception will be thrown if something unsavory happens.

Parameters:
frameID - The frame ID (String identifying the frame type).
Returns:
the Class object to be used to handle the frame.

MinimumLength

public static int MinimumLength(short version)
A little utility to return the minimum length of a frame according to the ID3v2 version. This is unfortunately a bit hackish, but I haven't found another way that isn't a shameful resource drain.

Parameters:
version - the ID3v2 version for which we want to find the minimum length of a frame.
Returns:
the mimimum length of a frame for the given version parameter.

clone

public abstract java.lang.Object clone()
Returns a clone of this ID3v2 frame.

Overrides:
clone in class java.lang.Object
Returns:
a clone of this ID3v2 frame.

updateChecksum

public abstract void updateChecksum(DataOutputChecksum checksum)
Updates a checksum with this frame's data

Parameters:
checksum - the checksum to update

getChecksum

public abstract java.util.zip.Checksum getChecksum()
Returns a checksum updated with this frame's data.

Returns:
a checksum updated with this frame's data.

hashCode

public abstract int hashCode()
Returns a hash code for this ID3v2 frame.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code for this ID3v2 frame.

equals

public abstract boolean equals(java.lang.Object other)
Compares this ID3v2 frame with another object.

Overrides:
equals in class java.lang.Object
Parameters:
other - The other object.
Returns:
true if the two objects are of the same class and both non-null, false otherwise.

getFrameID

public abstract java.lang.String getFrameID()
Returns the frame ID of this frame.

Returns:
the frame ID of this frame.

getFormatFlags

public abstract byte getFormatFlags()
Returns the format flags of this frame.

Returns:
the format flags of this frame.

setFormatFlags

public abstract void setFormatFlags(byte flags)
Sets the format flags of this frame.

Parameters:
flags - The flags.

getStatusFlags

public abstract byte getStatusFlags()
Returns the status flags of this frame.

Returns:
the status flags of this frame.

setStatusFlags

public abstract void setStatusFlags(byte flags)
Sets the status flags of this frame.

Parameters:
flags - The flags.

isChanged

public abstract boolean isChanged()
Returns true is this frame has been changed.

Returns:
true is this frame has been changed.

setChanged

public abstract void setChanged(boolean changed)
Sets the changed state of this frame

Parameters:
changed - true if the frame is to be considered changed.

getRawData

public abstract byte[] getRawData()
Returns the raw data corresponding to this frame. This does not include the frame header, or any data transformations that are indicated in the frame header flags. If the frame contains invalid data and should not be written out, the implementation should return a zero-length byte array.

Returns:
the raw data corresponding to this frame.

setRawData

public abstract void setRawData(byte[] rawData)
                         throws FrameDataFormatException,
                                java.lang.IllegalArgumentException
Sets the raw data corresponding to this frame, and changes the frame's internal data represntation to reflect this new raw data, i.e. a frame class which has special getter/setter methods must update the data to be returned by those methods when the raw data is changed.

Parameters:
rawData - The raw data.
Throws:
FrameDataFormatException - if the raw data is not in an appropriate format for this frame type.
java.lang.IllegalArgumentException - if the specified raw data is null.

toString

public abstract java.lang.String toString()
Returns a String representation of this frame.

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

toByteArray

public abstract byte[] toByteArray()
Returns a byte array containing the representation of this frame as it should be written to an ID3v2 tag. This includes the frame header, and any data transformations that are indicated the frame header flags. Be careful not to write an empty frame to the stream!

Returns:
a byte array containing the representation of this frame as it should be written to an ID3v2 tag.

writeTo

public abstract void writeTo(java.io.OutputStream outputStream)
                      throws java.io.IOException,
                             java.lang.IllegalArgumentException
Writes this tag to an output stream. The bytes written to the stream are identical to those returned by toByteArray(). Be careful not to write an empty frame to the stream!

Parameters:
outputStream - The output stream.
Throws:
java.io.IOException - if there is a problem writing to the stream.
java.lang.IllegalArgumentException - if the specified output stream is null.

isOfRepeatableType

public abstract boolean isOfRepeatableType()
Certain frame types can coexist with others of their type within a certain tag, while others must be unique. A subclass of Frame can be queried whether it represents a frame type that can exist in multiple instances if its isOfRepeatableType() method returns true.

Returns:
whether it is correct for multiple frames of this type to exist in the same ID3v2 tag.

getHeader

protected abstract FrameHeader getHeader()
Returns the FrameHeader object that corresponds to this Frame instance.

If there is a good reason to make this a public method, chime in.

Returns:
this frame's FrameHeader object.