FileDocCategorySizeDatePackage
AbstractFrameBodyTextInfo.javaAPI DocJaudiotagger 2.0.48518Wed Mar 30 16:12:02 BST 2011org.jaudiotagger.tag.id3.framebody

AbstractFrameBodyTextInfo

public abstract class AbstractFrameBodyTextInfo extends AbstractID3v2FrameBody
Abstract representation of a Text Frame

The text information frames are often the most important frames, containing information like artist, album and more. There may only be one text information frame of its kind in an tag. In ID3v24 All text information frames supports multiple strings, stored as a null separated list, where null is represented by the termination code for the character encoding. All text frame identifiers begin with "T". Only text frame identifiers begin with "T", with the exception of the "TXXX" frame. All the text information frames have the following format:

Text encoding $xx Information

The list of valid text encodings increased from two in ID3v23 to four in ID3v24

iTunes incorrectly writes null terminators at the end of every String, even though it only writes one String.

You can retrieve the first value without the null terminator using {@link #getFirstTextValue}

Fields Summary
Constructors Summary
protected AbstractFrameBodyTextInfo()
Creates a new FrameBodyTextInformation datatype. The super.super Constructor sets up the Object list for the frame.

        super();
        setObjectValue(DataTypes.OBJ_TEXT_ENCODING, TextEncoding.ISO_8859_1);
        setObjectValue(DataTypes.OBJ_TEXT, "");
protected AbstractFrameBodyTextInfo(AbstractFrameBodyTextInfo body)
Copy Constructor

param
body AbstractFrameBodyTextInformation

        super(body);
protected AbstractFrameBodyTextInfo(byte textEncoding, String text)
Creates a new FrameBodyTextInformation data type. This is used when user wants to create a new frame based on data in a user interface.

param
textEncoding Specifies what encoding should be used to write text to file.
param
text Specifies the text String.

        super();
        setObjectValue(DataTypes.OBJ_TEXT_ENCODING, textEncoding);
        setObjectValue(DataTypes.OBJ_TEXT, text);
protected AbstractFrameBodyTextInfo(ByteBuffer byteBuffer, int frameSize)
Creates a new FrameBodyTextInformation data type from file.

The super.super Constructor sets up the Object list for the frame.

param
byteBuffer
param
frameSize
throws
InvalidTagException if unable to create framebody from buffer

        super(byteBuffer, frameSize);
Methods Summary
public voidaddTextValue(java.lang.String value)
Add additional value to value

param
value at index

        TextEncodedStringSizeTerminated text = (TextEncodedStringSizeTerminated) getObject(DataTypes.OBJ_TEXT);
        text.addValue(value);
public java.lang.StringgetFirstTextValue()
Get first value

return
value at index 0

        TextEncodedStringSizeTerminated text = (TextEncodedStringSizeTerminated) getObject(DataTypes.OBJ_TEXT);
        return text.getValueAtIndex(0);
public intgetNumberOfValues()

return
number of text values, usually one

        TextEncodedStringSizeTerminated text = (TextEncodedStringSizeTerminated) getObject(DataTypes.OBJ_TEXT);
        return text.getNumberOfValues();
public java.lang.StringgetText()
Retrieve the complete text String as it is held internally. If multiple values are held these wil be returned, needless trailing nulls will also be returned

return
the text string

        return (String) getObjectValue(DataTypes.OBJ_TEXT);
public java.lang.StringgetTextWithoutTrailingNulls()
Retrieve the complete text String but without any trailing nulls If multiple values are held these will be returned, needless trailing nulls will not be returned

return
the text string

        TextEncodedStringSizeTerminated text = (TextEncodedStringSizeTerminated) getObject(DataTypes.OBJ_TEXT);
        return text.getValueWithoutTrailingNull();
public java.lang.StringgetUserFriendlyValue()

        return getTextWithoutTrailingNulls();
public java.lang.StringgetValueAtIndex(int index)
Get text value at index When a multiple values are stored within a single text frame this method allows access to any of the individual values.

param
index
return
value at index

        TextEncodedStringSizeTerminated text = (TextEncodedStringSizeTerminated) getObject(DataTypes.OBJ_TEXT);
        return text.getValueAtIndex(index);
public voidsetText(java.lang.String text)
Set the Full Text String.

If this String contains null terminator characters these are parsed as value separators, allowing you to hold multiple strings within one text frame. This functionality is only officially support in ID3v24.

param
text to set

        if (text == null)
        {
            throw new IllegalArgumentException(ErrorMessage.GENERAL_INVALID_NULL_ARGUMENT.getMsg());
        }
        setObjectValue(DataTypes.OBJ_TEXT, text);
protected voidsetupObjectList()
Setup the Object List. All text frames contain a text encoding and then a text string.

TODO:would like to make final but cannot because overridden by FrameBodyTXXX

        objectList.add(new NumberHashMap(DataTypes.OBJ_TEXT_ENCODING, this, TextEncoding.TEXT_ENCODING_FIELD_SIZE));
        objectList.add(new TextEncodedStringSizeTerminated(DataTypes.OBJ_TEXT, this));
public voidwrite(java.io.ByteArrayOutputStream tagBuffer)
Because Text frames have a text encoding we need to check the text String does not contain characters that cannot be encoded in current encoding before we write data. If there are change the text encoding.

        //Ensure valid for type
        setTextEncoding(ID3TextEncodingConversion.getTextEncoding(getHeader(), getTextEncoding()));

        //Ensure valid for data
        if (!((TextEncodedStringSizeTerminated) getObject(DataTypes.OBJ_TEXT)).canBeEncoded())
        {
            this.setTextEncoding(ID3TextEncodingConversion.getUnicodeTextEncoding(getHeader()));
        }
        super.write(tagBuffer);