1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 package entagged.audioformats.generic;
20
21 import java.io.UnsupportedEncodingException;
22
23 /***
24 * Implementing classes represent a tag field for the entagged audio library.<br>
25 * Very basic functionality is defined for use with
26 * {@link entagged.audioformats.Tag}.
27 *
28 * @author Raphaël Slinckx
29 */
30 public interface TagField {
31
32 /***
33 * This method copies the data of the given filed to the current data.<br>
34 *
35 * @param field
36 * The field containing the data to be taken.
37 */
38 public void copyContent(TagField field);
39
40 /***
41 * Returns the Id of the represented tag field.<br>
42 * This value should uniquely identify a kind of tag data, like title.
43 * {@link AbstractTag} will use the "id" to summarize multiple
44 * fields.
45 *
46 * @return Unique identifier for the fields type. (title, artist...)
47 */
48 public String getId();
49
50 /***
51 * This method delivers the binary representation of the fields data in
52 * order to be directly written to the file.<br>
53 *
54 * @return Binary data representing the current tag field.<br>
55 * @throws UnsupportedEncodingException
56 * Most tag data represents text. In some cases the underlying
57 * implementation will need to convert the text data in java to
58 * a specific charset encoding. In these cases an
59 * {@link UnsupportedEncodingException} may occur.
60 */
61 public byte[] getRawContent() throws UnsupportedEncodingException;
62
63 /***
64 * Determines whether the represented field contains (is made up of) binary
65 * data, instead of text data.<br>
66 * Software can identify fields to be displayed because they are human
67 * readable if this mehtod returns <code>false</code>.
68 *
69 * @return <code>true</code> if field represents binary data (not human
70 * readable).
71 */
72 public boolean isBinary();
73
74 /***
75 * This method will set the field to represent binary data.<br>
76 * Some implementations may support conversions.<br>
77 * As of now (Octobre 2005) there is no implemenation really using this
78 * method to perform useful operations.
79 *
80 * @param b
81 * <code>true</code>, if the field contains binary data.
82 * @deprecated As for now is of no use. Implementations should use another
83 * way of setting this property.
84 */
85 public void isBinary(boolean b);
86
87 /***
88 * Identifies a field to be of common use.<br>
89 * Some software may differ between common and not common fields. A common
90 * one is for sure the title field. A web link may not be of common use for
91 * tagging. However some file formats, or future developement of users
92 * expectations will make more fields common than now can be known.
93 *
94 * @return <code>true</code> if the field is of common use.
95 */
96 public boolean isCommon();
97
98 /***
99 * Determines whether the content of the field is empty.<br>
100 *
101 * @return <code>true</code> if no data is stored (or empty String).
102 */
103 public boolean isEmpty();
104
105 /***
106 * This method returns a human readable description of the fields contents.<br>
107 * For text fields it should be the text itself. Other fields containing
108 * images may return a formatted string with image properties like width,
109 * height and so on.
110 *
111 * @return Description of the fields content.
112 */
113 public String toString();
114 }