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