Coverage Report

Coverage Report - org.jaudiotagger.tag.Tag

Classes in this File

 /*
  * 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 org.jaudiotagger.tag.datatype.Artwork;
 
 import java.util.Iterator;
 import java.util.List;
 
 /**
  * This interface represents the basic data structure for the default
  * audiolibrary functionality.<br>
  * <p/>
  * 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.<br>
  * For that kind of fields, the <b>commonly</b> used fields have adequate
  * methods for adding values. But it is possible the underlying implementation
  * does not support that kind of storing multiple values.<br>
  * <br>
  * <b>Code Examples:</b><br>
  * <p/>
  * <pre>
  * <code>
  * AudioFile file = AudioFileIO.read(new File(&quot;C:\\test.mp3&quot;));
  * <p/>
  * Tag tag = file.getTag();
  * </code>
  * </pre>
  *
  * @author Raphael Slinckx
  */
 public interface Tag {
     /**
      * Create the field based on the generic key and set it in the tag
      *
      * @param genericKey
      * @param value
      * @throws KeyNotFoundException
      * @throws FieldDataInvalidException
      */
     public void setField(FieldKey genericKey, String value) throws KeyNotFoundException, FieldDataInvalidException;
 
     /**
      * Create the field based on the generic key and add it to the tag
      *
      * @param genericKey
      * @param value
      * @throws KeyNotFoundException
      * @throws FieldDataInvalidException
      */
     public void addField(FieldKey genericKey, String value) throws KeyNotFoundException, FieldDataInvalidException;
 
     /**
      * Delete any fields with this key
      *
      * @param fieldKey
      * @throws KeyNotFoundException
      */
     public void deleteField(FieldKey fieldKey) throws KeyNotFoundException;
 
     /**
      * Returns a {@linkplain List list} of {@link TagField} objects whose &quot;{@linkplain TagField#getId() id}&quot;
      * is the specified one.<br>
      *
      * @param id The field id.
      * @return A list of {@link TagField} objects with the given &quot;id&quot;.
      */
     public List<TagField> get(String id);
 
 
     /**
      * Retrieve String value of the first value that exists for this format specific key
      * <p/>
      * <p>Can be used to retrieve fields with any identifier, useful if the identifier is not within {@link FieldKey}
      *
      * @param id
      * @return
      */
     public String getFirst(String id);
 
     /**
      * Retrieve String value of the first tagfield that exists for this generic key
      *
      * @param id
      * @return String value or empty string
      * @throws KeyNotFoundException
      */
     public String getFirst(FieldKey id) throws KeyNotFoundException;
 
     /**
      * Retrieve the first field that exists for this format specific key
      * <p/>
      * <p>Can be used to retrieve fields with any identifier, useful if the identifier is not within {@link FieldKey}
      *
      * @param id audio specific key
      * @return tag field or null if doesnt exist
      */
     public TagField getFirstField(String id);
 
     /**
      * @param id
      * @return the first field that matches this generic key
      */
     public TagField getFirstField(FieldKey id);
 
 
     /**
      * Returns <code>true</code>, if at least one of the contained
      * {@linkplain TagField fields} is a common field ({@link TagField#isCommon()}).
      *
      * @return <code>true</code> if a {@linkplain TagField#isCommon() common}
      *         field is present.
      */
     public boolean hasCommonFields();
 
     /**
      * Determines whether the tag has at least one field with the specified
      * &quot;id&quot;.
      *
      * @param id The field id to look for.
      * @return <code>true</code> if tag contains a {@link TagField} with the
      *         given {@linkplain TagField#getId() id}.
      */
     public boolean hasField(String id);
 
     /**
      * Determines whether the tag has no fields specified.<br>
      *
      * @return <code>true</code> if tag contains no field.
      */
     public boolean isEmpty();
 
 
     //TODO, do we need this
     public String toString();
 
     /**
      * Returns a {@linkplain List list} of {@link TagField} objects whose &quot;{@linkplain TagField#getId() id}&quot;
      * is the specified one.<br>
      *
      * @param id The field id.
      * @return A list of {@link TagField} objects with the given &quot;id&quot;.
      * @throws KeyNotFoundException
      */
     public List<TagField> getFields(FieldKey id) throws KeyNotFoundException;
 
 
     /**
      * Iterator over all the fields within the tag, handle multiple fields with the same id
      *
      * @return iterator over whole list
      */
     public Iterator<TagField> getFields();
 
     /**
      * Return the number of fields
      * <p/>
      * <p>Fields with the same identifiers are counted seperately
      * i.e two title fields would contribute two to the count
      *
      * @return total number of fields
      */
     public int getFieldCount();
 
     //TODO is this a special field?
     public boolean setEncoding(String enc) throws FieldDataInvalidException;
 
 
     /**
      * @return a list of all artwork in this file using the format indepedent Artwork class
      */
     public List<Artwork> getArtworkList();
 
     /**
      * @return first artwork or null if none exist
      */
     public Artwork getFirstArtwork();
 
     /**
      * Delete any instance of tag fields used to store artwork
      *
      * <p>We need this additional deleteField method because in some formats artwork can be stored
      * in multiple fields
      *
      * @throws KeyNotFoundException
      */
     public void deleteArtworkField() throws KeyNotFoundException;
 
 
     /**
      * Create artwork field based on the data in artwork
      *
      * @param artwork
      * @return suitable tagfield for this format that represents the artwork data
      * @throws FieldDataInvalidException
      */
     public TagField createField(Artwork artwork) throws FieldDataInvalidException;
 
     /**
      * Create artwork field based on the data in artwork and then set it in the tag itself
      * <p/>
      *
      * @param artwork
      * @throws FieldDataInvalidException
      */
     public void setField(Artwork artwork) throws FieldDataInvalidException;
 
     /**
      * Create artwork field based on the data in artwork and then add it to the tag itself
      * <p/>
      *
      * @param artwork
      * @throws FieldDataInvalidException
      */
     public void addField(Artwork artwork) throws FieldDataInvalidException;
 
     /**
      * Sets a field in the structure, used internally by the library<br>
      * <p/>
      * <p>It is not recommended to use this method for normal use of the
      * audiolibrary. The developer will circumvent the underlying
      * implementation. For example, if one adds a field with the field id
      * &quot;TALB&quot; for an mp3 file, and the given {@link TagField}
      * implementation does not return a text field compliant data with
      * {@link TagField#getRawContent()} other software and the audio library
      * won't read the file correctly, if they do read it at all. <br>
      * So for short:<br>
      * <uil>
      * <li>The field is stored without validation</li>
      * <li>No conversion of data is perfomed</li>
      * </ul>
      *
      * @param field The field to add.
      * @throws FieldDataInvalidException
      */
     public void setField(TagField field) throws FieldDataInvalidException;
 
     /**
      * Adds a field to the structure, used internally by the library<br>
      * <p/>
      * <p>It is not recommended to use this method for normal use of the
      * audiolibrary. The developer will circumvent the underlying
      * implementation. For example, if one adds a field with the field id
      * &quot;TALB&quot; for an mp3 file, and the given {@link TagField}
      * implementation does not return a text field compliant data with
      * {@link TagField#getRawContent()} other software and the audio library
      * won't read the file correctly, if they do read it at all. <br>
      * So for short:<br>
      * <uil>
      * <li>The field is stored without validation</li>
      * <li>No conversion of data is perfomed</li>
      * </ul>
      *
      * @param field The field to add.
      * @throws FieldDataInvalidException
      */
     public void addField(TagField field) throws FieldDataInvalidException;
 
     /**
      * Create a new field based on generic key, used internally by the library
      * <p/>
      * <p>Only textual data supported at the moment. The genericKey will be mapped
      * to the correct implementation key and return a TagField.
      * <p/>
      * It is not recommended to use this method for normal use of the
      * audiolibrary, this is snot added to the structure
      *
      * @param genericKey is the generic key
      * @param value      to store
      * @return
      * @throws KeyNotFoundException
      * @throws FieldDataInvalidException
      */
     public TagField createField(FieldKey genericKey, String value) throws KeyNotFoundException, FieldDataInvalidException;
 
 
 }

