1 /*
2 * Copyright (c) 1999, 2016, 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.stream.Stream;
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 *
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 */
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 */
84 public boolean isSourceEncodingSupported(final Encoding sourceEncoding) {
85 return Stream.of(getSourceEncodings()).anyMatch(sourceEncoding::equals);
86 }
87
88 /**
89 * Indicates whether the format converter supports conversion to the
90 * specified target format encoding.
91 *
92 * @param targetEncoding the target format encoding for which support is
93 * queried
94 * @return {@code true} if the encoding is supported, otherwise
95 * {@code false}
96 * @throws NullPointerException if {@code targetEncoding} is {@code null}
97 */
98 public boolean isTargetEncodingSupported(final Encoding targetEncoding) {
99 return Stream.of(getTargetEncodings()).anyMatch(targetEncoding::equals);
100 }
101
102 /**
103 * Obtains the set of target format encodings supported by the format
104 * converter given a particular source format. If no target format encodings
105 * are supported for this source format, an array of length 0 is returned.
106 *
107 * @param sourceFormat format of the incoming data
108 * @return array of supported target format encodings
109 * @throws NullPointerException if {@code sourceFormat} is {@code null}
110 */
111 public abstract Encoding[] getTargetEncodings(AudioFormat sourceFormat);
112
113 /**
114 * Indicates whether the format converter supports conversion to a
115 * particular encoding from a particular format.
116 *
117 * @param targetEncoding desired encoding of the outgoing data
118 * @param sourceFormat format of the incoming data
119 * @return {@code true} if the conversion is supported, otherwise
120 * {@code false}
121 * @throws NullPointerException if {@code targetEncoding} or
122 * {@code sourceFormat} are {@code null}
123 */
124 public boolean isConversionSupported(final Encoding targetEncoding,
125 final AudioFormat sourceFormat) {
126 return Stream.of(getTargetEncodings(sourceFormat))
127 .anyMatch(targetEncoding::equals);
128 }
129
130 /**
131 * Obtains the set of target formats with the encoding specified supported
132 * by the format converter. If no target formats with the specified encoding
133 * are supported for this source format, an array of length 0 is returned.
134 *
135 * @param targetEncoding desired encoding of the stream after processing
136 * @param sourceFormat format of the incoming data
137 * @return array of supported target formats
138 * @throws NullPointerException if {@code targetEncoding} or
139 * {@code sourceFormat} are {@code null}
140 */
141 public abstract AudioFormat[] getTargetFormats(Encoding targetEncoding,
142 AudioFormat sourceFormat);
143
144 /**
145 * Indicates whether the format converter supports conversion to one
146 * particular format from another.
147 *
148 * @param targetFormat desired format of outgoing data
149 * @param sourceFormat format of the incoming data
150 * @return {@code true} if the conversion is supported, otherwise
151 * {@code false}
152 * @throws NullPointerException if {@code targetFormat} or
153 * {@code sourceFormat} are {@code null}
154 */
155 public boolean isConversionSupported(final AudioFormat targetFormat,
156 final AudioFormat sourceFormat) {
157 final Encoding targetEncoding = targetFormat.getEncoding();
158 return Stream.of(getTargetFormats(targetEncoding, sourceFormat))
159 .anyMatch(targetFormat::matches);
160 }
161
162 /**
163 * Obtains an audio input stream with the specified encoding from the given
164 * audio input stream.
165 *
166 * @param targetEncoding desired encoding of the stream after processing
167 * @param sourceStream stream from which data to be processed should be
168 * read
169 * @return stream from which processed data with the specified target
170 * encoding may be read
171 * @throws IllegalArgumentException if the format combination supplied is
172 * not supported
173 * @throws NullPointerException if {@code targetEncoding} or
174 * {@code sourceStream} are {@code null}
175 */
176 public abstract AudioInputStream getAudioInputStream(
177 Encoding targetEncoding, AudioInputStream sourceStream);
178
|
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 *
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
178 public abstract AudioInputStream getAudioInputStream(
179 Encoding targetEncoding, AudioInputStream sourceStream);
180
|