1 /* 2 * Copyright (c) 1999, 2018, 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 * Obtains the set of source format encodings from which format conversion 56 * services are provided by this provider. 57 * 58 * @return array of source format encodings. If for some reason provider 59 * does not provide any conversion services, an array of length 0 is 60 * returned. 61 */ getSourceEncodings()62 public abstract Encoding[] getSourceEncodings(); 63 64 /** 65 * Obtains the set of target format encodings to which format conversion 66 * services are provided by this provider. 67 * 68 * @return array of target format encodings. If for some reason provider 69 * does not provide any conversion services, an array of length 0 is 70 * returned. 71 */ getTargetEncodings()72 public abstract Encoding[] getTargetEncodings(); 73 74 /** 75 * Indicates whether the format converter supports conversion from the 76 * specified source format encoding. 77 * 78 * @param sourceEncoding the source format encoding for which support is 79 * queried 80 * @return {@code true} if the encoding is supported, otherwise 81 * {@code false} 82 * @throws NullPointerException if {@code sourceEncoding} is {@code null} 83 */ isSourceEncodingSupported(final Encoding sourceEncoding)84 public boolean isSourceEncodingSupported(final Encoding sourceEncoding) { 85 return Arrays.stream(getSourceEncodings()) 86 .anyMatch(sourceEncoding::equals); 87 } 88 89 /** 90 * Indicates whether the format converter supports conversion to the 91 * specified target format encoding. 92 * 93 * @param targetEncoding the target format encoding for which support is 94 * queried 95 * @return {@code true} if the encoding is supported, otherwise 96 * {@code false} 97 * @throws NullPointerException if {@code targetEncoding} is {@code null} 98 */ isTargetEncodingSupported(final Encoding targetEncoding)99 public boolean isTargetEncodingSupported(final Encoding targetEncoding) { 100 return Arrays.stream(getTargetEncodings()) 101 .anyMatch(targetEncoding::equals); 102 } 103 104 /** 105 * Obtains the set of target format encodings supported by the format 106 * converter given a particular source format. If no target format encodings 107 * are supported for this source format, an array of length 0 is returned. 108 * 109 * @param sourceFormat format of the incoming data 110 * @return array of supported target format encodings 111 * @throws NullPointerException if {@code sourceFormat} is {@code null} 112 */ getTargetEncodings(AudioFormat sourceFormat)113 public abstract Encoding[] getTargetEncodings(AudioFormat sourceFormat); 114 115 /** 116 * Indicates whether the format converter supports conversion to a 117 * particular encoding from a particular format. 118 * 119 * @param targetEncoding desired encoding of the outgoing data 120 * @param sourceFormat format of the incoming data 121 * @return {@code true} if the conversion is supported, otherwise 122 * {@code false} 123 * @throws NullPointerException if {@code targetEncoding} or 124 * {@code sourceFormat} are {@code null} 125 */ isConversionSupported(final Encoding targetEncoding, final AudioFormat sourceFormat)126 public boolean isConversionSupported(final Encoding targetEncoding, 127 final AudioFormat sourceFormat) { 128 return Arrays.stream(getTargetEncodings(sourceFormat)) 129 .anyMatch(targetEncoding::equals); 130 } 131 132 /** 133 * Obtains the set of target formats with the encoding specified supported 134 * by the format converter. If no target formats with the specified encoding 135 * are supported for this source format, an array of length 0 is returned. 136 * 137 * @param targetEncoding desired encoding of the stream after processing 138 * @param sourceFormat format of the incoming data 139 * @return array of supported target formats 140 * @throws NullPointerException if {@code targetEncoding} or 141 * {@code sourceFormat} are {@code null} 142 */ getTargetFormats(Encoding targetEncoding, AudioFormat sourceFormat)143 public abstract AudioFormat[] getTargetFormats(Encoding targetEncoding, 144 AudioFormat sourceFormat); 145 146 /** 147 * Indicates whether the format converter supports conversion to one 148 * particular format from another. 149 * 150 * @param targetFormat desired format of outgoing data 151 * @param sourceFormat format of the incoming data 152 * @return {@code true} if the conversion is supported, otherwise 153 * {@code false} 154 * @throws NullPointerException if {@code targetFormat} or 155 * {@code sourceFormat} are {@code null} 156 */ isConversionSupported(final AudioFormat targetFormat, final AudioFormat sourceFormat)157 public boolean isConversionSupported(final AudioFormat targetFormat, 158 final AudioFormat sourceFormat) { 159 final Encoding targetEncoding = targetFormat.getEncoding(); 160 return Arrays.stream(getTargetFormats(targetEncoding, sourceFormat)) 161 .anyMatch(targetFormat::matches); 162 } 163 164 /** 165 * Obtains an audio input stream with the specified encoding from the given 166 * audio input stream. 167 * 168 * @param targetEncoding desired encoding of the stream after processing 169 * @param sourceStream stream from which data to be processed should be 170 * read 171 * @return stream from which processed data with the specified target 172 * encoding may be read 173 * @throws IllegalArgumentException if the format combination supplied is 174 * not supported 175 * @throws NullPointerException if {@code targetEncoding} or 176 * {@code sourceStream} are {@code null} 177 */ getAudioInputStream( Encoding targetEncoding, AudioInputStream sourceStream)178 public abstract AudioInputStream getAudioInputStream( 179 Encoding targetEncoding, AudioInputStream sourceStream); 180 181 /** 182 * Obtains an audio input stream with the specified format from the given 183 * audio input stream. 184 * 185 * @param targetFormat desired data format of the stream after processing 186 * @param sourceStream stream from which data to be processed should be 187 * read 188 * @return stream from which processed data with the specified format may be 189 * read 190 * @throws IllegalArgumentException if the format combination supplied is 191 * not supported 192 * @throws NullPointerException if {@code targetFormat} or 193 * {@code sourceStream} are {@code null} 194 */ getAudioInputStream( AudioFormat targetFormat, AudioInputStream sourceStream)195 public abstract AudioInputStream getAudioInputStream( 196 AudioFormat targetFormat, AudioInputStream sourceStream); 197 } 198