com.tffenterprises.music.io
Class TaggedFile

java.lang.Object
  extended by com.tffenterprises.music.io.TaggedFile

public class TaggedFile
extends java.lang.Object

This class represents a music file with ID3 tags. Using this class, one can read and write ID3v1 and ID3v2 tags. It is also possible to not worry about what kind of ID3 tags the file has; it will use ID3v2 tags by default, but will use ID3v1 tags if they are the only ones present. The user can give TaggedFile an instance of an ID3 subclass for writing, and TaggedFile will write it at its proper place or create an of a known ID3 subclass if the supplied one is unknown. TaggedFile does not abstract the physical relationship of the file with the tags. When the user requests a tag object from TaggedFile, the result will be whatever's on the disk. A class that abstracts that relationship could easily be built by encapsulating a TaggedFile instance.

Version:
1.0d1 $Date: 2003/03/16 18:52:29 $
Author:
Guillaume Lessard

Field Summary
private  boolean checkedID3v1
          Internal flag: has the file been checked for an ID3v1 tag ?
private  boolean checkedID3v2
          Internal flag: has the file been checked for an ID3v2 tag ?
private  java.io.RandomAccessFile raFile
          The underlying file, handled via the RandomAccessFile class.
static java.lang.String ReadOnly
          The read-only mode.
static java.lang.String ReadWrite
          The read-write mode.
private  boolean tagID3v1present
          Is there an ID3v1 tag in the file ?
private  boolean tagID3v2present
          Is there an ID3v2 tag in the file ?
 
Constructor Summary
TaggedFile(java.io.File theFile, java.lang.String openmode)
          Constructor, from a File object and an openmode, either TaggedFile.ReadOnly or TaggedFile.ReadWrite.
TaggedFile(java.lang.String pathname, java.lang.String openmode)
          Constructor, from a pathname and an openmode, either TaggedFile.ReadOnly or TaggedFile.ReadWrite.
 
Method Summary
private  void adjustFileLength(byte[] tagBytes)
          Adjust the length of the file in order to exactly fit the byte array, which represents an ID3v2 tag.
 void close()
          Closes the underlying file stream and releases any system resources associated with it.
private  void findMpegAudioStart()
          Positions the file at the beginning of the first frame of MP3 data, past the ID3v2 tag if there is one.
 ID3v1 getID3v1()
          Obtain the ID3v1 tag associated with this file.
 ID3v2 getID3v2()
          Return the ID3v2 tag associated with this file.
 byte[] getID3v2Bytes()
          Return a byte array containing the encoded ID3v2 tag associated with this file.
 java.io.RandomAccessFile getRAFile()
          Returns the underlying RandomAccessFile object.
 ID3Tag getTag()
          Obtain an ID3 tag associated with this file.
 boolean hasID3v1()
          Returns a boolean indicating whether the TaggedFile has an ID3v1 tag.
 boolean hasID3v2()
          Returns a boolean indicating whether the TaggedFile has an ID3v2 tag.
 boolean hasTag()
          Returns a boolean indicating whether the TaggedFile has a tag.
 long length()
          Returns the length of the underlying file.
 void removeID3v1()
          Remove the ID3v1 tag, if any, from the file.
 void writeID3v1(ID3v1 tag)
          Write an ID3v1 object to the file.
 void writeID3v2(ID3v2 tag)
          Write the an ID3v2 object to the file.
 void writeID3v2(ID3v2 tag, int newLengthInFile)
          Write an ID3v2 object to the file.
 void writeID3v2Bytes(byte[] tagBytes)
          Write a byte array to file, assuming it contains ID3v2 information.
 void writeTag(ID3Tag tag)
          Write a given ID3 tag to the file.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ReadOnly

public static java.lang.String ReadOnly
The read-only mode.


ReadWrite

public static java.lang.String ReadWrite
The read-write mode.


raFile

private java.io.RandomAccessFile raFile
The underlying file, handled via the RandomAccessFile class.


checkedID3v1

private boolean checkedID3v1
Internal flag: has the file been checked for an ID3v1 tag ?


tagID3v1present

private boolean tagID3v1present
Is there an ID3v1 tag in the file ?


checkedID3v2

private boolean checkedID3v2
Internal flag: has the file been checked for an ID3v2 tag ?


tagID3v2present

private boolean tagID3v2present
Is there an ID3v2 tag in the file ?

Constructor Detail

TaggedFile

public TaggedFile(java.io.File theFile,
                  java.lang.String openmode)
           throws java.lang.SecurityException,
                  java.io.IOException
Constructor, from a File object and an openmode, either TaggedFile.ReadOnly or TaggedFile.ReadWrite.

Parameters:
theFile - a File object to open.
openmode - the opening mode to use, either TaggedFile.ReadOnly or TaggedFile.ReadWrite.
Throws:
java.lang.SecurityException - if the program cannot open the file in the mode that was requested.
java.io.IOException - if some other I/O error occurs.

TaggedFile

public TaggedFile(java.lang.String pathname,
                  java.lang.String openmode)
           throws java.lang.SecurityException,
                  java.io.IOException
Constructor, from a pathname and an openmode, either TaggedFile.ReadOnly or TaggedFile.ReadWrite.

Parameters:
pathname - the pathname of a file to open.
openmode - the opening mode to use, either TaggedFile.ReadOnly or TaggedFile.ReadWrite.
Throws:
java.lang.SecurityException - if the program cannot open the file in the mode that was requested.
java.io.IOException - if some other I/O error occurs.
Method Detail

