org.blinkenlights.jid3.v2
Class ID3V2Tag

java.lang.Object
  extended byorg.blinkenlights.jid3.ID3Tag
      extended byorg.blinkenlights.jid3.v2.ID3V2Tag
All Implemented Interfaces:
ID3Visitable
Direct Known Subclasses:
ID3V2_3_0Tag

public abstract class ID3V2Tag
extends ID3Tag


Field Summary
protected  boolean m_bCRCDataFlag
          Flag indicating whether a CRC value exists in the extended header.
protected  boolean m_bExperimentalFlag
          Flag indicating this tag should be considered experimental.
protected  boolean m_bExtendedHeaderFlag
          Flag indicating whether the extended header is present or not.
protected  boolean m_bUnsynchronizationUsedFlag
          Flag indicating whether unsynchronization is used in this tag or not.
protected  int m_iPaddingLength
          Value specifying the amount of padding which is appended to the frames in this tag.
protected  java.util.Map m_oFrameIdToFrameMap
          Mapping from frame ID to list containing frames.
 
Constructor Summary
ID3V2Tag(boolean bUnsynchronizationUsedFlag, boolean bExtendedHeaderFlag, boolean bExperimentalFlag)
          Construct an ID3 V2 tag, specifying flag values.
 
Method Summary
abstract  boolean containsAtLeastOneFrame()
          Check if this tag contains at least one frame.
abstract  java.lang.String getAlbum()
          Convenience method for retrieving album title directly from tag.
abstract  java.lang.String getArtist()
          Convenience method for retrieving artist directly from tag.
abstract  java.lang.String getComment()
          Convenience method for retrieving the comment directly from tag.
 boolean getCRC()
          Get the current CRC status for the extended header in this frame.
static int getDefaultPaddingLength()
          Get the default padding length currently set for newly created tags.
 boolean getExtendedHeader()
          Get the current extended header status for this tag.
abstract  java.lang.String getGenre()
          Convenience method for retrieving the genre directly from tag.
 int getPaddingLength()
          Get the padding length currently set for this tag.
 ID3V2Frame[] getSingleFrames()
          Get all frames set in this tag which can only be stored once in the tag.
abstract  java.lang.String getTitle()
          Convenience method for retrieving song title directly from tag.
abstract  int getTotalTracks()
          Convenience method for retrieving total number of tracks directly from tag.
abstract  int getTrackNumber()
          Convenience method for retrieving track number directly from tag.
 boolean getUnsynchronization()
          Get the current unsynchronization status for this tag.
abstract  int getYear()
          Convenience method for retrieving year directly from tag.
static ID3V2Tag read(java.io.InputStream oIS)
          Read a tag from an input stream.
abstract  void sanityCheck()
           
abstract  void setAlbum(java.lang.String sAlbum)
          Convenience method for setting album title directly from tag.
abstract  void setArtist(java.lang.String sArtist)
          Convenience method for setting artist directly from tag.