1		/*
2		* Entagged Audio Tag library
3		* Copyright (c) 2003-2005 Raphaël Slinckx <raphael@slinckx.net>
4		*
5		* This library is free software; you can redistribute it and/or
6		* modify it under the terms of the GNU Lesser General Public
7		* License as published by the Free Software Foundation; either
8		* version 2.1 of the License, or (at your option) any later version.
9		*
10		* This library is distributed in the hope that it will be useful,
11		* but WITHOUT ANY WARRANTY; without even the implied warranty of
12		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13		* Lesser General Public License for more details.
14		*
15		* You should have received a copy of the GNU Lesser General Public
16		* License along with this library; if not, write to the Free Software
17		* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18		*/
19		package org.jaudiotagger.tag;
20
21		import org.jaudiotagger.tag.datatype.Artwork;
22
23		import java.util.Iterator;
24		import java.util.List;
25
26		/**
27		* This interface represents the basic data structure for the default
28		* audiolibrary functionality.<br>
29		* <p/>
30		* Some audio file tagging systems allow to specify multiple values for one type
31		* of information. The artist for example. Some songs may be a cooperation of
32		* two or more artists. Sometimes a tagging user wants to specify them in the
33		* tag without making one long text string.<br>
34		* For that kind of fields, the <b>commonly</b> used fields have adequate
35		* methods for adding values. But it is possible the underlying implementation
36		* does not support that kind of storing multiple values.<br>
37		* <br>
38		* <b>Code Examples:</b><br>
39		* <p/>
40		* <pre>
41		* <code>
42		* AudioFile file = AudioFileIO.read(new File("C:\\test.mp3"));
43		* <p/>
44		* Tag tag = file.getTag();
45		* </code>
46		* </pre>
47		*
48		* @author Raphael Slinckx
49		*/
50		public interface Tag {
51		/**
52		* Create the field based on the generic key and set it in the tag
53		*
54		* @param genericKey
55		* @param value
56		* @throws KeyNotFoundException
57		* @throws FieldDataInvalidException
58		*/
59		public void setField(FieldKey genericKey, String value) throws KeyNotFoundException, FieldDataInvalidException;
60
61		/**
62		* Create the field based on the generic key and add it to the tag
63		*
64		* @param genericKey
65		* @param value
66		* @throws KeyNotFoundException
67		* @throws FieldDataInvalidException
68		*/
69		public void addField(FieldKey genericKey, String value) throws KeyNotFoundException, FieldDataInvalidException;
70
71		/**
72		* Delete any fields with this key
73		*
74		* @param fieldKey
75		* @throws KeyNotFoundException
76		*/
77		public void deleteField(FieldKey fieldKey) throws KeyNotFoundException;
78
79		/**
80		* Returns a {@linkplain List list} of {@link TagField} objects whose "{@linkplain TagField#getId() id}"
81		* is the specified one.<br>
82		*
83		* @param id The field id.
84		* @return A list of {@link TagField} objects with the given "id".
85		*/
86		public List<TagField> get(String id);
87
88
89		/**
90		* Retrieve String value of the first value that exists for this format specific key
91		* <p/>
92		* <p>Can be used to retrieve fields with any identifier, useful if the identifier is not within {@link FieldKey}
93		*
94		* @param id
95		* @return
96		*/
97		public String getFirst(String id);
98
99		/**
100		* Retrieve String value of the first tagfield that exists for this generic key
101		*
102		* @param id
103		* @return String value or empty string
104		* @throws KeyNotFoundException
105		*/
106		public String getFirst(FieldKey id) throws KeyNotFoundException;
107
108		/**
109		* Retrieve the first field that exists for this format specific key
110		* <p/>
111		* <p>Can be used to retrieve fields with any identifier, useful if the identifier is not within {@link FieldKey}
112		*
113		* @param id audio specific key
114		* @return tag field or null if doesnt exist
115		*/
116		public TagField getFirstField(String id);
117
118		/**
119		* @param id
120		* @return the first field that matches this generic key
121		*/
122		public TagField getFirstField(FieldKey id);
123
124
125		/**
126		* Returns <code>true</code>, if at least one of the contained
127		* {@linkplain TagField fields} is a common field ({@link TagField#isCommon()}).
128		*
129		* @return <code>true</code> if a {@linkplain TagField#isCommon() common}
130		* field is present.
131		*/
132		public boolean hasCommonFields();
133
134		/**
135		* Determines whether the tag has at least one field with the specified
136		* "id".
137		*
138		* @param id The field id to look for.
139		* @return <code>true</code> if tag contains a {@link TagField} with the
140		* given {@linkplain TagField#getId() id}.
141		*/
142		public boolean hasField(String id);
143
144		/**
145		* Determines whether the tag has no fields specified.<br>
146		*
147		* @return <code>true</code> if tag contains no field.
148		*/
149		public boolean isEmpty();
150
151
152		//TODO, do we need this
153		public String toString();
154
155		/**
156		* Returns a {@linkplain List list} of {@link TagField} objects whose "{@linkplain TagField#getId() id}"
157		* is the specified one.<br>
158		*
159		* @param id The field id.
160		* @return A list of {@link TagField} objects with the given "id".
161		* @throws KeyNotFoundException
162		*/
163		public List<TagField> getFields(FieldKey id) throws KeyNotFoundException;
164
165
166		/**
167		* Iterator over all the fields within the tag, handle multiple fields with the same id
168		*
169		* @return iterator over whole list
170		*/
171		public Iterator<TagField> getFields();
172
173		/**
174		* Return the number of fields
175		* <p/>
176		* <p>Fields with the same identifiers are counted seperately
177		* i.e two title fields would contribute two to the count
178		*
179		* @return total number of fields
180		*/
181		public int getFieldCount();
182
183		//TODO is this a special field?
184		public boolean setEncoding(String enc) throws FieldDataInvalidException;
185
186
187		/**
188		* @return a list of all artwork in this file using the format indepedent Artwork class
189		*/
190		public List<Artwork> getArtworkList();
191
192		/**
193		* @return first artwork or null if none exist
194		*/
195		public Artwork getFirstArtwork();
196
197		/**
198		* Delete any instance of tag fields used to store artwork
199		*
200		* <p>We need this additional deleteField method because in some formats artwork can be stored
201		* in multiple fields
202		*
203		* @throws KeyNotFoundException
204		*/
205		public void deleteArtworkField() throws KeyNotFoundException;
206
207
208		/**
209		* Create artwork field based on the data in artwork
210		*
211		* @param artwork
212		* @return suitable tagfield for this format that represents the artwork data
213		* @throws FieldDataInvalidException
214		*/
215		public TagField createField(Artwork artwork) throws FieldDataInvalidException;
216
217		/**
218		* Create artwork field based on the data in artwork and then set it in the tag itself
219		* <p/>
220		*
221		* @param artwork
222		* @throws FieldDataInvalidException
223		*/
224		public void setField(Artwork artwork) throws FieldDataInvalidException;
225
226		/**
227		* Create artwork field based on the data in artwork and then add it to the tag itself
228		* <p/>
229		*
230		* @param artwork
231		* @throws FieldDataInvalidException
232		*/
233		public void addField(Artwork artwork) throws FieldDataInvalidException;
234
235		/**
236		* Sets a field in the structure, used internally by the library<br>
237		* <p/>
238		* <p>It is not recommended to use this method for normal use of the
239		* audiolibrary. The developer will circumvent the underlying
240		* implementation. For example, if one adds a field with the field id
241		* "TALB" for an mp3 file, and the given {@link TagField}
242		* implementation does not return a text field compliant data with
243		* {@link TagField#getRawContent()} other software and the audio library
244		* won't read the file correctly, if they do read it at all. <br>
245		* So for short:<br>
246		* <uil>
247		* <li>The field is stored without validation</li>
248		* <li>No conversion of data is perfomed</li>
249		* </ul>
250		*
251		* @param field The field to add.
252		* @throws FieldDataInvalidException
253		*/
254		public void setField(TagField field) throws FieldDataInvalidException;
255
256		/**
257		* Adds a field to the structure, used internally by the library<br>
258		* <p/>
259		* <p>It is not recommended to use this method for normal use of the
260		* audiolibrary. The developer will circumvent the underlying
261		* implementation. For example, if one adds a field with the field id
262		* "TALB" for an mp3 file, and the given {@link TagField}
263		* implementation does not return a text field compliant data with
264		* {@link TagField#getRawContent()} other software and the audio library
265		* won't read the file correctly, if they do read it at all. <br>
266		* So for short:<br>
267		* <uil>
268		* <li>The field is stored without validation</li>
269		* <li>No conversion of data is perfomed</li>
270		* </ul>
271		*
272		* @param field The field to add.
273		* @throws FieldDataInvalidException
274		*/
275		public void addField(TagField field) throws FieldDataInvalidException;
276
277		/**
278		* Create a new field based on generic key, used internally by the library
279		* <p/>
280		* <p>Only textual data supported at the moment. The genericKey will be mapped
281		* to the correct implementation key and return a TagField.
282		* <p/>
283		* It is not recommended to use this method for normal use of the
284		* audiolibrary, this is snot added to the structure
285		*
286		* @param genericKey is the generic key
287		* @param value to store
288		* @return
289		* @throws KeyNotFoundException
290		* @throws FieldDataInvalidException
291		*/
292		public TagField createField(FieldKey genericKey, String value) throws KeyNotFoundException, FieldDataInvalidException;
293
294
295		}