feat(jdk8): move files to new folder to avoid resources compiled.

jdkSrc/jdk8/javax/sound/sampled/AudioFormat.java

@@ -0,0 +1,670 @@
+/*
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package javax.sound.sampled;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * <code>AudioFormat</code> is the class that specifies a particular arrangement of data in a sound stream.
+ * By examining the information stored in the audio format, you can discover how to interpret the bits in the
+ * binary sound data.
+ * <p>
+ * Every data line has an audio format associated with its data stream. The audio format of a source (playback) data line indicates
+ * what kind of data the data line expects to receive for output.  For a target (capture) data line, the audio format specifies the kind
+ * of the data that can be read from the line.
+ * Sound files also have audio formats, of course.  The <code>{@link AudioFileFormat}</code>
+ * class encapsulates an <code>AudioFormat</code> in addition to other,
+ * file-specific information.  Similarly, an <code>{@link AudioInputStream}</code> has an
+ * <code>AudioFormat</code>.
+ * <p>
+ * The <code>AudioFormat</code> class accommodates a number of common sound-file encoding techniques, including
+ * pulse-code modulation (PCM), mu-law encoding, and a-law encoding.  These encoding techniques are predefined,
+ * but service providers can create new encoding types.
+ * The encoding that a specific format uses is named by its <code>encoding</code> field.
+ *<p>
+ * In addition to the encoding, the audio format includes other properties that further specify the exact
+ * arrangement of the data.
+ * These include the number of channels, sample rate, sample size, byte order, frame rate, and frame size.
+ * Sounds may have different numbers of audio channels: one for mono, two for stereo.
+ * The sample rate measures how many "snapshots" (samples) of the sound pressure are taken per second, per channel.
+ * (If the sound is stereo rather than mono, two samples are actually measured at each instant of time: one for the left channel,
+ * and another for the right channel; however, the sample rate still measures the number per channel, so the rate is the same
+ * regardless of the number of channels.   This is the standard use of the term.)
+ * The sample size indicates how many bits are used to store each snapshot; 8 and 16 are typical values.
+ * For 16-bit samples (or any other sample size larger than a byte),
+ * byte order is important; the bytes in each sample are arranged in
+ * either the "little-endian" or "big-endian" style.
+ * For encodings like PCM, a frame consists of the set of samples for all channels at a given
+ * point in time, and so the size of a frame (in bytes) is always equal to the size of a sample (in bytes) times
+ * the number of channels.  However, with some other sorts of encodings a frame can contain
+ * a bundle of compressed data for a whole series of samples, as well as additional, non-sample
+ * data.  For such encodings, the sample rate and sample size refer to the data after it is decoded into PCM,
+ * and so they are completely different from the frame rate and frame size.
+ *
+ * <p>An <code>AudioFormat</code> object can include a set of
+ * properties. A property is a pair of key and value: the key
+ * is of type <code>String</code>, the associated property
+ * value is an arbitrary object. Properties specify
+ * additional format specifications, like the bit rate for
+ * compressed formats. Properties are mainly used as a means
+ * to transport additional information of the audio format
+ * to and from the service providers. Therefore, properties
+ * are ignored in the {@link #matches(AudioFormat)} method.
+ * However, methods which rely on the installed service
+ * providers, like {@link AudioSystem#isConversionSupported
+ * (AudioFormat, AudioFormat) isConversionSupported} may consider
+ * properties, depending on the respective service provider
+ * implementation.
+ *
+ * <p>The following table lists some common properties which
+ * service providers should use, if applicable:
+ *
+ * <table border=0>
+ *  <caption>Audio Format Properties</caption>
+ *  <tr>
+ *   <th>Property key</th>
+ *   <th>Value type</th>
+ *   <th>Description</th>
+ *  </tr>
+ *  <tr>
+ *   <td>&quot;bitrate&quot;</td>
+ *   <td>{@link java.lang.Integer Integer}</td>
+ *   <td>average bit rate in bits per second</td>
+ *  </tr>
+ *  <tr>
+ *   <td>&quot;vbr&quot;</td>
+ *   <td>{@link java.lang.Boolean Boolean}</td>
+ *   <td><code>true</code>, if the file is encoded in variable bit
+ *       rate (VBR)</td>
+ *  </tr>
+ *  <tr>
+ *   <td>&quot;quality&quot;</td>
+ *   <td>{@link java.lang.Integer Integer}</td>
+ *   <td>encoding/conversion quality, 1..100</td>
+ *  </tr>
+ * </table>
+ *
+ * <p>Vendors of service providers (plugins) are encouraged
+ * to seek information about other already established
+ * properties in third party plugins, and follow the same
+ * conventions.
+ *
+ * @author Kara Kytle
+ * @author Florian Bomers
+ * @see DataLine#getFormat
+ * @see AudioInputStream#getFormat
+ * @see AudioFileFormat
+ * @see javax.sound.sampled.spi.FormatConversionProvider
+ * @since 1.3
+ */
+public class AudioFormat {
+
+    // INSTANCE VARIABLES
+
+
+    /**
+     * The audio encoding technique used by this format.
+     */
+    protected Encoding encoding;
+
+    /**
+     * The number of samples played or recorded per second, for sounds that have this format.
+     */
+    protected float sampleRate;
+
+    /**
+     * The number of bits in each sample of a sound that has this format.
+     */
+    protected int sampleSizeInBits;
+
+    /**
+     * The number of audio channels in this format (1 for mono, 2 for stereo).
+     */
+    protected int channels;
+
+    /**
+     * The number of bytes in each frame of a sound that has this format.
+     */
+    protected int frameSize;
+
+    /**
+     * The number of frames played or recorded per second, for sounds that have this format.
+     */
+    protected float frameRate;
+
+    /**
+     * Indicates whether the audio data is stored in big-endian or little-endian order.
+     */
+    protected boolean bigEndian;
+
+
+    /** The set of properties */
+    private HashMap<String, Object> properties;
+
+
+    /**
+     * Constructs an <code>AudioFormat</code> with the given parameters.
+     * The encoding specifies the convention used to represent the data.
+     * The other parameters are further explained in the {@link AudioFormat
+     * class description}.
+     * @param encoding                  the audio encoding technique
+     * @param sampleRate                the number of samples per second
+     * @param sampleSizeInBits  the number of bits in each sample
+     * @param channels                  the number of channels (1 for mono, 2 for stereo, and so on)
+     * @param frameSize                 the number of bytes in each frame
+     * @param frameRate                 the number of frames per second
+     * @param bigEndian                 indicates whether the data for a single sample
+     *                                                  is stored in big-endian byte order (<code>false</code>
+     *                                                  means little-endian)
+     */
+    public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits,
+                       int channels, int frameSize, float frameRate, boolean bigEndian) {
+
+        this.encoding = encoding;
+        this.sampleRate = sampleRate;
+        this.sampleSizeInBits = sampleSizeInBits;
+        this.channels = channels;
+        this.frameSize = frameSize;
+        this.frameRate = frameRate;
+        this.bigEndian = bigEndian;
+        this.properties = null;
+    }
+
+
+    /**
+     * Constructs an <code>AudioFormat</code> with the given parameters.
+     * The encoding specifies the convention used to represent the data.
+     * The other parameters are further explained in the {@link AudioFormat
+     * class description}.
+     * @param encoding         the audio encoding technique
+     * @param sampleRate       the number of samples per second
+     * @param sampleSizeInBits the number of bits in each sample
+     * @param channels         the number of channels (1 for mono, 2 for
+     *                         stereo, and so on)
+     * @param frameSize        the number of bytes in each frame
+     * @param frameRate        the number of frames per second
+     * @param bigEndian        indicates whether the data for a single sample
+     *                         is stored in big-endian byte order
+     *                         (<code>false</code> means little-endian)
+     * @param properties       a <code>Map&lt;String,Object&gt;</code> object
+     *                         containing format properties
+     *
+     * @since 1.5
+     */
+    public AudioFormat(Encoding encoding, float sampleRate,
+                       int sampleSizeInBits, int channels,
+                       int frameSize, float frameRate,
+                       boolean bigEndian, Map<String, Object> properties) {
+        this(encoding, sampleRate, sampleSizeInBits, channels,
+             frameSize, frameRate, bigEndian);
+        this.properties = new HashMap<String, Object>(properties);
+    }
+
+
+    /**
+     * Constructs an <code>AudioFormat</code> with a linear PCM encoding and
+     * the given parameters.  The frame size is set to the number of bytes
+     * required to contain one sample from each channel, and the frame rate
+     * is set to the sample rate.
+     *
+     * @param sampleRate                the number of samples per second
+     * @param sampleSizeInBits  the number of bits in each sample
+     * @param channels                  the number of channels (1 for mono, 2 for stereo, and so on)
+     * @param signed                    indicates whether the data is signed or unsigned
+     * @param bigEndian                 indicates whether the data for a single sample
+     *                                                  is stored in big-endian byte order (<code>false</code>
+     *                                                  means little-endian)
+     */
+    public AudioFormat(float sampleRate, int sampleSizeInBits,
+                       int channels, boolean signed, boolean bigEndian) {
+
+        this((signed == true ? Encoding.PCM_SIGNED : Encoding.PCM_UNSIGNED),
+             sampleRate,
+             sampleSizeInBits,
+             channels,
+             (channels == AudioSystem.NOT_SPECIFIED || sampleSizeInBits == AudioSystem.NOT_SPECIFIED)?
+             AudioSystem.NOT_SPECIFIED:
+             ((sampleSizeInBits + 7) / 8) * channels,
+             sampleRate,
+             bigEndian);
+    }
+
+    /**
+     * Obtains the type of encoding for sounds in this format.
+     *
+     * @return the encoding type
+     * @see Encoding#PCM_SIGNED
+     * @see Encoding#PCM_UNSIGNED
+     * @see Encoding#ULAW
+     * @see Encoding#ALAW
+     */
+    public Encoding getEncoding() {
+
+        return encoding;
+    }
+
+    /**
+     * Obtains the sample rate.
+     * For compressed formats, the return value is the sample rate of the uncompressed
+     * audio data.
+     * When this AudioFormat is used for queries (e.g. {@link
+     * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
+     * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
+     * DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample rate of
+     * <code>AudioSystem.NOT_SPECIFIED</code> means that any sample rate is
+     * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
+     * the sample rate is not defined for this audio format.
+     * @return the number of samples per second,
+     * or <code>AudioSystem.NOT_SPECIFIED</code>
+     *
+     * @see #getFrameRate()
+     * @see AudioSystem#NOT_SPECIFIED
+     */
+    public float getSampleRate() {
+
+        return sampleRate;
+    }
+
+    /**
+     * Obtains the size of a sample.
+     * For compressed formats, the return value is the sample size of the
+     * uncompressed audio data.
+     * When this AudioFormat is used for queries (e.g. {@link
+     * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
+     * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
+     * DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample size of
+     * <code>AudioSystem.NOT_SPECIFIED</code> means that any sample size is
+     * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
+     * the sample size is not defined for this audio format.
+     * @return the number of bits in each sample,
+     * or <code>AudioSystem.NOT_SPECIFIED</code>
+     *
+     * @see #getFrameSize()
+     * @see AudioSystem#NOT_SPECIFIED
+     */
+    public int getSampleSizeInBits() {
+
+        return sampleSizeInBits;
+    }
+
+    /**
+     * Obtains the number of channels.
+     * When this AudioFormat is used for queries (e.g. {@link
+     * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
+     * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
+     * DataLine.Info#getFormats() DataLine.Info.getFormats}), a return value of
+     * <code>AudioSystem.NOT_SPECIFIED</code> means that any (positive) number of channels is
+     * acceptable.
+     * @return The number of channels (1 for mono, 2 for stereo, etc.),
+     * or <code>AudioSystem.NOT_SPECIFIED</code>
+     *
+     * @see AudioSystem#NOT_SPECIFIED
+     */
+    public int getChannels() {
+
+        return channels;
+    }
+
+    /**
+     * Obtains the frame size in bytes.
+     * When this AudioFormat is used for queries (e.g. {@link
+     * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
+     * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
+     * DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame size of
+     * <code>AudioSystem.NOT_SPECIFIED</code> means that any frame size is
+     * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
+     * the frame size is not defined for this audio format.
+     * @return the number of bytes per frame,
+     * or <code>AudioSystem.NOT_SPECIFIED</code>
+     *
+     * @see #getSampleSizeInBits()
+     * @see AudioSystem#NOT_SPECIFIED
+     */
+    public int getFrameSize() {
+
+        return frameSize;
+    }
+
+    /**
+     * Obtains the frame rate in frames per second.
+     * When this AudioFormat is used for queries (e.g. {@link
+     * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
+     * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
+     * DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame rate of
+     * <code>AudioSystem.NOT_SPECIFIED</code> means that any frame rate is
+     * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
+     * the frame rate is not defined for this audio format.
+     * @return the number of frames per second,
+     * or <code>AudioSystem.NOT_SPECIFIED</code>
+     *
+     * @see #getSampleRate()
+     * @see AudioSystem#NOT_SPECIFIED
+     */
+    public float getFrameRate() {
+
+        return frameRate;
+    }
+
+
+    /**
+     * Indicates whether the audio data is stored in big-endian or little-endian
+     * byte order.  If the sample size is not more than one byte, the return value is
+     * irrelevant.
+     * @return <code>true</code> if the data is stored in big-endian byte order,
+     * <code>false</code> if little-endian
+     */
+    public boolean isBigEndian() {
+
+        return bigEndian;
+    }
+
+
+    /**
+     * Obtain an unmodifiable map of properties.
+     * The concept of properties is further explained in
+     * the {@link AudioFileFormat class description}.
+     *
+     * @return a <code>Map&lt;String,Object&gt;</code> object containing
+     *         all properties. If no properties are recognized, an empty map is
+     *         returned.
+     *
+     * @see #getProperty(String)
+     * @since 1.5
+     */
+    public Map<String,Object> properties() {
+        Map<String,Object> ret;
+        if (properties == null) {
+            ret = new HashMap<String,Object>(0);
+        } else {
+            ret = (Map<String,Object>) (properties.clone());
+        }
+        return (Map<String,Object>) Collections.unmodifiableMap(ret);
+    }
+
+
+    /**
+     * Obtain the property value specified by the key.
+     * The concept of properties is further explained in
+     * the {@link AudioFileFormat class description}.
+     *
+     * <p>If the specified property is not defined for a
+     * particular file format, this method returns
+     * <code>null</code>.
+     *
+     * @param key the key of the desired property
+     * @return the value of the property with the specified key,
+     *         or <code>null</code> if the property does not exist.
+     *
+     * @see #properties()
+     * @since 1.5
+     */
+    public Object getProperty(String key) {
+        if (properties == null) {
+            return null;
+        }
+        return properties.get(key);
+    }
+
+
+    /**
+     * Indicates whether this format matches the one specified.
+     * To match, two formats must have the same encoding,
+     * and consistent values of the number of channels, sample rate, sample size,
+     * frame rate, and frame size.
+     * The values of the property are consistent if they are equal
+     * or the specified format has the property value
+     * {@code AudioSystem.NOT_SPECIFIED}.
+     * The byte order (big-endian or little-endian) must be the same
+     * if the sample size is greater than one byte.
+     *
+     * @param format format to test for match
+     * @return {@code true} if this format matches the one specified,
+     *         {@code false} otherwise.
+     */
+    public boolean matches(AudioFormat format) {
+        if (format.getEncoding().equals(getEncoding())
+                && (format.getChannels() == AudioSystem.NOT_SPECIFIED
+                    || format.getChannels() == getChannels())
+                && (format.getSampleRate() == (float)AudioSystem.NOT_SPECIFIED
+                    || format.getSampleRate() == getSampleRate())
+                && (format.getSampleSizeInBits() == AudioSystem.NOT_SPECIFIED
+                    || format.getSampleSizeInBits() == getSampleSizeInBits())
+                && (format.getFrameRate() == (float)AudioSystem.NOT_SPECIFIED
+                    || format.getFrameRate() == getFrameRate())
+                && (format.getFrameSize() == AudioSystem.NOT_SPECIFIED
+                    || format.getFrameSize() == getFrameSize())
+                && (getSampleSizeInBits() <= 8
+                    || format.isBigEndian() == isBigEndian())) {
+            return true;
+        }
+        return false;
+    }
+
+
+    /**
+     * Returns a string that describes the format, such as:
+     * "PCM SIGNED 22050 Hz 16 bit mono big-endian".  The contents of the string
+     * may vary between implementations of Java Sound.
+     *
+     * @return a string that describes the format parameters
+     */
+    public String toString() {
+        String sEncoding = "";
+        if (getEncoding() != null) {
+            sEncoding = getEncoding().toString() + " ";
+        }
+
+        String sSampleRate;
+        if (getSampleRate() == (float) AudioSystem.NOT_SPECIFIED) {
+            sSampleRate = "unknown sample rate, ";
+        } else {
+            sSampleRate = "" + getSampleRate() + " Hz, ";
+        }
+
+        String sSampleSizeInBits;
+        if (getSampleSizeInBits() == (float) AudioSystem.NOT_SPECIFIED) {
+            sSampleSizeInBits = "unknown bits per sample, ";
+        } else {
+            sSampleSizeInBits = "" + getSampleSizeInBits() + " bit, ";
+        }
+
+        String sChannels;
+        if (getChannels() == 1) {
+            sChannels = "mono, ";
+        } else
+            if (getChannels() == 2) {
+                sChannels = "stereo, ";
+            } else {
+                if (getChannels() == AudioSystem.NOT_SPECIFIED) {
+                    sChannels = " unknown number of channels, ";
+                } else {
+                    sChannels = ""+getChannels()+" channels, ";
+                }
+            }
+
+        String sFrameSize;
+        if (getFrameSize() == (float) AudioSystem.NOT_SPECIFIED) {
+            sFrameSize = "unknown frame size, ";
+        } else {
+            sFrameSize = "" + getFrameSize()+ " bytes/frame, ";
+        }
+
+        String sFrameRate = "";
+        if (Math.abs(getSampleRate() - getFrameRate()) > 0.00001) {
+            if (getFrameRate() == (float) AudioSystem.NOT_SPECIFIED) {
+                sFrameRate = "unknown frame rate, ";
+            } else {
+                sFrameRate = getFrameRate() + " frames/second, ";
+            }
+        }
+
+        String sEndian = "";
+        if ((getEncoding().equals(Encoding.PCM_SIGNED)
+             || getEncoding().equals(Encoding.PCM_UNSIGNED))
+            && ((getSampleSizeInBits() > 8)
+                || (getSampleSizeInBits() == AudioSystem.NOT_SPECIFIED))) {
+            if (isBigEndian()) {
+                sEndian = "big-endian";
+            } else {
+                sEndian = "little-endian";
+            }
+        }
+
+        return sEncoding
+            + sSampleRate
+            + sSampleSizeInBits
+            + sChannels
+            + sFrameSize
+            + sFrameRate
+            + sEndian;
+
+    }
+
+    /**
+     * The <code>Encoding</code> class  names the  specific type of data representation
+     * used for an audio stream.   The encoding includes aspects of the
+     * sound format other than the number of channels, sample rate, sample size,
+     * frame rate, frame size, and byte order.
+     * <p>
+     * One ubiquitous type of audio encoding is pulse-code modulation (PCM),
+     * which is simply a linear (proportional) representation of the sound
+     * waveform.  With PCM, the number stored in each sample is proportional
+     * to the instantaneous amplitude of the sound pressure at that point in
+     * time.  The numbers may be signed or unsigned integers or floats.
+     * Besides PCM, other encodings include mu-law and a-law, which are nonlinear
+     * mappings of the sound amplitude that are often used for recording speech.
+     * <p>
+     * You can use a predefined encoding by referring to one of the static
+     * objects created by this class, such as PCM_SIGNED or
+     * PCM_UNSIGNED.  Service providers can create new encodings, such as
+     * compressed audio formats, and make
+     * these available through the <code>{@link AudioSystem}</code> class.
+     * <p>
+     * The <code>Encoding</code> class is static, so that all
+     * <code>AudioFormat</code> objects that have the same encoding will refer
+     * to the same object (rather than different instances of the same class).
+     * This allows matches to be made by checking that two format's encodings
+     * are equal.
+     *
+     * @see AudioFormat
+     * @see javax.sound.sampled.spi.FormatConversionProvider
+     *
+     * @author Kara Kytle
+     * @since 1.3
+     */
+    public static class Encoding {
+
+
+        // ENCODING DEFINES
+
+        /**
+         * Specifies signed, linear PCM data.
+         */
+        public static final Encoding PCM_SIGNED = new Encoding("PCM_SIGNED");
+
+        /**
+         * Specifies unsigned, linear PCM data.
+         */
+        public static final Encoding PCM_UNSIGNED = new Encoding("PCM_UNSIGNED");
+
+        /**
+         * Specifies floating-point PCM data.
+         *
+         * @since 1.7
+         */
+        public static final Encoding PCM_FLOAT = new Encoding("PCM_FLOAT");
+
+        /**
+         * Specifies u-law encoded data.
+         */
+        public static final Encoding ULAW = new Encoding("ULAW");
+
+        /**
+         * Specifies a-law encoded data.
+         */
+        public static final Encoding ALAW = new Encoding("ALAW");
+
+
+        // INSTANCE VARIABLES
+
+        /**
+         * Encoding name.
+         */
+        private String name;
+
+
+        // CONSTRUCTOR
+
+        /**
+         * Constructs a new encoding.
+         * @param name  the name of the new type of encoding
+         */
+        public Encoding(String name) {
+            this.name = name;
+        }
+
+
+        // METHODS
+
+        /**
+         * Finalizes the equals method
+         */
+        public final boolean equals(Object obj) {
+            if (toString() == null) {
+                return (obj != null) && (obj.toString() == null);
+            }
+            if (obj instanceof Encoding) {
+                return toString().equals(obj.toString());
+            }
+            return false;
+        }
+
+        /**
+         * Finalizes the hashCode method
+         */
+        public final int hashCode() {
+            if (toString() == null) {
+                return 0;
+            }
+            return toString().hashCode();
+        }
+
+        /**
+         * Provides the <code>String</code> representation of the encoding.  This <code>String</code> is
+         * the same name that was passed to the constructor.  For the predefined encodings, the name
+         * is similar to the encoding's variable (field) name.  For example, <code>PCM_SIGNED.toString()</code> returns
+         * the name "pcm_signed".
+         *
+         * @return the encoding name
+         */
+        public final String toString() {
+            return name;
+        }
+
+    } // class Encoding
+}