33 import javax.sound.sampled.AudioFileFormat; |
33 import javax.sound.sampled.AudioFileFormat; |
34 import javax.sound.sampled.AudioInputStream; |
34 import javax.sound.sampled.AudioInputStream; |
35 import javax.sound.sampled.UnsupportedAudioFileException; |
35 import javax.sound.sampled.UnsupportedAudioFileException; |
36 |
36 |
37 /** |
37 /** |
38 * Provider for audio file reading services. Classes providing concrete |
38 * Provider for audio file reading services. Classes providing concrete |
39 * implementations can parse the format information from one or more types of |
39 * implementations can parse the format information from one or more types of |
40 * audio file, and can produce audio input streams from files of these types. |
40 * audio file, and can produce audio input streams from files of these types. |
41 * |
41 * |
42 * @author Kara Kytle |
42 * @author Kara Kytle |
43 * @since 1.3 |
43 * @since 1.3 |
44 */ |
44 */ |
45 public abstract class AudioFileReader { |
45 public abstract class AudioFileReader { |
46 |
46 |
47 /** |
47 /** |
48 * Obtains the audio file format of the input stream provided. The stream must |
48 * Obtains the audio file format of the input stream provided. The stream |
49 * point to valid audio file data. In general, audio file readers may |
49 * must point to valid audio file data. In general, audio file readers may |
50 * need to read some data from the stream before determining whether they |
50 * need to read some data from the stream before determining whether they |
51 * support it. These parsers must |
51 * support it. These parsers must be able to mark the stream, read enough |
52 * be able to mark the stream, read enough data to determine whether they |
52 * data to determine whether they support the stream, and, if not, reset the |
53 * support the stream, and, if not, reset the stream's read pointer to its original |
53 * stream's read pointer to its original position. If the input stream does |
54 * position. If the input stream does not support this, this method may fail |
54 * not support this, this method may fail with an {@code IOException}. |
55 * with an <code>IOException</code>. |
55 * |
56 * @param stream the input stream from which file format information should be |
56 * @param stream the input stream from which file format information should |
57 * extracted |
57 * be extracted |
58 * @return an <code>AudioFileFormat</code> object describing the audio file format |
58 * @return an {@code AudioFileFormat} object describing the audio file |
59 * @throws UnsupportedAudioFileException if the stream does not point to valid audio |
59 * format |
60 * file data recognized by the system |
60 * @throws UnsupportedAudioFileException if the stream does not point to |
|
61 * valid audio file data recognized by the system |
61 * @throws IOException if an I/O exception occurs |
62 * @throws IOException if an I/O exception occurs |
62 * @see InputStream#markSupported |
63 * @see InputStream#markSupported |
63 * @see InputStream#mark |
64 * @see InputStream#mark |
64 */ |
65 */ |
65 public abstract AudioFileFormat getAudioFileFormat(InputStream stream) throws UnsupportedAudioFileException, IOException; |
66 public abstract AudioFileFormat getAudioFileFormat(InputStream stream) |
|
67 throws UnsupportedAudioFileException, IOException; |
66 |
68 |
67 /** |
69 /** |
68 * Obtains the audio file format of the URL provided. The URL must |
70 * Obtains the audio file format of the URL provided. The URL must point to |
69 * point to valid audio file data. |
71 * valid audio file data. |
70 * @param url the URL from which file format information should be |
72 * |
71 * extracted |
73 * @param url the URL from which file format information should be |
72 * @return an <code>AudioFileFormat</code> object describing the audio file format |
74 * extracted |
73 * @throws UnsupportedAudioFileException if the URL does not point to valid audio |
75 * @return an {@code AudioFileFormat} object describing the audio file |
74 * file data recognized by the system |
76 * format |
|
77 * @throws UnsupportedAudioFileException if the URL does not point to valid |
|
78 * audio file data recognized by the system |
75 * @throws IOException if an I/O exception occurs |
79 * @throws IOException if an I/O exception occurs |
76 */ |
80 */ |
77 public abstract AudioFileFormat getAudioFileFormat(URL url) throws UnsupportedAudioFileException, IOException; |
81 public abstract AudioFileFormat getAudioFileFormat(URL url) |
|
82 throws UnsupportedAudioFileException, IOException; |
78 |
83 |
79 /** |
84 /** |
80 * Obtains the audio file format of the <code>File</code> provided. The <code>File</code> must |
85 * Obtains the audio file format of the {@code File} provided. |
81 * point to valid audio file data. |
86 * The {@code File} must point to valid audio file data. |
82 * @param file the <code>File</code> from which file format information should be |
87 * |
83 * extracted |
88 * @param file the {@code File} from which file format information |
84 * @return an <code>AudioFileFormat</code> object describing the audio file format |
89 * should be extracted |
85 * @throws UnsupportedAudioFileException if the <code>File</code> does not point to valid audio |
90 * @return an {@code AudioFileFormat} object describing the audio file |
86 * file data recognized by the system |
91 * format |
|
92 * @throws UnsupportedAudioFileException if the {@code File} does not point |
|
93 * to valid audio file data recognized by the system |
87 * @throws IOException if an I/O exception occurs |
94 * @throws IOException if an I/O exception occurs |
88 */ |
95 */ |
89 public abstract AudioFileFormat getAudioFileFormat(File file) throws UnsupportedAudioFileException, IOException; |
96 public abstract AudioFileFormat getAudioFileFormat(File file) |
|
97 throws UnsupportedAudioFileException, IOException; |
90 |
98 |
91 /** |
99 /** |
92 * Obtains an audio input stream from the input stream provided. The stream must |
100 * Obtains an audio input stream from the input stream provided. The stream |
93 * point to valid audio file data. In general, audio file readers may |
101 * must point to valid audio file data. In general, audio file readers may |
94 * need to read some data from the stream before determining whether they |
102 * need to read some data from the stream before determining whether they |
95 * support it. These parsers must |
103 * support it. These parsers must be able to mark the stream, read enough |
96 * be able to mark the stream, read enough data to determine whether they |
104 * data to determine whether they support the stream, and, if not, reset the |
97 * support the stream, and, if not, reset the stream's read pointer to its original |
105 * stream's read pointer to its original position. If the input stream does |
98 * position. If the input stream does not support this, this method may fail |
106 * not support this, this method may fail with an {@code IOException}. |
99 * with an <code>IOException</code>. |
107 * |
100 * @param stream the input stream from which the <code>AudioInputStream</code> should be |
108 * @param stream the input stream from which the {@code AudioInputStream} |
101 * constructed |
109 * should be constructed |
102 * @return an <code>AudioInputStream</code> object based on the audio file data contained |
110 * @return an {@code AudioInputStream} object based on the audio file data |
103 * in the input stream. |
111 * contained in the input stream. |
104 * @throws UnsupportedAudioFileException if the stream does not point to valid audio |
112 * @throws UnsupportedAudioFileException if the stream does not point to |
105 * file data recognized by the system |
113 * valid audio file data recognized by the system |
106 * @throws IOException if an I/O exception occurs |
114 * @throws IOException if an I/O exception occurs |
107 * @see InputStream#markSupported |
115 * @see InputStream#markSupported |
108 * @see InputStream#mark |
116 * @see InputStream#mark |
109 */ |
117 */ |
110 public abstract AudioInputStream getAudioInputStream(InputStream stream) throws UnsupportedAudioFileException, IOException; |
118 public abstract AudioInputStream getAudioInputStream(InputStream stream) |
|
119 throws UnsupportedAudioFileException, IOException; |
111 |
120 |
112 /** |
121 /** |
113 * Obtains an audio input stream from the URL provided. The URL must |
122 * Obtains an audio input stream from the URL provided. The URL must point |
114 * point to valid audio file data. |
123 * to valid audio file data. |
115 * @param url the URL for which the <code>AudioInputStream</code> should be |
124 * |
116 * constructed |
125 * @param url the URL for which the {@code AudioInputStream} should be |
117 * @return an <code>AudioInputStream</code> object based on the audio file data pointed |
126 * constructed |
118 * to by the URL |
127 * @return an {@code AudioInputStream} object based on the audio file data |
119 * @throws UnsupportedAudioFileException if the URL does not point to valid audio |
128 * pointed to by the URL |
120 * file data recognized by the system |
129 * @throws UnsupportedAudioFileException if the URL does not point to valid |
|
130 * audio file data recognized by the system |
121 * @throws IOException if an I/O exception occurs |
131 * @throws IOException if an I/O exception occurs |
122 */ |
132 */ |
123 public abstract AudioInputStream getAudioInputStream(URL url) throws UnsupportedAudioFileException, IOException; |
133 public abstract AudioInputStream getAudioInputStream(URL url) |
|
134 throws UnsupportedAudioFileException, IOException; |
124 |
135 |
125 /** |
136 /** |
126 * Obtains an audio input stream from the <code>File</code> provided. The <code>File</code> must |
137 * Obtains an audio input stream from the {@code File} provided. |
127 * point to valid audio file data. |
138 * The {@code File} must point to valid audio file data. |
128 * @param file the <code>File</code> for which the <code>AudioInputStream</code> should be |
139 * |
129 * constructed |
140 * @param file the {@code File} for which the {@code AudioInputStream} |
130 * @return an <code>AudioInputStream</code> object based on the audio file data pointed |
141 * should be constructed |
131 * to by the File |
142 * @return an {@code AudioInputStream} object based on the audio file data |
132 * @throws UnsupportedAudioFileException if the <code>File</code> does not point to valid audio |
143 * pointed to by the File |
133 * file data recognized by the system |
144 * @throws UnsupportedAudioFileException if the {@code File} does not point |
|
145 * to valid audio file data recognized by the system |
134 * @throws IOException if an I/O exception occurs |
146 * @throws IOException if an I/O exception occurs |
135 */ |
147 */ |
136 public abstract AudioInputStream getAudioInputStream(File file) throws UnsupportedAudioFileException, IOException; |
148 public abstract AudioInputStream getAudioInputStream(File file) |
|
149 throws UnsupportedAudioFileException, IOException; |
137 } |
150 } |