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

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

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

This class is the basis for all text-based frame types in ID3v2, including but not exclusive to the text frame type. TextBaseFrame includes a number of String-handling utilities, as well as utilities involving text encoding.

Version:
1.0d1 $Date: 2002/10/12 19:59:22 $
Author:
Guillaume Lessard
See Also:
Serialized Form

Field Summary
static char BOM_CHAR
          A utility char, the byte-order mark (non-breaking space) character.
static java.lang.String BOM_CHAR_STRING
          A utility string, containing only the BOM (non-breaking space) character.
private static java.util.Hashtable ENCODING_BYTES
          The encoding strings, indexing their bytes; converse of the previous.
static java.lang.String[] ENCODING_STRINGS
          The encoding strings, indexed by ID3v2 encoding id.
static java.lang.String ISO_8859_1
          The ISO 8859-1 string encoding.
static java.lang.String NULL_BOM_STRING
          A utility string, containing a null character followed by a BOM.
static char NULL_CHAR
          A utility char, the null character.
static java.lang.String NULL_CHAR_STRING
          A utility string, containing only the null character.
static java.lang.String UNICODE
          The Unicode string encoding.
static java.lang.String UNICODE_BIG
          The Unicode string encoding, with big-endian byte ordering.
static java.lang.String UNICODE_LITTLE
          The Unicode string encoding, with little-endian byte ordering.
static java.lang.String UTF8
          The UTF-8 string encoding, that the 3-bytes-maximum version of it...
 
Constructor Summary
protected TextBasedFrame()
          Protected default constructor.
protected TextBasedFrame(FrameHeader header)
          Frame subclasses MUST provide a constructor with this parameter list.
 
Method Summary
 byte[] getNullBytes(java.lang.String encoding)
          Returns the ID3v2 string-separator null byte(s), for the named encoding.
 java.lang.String getTextEncoding(byte b)
          Returns a string representing the text encoding used by this frame, given a byte containing the ID3v2 specification's representation of an encoding.
 java.lang.String getTextEncoding(ByteArrayInputStream in)
          Returns a string representing the text encoding used by this frame, given a byte containing the ID3v2 specification's representation of an encoding.
 byte[] getTextEncoding(java.lang.String encoding)
          Returns a byte array containing ID3v2's byte representation of encodings, given a named encoding.
 boolean is8859String(java.lang.String string)
          Tests a String to see if it can be encoded in ISO-8859-1.
 char[] read8859Characters(ByteArrayInputStream in)
          Reads an array of characters from a ByteArrayInputStream, using the ISO 8859-1 encoding.
 java.lang.String read8859String(ByteArrayInputStream in)
          Reads a string from a ByteArrayInputStream, using the ISO 8859-1 encoding.
protected  char[] readCharacters(ByteArrayInputStream in, java.lang.String encoding)
          Reads an array of characters from a ByteArrayInputStream, using the named character encoding.
protected  java.lang.String readString(ByteArrayInputStream in, java.lang.String encoding)
          Reads a String from a ByteArrayInputStream, using the named character encoding.
 char[] readUnicodeCharacters(ByteArrayInputStream in)
          Reads an array of characters from a ByteArrayInputStream, using the Unicode encoding.
 java.lang.String readUnicodeString(ByteArrayInputStream in)
          Reads a String from a ByteArrayInputStream, using the Unicode encoding.
 
Methods inherited from class com.tffenterprises.music.tag.id3v2.frame.BaseFrame
clone, equals, getBytes, getChecksum, getFormatFlags, getFrameID, getHeader, getRawData, getStatusFlags, hashCode, isChanged, isOfRepeatableType, setChanged, setFormatFlags, setRawData, setStatusFlags, toByteArray, toString, updateChecksum, writeTo
 
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

ISO_8859_1

public static final java.lang.String ISO_8859_1
The ISO 8859-1 string encoding.

See Also:
Constant Field Values

UNICODE

public static final java.lang.String UNICODE
The Unicode string encoding.

See Also:
Constant Field Values

UNICODE_BIG

public static final java.lang.String UNICODE_BIG
The Unicode string encoding, with big-endian byte ordering.

See Also:
Constant Field Values

UNICODE_LITTLE

public static final java.lang.String UNICODE_LITTLE
The Unicode string encoding, with little-endian byte ordering.

See Also:
Constant Field Values

UTF8

public static final java.lang.String UTF8
The UTF-8 string encoding, that the 3-bytes-maximum version of it...

See Also:
Constant Field Values

NULL_CHAR

public static final char NULL_CHAR
A utility char, the null character.

See Also:
Constant Field Values

BOM_CHAR

public static final char BOM_CHAR
A utility char, the byte-order mark (non-breaking space) character.

See Also:
Constant Field Values

NULL_CHAR_STRING

public static final java.lang.String NULL_CHAR_STRING
A utility string, containing only the null character.


BOM_CHAR_STRING

public static final java.lang.String BOM_CHAR_STRING
A utility string, containing only the BOM (non-breaking space) character.


NULL_BOM_STRING

public static final java.lang.String NULL_BOM_STRING
A utility string, containing a null character followed by a BOM.


ENCODING_STRINGS

public static final java.lang.String[] ENCODING_STRINGS
The encoding strings, indexed by ID3v2 encoding id.


ENCODING_BYTES

private static final java.util.Hashtable ENCODING_BYTES
The encoding strings, indexing their bytes; converse of the previous.

Constructor Detail

TextBasedFrame

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


TextBasedFrame

