1 /*
   2  * Copyright (c) 1999, 2013, 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;
  27 
  28 import java.util.Collections;
  29 import java.util.HashMap;
  30 import java.util.Map;
  31 
  32 /**
  33  * <code>AudioFormat</code> is the class that specifies a particular arrangement of data in a sound stream.
  34  * By examing the information stored in the audio format, you can discover how to interpret the bits in the
  35  * binary sound data.
  36  * <p>
  37  * Every data line has an audio format associated with its data stream. The audio format of a source (playback) data line indicates
  38  * what kind of data the data line expects to receive for output.  For a target (capture) data line, the audio format specifies the kind
  39  * of the data that can be read from the line.
  40  * Sound files also have audio formats, of course.  The <code>{@link AudioFileFormat}</code>
  41  * class encapsulates an <code>AudioFormat</code> in addition to other,
  42  * file-specific information.  Similarly, an <code>{@link AudioInputStream}</code> has an
  43  * <code>AudioFormat</code>.
  44  * <p>
  45  * The <code>AudioFormat</code> class accommodates a number of common sound-file encoding techniques, including
  46  * pulse-code modulation (PCM), mu-law encoding, and a-law encoding.  These encoding techniques are predefined,
  47  * but service providers can create new encoding types.
  48  * The encoding that a specific format uses is named by its <code>encoding</code> field.
  49  *<p>
  50  * In addition to the encoding, the audio format includes other properties that further specify the exact
  51  * arrangement of the data.
  52  * These include the number of channels, sample rate, sample size, byte order, frame rate, and frame size.
  53  * Sounds may have different numbers of audio channels: one for mono, two for stereo.
  54  * The sample rate measures how many "snapshots" (samples) of the sound pressure are taken per second, per channel.
  55  * (If the sound is stereo rather than mono, two samples are actually measured at each instant of time: one for the left channel,
  56  * and another for the right channel; however, the sample rate still measures the number per channel, so the rate is the same
  57  * regardless of the number of channels.   This is the standard use of the term.)
  58  * The sample size indicates how many bits are used to store each snapshot; 8 and 16 are typical values.
  59  * For 16-bit samples (or any other sample size larger than a byte),
  60  * byte order is important; the bytes in each sample are arranged in
  61  * either the "little-endian" or "big-endian" style.
  62  * For encodings like PCM, a frame consists of the set of samples for all channels at a given
  63  * point in time, and so the size of a frame (in bytes) is always equal to the size of a sample (in bytes) times
  64  * the number of channels.  However, with some other sorts of encodings a frame can contain
  65  * a bundle of compressed data for a whole series of samples, as well as additional, non-sample
  66  * data.  For such encodings, the sample rate and sample size refer to the data after it is decoded into PCM,
  67  * and so they are completely different from the frame rate and frame size.
  68  *
  69  * <p>An <code>AudioFormat</code> object can include a set of
  70  * properties. A property is a pair of key and value: the key
  71  * is of type <code>String</code>, the associated property
  72  * value is an arbitrary object. Properties specify
  73  * additional format specifications, like the bit rate for
  74  * compressed formats. Properties are mainly used as a means
  75  * to transport additional information of the audio format
  76  * to and from the service providers. Therefore, properties
  77  * are ignored in the {@link #matches(AudioFormat)} method.
  78  * However, methods which rely on the installed service
  79  * providers, like {@link AudioSystem#isConversionSupported
  80  * (AudioFormat, AudioFormat) isConversionSupported} may consider
  81  * properties, depending on the respective service provider
  82  * implementation.
  83  *
  84  * <p>The following table lists some common properties which
  85  * service providers should use, if applicable:
  86  *
  87  * <table border=0>
  88  *  <caption>Audio Format Property Keys</caption>
  89  *  <tr>
  90  *   <th>Property key</th>
  91  *   <th>Value type</th>
  92  *   <th>Description</th>
  93  *  </tr>
  94  *  <tr>
  95  *   <td>&quot;bitrate&quot;</td>
  96  *   <td>{@link java.lang.Integer Integer}</td>
  97  *   <td>average bit rate in bits per second</td>
  98  *  </tr>
  99  *  <tr>
 100  *   <td>&quot;vbr&quot;</td>
 101  *   <td>{@link java.lang.Boolean Boolean}</td>
 102  *   <td><code>true</code>, if the file is encoded in variable bit
 103  *       rate (VBR)</td>
 104  *  </tr>
 105  *  <tr>
 106  *   <td>&quot;quality&quot;</td>
 107  *   <td>{@link java.lang.Integer Integer}</td>
 108  *   <td>encoding/conversion quality, 1..100</td>
 109  *  </tr>
 110  * </table>
 111  *
 112  * <p>Vendors of service providers (plugins) are encouraged
 113  * to seek information about other already established
 114  * properties in third party plugins, and follow the same
 115  * conventions.
 116  *
 117  * @author Kara Kytle
 118  * @author Florian Bomers
 119  * @see DataLine#getFormat
 120  * @see AudioInputStream#getFormat
 121  * @see AudioFileFormat
 122  * @see javax.sound.sampled.spi.FormatConversionProvider
 123  * @since 1.3
 124  */
 125 public class AudioFormat {
 126 
 127     // INSTANCE VARIABLES
 128 
 129 
 130     /**
 131      * The audio encoding technique used by this format.
 132      */
 133     protected Encoding encoding;
 134 
 135     /**
 136      * The number of samples played or recorded per second, for sounds that have this format.
 137      */
 138     protected float sampleRate;
 139 
 140     /**
 141      * The number of bits in each sample of a sound that has this format.
 142      */
 143     protected int sampleSizeInBits;
 144 
 145     /**
 146      * The number of audio channels in this format (1 for mono, 2 for stereo).
 147      */
 148     protected int channels;
 149 
 150     /**
 151      * The number of bytes in each frame of a sound that has this format.
 152      */
 153     protected int frameSize;
 154 
 155     /**
 156      * The number of frames played or recorded per second, for sounds that have this format.
 157      */
 158     protected float frameRate;
 159 
 160     /**
 161      * Indicates whether the audio data is stored in big-endian or little-endian order.
 162      */
 163     protected boolean bigEndian;
 164 
 165 
 166     /** The set of properties */
 167     private HashMap<String, Object> properties;
 168 
 169 
 170     /**
 171      * Constructs an <code>AudioFormat</code> with the given parameters.
 172      * The encoding specifies the convention used to represent the data.
 173      * The other parameters are further explained in the {@link AudioFormat
 174      * class description}.
 175      * @param encoding                  the audio encoding technique
 176      * @param sampleRate                the number of samples per second
 177      * @param sampleSizeInBits  the number of bits in each sample
 178      * @param channels                  the number of channels (1 for mono, 2 for stereo, and so on)
 179      * @param frameSize                 the number of bytes in each frame
 180      * @param frameRate                 the number of frames per second
 181      * @param bigEndian                 indicates whether the data for a single sample
 182      *                                                  is stored in big-endian byte order (<code>false</code>
 183      *                                                  means little-endian)
 184      */
 185     public AudioFormat(Encoding encoding, float sampleRate, int sampleSizeInBits,
 186                        int channels, int frameSize, float frameRate, boolean bigEndian) {
 187 
 188         this.encoding = encoding;
 189         this.sampleRate = sampleRate;
 190         this.sampleSizeInBits = sampleSizeInBits;
 191         this.channels = channels;
 192         this.frameSize = frameSize;
 193         this.frameRate = frameRate;
 194         this.bigEndian = bigEndian;
 195         this.properties = null;
 196     }
 197 
 198 
 199     /**
 200      * Constructs an <code>AudioFormat</code> with the given parameters.
 201      * The encoding specifies the convention used to represent the data.
 202      * The other parameters are further explained in the {@link AudioFormat
 203      * class description}.
 204      * @param encoding         the audio encoding technique
 205      * @param sampleRate       the number of samples per second
 206      * @param sampleSizeInBits the number of bits in each sample
 207      * @param channels         the number of channels (1 for mono, 2 for
 208      *                         stereo, and so on)
 209      * @param frameSize        the number of bytes in each frame
 210      * @param frameRate        the number of frames per second
 211      * @param bigEndian        indicates whether the data for a single sample
 212      *                         is stored in big-endian byte order
 213      *                         (<code>false</code> means little-endian)
 214      * @param properties       a <code>Map&lt;String,Object&gt;</code> object
 215      *                         containing format properties
 216      *
 217      * @since 1.5
 218      */
 219     public AudioFormat(Encoding encoding, float sampleRate,
 220                        int sampleSizeInBits, int channels,
 221                        int frameSize, float frameRate,
 222                        boolean bigEndian, Map<String, Object> properties) {
 223         this(encoding, sampleRate, sampleSizeInBits, channels,
 224              frameSize, frameRate, bigEndian);
 225         this.properties = new HashMap<String, Object>(properties);
 226     }
 227 
 228 
 229     /**
 230      * Constructs an <code>AudioFormat</code> with a linear PCM encoding and
 231      * the given parameters.  The frame size is set to the number of bytes
 232      * required to contain one sample from each channel, and the frame rate
 233      * is set to the sample rate.
 234      *
 235      * @param sampleRate                the number of samples per second
 236      * @param sampleSizeInBits  the number of bits in each sample
 237      * @param channels                  the number of channels (1 for mono, 2 for stereo, and so on)
 238      * @param signed                    indicates whether the data is signed or unsigned
 239      * @param bigEndian                 indicates whether the data for a single sample
 240      *                                                  is stored in big-endian byte order (<code>false</code>
 241      *                                                  means little-endian)
 242      */
 243     public AudioFormat(float sampleRate, int sampleSizeInBits,
 244                        int channels, boolean signed, boolean bigEndian) {
 245 
 246         this((signed == true ? Encoding.PCM_SIGNED : Encoding.PCM_UNSIGNED),
 247              sampleRate,
 248              sampleSizeInBits,
 249              channels,
 250              (channels == AudioSystem.NOT_SPECIFIED || sampleSizeInBits == AudioSystem.NOT_SPECIFIED)?
 251              AudioSystem.NOT_SPECIFIED:
 252              ((sampleSizeInBits + 7) / 8) * channels,
 253              sampleRate,
 254              bigEndian);
 255     }
 256 
 257     /**
 258      * Obtains the type of encoding for sounds in this format.
 259      *
 260      * @return the encoding type
 261      * @see Encoding#PCM_SIGNED
 262      * @see Encoding#PCM_UNSIGNED
 263      * @see Encoding#ULAW
 264      * @see Encoding#ALAW
 265      */
 266     public Encoding getEncoding() {
 267 
 268         return encoding;
 269     }
 270 
 271     /**
 272      * Obtains the sample rate.
 273      * For compressed formats, the return value is the sample rate of the uncompressed
 274      * audio data.
 275      * When this AudioFormat is used for queries (e.g. {@link
 276      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
 277      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
 278      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample rate of
 279      * <code>AudioSystem.NOT_SPECIFIED</code> means that any sample rate is
 280      * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
 281      * the sample rate is not defined for this audio format.
 282      * @return the number of samples per second,
 283      * or <code>AudioSystem.NOT_SPECIFIED</code>
 284      *
 285      * @see #getFrameRate()
 286      * @see AudioSystem#NOT_SPECIFIED
 287      */
 288     public float getSampleRate() {
 289 
 290         return sampleRate;
 291     }
 292 
 293     /**
 294      * Obtains the size of a sample.
 295      * For compressed formats, the return value is the sample size of the
 296      * uncompressed audio data.
 297      * When this AudioFormat is used for queries (e.g. {@link
 298      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
 299      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
 300      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a sample size of
 301      * <code>AudioSystem.NOT_SPECIFIED</code> means that any sample size is
 302      * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
 303      * the sample size is not defined for this audio format.
 304      * @return the number of bits in each sample,
 305      * or <code>AudioSystem.NOT_SPECIFIED</code>
 306      *
 307      * @see #getFrameSize()
 308      * @see AudioSystem#NOT_SPECIFIED
 309      */
 310     public int getSampleSizeInBits() {
 311 
 312         return sampleSizeInBits;
 313     }
 314 
 315     /**
 316      * Obtains the number of channels.
 317      * When this AudioFormat is used for queries (e.g. {@link
 318      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
 319      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
 320      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a return value of
 321      * <code>AudioSystem.NOT_SPECIFIED</code> means that any (positive) number of channels is
 322      * acceptable.
 323      * @return The number of channels (1 for mono, 2 for stereo, etc.),
 324      * or <code>AudioSystem.NOT_SPECIFIED</code>
 325      *
 326      * @see AudioSystem#NOT_SPECIFIED
 327      */
 328     public int getChannels() {
 329 
 330         return channels;
 331     }
 332 
 333     /**
 334      * Obtains the frame size in bytes.
 335      * When this AudioFormat is used for queries (e.g. {@link
 336      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
 337      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
 338      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame size of
 339      * <code>AudioSystem.NOT_SPECIFIED</code> means that any frame size is
 340      * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
 341      * the frame size is not defined for this audio format.
 342      * @return the number of bytes per frame,
 343      * or <code>AudioSystem.NOT_SPECIFIED</code>
 344      *
 345      * @see #getSampleSizeInBits()
 346      * @see AudioSystem#NOT_SPECIFIED
 347      */
 348     public int getFrameSize() {
 349 
 350         return frameSize;
 351     }
 352 
 353     /**
 354      * Obtains the frame rate in frames per second.
 355      * When this AudioFormat is used for queries (e.g. {@link
 356      * AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
 357      * AudioSystem.isConversionSupported}) or capabilities (e.g. {@link
 358      * DataLine.Info#getFormats() DataLine.Info.getFormats}), a frame rate of
 359      * <code>AudioSystem.NOT_SPECIFIED</code> means that any frame rate is
 360      * acceptable. <code>AudioSystem.NOT_SPECIFIED</code> is also returned when
 361      * the frame rate is not defined for this audio format.
 362      * @return the number of frames per second,
 363      * or <code>AudioSystem.NOT_SPECIFIED</code>
 364      *
 365      * @see #getSampleRate()
 366      * @see AudioSystem#NOT_SPECIFIED
 367      */
 368     public float getFrameRate() {
 369 
 370         return frameRate;
 371     }
 372 
 373 
 374     /**
 375      * Indicates whether the audio data is stored in big-endian or little-endian
 376      * byte order.  If the sample size is not more than one byte, the return value is
 377      * irrelevant.
 378      * @return <code>true</code> if the data is stored in big-endian byte order,
 379      * <code>false</code> if little-endian
 380      */
 381     public boolean isBigEndian() {
 382 
 383         return bigEndian;
 384     }
 385 
 386 
 387     /**
 388      * Obtain an unmodifiable map of properties.
 389      * The concept of properties is further explained in
 390      * the {@link AudioFileFormat class description}.
 391      *
 392      * @return a <code>Map&lt;String,Object&gt;</code> object containing
 393      *         all properties. If no properties are recognized, an empty map is
 394      *         returned.
 395      *
 396      * @see #getProperty(String)
 397      * @since 1.5
 398      */
 399     public Map<String,Object> properties() {
 400         Map<String,Object> ret;
 401         if (properties == null) {
 402             ret = new HashMap<String,Object>(0);
 403         } else {
 404             ret = (Map<String,Object>) (properties.clone());
 405         }
 406         return (Map<String,Object>) Collections.unmodifiableMap(ret);
 407     }
 408 
 409 
 410     /**
 411      * Obtain the property value specified by the key.
 412      * The concept of properties is further explained in
 413      * the {@link AudioFileFormat class description}.
 414      *
 415      * <p>If the specified property is not defined for a
 416      * particular file format, this method returns
 417      * <code>null</code>.
 418      *
 419      * @param key the key of the desired property
 420      * @return the value of the property with the specified key,
 421      *         or <code>null</code> if the property does not exist.
 422      *
 423      * @see #properties()
 424      * @since 1.5
 425      */
 426     public Object getProperty(String key) {
 427         if (properties == null) {
 428             return null;
 429         }
 430         return properties.get(key);
 431     }
 432 
 433 
 434     /**
 435      * Indicates whether this format matches the one specified.
 436      * To match, two formats must have the same encoding,
 437      * and consistent values of the number of channels, sample rate, sample size,
 438      * frame rate, and frame size.
 439      * The values of the property are consistent if they are equal
 440      * or the specified format has the property value
 441      * {@code AudioSystem.NOT_SPECIFIED}.
 442      * The byte order (big-endian or little-endian) must be the same
 443      * if the sample size is greater than one byte.
 444      *
 445      * @param format format to test for match
 446      * @return {@code true} if this format matches the one specified,
 447      *         {@code false} otherwise.
 448      */
 449     public boolean matches(AudioFormat format) {
 450         if (format.getEncoding().equals(getEncoding())
 451                 && (format.getChannels() == AudioSystem.NOT_SPECIFIED
 452                     || format.getChannels() == getChannels())
 453                 && (format.getSampleRate() == (float)AudioSystem.NOT_SPECIFIED
 454                     || format.getSampleRate() == getSampleRate())
 455                 && (format.getSampleSizeInBits() == AudioSystem.NOT_SPECIFIED
 456                     || format.getSampleSizeInBits() == getSampleSizeInBits())
 457                 && (format.getFrameRate() == (float)AudioSystem.NOT_SPECIFIED
 458                     || format.getFrameRate() == getFrameRate())
 459                 && (format.getFrameSize() == AudioSystem.NOT_SPECIFIED
 460                     || format.getFrameSize() == getFrameSize())
 461                 && (getSampleSizeInBits() <= 8
 462                     || format.isBigEndian() == isBigEndian())) {
 463             return true;
 464         }
 465         return false;
 466     }
 467 
 468 
 469     /**
 470      * Returns a string that describes the format, such as:
 471      * "PCM SIGNED 22050 Hz 16 bit mono big-endian".  The contents of the string
 472      * may vary between implementations of Java Sound.
 473      *
 474      * @return a string that describes the format parameters
 475      */
 476     public String toString() {
 477         String sEncoding = "";
 478         if (getEncoding() != null) {
 479             sEncoding = getEncoding().toString() + " ";
 480         }
 481 
 482         String sSampleRate;
 483         if (getSampleRate() == (float) AudioSystem.NOT_SPECIFIED) {
 484             sSampleRate = "unknown sample rate, ";
 485         } else {
 486             sSampleRate = "" + getSampleRate() + " Hz, ";
 487         }
 488 
 489         String sSampleSizeInBits;
 490         if (getSampleSizeInBits() == (float) AudioSystem.NOT_SPECIFIED) {
 491             sSampleSizeInBits = "unknown bits per sample, ";
 492         } else {
 493             sSampleSizeInBits = "" + getSampleSizeInBits() + " bit, ";
 494         }
 495 
 496         String sChannels;
 497         if (getChannels() == 1) {
 498             sChannels = "mono, ";
 499         } else
 500             if (getChannels() == 2) {
 501                 sChannels = "stereo, ";
 502             } else {
 503                 if (getChannels() == AudioSystem.NOT_SPECIFIED) {
 504                     sChannels = " unknown number of channels, ";
 505                 } else {
 506                     sChannels = ""+getChannels()+" channels, ";
 507                 }
 508             }
 509 
 510         String sFrameSize;
 511         if (getFrameSize() == (float) AudioSystem.NOT_SPECIFIED) {
 512             sFrameSize = "unknown frame size, ";
 513         } else {
 514             sFrameSize = "" + getFrameSize()+ " bytes/frame, ";
 515         }
 516 
 517         String sFrameRate = "";
 518         if (Math.abs(getSampleRate() - getFrameRate()) > 0.00001) {
 519             if (getFrameRate() == (float) AudioSystem.NOT_SPECIFIED) {
 520                 sFrameRate = "unknown frame rate, ";
 521             } else {
 522                 sFrameRate = getFrameRate() + " frames/second, ";
 523             }
 524         }
 525 
 526         String sEndian = "";
 527         if ((getEncoding().equals(Encoding.PCM_SIGNED)
 528              || getEncoding().equals(Encoding.PCM_UNSIGNED))
 529             && ((getSampleSizeInBits() > 8)
 530                 || (getSampleSizeInBits() == AudioSystem.NOT_SPECIFIED))) {
 531             if (isBigEndian()) {
 532                 sEndian = "big-endian";
 533             } else {
 534                 sEndian = "little-endian";
 535             }
 536         }
 537 
 538         return sEncoding
 539             + sSampleRate
 540             + sSampleSizeInBits
 541             + sChannels
 542             + sFrameSize
 543             + sFrameRate
 544             + sEndian;
 545 
 546     }
 547 
 548     /**
 549      * The <code>Encoding</code> class  names the  specific type of data representation
 550      * used for an audio stream.   The encoding includes aspects of the
 551      * sound format other than the number of channels, sample rate, sample size,
 552      * frame rate, frame size, and byte order.
 553      * <p>
 554      * One ubiquitous type of audio encoding is pulse-code modulation (PCM),
 555      * which is simply a linear (proportional) representation of the sound
 556      * waveform.  With PCM, the number stored in each sample is proportional
 557      * to the instantaneous amplitude of the sound pressure at that point in
 558      * time.  The numbers may be signed or unsigned integers or floats.
 559      * Besides PCM, other encodings include mu-law and a-law, which are nonlinear
 560      * mappings of the sound amplitude that are often used for recording speech.
 561      * <p>
 562      * You can use a predefined encoding by referring to one of the static
 563      * objects created by this class, such as PCM_SIGNED or
 564      * PCM_UNSIGNED.  Service providers can create new encodings, such as
 565      * compressed audio formats, and make
 566      * these available through the <code>{@link AudioSystem}</code> class.
 567      * <p>
 568      * The <code>Encoding</code> class is static, so that all
 569      * <code>AudioFormat</code> objects that have the same encoding will refer
 570      * to the same object (rather than different instances of the same class).
 571      * This allows matches to be made by checking that two format's encodings
 572      * are equal.
 573      *
 574      * @see AudioFormat
 575      * @see javax.sound.sampled.spi.FormatConversionProvider
 576      *
 577      * @author Kara Kytle
 578      * @since 1.3
 579      */
 580     public static class Encoding {
 581 
 582 
 583         // ENCODING DEFINES
 584 
 585         /**
 586          * Specifies signed, linear PCM data.
 587          */
 588         public static final Encoding PCM_SIGNED = new Encoding("PCM_SIGNED");
 589 
 590         /**
 591          * Specifies unsigned, linear PCM data.
 592          */
 593         public static final Encoding PCM_UNSIGNED = new Encoding("PCM_UNSIGNED");
 594 
 595         /**
 596          * Specifies floating-point PCM data.
 597          *
 598          * @since 1.7
 599          */
 600         public static final Encoding PCM_FLOAT = new Encoding("PCM_FLOAT");
 601 
 602         /**
 603          * Specifies u-law encoded data.
 604          */
 605         public static final Encoding ULAW = new Encoding("ULAW");
 606 
 607         /**
 608          * Specifies a-law encoded data.
 609          */
 610         public static final Encoding ALAW = new Encoding("ALAW");
 611 
 612 
 613         // INSTANCE VARIABLES
 614 
 615         /**
 616          * Encoding name.
 617          */
 618         private String name;
 619 
 620 
 621         // CONSTRUCTOR
 622 
 623         /**
 624          * Constructs a new encoding.
 625          * @param name  the name of the new type of encoding
 626          */
 627         public Encoding(String name) {
 628             this.name = name;
 629         }
 630 
 631 
 632         // METHODS
 633 
 634         /**
 635          * Finalizes the equals method
 636          */
 637         public final boolean equals(Object obj) {
 638             if (toString() == null) {
 639                 return (obj != null) && (obj.toString() == null);
 640             }
 641             if (obj instanceof Encoding) {
 642                 return toString().equals(obj.toString());
 643             }
 644             return false;
 645         }
 646 
 647         /**
 648          * Finalizes the hashCode method
 649          */
 650         public final int hashCode() {
 651             if (toString() == null) {
 652                 return 0;
 653             }
 654             return toString().hashCode();
 655         }
 656 
 657         /**
 658          * Provides the <code>String</code> representation of the encoding.  This <code>String</code> is
 659          * the same name that was passed to the constructor.  For the predefined encodings, the name
 660          * is similar to the encoding's variable (field) name.  For example, <code>PCM_SIGNED.toString()</code> returns
 661          * the name "pcm_signed".
 662          *
 663          * @return the encoding name
 664          */
 665         public final String toString() {
 666             return name;
 667         }
 668 
 669     } // class Encoding
 670 }