helliker.id3
Class ID3v2Tag

java.lang.Object
  |
  +--helliker.id3.ID3v2Tag
All Implemented Interfaces:
ID3Tag

public class ID3v2Tag
extends java.lang.Object
implements ID3Tag


Constructor Summary
ID3v2Tag(java.io.File mp3, long mpegOffset)
          Create an id3v2 tag bound to the file provided as a parameter.
 
Method Summary
 void copyFrom(ID3Tag tag)
          Copies information from the ID3Tag parameter and inserts it into this tag.
 byte[] getBytes()
          Return a binary representation of this object to be written to a file.
 byte[] getFrameData(java.lang.String id)
          Returns the data found in the frame specified by the id.
 java.lang.String getFrameDataString(java.lang.String id)
          Returns the textual information contained in the frame specified by the id.
 int getPadding()
          Returns the current number of padding bytes in this id3v2 tag.
 int getSize()
          Returns the size of this id3v2 tag.
 int getTotalSize()
          Returns the actual size of the tag when written.
 void removeFrame(java.lang.String id)
          Remove the frame with the specified id from the file.
 void removeTag()
          Remove an existing id3v2 tag from the file passed to the constructor.
 void setCommentFrame(java.lang.String description, java.lang.String comment)
          Set the data contained in the comments frame (COMM).
 void setPadding(int pad)
          Set the amount of padding to use when writing this tag.
 void setTextFrame(java.lang.String id, java.lang.String data)
          Set the data contained in a text frame.
 void setURLFrame(java.lang.String id, java.lang.String data)
          Set the data contained in a URL frame.
 void setUserDefinedTextFrame(java.lang.String description, java.lang.String value)
          Sets the data contained in the user defined text frame (TXXX).
 void setUserDefinedURLFrame(java.lang.String description, java.lang.String value)
          Sets the data contained in the user defined url frame (WXXX).
 boolean tagExists()
          Returns true if an id3v2 tag exists in the file that was passed to the constructor and false otherwise
 java.lang.String toString()
          Return a string representation of this object.
 void updateFrameData(java.lang.String id, byte[] data)
          Updates the data for the frame specified by id.
 void writeTag()
          Saves all the information in the tag to the file passed to the constructor.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ID3v2Tag

public ID3v2Tag(java.io.File mp3,
                long mpegOffset)
         throws java.io.FileNotFoundException,
                java.io.IOException,
                ID3v2FormatException
Create an id3v2 tag bound to the file provided as a parameter. If a tag exists in the file already, then all the information in the tag will be extracted. If a tag doesn't exist, then this is the file that will be written to when the writeTag method is called.

Parameters:
mp3 - the file to write/read the the tag information to/from
mpegOffset - the byte offset where the mpeg frames begin
Throws:
java.io.FileNotFoundException - if an error occurs
java.io.IOException - if an error occurs
ID3v2FormatException - if an exisiting id3v2 tag isn't correct
Method Detail

writeTag

public void writeTag()
              throws java.io.FileNotFoundException,
                     java.io.IOException
Saves all the information in the tag to the file passed to the constructor. If a tag doesn't exist, a tag is prepended to the file. If the padding has not changed since the creation of this object and the size is less than the original size + the original padding, then the previous tag and part of the previous padding will be overwritten. Otherwise, a new tag will be prepended to the file.

Specified by:
writeTag in interface ID3Tag
Throws:
java.io.FileNotFoundException - if an error occurs
java.io.IOException - if an error occurs

removeTag

public void removeTag()
               throws java.io.FileNotFoundException,
                      java.io.IOException
Remove an existing id3v2 tag from the file passed to the constructor.

Specified by:
removeTag in interface ID3Tag
Returns:
true if the removal was a success
Throws:
java.io.FileNotFoundException - if an error occurs
java.io.IOException - if an error occurs

getBytes

public byte[] getBytes()
Return a binary representation of this object to be written to a file. This is in the format of the id3v2 specifications. This includes the header, extended header (if it exists), the frames, padding (if it exists), and a footer (if it exists).