protected TextBasedFrame(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

is8859String

public boolean is8859String(java.lang.String string)
Tests a String to see if it can be encoded in ISO-8859-1.

Parameters:
string - The String to test.
Returns:
true if ISO-8859-1 can be used to encode the specified string, false otherwise. If the specified String is null, this method returns false.

getTextEncoding

public java.lang.String getTextEncoding(ByteArrayInputStream in)
                                 throws FrameDataFormatException
Returns a string representing the text encoding used by this frame, given a byte containing the ID3v2 specification's representation of an encoding. The byte will be read off the ByteArrayInputStream parameter.

The returned string will always be the name of an encoding type useable by java.

For the moment, this method returns either "ISO8859_1" or "Unicode". Note that in the case of Unicode, further probing may be necessary in order to determine the byte ordering. The readUnicodeString() method does such additional probing.

Parameters:
in - stream where to get the encoding, in its ID3v2 representation.
Returns:
a string representing the text encoding used by this frame.
Throws:
FrameDataFormatException - if the byte value is not one supported by ID3v2.

getTextEncoding

public java.lang.String getTextEncoding(byte b)
                                 throws FrameDataFormatException
Returns a string representing the text encoding used by this frame, given a byte containing the ID3v2 specification's representation of an encoding.

The returned string will always be the name of an encoding type useable by java.

For the moment, this method returns either "ISO8859_1" or "Unicode". Note that in the case of Unicode, further probing may be necessary in order to determine the byte ordering. The readUnicodeString() method does such additional probing.

Parameters:
b - the encoding, in its ID3v2 representation.
Returns:
a string representing the text encoding used by this frame.
Throws:
FrameDataFormatException - if the byte value is not one supported by ID3v2.

getTextEncoding

public byte[] getTextEncoding(java.lang.String encoding)
                       throws FrameDataFormatException
Returns a byte array containing ID3v2's byte representation of encodings, given a named encoding.

The named encoding should always be an encoding type useable by java.

Parameters:
encoding - the name of the encoding.
Returns:
a byte array representing the text encoding used by this frame.
Throws:
FrameDataFormatException - if the named encoding isn't supported by the ID3v2 specification.

getNullBytes

public byte[] getNullBytes(java.lang.String encoding)
                    throws FrameDataFormatException
Returns the ID3v2 string-separator null byte(s), for the named encoding.

Parameters:
encoding - the encoding to use for the string terminator.
Returns:
the ID3v2 string-separator null byte(s), for the named encoding.
Throws:
FrameDataFormatException - if the named encoding is not supported.

read8859String

public java.lang.String read8859String(ByteArrayInputStream in)
                                throws FrameDataFormatException
Reads a string from a ByteArrayInputStream, using the ISO 8859-1 encoding. This method will use all the bytes remaining in the ByteArrayInputStream to create the string.

Parameters:
in - A ByteArrayInputStream to milk for characters.
Returns:
a string read from characters encoded as ISO 8859-1.
Throws:
FrameDataFormatException - if the requested encoding is not supported, or if the data is malformed.

read8859Characters

public char[] read8859Characters(ByteArrayInputStream in)
                          throws FrameDataFormatException
Reads an array of characters from a ByteArrayInputStream, using the ISO 8859-1 encoding. This method will use all the bytes remaining in the ByteArrayInputStream to create the array of characters.

Parameters:
in - A ByteArrayInputStream to milk for characters.
Returns:
an array of characters originally encoded as ISO 8859-1.
Throws:
FrameDataFormatException - if the requested encoding is not supported, or if the data is malformed.

readUnicodeString

public java.lang.String readUnicodeString(ByteArrayInputStream in)
                                   throws FrameDataFormatException
Reads a String from a ByteArrayInputStream, using the Unicode encoding. This method will use all the bytes remaining in the ByteArrayInputStream to create the string.

Parameters:
in - A ByteArrayInputStream to milk for characters.
Returns:
a string read from characters encoded as Unicode.
Throws:
FrameDataFormatException - if the requested encoding is not supported, or if the data is malformed.

readUnicodeCharacters

public char[] readUnicodeCharacters(ByteArrayInputStream in)
                             throws FrameDataFormatException
Reads an array of characters from a ByteArrayInputStream, using the Unicode encoding. This method will use all the bytes remaining in the ByteArrayInputStream to create the array of characters.

Parameters:
in - A ByteArrayInputStream to milk for characters.
Returns:
an array of characters originally encoded as ISO 8859-1.
Throws:
FrameDataFormatException - if the requested encoding is not supported, or if the data is malformed.

readString

protected java.lang.String readString(ByteArrayInputStream in,
                                      java.lang.String encoding)
                               throws FrameDataFormatException
Reads a String from a ByteArrayInputStream, using the named character encoding. This method will use all the bytes remaining in the ByteArrayInputStream to create the string. If there is a null termination in the stream, anything after that will be ignored.

The encoding string used should be one of the strings defined as public static variables for the TextBasedFrame class. Other character encodings may be unsupported by java VMs.

Parameters:
in - A ByteArrayInputStream to milk for characters.
encoding - The name of the character encoding to be used.
Returns:
a string read from characters encoded as Unicode.
Throws:
FrameDataFormatException - if the requested encoding is not supported, or if the data is malformed.

readCharacters

protected char[] readCharacters(ByteArrayInputStream in,
                                java.lang.String encoding)
                         throws FrameDataFormatException
Reads an array of characters from a ByteArrayInputStream, using the named character encoding. This method will use all the bytes remaining in the ByteArrayInputStream to create the array of characters.

The encoding string used should be one of the strings defined as public static variables for the TextBasedFrame class. Other character encodings may be unsupported by java VMs.

Parameters:
in - A ByteArrayInputStream to milk for characters.
encoding - The name of the character encoding to be used.
Returns:
an array of characters.
Throws:
FrameDataFormatException - if the requested encoding is not supported, or if the data is malformed.