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

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

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

This is an abstract superclass implementing common code for subclasses of Frame. BaseFrame implements shared instance code, while Frame has static code only.

The only methods required of a a subclass of BaseFrame are appropriate constructor, including a default public constructor and a constructor accepting a FrameHeader object as a parameter (see BaseFrame(FrameHeader header). BaseFrame subclasess must also provide implementations of getRawData() and setRawData(byte[] data).

Ideally, subclasses should also override and extend the methods clone(), getChecksum() and toString().

Note that among the constructors, a the default constructor is required for correct behaviour of the clone() method.

Version:
1.0d1 $Date: 2002/10/31 08:23:15 $
Author:
Guillaume Lessard, Daniel M. Zimmerman
See Also:
Serialized Form

Field Summary
private  boolean changed
          The changed bit for this frame.
private  FrameHeader header
          This frame's FrameHeader
 
Constructor Summary
protected BaseFrame()
          Protected default constructor.
protected BaseFrame(FrameHeader header)
          Frame subclasses MUST provide a constructor with this parameter list.
 
Method Summary
 java.lang.Object clone()
          Returns a clone of this ID3v2 frame.
 boolean equals(java.lang.Object other)
          Compares this ID3v2 frame with another object.
protected  byte[] getBytes()
          Returns this frame object's byte representation, in a fast way that is potentially less secure than getRawData().
 java.util.zip.Checksum getChecksum()
          Returns a CheckSum object updated with this object.
 byte getFormatFlags()
          Returns the format flags of this frame.
 java.lang.String getFrameID()
          Returns the frame ID of this frame.
protected  FrameHeader getHeader()
          Returns this frame object's FrameHeader instance.
abstract  byte[] getRawData()
          Returns the raw data corresponding to this frame.
 byte getStatusFlags()
          Returns the status flags of this frame.
 int hashCode()
          Returns a hash code for this ID3v2 frame.
 boolean isChanged()
          Returns the changed state of this frame.
 boolean isOfRepeatableType()
          Returns whether it is correct for multiple frames of the same type as this one to coexist in the same ID3v2 tag.
 void setChanged(boolean changed)
          Sets the changed state of this frame
 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.
 void setStatusFlags(byte flags)
          Sets the status flags of this frame.
 byte[] toByteArray()
          Returns a byte array containing the representation of this frame as it should be written to an ID3v2 tag.
 java.lang.String toString()
          Returns a String representation of this frame.
 void updateChecksum(DataOutputChecksum checksum)
          Updates a DataOutputChecksum object with this frame's data.
private  void writeFrameBytesToStream(java.io.OutputStream os, byte[] frameBytes)
          Utility method to write the given frame data to the given output stream.
 void writeTo(java.io.OutputStream outputStream)
          Writes this tag to an output stream.
 
Methods inherited from class com.tffenterprises.music.tag.id3v2.Frame
FromByteArray, FromByteArray, FromInputStream, GetFrameClassForID, getNewInstance, getNewInstance, getNewInstance, MinimumLength, RegisterFrameClass, UnregisterFrameClass
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

header

private FrameHeader header
This frame's FrameHeader


changed

private transient boolean changed
The changed bit for this frame.

Constructor Detail

BaseFrame

protected BaseFrame()
Protected default constructor. BaseFrame is an abstract class, so it should not be instantiated directly; this constructor is provided as a utility for subclasses of BaseFrame.


BaseFrame

protected BaseFrame(FrameHeader header)
             throws java.lang.IllegalArgumentException
Frame subclasses MUST provide a constructor with this parameter list. Such a constructor should do little more than sanity checking, and should throw nothing else than RuntimeExceptions in the case of crippling errors, or IllegalArgumentExceptions for serious failures in sanity-checking.

Parameters:
header - The FrameHeader to be used for this Frame instance. See FrameHeader for details.
Throws:
java.lang.IllegalArgumentException - This is exception is thrown when the parameter is unacceptable for use with an object of this Frame class/subclass.
Method Detail

clone

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

Specified by:
clone in class Frame
Returns:
a clone of this ID3v2 frame.

updateChecksum

public void updateChecksum(DataOutputChecksum checksum)
Updates a DataOutputChecksum object with this frame's data. Subclasses don't need to override this method, as the output of the getRawData() method is processed. If somehow some other transient data is relevant, then they can override this method.

Specified by:
updateChecksum in class Frame
Parameters:
checksum - the Checksum to be updated.

getChecksum

public final java.util.zip.Checksum getChecksum()
Returns a CheckSum object updated with this object. Subclasses should override this method rather than the hashCode method. Subclasses need only update the CheckSum with their extra data, as the class name is already taken into account.

Note that as long as all the frame's significant data makes it in the output of getRawData(), there isn't really a need to override this method.

Specified by:
getChecksum in class Frame
Returns:
a CheckSum object updated with this object's data.

hashCode

public final int hashCode()
Returns a hash code for this ID3v2 frame. This method should be overridden by subclasses and updated with their local data.

Specified by:
hashCode in class Frame
Returns:
a hash code for this ID3v2 frame.

equals

public boolean equals(java.lang.Object other)
Compares this ID3v2 frame with another object. This method compares the classes of the objects, and returns false if the objects are either not of the same class or if one is null but the other is not. It returns true otherwise, regardless of the contents of the objects; thus, it can be used within the equals() methods of subclasses, with a call to "super.equals()", to do the class and nullness comparison.

Specified by:
equals in class Frame
Parameters:
other - The other object.
Returns:
true if the two objects are of the same class and both non-null, false otherwise.

toString

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

Specified by:
toString in class Frame
Returns:
a String representation of this frame.

getFrameID

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

Specified by:
getFrameID in class Frame
Returns:
the frame ID of this frame.

getStatusFlags

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

Specified by:
getStatusFlags in class Frame
Returns:
the status flags of this frame.

setStatusFlags

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

Specified by:
setStatusFlags in class Frame
Parameters:
flags - The new status flags.

getFormatFlags

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

Specified by:
getFormatFlags in class Frame
Returns:
the format flags of this frame.

setFormatFlags

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

Specified by:
setFormatFlags in class Frame
Parameters:
flags - The new format flags.

isChanged

public boolean isChanged()
Returns the changed state of this frame.

Specified by:
isChanged in class Frame
Returns:
the changed state of this frame.

setChanged

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

Specified by:
setChanged in class Frame
Parameters:
changed - whether 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! NOTE: subclasses must override this.

Specified by:
getRawData in class Frame
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.

NOTE: subclasses must override this.

Specified by:
setRawData in class Frame
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.

toByteArray

public 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.

Specified by:
toByteArray in class Frame
Returns:
a byte array containing the representation of this frame as it should be written to an ID3v2 tag.

writeTo

public 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().

Specified by:
writeTo in class Frame
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.

writeFrameBytesToStream

private void writeFrameBytesToStream(java.io.OutputStream os,
                                     byte[] frameBytes)
                              throws java.io.IOException
Utility method to write the given frame data to the given output stream.

Parameters:
os - The output stream.
frameBytes - the bytes to be written out to the output stream.
Throws:
java.io.IOException - if there is a problem writing to the stream.

isOfRepeatableType

public boolean isOfRepeatableType()
Returns whether it is correct for multiple frames of the same type as this one to coexist in the same ID3v2 tag. This default implementation returns false for convenience, given that multiplicity is disallowed in most cases.

Specified by:
isOfRepeatableType in class Frame
Returns:
true if it is correct for multiple frames of this type to exist in the same ID3v2 tag, false otherwise.

getHeader

protected final FrameHeader getHeader()
Returns this frame object's FrameHeader instance.

Specified by:
getHeader in class Frame
Returns:
this frame object's FrameHeader instance.

getBytes

protected byte[] getBytes()
Returns this frame object's byte representation, in a fast way that is potentially less secure than getRawData(). This method is to be used by subclasses of BaseFrame only, and overridden in cases where the functionality of getRawData() can be sped up at the expense of security.

The default implementation (this one) simply calls getRawData()

Returns:
a frame object's byte representation.