/*
* Entagged Audio Tag library
* Copyright (c) 2003-2005 Raphaël Slinckx <raphael@slinckx.net>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
package org.jaudiotagger.tag;
import java.io.UnsupportedEncodingException;
/**
* Implementing classes represent a tag field for the entagged audio library.<br>
* Very basic functionality is defined for use with
* {@link org.jaudiotagger.tag.Tag}.
*
* @author Rapha�l Slinckx
*/
public interface TagField {
/**
* This method copies the data of the given field to the current data.<br>
*
* @param field The field containing the data to be taken.
*/
public void copyContent(TagField field);
/**
* Returns the Id of the represented tag field.<br>
* This value should uniquely identify a kind of tag data, like title.
* {@link org.jaudiotagger.audio.generic.AbstractTag} will use the "id" to summarize multiple
* fields.
*
* @return Unique identifier for the fields type. (title, artist...)
*/
public String getId();
/**
* This method delivers the binary representation of the fields data in
* order to be directly written to the file.<br>
*
* @return Binary data representing the current tag field.<br>
* @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
* {@link UnsupportedEncodingException} may occur.
*/
public byte[] getRawContent() throws UnsupportedEncodingException;
/**
* Determines whether the represented field contains (is made up of) binary
* data, instead of text data.<br>
* Software can identify fields to be displayed because they are human
* readable if this method returns <code>false</code>.
*
* @return <code>true</code> if field represents binary data (not human
* readable).
*/
public boolean isBinary();
/**
* This method will set the field to represent binary data.<br>
* <p/>
* Some implementations may support conversions.<br>
* As of now (Octobre 2005) there is no implementation really using this
* method to perform useful operations.
*
* @param b <code>true</code>, if the field contains binary data.
* //@deprecated As for now is of no use. Implementations should use another
* // way of setting this property.
*/
public void isBinary(boolean b);
/**
* Identifies a field to be of common use.<br>
* <p/>
* Some software may differ between common and not common fields. A common
* one is for sure the title field. A web link may not be of common use for
* tagging. However some file formats, or future development of users
* expectations will make more fields common than now can be known.
*
* @return <code>true</code> if the field is of common use.
*/
public boolean isCommon();
/**
* Determines whether the content of the field is empty.<br>
*
* @return <code>true</code> if no data is stored (or empty String).
*/
public boolean isEmpty();
/**
* This method returns a human readable description of the fields contents.<br>
* For text fields it should be the text itself. Other fields containing
* images may return a formatted string with image properties like width,
* height and so on.
*
* @return Description of the fields content.
*/
public String toString();
}