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 org.jaudiotagger.tag.mp4.field.Mp4TagCoverField;
 
 import java.util.Iterator;
 import java.util.List;
 import java.io.IOException;
 
 /**
  * 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 Rapha�l Slinckx
  */
 public interface Tag
 {
     /**
      * Adds a tagfield to the structure.<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 withoud validation</li>
      * <li>No conversion of data is perfomed</li>
      * </ul>
      *
      * @param field The field to add.
      */
     public void add(TagField field) throws FieldDataInvalidException;
 
     /**
      * Adds an album to the tag.<br>
      *
      * @param album Album description
      */
     public void addAlbum(String album) throws FieldDataInvalidException;
 
     /**
      * Adds an artist to the tag.<br>
      *
      * @param artist Artist's name
      */
     public void addArtist(String artist) throws FieldDataInvalidException;
 
     /**
      * Adds a comment to the tag.<br>
      *
      * @param comment Comment.
      */
     public void addComment(String comment) throws FieldDataInvalidException;
 
     /**
      * Adds a genre to the tag.<br>
      *
      * @param genre Genre
      */
     public void addGenre(String genre) throws FieldDataInvalidException;
 
     /**
      * Adds a title to the tag.<br>
      *
      * @param title Title
      */
     public void addTitle(String title) throws FieldDataInvalidException;
 
     /**
      * Adds a track to the tag.<br>
      *
      * @param track Track
      */
     public void addTrack(String track) throws FieldDataInvalidException;
 
     /**
      * Adds a year to the Tag.<br>
      *
      * @param year Year
      */
     public void addYear(String year) throws FieldDataInvalidException;
 
     /**
      * 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);
 
     /**
      * @return
      */
     public List<TagField> getAlbum();
 
 
     /**
      * @return
      */
     public List<TagField> getArtist();
 
     /**
      * @return
      */
     public List<TagField> getComment();
 
     /**
      * @return
      */
     public List<TagField> getGenre();
 
     /**
      * @return
      */
     public List<TagField> getTitle();
 
     /**
      * @return
      */
     public List<TagField> getTrack();
 
     /**
      * @return
      */
     public List<TagField> getYear();
 
 
     /**
      * @return
      */
     public String getFirstAlbum();
 
     /**
      * @return
      */
     public String getFirstArtist();
 
     /**
      * @return
      */
     public String getFirstComment();
 
     /**
      * @return
      */
     public String getFirstGenre();
 
     /**
      * @return
      */
     public String getFirstTitle();
 
     /**
      * @return
      */
     public String getFirstTrack();
 
     /**
      * @return
      */
     public String getFirstYear();
 
     /**
      * 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();
 
     /**
      * @param field
      * @throws FieldDataInvalidException
      */
     public void set(TagField field) throws FieldDataInvalidException;
 
     /**
      * @param s
      * @throws FieldDataInvalidException
      */
     public void setAlbum(String s) throws FieldDataInvalidException;
 
 
     /**
      * @param s
      * @throws FieldDataInvalidException
      */
     public void setArtist(String s) throws FieldDataInvalidException;
 
     /**
      * @param s
      * @throws FieldDataInvalidException
      */
     public void setComment(String s) throws FieldDataInvalidException;
 
 
     /**
      * @param s
      * @throws FieldDataInvalidException
      */
     public void setGenre(String s) throws FieldDataInvalidException;
 
     /**
      * @param s
      * @throws FieldDataInvalidException
      */
     public void setTitle(String s) throws FieldDataInvalidException;
 
     /**
      * @param s
      * @throws FieldDataInvalidException
      */
     public void setTrack(String s) throws FieldDataInvalidException;
 
     /**
      * @param s
      * @throws FieldDataInvalidException
      */
     public void setYear(String s) throws FieldDataInvalidException;
 
 
     /**
      * Create a new TagField based on generic key
      * <p/>
      * <p>Only textual data supported at the moment. The genericKey will be mapped
      * to the correct implementation key and return a TagField.
      *
      * @param genericKey is the generic key
      * @param value      to store
      * @return
      */
     public TagField createTagField(TagFieldKey genericKey, String value) throws KeyNotFoundException, FieldDataInvalidException;
 
 
     /**
      * Retrieve the first value that exists for this key
      *
      * @param id
      * @return
      */
     public String getFirst(String id);
 
     /**
      * Retrieve String value of first tagfield that exists for this key
      *
      * @param id
      * @return String value or empty string
      */
     public String getFirst(TagFieldKey id) throws KeyNotFoundException;
 
     /**
      * Retrieve the first tagfield that exists for this key
      * <p/>
      * <p>Can be used to retrieve fields with any identifier, useful if the identifier is not within  the
      * jaudiotagger enum
      *
      * @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(TagFieldKey id);
 
     //TODO, do we need this
     public String toString();
 
     /**
      * Delete any instance of tag fields with this key
      *
      * @param tagFieldKey
      */
     public void deleteTagField(TagFieldKey tagFieldKey) 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;
 
     /**
      * 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(TagFieldKey id) throws KeyNotFoundException;
 
     /**
      *
      * @return a list of all artwork in this file using the format indepedent Artwork class
      */
     public List<Artwork> getArtworkList();
 
     /**
      *
      * @return first arttwork or null if none exist
      */
     public Artwork getFirstArtwork();
 
     /**
      * Create artwork field based on the data in artwork
      *
      * @return suitabel tagfield for this format that represents the artwork data
      */
     public TagField  createArtworkField(Artwork artwork) throws FieldDataInvalidException;
 
     /**
      * Create artwork field based on the data in artwork and then set it in the tag itself
      *
      * <p>Note We provide this extra method to get round problem with VorbisComment requiring two seperate fields to
      * represent an artwork field
      *
      * @return suitabel tagfield for this format that represents the artwork data
      */
     public void createAndSetArtworkField(Artwork artwork) throws 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		import org.jaudiotagger.tag.mp4.field.Mp4TagCoverField;
23
24		import java.util.Iterator;
25		import java.util.List;
26		import java.io.IOException;
27
28		/**
29		* This interface represents the basic data structure for the default
30		* audiolibrary functionality.<br>
31		* <p/>
32		* Some audio file tagging systems allow to specify multiple values for one type
33		* of information. The artist for example. Some songs may be a cooperation of
34		* two or more artists. Sometimes a tagging user wants to specify them in the
35		* tag without making one long text string.<br>
36		* For that kind of fields, the <b>commonly</b> used fields have adequate
37		* methods for adding values. But it is possible the underlying implementation
38		* does not support that kind of storing multiple values.<br>
39		* <br>
40		* <b>Code Examples:</b><br>
41		* <p/>
42		* <pre>
43		* <code>
44		* AudioFile file = AudioFileIO.read(new File("C:\\test.mp3"));
45		* <p/>
46		* Tag tag = file.getTag();
47		* </code>
48		* </pre>
49		*
50		* @author Rapha�l Slinckx
51		*/
52		public interface Tag
53		{
54		/**
55		* Adds a tagfield to the structure.<br>
56		* <p/>
57		* <p>It is not recommended to use this method for normal use of the
58		* audiolibrary. The developer will circumvent the underlying
59		* implementation. For example, if one adds a field with the field id
60		* "TALB" for an mp3 file, and the given {@link TagField}
61		* implementation does not return a text field compliant data with
62		* {@link TagField#getRawContent()} other software and the audio library
63		* won't read the file correctly, if they do read it at all. <br>
64		* So for short:<br>
65		* <uil>
66		* <li>The field is stored withoud validation</li>
67		* <li>No conversion of data is perfomed</li>
68		* </ul>
69		*
70		* @param field The field to add.
71		*/
72		public void add(TagField field) throws FieldDataInvalidException;
73
74		/**
75		* Adds an album to the tag.<br>
76		*
77		* @param album Album description
78		*/
79		public void addAlbum(String album) throws FieldDataInvalidException;
80
81		/**
82		* Adds an artist to the tag.<br>
83		*
84		* @param artist Artist's name
85		*/
86		public void addArtist(String artist) throws FieldDataInvalidException;
87
88		/**
89		* Adds a comment to the tag.<br>
90		*
91		* @param comment Comment.
92		*/
93		public void addComment(String comment) throws FieldDataInvalidException;
94
95		/**
96		* Adds a genre to the tag.<br>
97		*
98		* @param genre Genre
99		*/
100		public void addGenre(String genre) throws FieldDataInvalidException;
101
102		/**
103		* Adds a title to the tag.<br>
104		*
105		* @param title Title
106		*/
107		public void addTitle(String title) throws FieldDataInvalidException;
108
109		/**
110		* Adds a track to the tag.<br>
111		*
112		* @param track Track
113		*/
114		public void addTrack(String track) throws FieldDataInvalidException;
115
116		/**
117		* Adds a year to the Tag.<br>
118		*
119		* @param year Year
120		*/
121		public void addYear(String year) throws FieldDataInvalidException;
122
123		/**
124		* Returns a {@linkplain List list} of {@link TagField} objects whose "{@linkplain TagField#getId() id}"
125		* is the specified one.<br>
126		*
127		* @param id The field id.
128		* @return A list of {@link TagField} objects with the given "id".
129		*/
130		public List<TagField> get(String id);
131
132		/**
133		* @return
134		*/
135		public List<TagField> getAlbum();
136
137
138		/**
139		* @return
140		*/
141		public List<TagField> getArtist();
142
143		/**
144		* @return
145		*/
146		public List<TagField> getComment();
147
148		/**
149		* @return
150		*/
151		public List<TagField> getGenre();
152
153		/**
154		* @return
155		*/
156		public List<TagField> getTitle();
157
158		/**
159		* @return
160		*/
161		public List<TagField> getTrack();
162
163		/**
164		* @return
165		*/
166		public List<TagField> getYear();
167
168
169		/**
170		* @return
171		*/
172		public String getFirstAlbum();
173
174		/**
175		* @return
176		*/
177		public String getFirstArtist();
178
179		/**
180		* @return
181		*/
182		public String getFirstComment();
183
184		/**
185		* @return
186		*/
187		public String getFirstGenre();
188
189		/**
190		* @return
191		*/
192		public String getFirstTitle();
193
194		/**
195		* @return
196		*/
197		public String getFirstTrack();
198
199		/**
200		* @return
201		*/
202		public String getFirstYear();
203
204		/**
205		* Returns <code>true</code>, if at least one of the contained
206		* {@linkplain TagField fields} is a common field ({@link TagField#isCommon()}).
207		*
208		* @return <code>true</code> if a {@linkplain TagField#isCommon() common}
209		* field is present.
210		*/
211		public boolean hasCommonFields();
212
213		/**
214		* Determines whether the tag has at least one field with the specified
215		* "id".
216		*
217		* @param id The field id to look for.
218		* @return <code>true</code> if tag contains a {@link TagField} with the
219		* given {@linkplain TagField#getId() id}.
220		*/
221		public boolean hasField(String id);
222
223		/**
224		* Determines whether the tag has no fields specified.<br>
225		*
226		* @return <code>true</code> if tag contains no field.
227		*/
228		public boolean isEmpty();
229
230		/**
231		* @param field
232		* @throws FieldDataInvalidException
233		*/
234		public void set(TagField field) throws FieldDataInvalidException;
235
236		/**
237		* @param s
238		* @throws FieldDataInvalidException
239		*/
240		public void setAlbum(String s) throws FieldDataInvalidException;
241
242
243		/**
244		* @param s
245		* @throws FieldDataInvalidException
246		*/
247		public void setArtist(String s) throws FieldDataInvalidException;
248
249		/**
250		* @param s
251		* @throws FieldDataInvalidException
252		*/
253		public void setComment(String s) throws FieldDataInvalidException;
254
255
256		/**
257		* @param s
258		* @throws FieldDataInvalidException
259		*/
260		public void setGenre(String s) throws FieldDataInvalidException;
261
262		/**
263		* @param s
264		* @throws FieldDataInvalidException
265		*/
266		public void setTitle(String s) throws FieldDataInvalidException;
267
268		/**
269		* @param s
270		* @throws FieldDataInvalidException
271		*/
272		public void setTrack(String s) throws FieldDataInvalidException;
273
274		/**
275		* @param s
276		* @throws FieldDataInvalidException
277		*/
278		public void setYear(String s) throws FieldDataInvalidException;
279
280
281		/**
282		* Create a new TagField based on generic key
283		* <p/>
284		* <p>Only textual data supported at the moment. The genericKey will be mapped
285		* to the correct implementation key and return a TagField.
286		*
287		* @param genericKey is the generic key
288		* @param value to store
289		* @return
290		*/
291		public TagField createTagField(TagFieldKey genericKey, String value) throws KeyNotFoundException, FieldDataInvalidException;
292
293
294		/**
295		* Retrieve the first value that exists for this key
296		*
297		* @param id
298		* @return
299		*/
300		public String getFirst(String id);
301
302		/**
303		* Retrieve String value of first tagfield that exists for this key
304		*
305		* @param id
306		* @return String value or empty string
307		*/
308		public String getFirst(TagFieldKey id) throws KeyNotFoundException;
309
310		/**
311		* Retrieve the first tagfield that exists for this key
312		* <p/>
313		* <p>Can be used to retrieve fields with any identifier, useful if the identifier is not within the
314		* jaudiotagger enum
315		*
316		* @param id audio specific key
317		* @return tag field or null if doesnt exist
318		*/
319		public TagField getFirstField(String id);
320
321		/**
322		*
323		* @param id
324		* @return the first field that matches this generic key
325		*/
326		public TagField getFirstField(TagFieldKey id);
327
328		//TODO, do we need this
329		public String toString();
330
331		/**
332		* Delete any instance of tag fields with this key
333		*
334		* @param tagFieldKey
335		*/
336		public void deleteTagField(TagFieldKey tagFieldKey) throws KeyNotFoundException;
337
338		/**
339		* Iterator over all the fields within the tag, handle multiple fields with the same id
340		*
341		* @return iterator over whole list
342		*/
343		public Iterator<TagField> getFields();
344
345		/**
346		* Return the number of fields
347		* <p/>
348		* <p>Fields with the same identifiers are counted seperately
349		* i.e two title fields would contribute two to the count
350		*
351		* @return total number of fields
352		*/
353		public int getFieldCount();
354
355		//TODO is this a special field?
356		public boolean setEncoding(String enc) throws FieldDataInvalidException;
357
358		/**
359		* Returns a {@linkplain List list} of {@link TagField} objects whose "{@linkplain TagField#getId() id}"
360		* is the specified one.<br>
361		*
362		* @param id The field id.
363		* @return A list of {@link TagField} objects with the given "id".
364		*/
365		public List<TagField> get(TagFieldKey id) throws KeyNotFoundException;
366
367		/**
368		*
369		* @return a list of all artwork in this file using the format indepedent Artwork class
370		*/
371		public List<Artwork> getArtworkList();
372
373		/**
374		*
375		* @return first arttwork or null if none exist
376		*/
377		public Artwork getFirstArtwork();
378
379		/**
380		* Create artwork field based on the data in artwork
381		*
382		* @return suitabel tagfield for this format that represents the artwork data
383		*/
384		public TagField createArtworkField(Artwork artwork) throws FieldDataInvalidException;
385
386		/**
387		* Create artwork field based on the data in artwork and then set it in the tag itself
388		*
389		* <p>Note We provide this extra method to get round problem with VorbisComment requiring two seperate fields to
390		* represent an artwork field
391		*
392		* @return suitabel tagfield for this format that represents the artwork data
393		*/
394		public void createAndSetArtworkField(Artwork artwork) throws FieldDataInvalidException;
395
396
397
398		}