abstract  void setComment(java.lang.String sComment)
          Convenience method for setting comment directly from tag.
 void setCRC(boolean bCRCUsed)
          Set the CRC flag (extended header must be enabled before this flag can be set.
static void setDefaultPaddingLength(int iPaddingLength)
          Set the default padding length to be added at the end of newly created tags.
 void setExtendedHeader(boolean bExtendedHeaderUsed)
          Set the extended header flag for this tag.
abstract  void setGenre(java.lang.String sGenre)
          Convenience method for setting genre directly from tag.
 void setPaddingLength(int iPaddingLength)
          Set the padding length to be added at the end of this tag.
abstract  void setTitle(java.lang.String sTitle)
          Convenience method for setting song title directly from tag.
abstract  void setTrackNumber(int iTrackNumber)
          Convenience method for setting track number directly from tag.
abstract  void setTrackNumber(int iTrackNumber, int iTotalTracks)
          Convenience method for setting track number and total number of tracks directly from tag.
 void setUnsynchronization(boolean bUnsynchronizationUsed)
          Set the unsynchronization status.
abstract  void setYear(int iYear)
          Convenience method for setting year directly from tag.
 java.lang.String toString()
          Represent a tag as string for debugging purposes.
abstract  void write(java.io.OutputStream oOS)
          Write this tag to an output stream.
 
Methods inherited from class org.blinkenlights.jid3.ID3Tag
useStrict, usingStrict
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.blinkenlights.jid3.util.ID3Visitable
accept
 

Field Detail

m_bUnsynchronizationUsedFlag

protected boolean m_bUnsynchronizationUsedFlag
Flag indicating whether unsynchronization is used in this tag or not.


m_bExtendedHeaderFlag

protected boolean m_bExtendedHeaderFlag
Flag indicating whether the extended header is present or not.


m_bExperimentalFlag

protected boolean m_bExperimentalFlag
Flag indicating this tag should be considered experimental.


m_bCRCDataFlag

protected boolean m_bCRCDataFlag
Flag indicating whether a CRC value exists in the extended header.


m_oFrameIdToFrameMap

protected java.util.Map m_oFrameIdToFrameMap
Mapping from frame ID to list containing frames. For frames that can only be used once.


m_iPaddingLength

protected int m_iPaddingLength
Value specifying the amount of padding which is appended to the frames in this tag.

Constructor Detail

ID3V2Tag

public ID3V2Tag(boolean bUnsynchronizationUsedFlag,
                boolean bExtendedHeaderFlag,
                boolean bExperimentalFlag)
Construct an ID3 V2 tag, specifying flag values.

Parameters:
bUnsynchronizationUsedFlag - specify whether unsynchronization is to be used in this tag or not
bExtendedHeaderFlag - specify whether the extended header will be present or not
bExperimentalFlag - specify whether this tag is to be considered experimental or not
Method Detail

getSingleFrames

public ID3V2Frame[] getSingleFrames()
Get all frames set in this tag which can only be stored once in the tag. This method exists to aid in testing.


containsAtLeastOneFrame

public abstract boolean containsAtLeastOneFrame()
Check if this tag contains at least one frame. An ID3V2 tag requires at least one frame to be written.

Returns:
true if this tag contains at least one frame, and false otherwise

sanityCheck

public abstract void sanityCheck()
                          throws ID3Exception
Throws:
ID3Exception

write

public abstract void write(java.io.OutputStream oOS)
                    throws ID3Exception
Write this tag to an output stream.

Parameters:
oOS - the output stream to which this tag is to be written
Throws:
ID3Exception - if an error occurs while writing

toString

public java.lang.String toString()
Description copied from class: ID3Tag
Represent a tag as string for debugging purposes.

Specified by:
toString in class ID3Tag
Returns:
a string representation of the contents of the tag

read

public static ID3V2Tag read(java.io.InputStream oIS)
                     throws ID3Exception
Read a tag from an input stream.

Parameters:
oIS - the input stream from which to read a tag
Returns:
the tag read
Throws:
ID3Exception - if an error occurs while reading the tag

setUnsynchronization

public void setUnsynchronization(boolean bUnsynchronizationUsed)
Set the unsynchronization status.

Parameters:
bUnsynchronizationUsed - an indication of whether unsynchronization should be used when writing this tag

getUnsynchronization

public boolean getUnsynchronization()
Get the current unsynchronization status for this tag.

Returns:
the current status of the unsynchronization flag

setExtendedHeader

public void setExtendedHeader(boolean bExtendedHeaderUsed)
Set the extended header flag for this tag.

Parameters:
bExtendedHeaderUsed - an indication of whether the extended header should be included in this tag

getExtendedHeader

public boolean getExtendedHeader()
Get the current extended header status for this tag.

Returns:
the current status of the extended header flag

setCRC

public void setCRC(boolean bCRCUsed)
            throws ID3Exception
Set the CRC flag (extended header must be enabled before this flag can be set.

Parameters:
bCRCUsed - an indication of whether a CRC value should be included in the extended header of this tag
Throws:
ID3Exception

getCRC

public boolean getCRC()
Get the current CRC status for the extended header in this frame.

Returns:
true if the extended header is enabled, and the CRC flag is also enabled, or false otherwise

setDefaultPaddingLength

public static void setDefaultPaddingLength(int iPaddingLength)
                                    throws ID3Exception
Set the default padding length to be added at the end of newly created tags. NOTE: When read by Winamp, it seems the last frame in a v2 tag is not seen, unless there are at least six bytes of padding at the end of the tag. For this reason, the default padding at the end of v2 tags is set to 16. This value can be modified if desired, but be aware of this observation regarding Winamp.

Parameters:
iPaddingLength - the padding length to use
Throws:
ID3Exception - if the padding length value is negative

setPaddingLength

public void setPaddingLength(int iPaddingLength)
                      throws ID3Exception
Set the padding length to be added at the end of this tag. NOTE: When read by Winamp, it seems the last frame in a v2 tag is not seen, unless there are at least six bytes of padding at the end of the tag. For this reason, the default padding at the end of v2 tags is set to 16. This value can be modified if desired, but be aware of this observation regarding Winamp.

Parameters:
iPaddingLength - the padding length to use
Throws:
ID3Exception - if the padding length value is negative

getDefaultPaddingLength

public static int getDefaultPaddingLength()
Get the default padding length currently set for newly created tags.

Returns:
the current padding length

getPaddingLength

public int getPaddingLength()
Get the padding length currently set for this tag.

Returns:
the current padding length

setArtist

public abstract void setArtist(java.lang.String sArtist)
                        throws ID3Exception
Convenience method for setting artist directly from tag.

Parameters:
sArtist - the artist name
Throws:
ID3Exception

getArtist

public abstract java.lang.String getArtist()
Convenience method for retrieving artist directly from tag.

Returns:
the artist value currently set
Throws:
ID3Exception

setTitle

public abstract void setTitle(java.lang.String sTitle)
                       throws ID3Exception
Convenience method for setting song title directly from tag.

Parameters:
sTitle - the song title
Throws:
ID3Exception

getTitle

public abstract java.lang.String getTitle()
Convenience method for retrieving song title directly from tag.

Returns:
the song title currently set
Throws:
ID3Exception

setAlbum

public abstract void setAlbum(java.lang.String sAlbum)
                       throws ID3Exception
Convenience method for setting album title directly from tag.

Parameters:
sAlbum - the album title
Throws:
ID3Exception

getAlbum

public abstract java.lang.String getAlbum()
Convenience method for retrieving album title directly from tag.

Returns:
the album title currently set
Throws:
ID3Exception

setYear

public abstract void setYear(int iYear)
                      throws ID3Exception
Convenience method for setting year directly from tag.

Returns:
the year of the recording
Throws:
ID3Exception

getYear

public abstract int getYear()
                     throws ID3Exception
Convenience method for retrieving year directly from tag.

Returns:
the year currently set
Throws:
ID3Exception - if no year was set

setTrackNumber

public abstract void setTrackNumber(int iTrackNumber)
                             throws ID3Exception
Convenience method for setting track number directly from tag.

Parameters:
iTrackNumber - the track number
Throws:
ID3Exception

setTrackNumber

public abstract void setTrackNumber(int iTrackNumber,
                                    int iTotalTracks)
                             throws ID3Exception
Convenience method for setting track number and total number of tracks directly from tag.

Parameters:
iTrackNumber - the track number
iTotalTracks - the total number of tracks
Throws:
ID3Exception

getTrackNumber

public abstract int getTrackNumber()
                            throws ID3Exception
Convenience method for retrieving track number directly from tag.

Returns:
the track number currently set
Throws:
ID3Exception - if not track number was set

getTotalTracks

public abstract int getTotalTracks()
                            throws ID3Exception
Convenience method for retrieving total number of tracks directly from tag.

Returns:
the total number of tracks currently set
Throws:
ID3Exception - if total number of tracks was not set

setGenre

public abstract void setGenre(java.lang.String sGenre)
                       throws ID3Exception
Convenience method for setting genre directly from tag.

Parameters:
sGenre - the genre (free-form)
Throws:
ID3Exception

getGenre

public abstract java.lang.String getGenre()
Convenience method for retrieving the genre directly from tag.

Returns:
the genre currently set
Throws:
ID3Exception

setComment

public abstract void setComment(java.lang.String sComment)
                         throws ID3Exception
Convenience method for setting comment directly from tag.

Parameters:
sComment - the comment
Throws:
ID3Exception

getComment

public abstract java.lang.String getComment()
Convenience method for retrieving the comment directly from tag.

Returns:
the comment currently set
Throws:
ID3Exception