1 /* 2 * Copyright (c) 1999, 2003, 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 26 package javax.sound.sampled.spi; 27 28 import java.io.InputStream; 29 30 import javax.sound.sampled.AudioFormat; 31 import javax.sound.sampled.AudioInputStream; 32 33 /** 34 * A format conversion provider provides format conversion services 35 * from one or more input formats to one or more output formats. 36 * Converters include codecs, which encode and/or decode audio data, 37 * as well as transcoders, etc. Format converters provide methods for 38 * determining what conversions are supported and for obtaining an audio 39 * stream from which converted data can be read. 40 * <p> 41 * The source format represents the format of the incoming 42 * audio data, which will be converted. 43 * <p> 44 * The target format represents the format of the processed, converted 45 * audio data. This is the format of the data that can be read from 46 * the stream returned by one of the <code>getAudioInputStream</code> methods. 47 * 48 * @author Kara Kytle 49 * @since 1.3 50 */ 51 public abstract class FormatConversionProvider { 52 53 54 // NEW METHODS 55 56 /** 57 * Obtains the set of source format encodings from which format 58 * conversion services are provided by this provider. 59 * @return array of source format encodings. If for some reason provider 60 * does not provide any conversion services, an array of length 0 is 61 * returned. 62 */ 63 public abstract AudioFormat.Encoding[] getSourceEncodings(); 64 65 66 /** 67 * Obtains the set of target format encodings to which format 68 * conversion services are provided by this provider. 69 * @return array of target format encodings. If for some reason provider 70 * does not provide any conversion services, an array of length 0 is 71 * returned. 72 */ 73 public abstract AudioFormat.Encoding[] getTargetEncodings(); 74 75 76 /** 77 * Indicates whether the format converter supports conversion from the 78 * specified source format encoding. 79 * @param sourceEncoding the source format encoding for which support is queried 80 * @return <code>true</code> if the encoding is supported, otherwise <code>false</code> 81 */ 82 public boolean isSourceEncodingSupported(AudioFormat.Encoding sourceEncoding){ 83 84 AudioFormat.Encoding sourceEncodings[] = getSourceEncodings(); 85 86 for(int i=0; i<sourceEncodings.length; i++) { 87 if( sourceEncoding.equals( sourceEncodings[i]) ) { 88 return true; 89 } 90 } 91 return false; 92 } 93 94 95 /** 96 * Indicates whether the format converter supports conversion to the 97 * specified target format encoding. 98 * @param targetEncoding the target format encoding for which support is queried 99 * @return <code>true</code> if the encoding is supported, otherwise <code>false</code> 100 */ 101 public boolean isTargetEncodingSupported(AudioFormat.Encoding targetEncoding){ 102 103 AudioFormat.Encoding targetEncodings[] = getTargetEncodings(); 104 105 for(int i=0; i<targetEncodings.length; i++) { 106 if( targetEncoding.equals( targetEncodings[i]) ) { 107 return true; 108 } 109 } 110 return false; 111 } 112 113 114 /** 115 * Obtains the set of target format encodings supported by the format converter 116 * given a particular source format. 117 * If no target format encodings are supported for this source format, 118 * an array of length 0 is returned. 119 * @return array of supported target format encodings. 120 */ 121 public abstract AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat); 122 123 124 /** 125 * Indicates whether the format converter supports conversion to a particular encoding 126 * from a particular format. 127 * @param targetEncoding desired encoding of the outgoing data 128 * @param sourceFormat format of the incoming data 129 * @return <code>true</code> if the conversion is supported, otherwise <code>false</code> 130 */ 131 public boolean isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat){ 132 133 AudioFormat.Encoding targetEncodings[] = getTargetEncodings(sourceFormat); 134 135 for(int i=0; i<targetEncodings.length; i++) { 136 if( targetEncoding.equals( targetEncodings[i]) ) { 137 return true; 138 } 139 } 140 return false; 141 } 142 143 144 /** 145 * Obtains the set of target formats with the encoding specified 146 * supported by the format converter 147 * If no target formats with the specified encoding are supported 148 * for this source format, an array of length 0 is returned. 149 * @return array of supported target formats. 150 */ 151 public abstract AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat); 152 153 154 /** 155 * Indicates whether the format converter supports conversion to one 156 * particular format from another. 157 * @param targetFormat desired format of outgoing data 158 * @param sourceFormat format of the incoming data 159 * @return <code>true</code> if the conversion is supported, otherwise <code>false</code> 160 */ 161 public boolean isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat){ 162 163 AudioFormat targetFormats[] = getTargetFormats( targetFormat.getEncoding(), sourceFormat ); 164 165 for(int i=0; i<targetFormats.length; i++) { 166 if( targetFormat.matches( targetFormats[i] ) ) { 167 return true; 168 } 169 } 170 return false; 171 } 172 173 174 /** 175 * Obtains an audio input stream with the specified encoding from the given audio 176 * input stream. 177 * @param targetEncoding desired encoding of the stream after processing 178 * @param sourceStream stream from which data to be processed should be read 179 * @return stream from which processed data with the specified target encoding may be read 180 * @throws IllegalArgumentException if the format combination supplied is 181 * not supported. 182 */ 183 public abstract AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream); 184 185 186 /** 187 * Obtains an audio input stream with the specified format from the given audio 188 * input stream. 189 * @param targetFormat desired data format of the stream after processing 190 * @param sourceStream stream from which data to be processed should be read 191 * @return stream from which processed data with the specified format may be read 192 * @throws IllegalArgumentException if the format combination supplied is 193 * not supported. 194 */ 195 public abstract AudioInputStream getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream); 196 197 }