getRAFile

public java.io.RandomAccessFile getRAFile()
Returns the underlying RandomAccessFile object.

Returns:
the underlying RandomAccessFile object.

close

public void close()
Closes the underlying file stream and releases any system resources associated with it. A closed file cannot perform input or output operations and cannot be reopened. Any unsaved tags will not be saved by this method.


length

public long length()
            throws java.io.IOException
Returns the length of the underlying file.

Returns:
the length of the underlying file.
Throws:
java.io.IOException - if an I/O error occurs.

hasID3v1

public boolean hasID3v1()
                 throws java.io.IOException
Returns a boolean indicating whether the TaggedFile has an ID3v1 tag. Note that this method isn't guaranteed to be quick, as it needs to read from the file every time.

Returns:
a boolean indicating whether the TaggedFile has an ID3v1 tag.
Throws:
java.io.IOException - if an I/O error occurs.

hasID3v2

public boolean hasID3v2()
                 throws java.io.IOException
Returns a boolean indicating whether the TaggedFile has an ID3v2 tag. Note that this method isn't guaranteed to be quick, as it needs to read from the file every time.

Returns:
a boolean indicating whether the TaggedFile has an ID3v2 tag.
Throws:
java.io.IOException - if an I/O error occurs.

hasTag

public boolean hasTag()
               throws java.io.IOException
Returns a boolean indicating whether the TaggedFile has a tag. Note that this method isn't guaranteed to be quick, as it needs to read from the file every time.

Returns:
a boolean indicating whether the TaggedFile has a tag.
Throws:
java.io.IOException - if an I/O error occurs.

writeID3v1

public void writeID3v1(ID3v1 tag)
                throws java.io.IOException
Write an ID3v1 object to the file.

Parameters:
tag - the tag to write.
Throws:
java.io.IOException - if an I/O error occurs.

removeID3v1

public void removeID3v1()
                 throws java.io.IOException
Remove the ID3v1 tag, if any, from the file.

Throws:
java.io.IOException - if an I/O error occurs.

writeID3v2

public void writeID3v2(ID3v2 tag)
                throws java.io.IOException
Write the an ID3v2 object to the file.

Parameters:
tag - the tag to write
Throws:
java.io.IOException - if an I/O error occurs.

writeID3v2

public void writeID3v2(ID3v2 tag,
                       int newLengthInFile)
                throws java.io.IOException
Write an ID3v2 object to the file. The parameter newLengthInFile is a target tag length, in bytes.

If the target is greater than the old tag length, the file will be lengthened. If the old tag length is greater than newLengthInFile, the old value will be used. If the tag cannot be made to fit in newLengthInFile bytes, the operation will fail. If newLengthInFile is non-positive, the tag is written using the minimum possible size.

Parameters:
tag - the tag to write
newLengthInFile - a target length in bytes for the tag
Throws:
java.io.IOException - if an I/O error occurs.

writeID3v2Bytes

public void writeID3v2Bytes(byte[] tagBytes)
                     throws java.io.IOException
Write a byte array to file, assuming it contains ID3v2 information.

Parameters:
tagBytes - a byte array containing ID3v2 information.
Throws:
java.io.IOException - if an I/O error occurs.

adjustFileLength

private void adjustFileLength(byte[] tagBytes)
                       throws java.io.IOException
Adjust the length of the file in order to exactly fit the byte array, which represents an ID3v2 tag.

Parameters:
tagBytes - a byte array containing ID3v2 information.
Throws:
java.io.IOException - if an I/O error occurs.

writeTag

public void writeTag(ID3Tag tag)
              throws java.io.IOException
Write a given ID3 tag to the file.

Parameters:
tag - the ID3 tag to write to the file.
Throws:
java.io.IOException - if an I/O error occurs.

getID3v1

public ID3v1 getID3v1()
               throws java.io.IOException
Obtain the ID3v1 tag associated with this file. If there is no ID3v1 tag, this method will return null.

Returns:
the ID3v1 tag associated with this file, or null if there is none.
Throws:
java.io.IOException - if an I/O error occurs.

getID3v2Bytes

public byte[] getID3v2Bytes()
                     throws java.io.IOException
Return a byte array containing the encoded ID3v2 tag associated with this file. If there is no ID3v2 tag, this method will return the null pointer.

Returns:
a byte array containing the ID3v2 tag associated with this file, or the null pointer.
Throws:
java.io.IOException - if an I/O error occurs.

getID3v2

public ID3v2 getID3v2()
               throws java.io.IOException
Return the ID3v2 tag associated with this file. If there is no ID3v2 tag, return the null pointer.

Returns:
the ID3v2 tag associated with this file, or the null pointer.
Throws:
java.io.IOException - if an I/O error occurs.

getTag

public ID3Tag getTag()
              throws java.io.IOException
Obtain an ID3 tag associated with this file. This method will preferentially return an ID3v2 tag.

Returns:
an ID3 tag associated with this file.
Throws:
java.io.IOException - if an I/O error occurs.

findMpegAudioStart

private void findMpegAudioStart()
                         throws java.io.IOException
Positions the file at the beginning of the first frame of MP3 data, past the ID3v2 tag if there is one.

Throws:
java.io.IOException - if an I/O error occurs.