1/* 2 * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package javax.sound.sampled.spi; 27 28import java.io.File; 29import java.io.IOException; 30import java.io.InputStream; 31import java.net.URL; 32 33import javax.sound.sampled.AudioFileFormat; 34import javax.sound.sampled.AudioInputStream; 35import javax.sound.sampled.UnsupportedAudioFileException; 36 37/** 38 * Provider for audio file reading services. Classes providing concrete 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. 41 * 42 * @author Kara Kytle 43 * @since 1.3 44 */ 45public abstract class AudioFileReader { 46 47 /** 48 * Obtains the audio file format of the input stream provided. The stream 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 51 * support it. These parsers must be able to mark the stream, read enough 52 * data to determine whether they support the stream, and reset the stream's 53 * read pointer to its original position. If the input stream does not 54 * support this, this method may fail with an {@code IOException}. 55 * 56 * @param stream the input stream from which file format information should 57 * be extracted 58 * @return an {@code AudioFileFormat} object describing the audio file 59 * format 60 * @throws UnsupportedAudioFileException if the stream does not point to 61 * valid audio file data recognized by the system 62 * @throws IOException if an I/O exception occurs 63 * @throws NullPointerException if {@code stream} is {@code null} 64 * @see InputStream#markSupported 65 * @see InputStream#mark 66 */ 67 public abstract AudioFileFormat getAudioFileFormat(InputStream stream) 68 throws UnsupportedAudioFileException, IOException; 69 70 /** 71 * Obtains the audio file format of the {@code URL} provided. The 72 * {@code URL} must point to valid audio file data. 73 * 74 * @param url the {@code URL} from which file format information should be 75 * extracted 76 * @return an {@code AudioFileFormat} object describing the audio file 77 * format 78 * @throws UnsupportedAudioFileException if the {@code URL} does not point 79 * to valid audio file data recognized by the system 80 * @throws IOException if an I/O exception occurs 81 * @throws NullPointerException if {@code url} is {@code null} 82 */ 83 public abstract AudioFileFormat getAudioFileFormat(URL url) 84 throws UnsupportedAudioFileException, IOException; 85 86 /** 87 * Obtains the audio file format of the {@code File} provided. The 88 * {@code File} must point to valid audio file data. 89 * 90 * @param file the {@code File} from which file format information should 91 * be extracted 92 * @return an {@code AudioFileFormat} object describing the audio file 93 * format 94 * @throws UnsupportedAudioFileException if the {@code File} does not point 95 * to valid audio file data recognized by the system 96 * @throws IOException if an I/O exception occurs 97 * @throws NullPointerException if {@code file} is {@code null} 98 */ 99 public abstract AudioFileFormat getAudioFileFormat(File file) 100 throws UnsupportedAudioFileException, IOException; 101 102 /** 103 * Obtains an audio input stream from the input stream provided. The stream 104 * must point to valid audio file data. In general, audio file readers may 105 * need to read some data from the stream before determining whether they 106 * support it. These parsers must be able to mark the stream, read enough 107 * data to determine whether they support the stream, and reset the stream's 108 * read pointer to its original position. If the input stream does not 109 * support this, this method may fail with an {@code IOException}. 110 * 111 * @param stream the input stream from which the {@code AudioInputStream} 112 * should be constructed 113 * @return an {@code AudioInputStream} object based on the audio file data 114 * contained in the input stream 115 * @throws UnsupportedAudioFileException if the stream does not point to 116 * valid audio file data recognized by the system 117 * @throws IOException if an I/O exception occurs 118 * @throws NullPointerException if {@code stream} is {@code null} 119 * @see InputStream#markSupported 120 * @see InputStream#mark 121 */ 122 public abstract AudioInputStream getAudioInputStream(InputStream stream) 123 throws UnsupportedAudioFileException, IOException; 124 125 /** 126 * Obtains an audio input stream from the {@code URL} provided. The 127 * {@code URL} must point to valid audio file data. 128 * 129 * @param url the {@code URL} for which the {@code AudioInputStream} should 130 * be constructed 131 * @return an {@code AudioInputStream} object based on the audio file data 132 * pointed to by the {@code URL} 133 * @throws UnsupportedAudioFileException if the {@code URL} does not point 134 * to valid audio file data recognized by the system 135 * @throws IOException if an I/O exception occurs 136 * @throws NullPointerException if {@code url} is {@code null} 137 */ 138 public abstract AudioInputStream getAudioInputStream(URL url) 139 throws UnsupportedAudioFileException, IOException; 140 141 /** 142 * Obtains an audio input stream from the {@code File} provided. The 143 * {@code File} must point to valid audio file data. 144 * 145 * @param file the {@code File} for which the {@code AudioInputStream} 146 * should be constructed 147 * @return an {@code AudioInputStream} object based on the audio file data 148 * pointed to by the File 149 * @throws UnsupportedAudioFileException if the {@code File} does not point 150 * to valid audio file data recognized by the system 151 * @throws IOException if an I/O exception occurs 152 * @throws NullPointerException if {@code file} is {@code null} 153 */ 154 public abstract AudioInputStream getAudioInputStream(File file) 155 throws UnsupportedAudioFileException, IOException; 156} 157