rev 57600 : 8236980: toString() cleanup in JavaSound
Reviewed-by: XXX

   1 /*
   2  * Copyright (c) 1999, 2017, 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 import java.util.Objects;
  32 
  33 /**
  34  * An instance of the {@code AudioFileFormat} class describes an audio file,
  35  * including the file type, the file's length in bytes, the length in sample
  36  * frames of the audio data contained in the file, and the format of the audio
  37  * data.
  38  * <p>
  39  * The {@link AudioSystem} class includes methods for determining the format of
  40  * an audio file, obtaining an audio input stream from an audio file, and
  41  * writing an audio file from an audio input stream.
  42  * <p>
  43  * An {@code AudioFileFormat} object can include a set of properties. A property
  44  * is a pair of key and value: the key is of type {@code String}, the associated
  45  * property value is an arbitrary object. Properties specify additional
  46  * informational meta data (like a author, copyright, or file duration).
  47  * Properties are optional information, and file reader and file writer
  48  * implementations are not required to provide or recognize properties.
  49  * <p>
  50  * The following table lists some common properties that should be used in
  51  * implementations:
  52  *
  53  * <table class="striped">
  54  * <caption>Audio File Format Properties</caption>
  55  * <thead>
  56  *   <tr>
  57  *     <th scope="col">Property key
  58  *     <th scope="col">Value type
  59  *     <th scope="col">Description
  60  * </thead>
  61  * <tbody>
  62  *   <tr>
  63  *     <th scope="row">"duration"
  64  *     <td>{@link Long Long}
  65  *     <td>playback duration of the file in microseconds
  66  *   <tr>
  67  *     <th scope="row">"author"
  68  *     <td>{@link String String}
  69  *     <td>name of the author of this file
  70  *   <tr>
  71  *     <th scope="row">"title"
  72  *     <td>{@link String String}
  73  *     <td>title of this file
  74  *   <tr>
  75  *     <th scope="row">"copyright"
  76  *     <td>{@link String String}
  77  *     <td>copyright message
  78  *   <tr>
  79  *     <th scope="row">"date"
  80  *     <td>{@link java.util.Date Date}
  81  *     <td>date of the recording or release
  82  *   <tr>
  83  *     <th scope="row">"comment"
  84  *     <td>{@link String String}
  85  *     <td>an arbitrary text
  86  * </tbody>
  87  * </table>
  88  *
  89  * @author David Rivas
  90  * @author Kara Kytle
  91  * @author Florian Bomers
  92  * @see AudioInputStream
  93  * @since 1.3
  94  */
  95 public class AudioFileFormat {
  96 
  97     /**
  98      * File type.
  99      */
 100     private final Type type;
 101 
 102     /**
 103      * File length in bytes.
 104      */
 105     private final int byteLength;
 106 
 107     /**
 108      * Format of the audio data contained in the file.
 109      */
 110     private final AudioFormat format;
 111 
 112     /**
 113      * Audio data length in sample frames.
 114      */
 115     private final int frameLength;
 116 
 117     /**
 118      * The set of properties.
 119      */
 120     private HashMap<String, Object> properties;
 121 
 122     /**
 123      * Constructs an audio file format object. This protected constructor is
 124      * intended for use by providers of file-reading services when returning
 125      * information about an audio file or about supported audio file formats.
 126      *
 127      * @param  type the type of the audio file
 128      * @param  byteLength the length of the file in bytes, or
 129      *         {@code AudioSystem.NOT_SPECIFIED}
 130      * @param  format the format of the audio data contained in the file
 131      * @param  frameLength the audio data length in sample frames, or
 132      *         {@code AudioSystem.NOT_SPECIFIED}
 133      * @see #getType
 134      */
 135     protected AudioFileFormat(Type type, int byteLength, AudioFormat format, int frameLength) {
 136 
 137         this.type = type;
 138         this.byteLength = byteLength;
 139         this.format = format;
 140         this.frameLength = frameLength;
 141         this.properties = null;
 142     }
 143 
 144     /**
 145      * Constructs an audio file format object. This public constructor may be
 146      * used by applications to describe the properties of a requested audio
 147      * file.
 148      *
 149      * @param  type the type of the audio file
 150      * @param  format the format of the audio data contained in the file
 151      * @param  frameLength the audio data length in sample frames, or
 152      *         {@code AudioSystem.NOT_SPECIFIED}
 153      */
 154     public AudioFileFormat(Type type, AudioFormat format, int frameLength) {
 155 
 156 
 157         this(type,AudioSystem.NOT_SPECIFIED,format,frameLength);
 158     }
 159 
 160     /**
 161      * Construct an audio file format object with a set of defined properties.
 162      * This public constructor may be used by applications to describe the
 163      * properties of a requested audio file. The properties map will be copied
 164      * to prevent any changes to it.
 165      *
 166      * @param  type the type of the audio file
 167      * @param  format the format of the audio data contained in the file
 168      * @param  frameLength the audio data length in sample frames, or
 169      *         {@code AudioSystem.NOT_SPECIFIED}
 170      * @param  properties a {@code Map<String, Object>} object with properties
 171      * @since 1.5
 172      */
 173     public AudioFileFormat(Type type, AudioFormat format,
 174                            int frameLength, Map<String, Object> properties) {
 175         this(type,AudioSystem.NOT_SPECIFIED,format,frameLength);
 176         this.properties = new HashMap<>(properties);
 177     }
 178 
 179     /**
 180      * Obtains the audio file type, such as {@code WAVE} or {@code AU}.
 181      *
 182      * @return the audio file type
 183      * @see Type#WAVE
 184      * @see Type#AU
 185      * @see Type#AIFF
 186      * @see Type#AIFC
 187      * @see Type#SND
 188      */
 189     public Type getType() {
 190         return type;
 191     }
 192 
 193     /**
 194      * Obtains the size in bytes of the entire audio file (not just its audio
 195      * data).
 196      *
 197      * @return the audio file length in bytes
 198      * @see AudioSystem#NOT_SPECIFIED
 199      */
 200     public int getByteLength() {
 201         return byteLength;
 202     }
 203 
 204     /**
 205      * Obtains the format of the audio data contained in the audio file.
 206      *
 207      * @return the audio data format
 208      */
 209     public AudioFormat getFormat() {
 210         return format;
 211     }
 212 
 213     /**
 214      * Obtains the length of the audio data contained in the file, expressed in
 215      * sample frames.
 216      *
 217      * @return the number of sample frames of audio data in the file
 218      * @see AudioSystem#NOT_SPECIFIED
 219      */
 220     public int getFrameLength() {
 221         return frameLength;
 222     }
 223 
 224     /**
 225      * Obtain an unmodifiable map of properties. The concept of properties is
 226      * further explained in the {@link AudioFileFormat class description}.
 227      *
 228      * @return a {@code Map<String, Object>} object containing all properties.
 229      *         If no properties are recognized, an empty map is returned.
 230      * @see #getProperty(String)
 231      * @since 1.5
 232      */
 233     @SuppressWarnings("unchecked") // Cast of result of clone
 234     public Map<String, Object> properties() {
 235         Map<String,Object> ret;
 236         if (properties == null) {
 237             ret = new HashMap<>(0);
 238         } else {
 239             ret = (Map<String,Object>) (properties.clone());
 240         }
 241         return Collections.unmodifiableMap(ret);
 242     }
 243 
 244     /**
 245      * Obtain the property value specified by the key. The concept of properties
 246      * is further explained in the {@link AudioFileFormat class description}.
 247      * <p>
 248      * If the specified property is not defined for a particular file format,
 249      * this method returns {@code null}.
 250      *
 251      * @param  key the key of the desired property
 252      * @return the value of the property with the specified key, or {@code null}
 253      *         if the property does not exist
 254      * @see #properties()
 255      * @since 1.5
 256      */
 257     public Object getProperty(String key) {
 258         if (properties == null) {
 259             return null;
 260         }
 261         return properties.get(key);
 262     }
 263 
 264     /**
 265      * Provides a string representation of the file format.
 266      *
 267      * @return the file format as a string
 268      */
 269     @Override
 270     public String toString() {
 271 
 272         StringBuffer buf = new StringBuffer();
 273 
 274         //$$fb2002-11-01: fix for 4672864: AudioFileFormat.toString() throws unexpected NullPointerException
 275         if (type != null) {
 276             buf.append(type.toString() + " (." + type.getExtension() + ") file");
 277         } else {
 278             buf.append("unknown file format");
 279         }
 280 
 281         if (byteLength != AudioSystem.NOT_SPECIFIED) {
 282             buf.append(", byte length: " + byteLength);
 283         }
 284 
 285         buf.append(", data format: " + format);
 286 
 287         if (frameLength != AudioSystem.NOT_SPECIFIED) {
 288             buf.append(", frame length: " + frameLength);
 289         }
 290 
 291         return new String(buf);
 292     }
 293 
 294     /**
 295      * An instance of the {@code Type} class represents one of the standard
 296      * types of audio file. Static instances are provided for the common types.
 297      */
 298     public static class Type {
 299 
 300         // FILE FORMAT TYPE DEFINES
 301 
 302         /**
 303          * Specifies a WAVE file.
 304          */
 305         public static final Type WAVE = new Type("WAVE", "wav");
 306 
 307         /**
 308          * Specifies an AU file.
 309          */
 310         public static final Type AU = new Type("AU", "au");
 311 
 312         /**
 313          * Specifies an AIFF file.
 314          */
 315         public static final Type AIFF = new Type("AIFF", "aif");
 316 
 317         /**
 318          * Specifies an AIFF-C file.
 319          */
 320         public static final Type AIFC = new Type("AIFF-C", "aifc");
 321 
 322         /**
 323          * Specifies a SND file.
 324          */
 325         public static final Type SND = new Type("SND", "snd");
 326 
 327         /**
 328          * File type name.
 329          */
 330         private final String name;
 331 
 332         /**
 333          * File type extension.
 334          */
 335         private final String extension;
 336 
 337         /**
 338          * Constructs a file type.
 339          *
 340          * @param  name the string that names the file type
 341          * @param  extension the string that commonly marks the file type
 342          *         without leading dot
 343          */
 344         public Type(final String name, final String extension) {
 345             this.name = name;
 346             this.extension = extension;
 347         }
 348 
 349         /**
 350          * Indicates whether the specified object is equal to this file type,
 351          * returning {@code true} if the objects are equal.
 352          *
 353          * @param  obj the reference object with which to compare
 354          * @return {@code true} if the specified object is equal to this file
 355          *         type; {@code false} otherwise
 356          */
 357         @Override
 358         public final boolean equals(final Object obj) {
 359             if (this == obj) {
 360                 return true;
 361             }
 362             if (!(obj instanceof Type)) {
 363                 return false;
 364             }
 365             return Objects.equals(name, ((Type) obj).name);
 366         }
 367 
 368         /**
 369          * Returns a hash code value for this file type.
 370          *
 371          * @return a hash code value for this file type
 372          */
 373         @Override
 374         public final int hashCode() {
 375             return name != null ? name.hashCode() : 0;
 376         }
 377 
 378         /**
 379          * Provides the file type's name as the {@code String} representation of
 380          * the file type.
 381          *
 382          * @return the file type's name
 383          */
 384         @Override
 385         public final String toString() {
 386             return name;
 387         }
 388 
 389         /**
 390          * Obtains the common file name extension for this file type.
 391          *
 392          * @return file type extension
 393          */
 394         public String getExtension() {
 395             return extension;
 396         }
 397     }
 398 }
--- EOF ---