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

   1 /*
   2  * Copyright (c) 1999, 2020, 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      * Returns a string representation of the audio file format.
 266      *
 267      * @return a string representation of the audio file format
 268      */
 269     @Override
 270     public String toString() {
 271         String str = "Unknown file format";


 272         //$$fb2002-11-01: fix for 4672864: AudioFileFormat.toString() throws unexpected NullPointerException
 273         if (getType() != null) {
 274             str = getType() + " (." + getType().getExtension() + ") file";


 275         }
 276         if (getByteLength() != AudioSystem.NOT_SPECIFIED) {
 277             str += ", byte length: " + getByteLength();

 278         }
 279         str += ", data format: " + getFormat();
 280         if (getFrameLength() != AudioSystem.NOT_SPECIFIED) {
 281             str += ", frame length: " + getFrameLength();


 282         }
 283         return str;

 284     }
 285 
 286     /**
 287      * An instance of the {@code Type} class represents one of the standard
 288      * types of audio file. Static instances are provided for the common types.
 289      */
 290     public static class Type {
 291 
 292         // FILE FORMAT TYPE DEFINES
 293 
 294         /**
 295          * Specifies a WAVE file.
 296          */
 297         public static final Type WAVE = new Type("WAVE", "wav");
 298 
 299         /**
 300          * Specifies an AU file.
 301          */
 302         public static final Type AU = new Type("AU", "au");
 303 
 304         /**
 305          * Specifies an AIFF file.
 306          */
 307         public static final Type AIFF = new Type("AIFF", "aif");
 308 
 309         /**
 310          * Specifies an AIFF-C file.
 311          */
 312         public static final Type AIFC = new Type("AIFF-C", "aifc");
 313 
 314         /**
 315          * Specifies a SND file.
 316          */
 317         public static final Type SND = new Type("SND", "snd");
 318 
 319         /**
 320          * File type name.
 321          */
 322         private final String name;
 323 
 324         /**
 325          * File type extension.
 326          */
 327         private final String extension;
 328 
 329         /**
 330          * Constructs a file type.
 331          *
 332          * @param  name the string that names the file type
 333          * @param  extension the string that commonly marks the file type
 334          *         without leading dot
 335          */
 336         public Type(final String name, final String extension) {
 337             this.name = name;
 338             this.extension = extension;
 339         }
 340 
 341         /**
 342          * Indicates whether the specified object is equal to this file type,
 343          * returning {@code true} if the objects are equal.
 344          *
 345          * @param  obj the reference object with which to compare
 346          * @return {@code true} if the specified object is equal to this file
 347          *         type; {@code false} otherwise
 348          */
 349         @Override
 350         public final boolean equals(final Object obj) {
 351             if (this == obj) {
 352                 return true;
 353             }
 354             if (!(obj instanceof Type)) {
 355                 return false;
 356             }
 357             return Objects.equals(name, ((Type) obj).name);
 358         }
 359 
 360         /**
 361          * Returns a hash code value for this file type.
 362          *
 363          * @return a hash code value for this file type
 364          */
 365         @Override
 366         public final int hashCode() {
 367             return name != null ? name.hashCode() : 0;
 368         }
 369 
 370         /**
 371          * Returns type's name as the string representation of the file type.

 372          *
 373          * @return a string representation of the file type
 374          */
 375         @Override
 376         public final String toString() {
 377             return name;
 378         }
 379 
 380         /**
 381          * Obtains the common file name extension for this file type.
 382          *
 383          * @return file type extension
 384          */
 385         public String getExtension() {
 386             return extension;
 387         }
 388     }
 389 }
--- EOF ---