Specified by:
getBytes in interface ID3Tag
Returns:
a binary representation of this id3v2 tag

setTextFrame

public void setTextFrame(java.lang.String id,
                         java.lang.String data)
Set the data contained in a text frame. This includes all frames with an id that starts with 'T' but excludes "TXXX". If an improper id is passed, then nothing will happen.

Parameters:
id - the id of the frame to set the data for
data - the data for the frame

setURLFrame

public void setURLFrame(java.lang.String id,
                        java.lang.String data)
Set the data contained in a URL frame. This includes all frames with an id that starts with 'W' but excludes "WXXX". If an improper id is passed, then nothing will happen.

Parameters:
id - the id of the frame to set the data for
data - the data for the frame

setUserDefinedTextFrame

public void setUserDefinedTextFrame(java.lang.String description,
                                    java.lang.String value)
Sets the data contained in the user defined text frame (TXXX).

Parameters:
description - a description of the data
value - the data for the frame

setUserDefinedURLFrame

public void setUserDefinedURLFrame(java.lang.String description,
                                   java.lang.String value)
Sets the data contained in the user defined url frame (WXXX).

Parameters:
description - a description of the url
value - the url for the frame

setCommentFrame

public void setCommentFrame(java.lang.String description,
                            java.lang.String comment)
Set the data contained in the comments frame (COMM).

Parameters:
description - a description of the comment
comment - the comment

removeFrame

public void removeFrame(java.lang.String id)
Remove the frame with the specified id from the file. If there is no frame with that id nothing will happen.

Parameters:
id - the id of the frame to remove

updateFrameData

public void updateFrameData(java.lang.String id,
                            byte[] data)
Updates the data for the frame specified by id. If no frame exists for the id specified, a new frame with that id is created.

Parameters:
id - the id of the frame to update
data - the data for the frame

getFrameDataString

public java.lang.String getFrameDataString(java.lang.String id)
                                    throws ID3v2FormatException
Returns the textual information contained in the frame specified by the id. Not every type of frame has textual information. If an id is specified that will not work, the empty string is returned.

Parameters:
id - the id of the frame to get text from
Returns:
the text information contained in the frame
Throws:
ID3v2FormatException - if an error is encountered parsing data

getFrameData

public byte[] getFrameData(java.lang.String id)
Returns the data found in the frame specified by the id. If the frame doesn't exist, then a zero length array is returned.

Parameters:
id - the id of the frame to get the data from
Returns:
the data found in the frame

tagExists

public boolean tagExists()
Returns true if an id3v2 tag exists in the file that was passed to the constructor and false otherwise

Returns:
true if an id3v2 tag exists in the file passed to the ctor

getSize

public int getSize()
Returns the size of this id3v2 tag. This includes only the frames, extended header, and padding. For the size of the entire tag including the header and footer, use getTotalSize method.

Returns:
the size (in bytes) of the id3v2 frames, extended header, footer

getTotalSize

public int getTotalSize()
Returns the actual size of the tag when written. Includes the header, extended header, frames, padding, and footer.

Returns:
the size (in bytes) of the entire id3v2 tag

getPadding

public int getPadding()
Returns the current number of padding bytes in this id3v2 tag.

Returns:
the current number of padding bytes in this id3v2 tag

setPadding

public void setPadding(int pad)
Set the amount of padding to use when writing this tag. There cannot be any padding if a footer exists. Nothing will happen if this function is called and a footer exists or if the number is negative.

Parameters:
pad - the amount of padding to use when writing this tag

toString

public java.lang.String toString()
Return a string representation of this object. This includes all data contained in all parts of this tag.

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

copyFrom

public void copyFrom(ID3Tag tag)
Copies information from the ID3Tag parameter and inserts it into this tag. Previous data will be overwritten. [NOT IMPLEMENTED]

Specified by:
copyFrom in interface ID3Tag
Parameters:
tag - the tag to copy from