1 /* 2 * Copyright (c) 1999, 2013, 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 * @param sourceFormat format of the incoming data 120 * @return array of supported target format encodings. 121 */ 122 public abstract AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat); 123 124 125 /** 126 * Indicates whether the format converter supports conversion to a particular encoding 127 * from a particular format. 128 * @param targetEncoding desired encoding of the outgoing data 129 * @param sourceFormat format of the incoming data 130 * @return <code>true</code> if the conversion is supported, otherwise <code>false</code> 131 */ 132 public boolean isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat){ 133 134 AudioFormat.Encoding targetEncodings[] = getTargetEncodings(sourceFormat); 135 136 for(int i=0; i<targetEncodings.length; i++) { 137 if( targetEncoding.equals( targetEncodings[i]) ) { 138 return true; 139 } 140 } 141 return false; 142 } 143 144 145 /** 146 * Obtains the set of target formats with the encoding specified 147 * supported by the format converter 148 * If no target formats with the specified encoding are supported 149 * for this source format, an array of length 0 is returned. 150 * @param targetEncoding desired encoding of the stream after processing 151 * @param sourceFormat format of the incoming data 152 * @return array of supported target formats. 153 */ 154 public abstract AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat); 155 156 157 /** 158 * Indicates whether the format converter supports conversion to one 159 * particular format from another. 160 * @param targetFormat desired format of outgoing data 161 * @param sourceFormat format of the incoming data 162 * @return <code>true</code> if the conversion is supported, otherwise <code>false</code> 163 */ 164 public boolean isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat){ 165 166 AudioFormat targetFormats[] = getTargetFormats( targetFormat.getEncoding(), sourceFormat ); 167 168 for(int i=0; i<targetFormats.length; i++) { 169 if( targetFormat.matches( targetFormats[i] ) ) { 170 return true; 171 } 172 } 173 return false; 174 } 175 176 177 /** 178 * Obtains an audio input stream with the specified encoding from the given audio 179 * input stream. 180 * @param targetEncoding desired encoding of the stream after processing 181 * @param sourceStream stream from which data to be processed should be read 182 * @return stream from which processed data with the specified target encoding may be read 183 * @throws IllegalArgumentException if the format combination supplied is 184 * not supported. 185 */ 186 public abstract AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream); 187 188 189 /** 190 * Obtains an audio input stream with the specified format from the given audio 191 * input stream. 192 * @param targetFormat desired data format of the stream after processing 193 * @param sourceStream stream from which data to be processed should be read 194 * @return stream from which processed data with the specified format may be read 195 * @throws IllegalArgumentException if the format combination supplied is 196 * not supported. 197 */ 198 public abstract AudioInputStream getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream); 199 200 }