org.jaudiotagger.tag
Interface Tag

All Known Implementing Classes:
AbstractID3v2Tag, AbstractTag, AsfTag, FlacTag, GenericTag, ID3v11Tag, ID3v1Tag, ID3v22Tag, ID3v23Tag, ID3v24Tag, Mp4Tag, RealTag, VorbisCommentTag, WavTag

public interface Tag

This interface represents the basic data structure for the default audio library functionality.

Some audio file tagging systems allow to specify multiple values for one type of information. The artist for example. Some songs may be a cooperation of two or more artists. Sometimes a tagging user wants to specify them in the tag without making one long text string.
The addField() method can be used for this but it is possible the underlying implementation does not support that kind of storing multiple values and will just overwrite the existing value

Code Examples:

 
 AudioFile file = AudioFileIO.read(new File("C:\\test.mp3"));
 

Tag tag = file.getTag();

Author:
Raphael Slinckx, Paul Taylor

Method Summary
 void addField(Artwork artwork)
          Create artwork field based on the data in artwork and then add it to the tag itself

 void addField(FieldKey genericKey, java.lang.String value)
          Create the field based on the generic key and add it to the tag This is handled differently by different formats
 void addField(TagField field)
          Adds a field to the structure, used internally by the library

 TagField createField(Artwork artwork)
          Create artwork field based on the data in artwork
 TagField createField(FieldKey genericKey, java.lang.String value)
          Create a new field based on generic key, used internally by the library

 void deleteArtworkField()
          Delete any instance of tag fields used to store artwork
 void deleteField(FieldKey fieldKey)
          Delete any fields with this key
 void deleteField(java.lang.String key)
          Delete any fields with this Flac (Vorbis Comment) id
 java.util.List<Artwork> getArtworkList()
           
 int getFieldCount()
          Return the number of fields

 int getFieldCountIncludingSubValues()
          Return the number of fields taking multiple value fields into consideration Fields that actually contain multiple values are counted seperately i.e.
 java.util.Iterator<TagField> getFields()
          Iterator over all the fields within the tag, handle multiple fields with the same id
 java.util.List<TagField> getFields(FieldKey id)
          Returns a list of TagField objects whose "id" is the specified one.
 java.util.List<TagField> getFields(java.lang.String id)
          Returns a list of TagField objects whose "id" is the specified one.
 java.lang.String getFirst(FieldKey id)
          Retrieve String value of the first tag field that exists for this generic key
 java.lang.String getFirst(java.lang.String id)
          Retrieve String value of the first value that exists for this format specific key

 Artwork getFirstArtwork()
           
 TagField getFirstField(FieldKey id)
           
 TagField getFirstField(java.lang.String id)
          Retrieve the first field that exists for this format specific key

 java.lang.String getSubValue(FieldKey id, int n, int m)
          Retrieve String value of the mth field within the nth tag field that exists for this id
 java.lang.String getValue(FieldKey id, int n)
          Retrieve String value of the nth tag field that exists for this generic key
 boolean hasCommonFields()
          Returns true, if at least one of the contained fields is a common field (TagField.isCommon()).
 boolean hasField(java.lang.String id)
          Determines whether the tag has at least one field with the specified "id".
 boolean isEmpty()
          Determines whether the tag has no fields specified.
 boolean setEncoding(java.lang.String enc)
           
 void setField(Artwork artwork)
          Create artwork field based on the data in artwork and then set it in the tag itself

 void setField(FieldKey genericKey, java.lang.String value)
          Create the field based on the generic key and set it in the tag
 void setField(TagField field)
          Sets a field in the structure, used internally by the library

 java.lang.String toString()
           
 

Method Detail

setField

void setField(FieldKey genericKey,
              java.lang.String value)
              throws KeyNotFoundException,
                     FieldDataInvalidException
Create the field based on the generic key and set it in the tag

Parameters:
genericKey -
value -
Throws:
KeyNotFoundException
FieldDataInvalidException

addField

void addField(FieldKey genericKey,
              java.lang.String value)
              throws KeyNotFoundException,
                     FieldDataInvalidException
Create the field based on the generic key and add it to the tag This is handled differently by different formats

Parameters:
genericKey -
value -
Throws:
KeyNotFoundException
FieldDataInvalidException

deleteField

void deleteField(FieldKey fieldKey)
                 throws KeyNotFoundException
Delete any fields with this key

Parameters:
fieldKey -
Throws:
KeyNotFoundException

deleteField

void deleteField(java.lang.String key)
                 throws KeyNotFoundException
Delete any fields with this Flac (Vorbis Comment) id

Parameters:
key -
Throws:
KeyNotFoundException

getFields

java.util.List<TagField> getFields(java.lang.String id)
Returns a list of TagField objects whose "id" is the specified one.

Can be used to retrieve fields with any identifier, useful if the identifier is not within FieldKey

Parameters:
id - The field id.
Returns:
A list of TagField objects with the given "id".

getFields

java.util.List<TagField> getFields(FieldKey id)
                                   throws KeyNotFoundException
