entagged.audioformats.mp3.util.id3frames
Class Id3Frame

java.lang.Object
  entagged.audioformats.mp3.util.id3frames.Id3Frame

All Implemented Interfaces:

TagField

Direct Known Subclasses:

GenericId3Frame, TextId3Frame, UfidId3Frame

public abstract class Id3Frame
extends Object
implements TagField

This class represents an ID3-Frame and provides basic information.

Author:

Raphaël Slinckx, Christian Laireiter

Field Summary

protected byte[]	flags The frame header flags are stored here. The flags have always been 2 bytes long.
protected byte	version ID3 version identifier.

Constructor Summary

Id3Frame()
Creates a new frame instance.
Id3 version assigned is 2.4.

Id3Frame(byte[] raw, byte id3Version)
Creates a frame instance which adjusts to the given raw-data.

Method Summary

protected abstract byte[]	build() This method creates a binary representation of the current Id3Frame data. This data can directly be written to a file or stream. s
Object	clone() (overridden)
protected void	copy(byte[] src, byte[] dst, int dstOffset)
boolean	equals(Object obj) (overridden) For Id3Frame objects the comparison can be easily done by comparing their binary representation which can be retrieved by invoking build().
protected byte[]	getBytes(String s, String encoding) Convenience method converting a string to a binary representation according to the given encoding.
byte[]	getFlags() Returns the flags of the frame.
abstract String	getId() (overridden) For Id3-Frames its something like "TCOM","TENC","TALB" and so on.
protected byte[]	getIdBytes() Convenience method for getting the binary representation of getId().
byte[]	getRawContent() (overridden) simply calls build() directly.
protected byte[]	getSize(int size) Converts the given value of size into a representation which can be used to write a frames size into a file (or stream). For now there are two different kinds of binary representation of a size value in ID3 frames. First the prior 2.4 variation which is a simple "litte endian". Second the 2.4 variation which utilizes Id3v2TagCreator.getSyncSafe(int).
protected String	getString(byte[] b, int offset, int length, String encoding) Another convenience Method which parses a byte array and returns a String instance.
protected int	indexOfFirstNull(byte[] b, int offset) Convenience method which searches for the next zero byte in an array.
abstract boolean	isBinary() (overridden)
void	isBinary(boolean b) (overridden)
abstract boolean	isCommon() (overridden)
protected abstract void	populate(byte[] raw) This method reads the given data of an ID3-Frame and interprets it implementation specific. The values of the Id3Frame instance are adjusted.

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface entagged.audioformats.generic.TagField

copyContent, isEmpty, toString

Field Detail

flags

protected byte[] flags

The frame header flags are stored here.
The flags have always been 2 bytes long. (Id3 version 2.x).

version

protected byte version

ID3 version identifier.

See Also:

Id3v2Tag.ID3V22, Id3v2Tag.ID3V23, Id3v2Tag.ID3V24

Constructor Detail

Id3Frame

public Id3Frame()

Creates a new frame instance.
Id3 version assigned is 2.4.

Id3Frame

public Id3Frame(byte[] raw,
                byte id3Version)
         throws UnsupportedEncodingException

Creates a frame instance which adjusts to the given raw-data.

Parameters:

raw - The data of the frame.

id3Version - The ID3-Tag version.

Throws:

UnsupportedEncodingException - If a textframe's content cannot be interpreted.

Method Detail

build

protected abstract byte[] build()
                         throws UnsupportedEncodingException

This method creates a binary representation of the current Id3Frame data.
This data can directly be written to a file or stream.
s

Returns:

Binary representation of current frame based on the implementation (what does it stand for) and data (its contents).

Throws:

UnsupportedEncodingException - If a text-Frame is constructed there can occur an error during text conversions.

clone

public Object clone()
             throws CloneNotSupportedException

(overridden)

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

See Also:

Object.clone()

copy

protected void copy(byte[] src,
                    byte[] dst,
                    int dstOffset)

equals

public boolean equals(Object obj)

(overridden)
For Id3Frame objects the comparison can be easily done by comparing their binary representation which can be retrieved by invoking build().

Overrides:

equals in class Object

See Also:

Object.equals(java.lang.Object)

getBytes

protected byte[] getBytes(String s,
                          String encoding)
                   throws UnsupportedEncodingException

Convenience method converting a string to a binary representation according to the given encoding.

Parameters:

s - The string to get the binary representation from.

encoding - The encoding which should be used.

Returns:

Binary representation of the given string in the given encoding with BOM for UTF and the terminating character(s).

Throws:

UnsupportedEncodingException - If the string needs to be converted and the encoding is not present.

getFlags

public byte[] getFlags()

Returns the flags of the frame.

Returns:

The flag bytes.

getId

public abstract String getId()

(overridden)
For Id3-Frames its something like "TCOM","TENC","TALB" and so on.

Specified by:

getId in interface TagField

Returns:

Unique identifier for the fields type. (title, artist...)

See Also:

TagField.getId()

getIdBytes

protected byte[] getIdBytes()

Convenience method for getting the binary representation of getId().

Returns:

The bytes of getId().

See Also:

String.getBytes()

getRawContent

public byte[] getRawContent()
                     throws UnsupportedEncodingException

(overridden)
simply calls build() directly.

Specified by:

getRawContent in interface TagField

Returns:

Binary data representing the current tag field.

Throws:

UnsupportedEncodingException - Most tag data represents text. In some cases the underlying implementation will need to convert the text data in java to a specific charset encoding. In these cases an UnsupportedEncodingException may occur.

See Also:

TagField.getRawContent()

getSize

protected byte[] getSize(int size)

Converts the given value of size into a representation which can be used to write a frames size into a file (or stream).
For now there are two different kinds of binary representation of a size value in ID3 frames.
First the prior 2.4 variation which is a simple "litte endian".
Second the 2.4 variation which utilizes Id3v2TagCreator.getSyncSafe(int).

Parameters:

size - The integer value to convert.

Returns:

The binary representation according to the ID3 version.

getString

protected String getString(byte[] b,
                           int offset,
                           int length,
                           String encoding)
                    throws UnsupportedEncodingException

Another convenience Method which parses a byte array and returns a String instance.

Parameters:

b - The array where the string resides.

offset - The offset in b where the string begins.

length - The length in bytes which makes up the string.

encoding - The encoding of the string in b.

Returns:

A String representation of the specified data.

Throws:

UnsupportedEncodingException - If an conversion error occurs or the encoding is not available on the running system.

indexOfFirstNull

protected int indexOfFirstNull(byte[] b,
                               int offset)

Convenience method which searches for the next zero byte in an array.

Parameters:

b - The array to search in.

offset - The offset of b from where to look for the next zero byte.

Returns:

The index of the zero byte in b if found. If none was found, "-1" is returned.

isBinary

public abstract boolean isBinary()

(overridden)

Specified by:

isBinary in interface TagField

Returns:

true if field represents binary data (not human readable).

See Also:

TagField.isBinary()

isBinary

public void isBinary(boolean b)

(overridden)

Specified by:

isBinary in interface TagField

Parameters:

b - true, if the field contains binary data.

See Also:

TagField.isBinary(boolean)

isCommon

public abstract boolean isCommon()

(overridden)

Specified by:

isCommon in interface TagField

Returns:

true if the field is of common use.

See Also:

TagField.isCommon()

populate

protected abstract void populate(byte[] raw)
                          throws UnsupportedEncodingException

This method reads the given data of an ID3-Frame and interprets it implementation specific.
The values of the Id3Frame instance are adjusted.

Parameters:

raw - The frame data.

Throws:

UnsupportedEncodingException - On text frames there can be such errors.