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