Returns a list of TagField objects whose "id" is the specified one.

Parameters:
id - The field id.
Returns:
A list of TagField objects with the given "id".
Throws:
KeyNotFoundException

getFields

java.util.Iterator<TagField> getFields()
Iterator over all the fields within the tag, handle multiple fields with the same id

Returns:
iterator over whole list

getFirst

java.lang.String getFirst(java.lang.String id)
Retrieve String value of the first value that exists for this format specific key

Can be used to retrieve fields with any identifier, useful if the identifier is not within FieldKey

Parameters:
id -
Returns:

getFirst

java.lang.String getFirst(FieldKey id)
                          throws KeyNotFoundException
Retrieve String value of the first tag field that exists for this generic key

Parameters:
id -
Returns:
String value or empty string
Throws:
KeyNotFoundException

getValue

java.lang.String getValue(FieldKey id,
                          int n)
Retrieve String value of the nth tag field that exists for this generic key

Parameters:
id -
n -
Returns:

getSubValue

java.lang.String getSubValue(FieldKey id,
                             int n,
                             int m)
Retrieve String value of the mth field within the nth tag field that exists for this id

This method id useful for formats that hold multiple values within one field, namely ID3v2 can hold multiple values within one Text Frame. the #getValue() method will return all values within the frame but this method lets you retrieve just the individual values.

Parameters:
id -
n -
Returns:

getFirstField

TagField getFirstField(java.lang.String id)
Retrieve the first field that exists for this format specific key

Can be used to retrieve fields with any identifier, useful if the identifier is not within FieldKey

Parameters:
id - audio specific key
Returns:
tag field or null if doesn't exist

getFirstField

TagField getFirstField(FieldKey id)
Parameters:
id -
Returns:
the first field that matches this generic key

hasCommonFields

boolean hasCommonFields()
Returns true, if at least one of the contained fields is a common field (TagField.isCommon()).

Returns:
true if a common field is present.

hasField

boolean hasField(java.lang.String id)
Determines whether the tag has at least one field with the specified "id".

Parameters:
id - The field id to look for.
Returns:
true if tag contains a TagField with the given id.

isEmpty

boolean isEmpty()
Determines whether the tag has no fields specified.

Returns:
true if tag contains no field.

toString

java.lang.String toString()
Overrides:
toString in class java.lang.Object

getFieldCount

int getFieldCount()
Return the number of fields

Fields with the same identifiers are counted separately i.e two TITLE fields in a Vorbis Comment file would count as two

Returns:
total number of fields

getFieldCountIncludingSubValues

int getFieldCountIncludingSubValues()
Return the number of fields taking multiple value fields into consideration Fields that actually contain multiple values are counted seperately i.e. a TCON frame in ID3v24 frame containing multiple genres would add to count for each genre.

Returns:
total number of fields taking multiple value fields into consideration

setEncoding

boolean setEncoding(java.lang.String enc)
                    throws FieldDataInvalidException
Throws:
FieldDataInvalidException

getArtworkList

java.util.List<Artwork> getArtworkList()
Returns:
a list of all artwork in this file using the format indepedent Artwork class

getFirstArtwork

Artwork getFirstArtwork()
Returns:
first artwork or null if none exist

deleteArtworkField

void deleteArtworkField()
                        throws KeyNotFoundException
Delete any instance of tag fields used to store artwork

We need this additional deleteField method because in some formats artwork can be stored in multiple fields

Throws:
KeyNotFoundException

createField

TagField createField(Artwork artwork)
                     throws FieldDataInvalidException
Create artwork field based on the data in artwork

Parameters:
artwork -
Returns:
suitable tagfield for this format that represents the artwork data
Throws:
FieldDataInvalidException

setField

void setField(Artwork artwork)
              throws FieldDataInvalidException
Create artwork field based on the data in artwork and then set it in the tag itself

Parameters:
artwork -
Throws:
FieldDataInvalidException

addField

void addField(Artwork artwork)
              throws FieldDataInvalidException
Create artwork field based on the data in artwork and then add it to the tag itself

Parameters:
artwork -
Throws:
FieldDataInvalidException

setField

void setField(TagField field)
              throws FieldDataInvalidException
Sets a field in the structure, used internally by the library

Parameters:
field - The field to add.
Throws:
FieldDataInvalidException

addField

void addField(TagField field)
              throws FieldDataInvalidException
Adds a field to the structure, used internally by the library

Parameters:
field - The field to add.
Throws:
FieldDataInvalidException

createField

TagField createField(FieldKey genericKey,
                     java.lang.String value)
                     throws KeyNotFoundException,
                            FieldDataInvalidException
Create a new field based on generic key, used internally by the library

Only textual data supported at the moment. The genericKey will be mapped to the correct implementation key and return a TagField.

Parameters:
genericKey - is the generic key
value - to store
Returns:
Throws:
KeyNotFoundException
FieldDataInvalidException


Copyright © 2005-2010 java.net. All Rights Reserved.