001/* Audio file format
002   Copyright (C) 2005 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.sound.sampled;
040
041import java.util.Collections;
042import java.util.HashMap;
043import java.util.Map;
044
045/**
046 * This describes an audio file, including information about its length,
047 * the format of the audio data, and other things.
048 * @since 1.3
049 */
050public class AudioFileFormat
051{
052  /**
053   * An instance of this type describes a standard audio file format.
054   * @since 1.3
055   */
056  public static class Type
057  {
058    // This is kind of goofy since there are multiple extensions for
059    // some of these.
060
061    /** The AIFC format.  */
062    public static final Type AIFC = new Type("AIFC", "aifc");
063
064    /** The AIFF format.  */
065    public static final Type AIFF = new Type("AIFF", "aiff");
066
067    /** The AU format.  */
068    public static final Type AU = new Type("AU", "au");
069
070    /** The SND format.  */
071    public static final Type SND = new Type("SND", "snd");
072
073    /** The WAVE format.  */
074    public static final Type WAVE = new Type ("WAVE", "wav");
075
076    private String name;
077    private String extension;
078
079    /**
080     * Create a new Type given its name and file extension.
081     * The file extension does not include the ".".
082     * @param name the type's name
083     * @param extension the file extension
084     */
085    public Type(String name, String extension)
086    {
087      this.name = name;
088      this.extension = extension;
089    }
090
091    public final boolean equals(Object o)
092    {
093      if (! (o instanceof Type))
094        return false;
095      Type other = (Type) o;
096      return name.equals(other.name) && extension.equals(other.extension);
097    }
098
099    public final int hashCode()
100    {
101      return name.hashCode() + extension.hashCode();
102    }
103
104    /**
105     * Return the extension associated with this Type.
106     */
107    public String getExtension()
108    {
109      return extension;
110    }
111
112    /**
113     * Return the name of this Type.
114     */
115    public final String toString()
116    {
117      return name;
118    }
119  }
120
121  private int byteLength;
122  private AudioFormat format;
123  private Type type;
124  private int frameLength;
125  private Map<String, Object> properties;
126
127  /**
128   * Create a new AudioFileFormat given the type, the format, and the
129   * frame length.  The new object will have an unspecified byte length,
130   * and an empty properties map.
131   * @param type the type
132   * @param fmt the format
133   * @param frameLen the frame length
134   */
135  public AudioFileFormat(Type type, AudioFormat fmt, int frameLen)
136  {
137    this.byteLength = AudioSystem.NOT_SPECIFIED;
138    this.format = fmt;
139    this.type = type;
140    this.frameLength = frameLen;
141    this.properties = Collections.<String, Object> emptyMap();
142  }
143
144  /**
145   * Create a new AudioFileFormat given the type, the format, the
146   * frame length, and some properties.  The new object will have an
147   * unspecified byte length.  A copy of the properties argument will
148   * be made, so changes to the map passed in will not affect the
149   * new AudioFileFormat.
150   * @param type the type
151   * @param fmt the format
152   * @param frameLen the frame length
153   * @param properties the properties
154   */
155  public AudioFileFormat(Type type, AudioFormat fmt, int frameLen,
156                         Map<String, Object> properties)
157  {
158    this.byteLength = AudioSystem.NOT_SPECIFIED;
159    this.format = fmt;
160    this.type = type;
161    this.frameLength = frameLen;
162    this.properties = Collections.unmodifiableMap(new HashMap<String, Object>(properties));
163  }
164
165  /**
166   * Create a new AudioFileFormat given the type, the byte length, the format,
167   * and the frame length.  The new object will have an empty properties map.
168   * @param type the type
169   * @param byteLen the byte length
170   * @param fmt the format
171   * @param frameLen the frame length
172   */
173  protected AudioFileFormat(Type type, int byteLen, AudioFormat fmt,
174                            int frameLen)
175  {
176    this.byteLength = byteLen;
177    this.format = fmt;
178    this.type = type;
179    this.frameLength = frameLen;
180    this.properties = Collections.<String, Object> emptyMap();
181  }
182
183  /**
184   * Return the byte length of this file format.
185   */
186  public int getByteLength()
187  {
188    return byteLength;
189  }
190
191  /**
192   * Return the AudioFormat associated with this file format.
193   */
194  public AudioFormat getFormat()
195  {
196    return format;
197  }
198
199  /**
200   * Return the frame length of this file format.
201   */
202  public int getFrameLength()
203  {
204    return frameLength;
205  }
206
207  /**
208   * Return the value of a property defined in this format.
209   * @param key the property name
210   * @return the value of the property, or null if the property is not defined
211   */
212  public Object getProperty(String key)
213  {
214    return properties.get(key);
215  }
216
217  /**
218   * Return the Type associated with this file format.
219   */
220  public Type getType()
221  {
222    return type;
223  }
224
225  /**
226   * Return the properties associated with this format, as a Map.
227   * The returned Map is unmodifiable.
228   */
229  public Map<String, Object> properties()
230  {
231    return properties;
232  }
233
234  /**
235   * Return a description of this AudioFileFormat.
236   */
237  public String toString()
238  {
239    return ("byteLength=" + byteLength + "; format=" + format
240            + "; type=" + type + "; frameLength=" + frameLength);
241  }
242}