|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.tffenterprises.music.tag.id3v2.frame.FrameHeader
public abstract class FrameHeader
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...
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 |
---|
private static java.util.ResourceBundle FRAMEHEADER_CLASS_INFO
private static java.util.Hashtable FRAMEHEADER_CLASSES
private static final java.lang.Class[] CONSTRUCTOR_PARAMS_TYPES_ARRAY
private static final java.lang.String DEFAULT
private java.lang.String id
private transient int frameLength
private transient int dataLength
private transient boolean changed
protected static final java.lang.String NULL_ID
Constructor Detail |
---|
protected FrameHeader()
This constructor should not be called by normal users of FrameHeader objects. Use the static factory method FrameHeader.getNewInstance(short version) instead.
protected FrameHeader(java.io.InputStream in) throws PaddingException, TagDataFormatException, java.io.IOException
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.
in
- An InputStream from which to read the FrameHeader information.
PaddingException
- if all bytes read as the Frame ID are nulls
java.io.IOException
- if the InputStream throws one
TagDataFormatException
Method Detail |
---|
public static boolean isValidFrameID(java.lang.String frameID)
frameID
- The frame ID string.
public static FrameHeader getNewInstance()
public static FrameHeader getNewInstance(short version) throws TagDataFormatException
version
- the version of ID3v2 for which to get a FrameHeader object
TagDataFormatException
public static FrameHeader getNewInstance(short version, java.lang.String frameID) throws TagDataFormatException
version
- the version.frameID
- the frame ID.
TagDataFormatException
public static FrameHeader getNewInstance(short version, java.io.InputStream in) throws PaddingException, TagDataFormatException, java.io.IOException
version
- the version of ID3v2 for which to get a FrameHeader objectin
- an InputStream
value
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
private static java.lang.Class GetFrameHeaderClass(short version) throws TagDataFormatException
version
- the ID3v2 version to which the subclass is to correspond.
FrameDataFormatException
- if the version is unsupported.
TagDataFormatException
private static java.lang.Class GetFrameHeaderClass(java.lang.String version)
version
- the ID3v2 version to which the subclass is to correspond.
public void updateChecksum(DataOutputChecksum checksum)
checksum
- a Checksum to be updated.public final java.util.zip.Checksum getChecksum()
public final int hashCode()
hashCode
in class java.lang.Object
public java.lang.Object clone()
clone
in class java.lang.Object
public boolean equals(java.lang.Object other)
equals
in class java.lang.Object
other
- The other object.
public java.lang.String toString()
String
representation of this
FrameHeader
object.
toString
in class java.lang.Object
String
representation of this
FrameHeader
object.public boolean isChanged()
FrameHeader
method has been changed.
FrameHeader
object has been changed.public void setChanged(boolean changed)
changed
- true to set the changed bit, false to clear it.public final java.lang.String getFrameID()
public void setFrameID(java.lang.String newID)
Subclasses will probably want to override this and check for sanity.
newID
- A string containing the new ID to use for the frame.public int getFrameLength()
protected final void setFrameLength(int theLength)
theLength
- the frame length in bytes.public int getDataLength()
protected final void setDataLength(int theLength)
theLength
- the data length in bytes.public byte getStatusFlags()
public void setStatusFlags(byte flags)
flags
- The flags byte that is to be used from now on.public final boolean checkStatusMask(byte flagMask)
flagMask
- the combination of bits to check in the status flags byte.
public final void setStatusMask(byte flagMask)
flagMask
- the combination of bits to set in the status flags byte.public final void unsetStatusMask(byte flagMask)
flagMask
- the combination of bits to unset in the status flags byte.public byte getFormatFlags()
public void setFormatFlags(byte flags)
flags
- The flags byte that is to be used from now on.public final boolean checkFormatMask(byte flagMask)
flagMask
- the combination of bits to check in the format flags byte.
public final void setFormatMask(byte flagMask)
flagMask
- the combination of bits to set in the format flags byte.public final void unsetFormatMask(byte flagMask)
flagMask
- the combination of bits to unset in the format flags byte.public boolean usesCompression()
true
if this frame used compression in
the stream from which it was read.
true
if this frame was read from compressed data.public boolean usesGroupID()
true
if this frame is part of a group of frames.
true
if this frame is part of a group of frames.public boolean usesEncryption()
true
if this frame was encrypted in the stream
from which it was read.
true
if this frame was encrypted in the stream.public boolean usesUnsynchronization()
true
if this frame was unsynchronized in the stream
from which it was read.
true
if this frame was unsynchronized in the stream.public boolean usesDataLengthIndicator()
true
if this frame encoded the length of its
data in the stream from which it was read.
boolean
valuepublic byte[] getFrameBytesFromStream(java.io.InputStream in, long availableBytes) throws java.io.IOException, TagDataFormatException, FrameDataFormatException
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.
in
- The InputStream from which to extract the bytes.
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
private byte[] decodeFrameBytesFromStream(java.io.InputStream stream) throws FrameDataFormatException
stream
- the stream from which the frame bytes will be read.
FrameDataFormatException
- if the data is formatted in an
incorrect or incompatible manner.public abstract void writeTo(java.io.OutputStream os) throws java.io.IOException
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
protected java.io.InputStream processInput(java.io.InputStream in) throws FrameDataFormatException
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".
in
- the initial input stream.
FrameDataFormatException
- if the frame cannot be decoded
for any reason (most likely
due to incorrect data formatting).protected java.io.OutputStream processOutput(java.io.OutputStream out) throws java.io.IOException
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.
out
- the OutputStream to which the frame will be written
java.io.IOException
- if an error occurs
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |