/*
 
* 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.io.File;
import java.io.OutputStream;
import java.io.IOException;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;


/**
 
* An instance of the <code>AudioFileFormat</code> class describes
 
* an audio file, including the file type, the file's length in bytes,
 
* the length in sample frames of the audio data contained in the file,
 
* and the format of the audio data.
 
* <p>
 
* The <code>{@link AudioSystem}</code> class includes methods for determining the format
 
* of an audio file, obtaining an audio input stream from an audio file, and
 
* writing an audio file from an audio input stream.
 
*
 
* <p>An <code>AudioFileFormat</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 informational
 
* meta data (like a author, copyright, or file duration).
 
* Properties are optional information, and file reader and file
 
* writer implementations are not required to provide or
 
* recognize properties.
 
*
 
* <p>The following table lists some common properties that should
 
* be used in implementations:
 
*
 
* <table border=1>
 
*
  
<caption>Audio File Format Properties</caption>
 
*
  
<tr>
 
*
   
<th>Property key</th>
 
*
   
<th>Value type</th>
 
*
   
<th>Description</th>
 
*
  
</tr>
 
*
  
<tr>
 
*
   
<td>&quot;duration&quot;</td>
 
*
   
<td>{@link java.lang.Long Long}</td>
 
*
   
<td>playback duration of the file in microseconds</td>
 
*
  
</tr>
 
*
  
<tr>
 
*
   
<td>&quot;author&quot;</td>
 
*
   
<td>{@link java.lang.String String}</td>
 
*
   
<td>name of the author of this file</td>
 
*
  
</tr>
 
*
  
<tr>
 
*
   
<td>&quot;title&quot;</td>
 
*
   
<td>{@link java.lang.String String}</td>
 
*
   
<td>title of this file</td>
 
*
  
</tr>
 
*
  
<tr>
 
*
   
<td>&quot;copyright&quot;</td>
 
*
   
<td>{@link java.lang.String String}</td>
 
*
   
<td>copyright message</td>
 
*
  
</tr>
 
*
  
<tr>
 
*
   
<td>&quot;date&quot;</td>
 
*
   
<td>{@link java.util.Date Date}</td>
 
*
   
<td>date of the recording or release</td>
 
*
  
</tr>
 
*
  
<tr>
 
*
   
<td>&quot;comment&quot;</td>
 
*
   
<td>{@link java.lang.String String}</td>
 
*
   
<td>an arbitrary text</td>
 
*
  
</tr>
 
* </table>
 
*
 
*
 
* @author David Rivas
 
* @author Kara Kytle
 
* @author Florian Bomers
 
* @see AudioInputStream
 
* @since 1.3
 
*/

public class AudioFileFormat {


    
// INSTANCE VARIABLES


    
/**
     
* File type.
     
*/
    
private Type type;

    
/**
     
* File length in bytes
     
*/
    
private int byteLength;

    
/**
     
* Format of the audio data contained in the file.
     
*/
    
private AudioFormat format;

    
/**
     
* Audio data length in sample frames
     
*/
    
private int frameLength;


    
/** The set of properties */
    
private HashMap<String, Object> properties;


    
/**
     
* Constructs an audio file format object.
     
* This protected constructor is intended for use by providers of file-reading
     
* services when returning information about an audio file or about supported audio file
     
* formats.
     
* @param type the type of the audio file
     
* @param byteLength the length of the file in bytes, or <code>AudioSystem.NOT_SPECIFIED</code>
     
* @param format the format of the audio data contained in the file
     
* @param frameLength the audio data length in sample frames, or <code>AudioSystem.NOT_SPECIFIED</code>
     
*
     
* @see #getType
     
*/

    
protected AudioFileFormat(Type type, int byteLength, AudioFormat format, int frameLength) {

        
this.type = type;
        
this.byteLength = byteLength;
        
this.format = format;
        
this.frameLength = frameLength;
        
this.properties = null;
    
}


    
/**
     
* Constructs an audio file format object.
     
* This public constructor may be used by applications to describe the
     
* properties of a requested audio file.
     
* @param type the type of the audio file
     
* @param format the format of the audio data contained in the file
     
* @param frameLength the audio data length in sample frames, or <code>AudioSystem.NOT_SPECIFIED</code>
     
*/

    
public AudioFileFormat(Type type, AudioFormat format, int frameLength) {


        
this(type,AudioSystem.NOT_SPECIFIED,format,frameLength);
    
}

    
/**
     
* Construct an audio file format object with a set of
     
* defined properties.
     
* This public constructor may be used by applications to describe the
     
* properties of a requested audio file. The properties map
     
* will be copied to prevent any changes to it.
     
*
     
* @param type
        
the type of the audio file
     
* @param format
      
the format of the audio data contained in the file
     
* @param frameLength the audio data length in sample frames, or
     
*
                    
<code>AudioSystem.NOT_SPECIFIED</code>
     
* @param properties
  
a <code>Map&lt;String,Object&gt;</code> object
     
*
        
with properties
     
*
     
* @since 1.5
     
*/

    
public AudioFileFormat(Type type, AudioFormat format,
                           
int frameLength, Map<String, Object> properties) {
        
this(type,AudioSystem.NOT_SPECIFIED,format,frameLength);
        
this.properties = new HashMap<String, Object>(properties);
    
}


    
/**
     
* Obtains the audio file type, such as <code>WAVE</code> or <code>AU</code>.
     
* @return the audio file type
     
*
     
* @see Type#WAVE
     
* @see Type#AU
     
* @see Type#AIFF
     
* @see Type#AIFC
     
* @see Type#SND
     
*/

    
public Type getType() {
        
return type;
    
}

    
/**
     
* Obtains the size in bytes of the entire audio file (not just its audio data).
     
* @return the audio file length in bytes
     
* @see AudioSystem#NOT_SPECIFIED
     
*/

    
public int getByteLength() {
        
return byteLength;
    
}

    
/**
     
* Obtains the format of the audio data contained in the audio file.
     
* @return the audio data format
     
*/

    
public AudioFormat getFormat() {
        
return format;
    
}

    
/**
     
* Obtains the length of the audio data contained in the file, expressed in sample frames.
     
* @return the number of sample frames of audio data in the file
     
* @see AudioSystem#NOT_SPECIFIED
     
*/

    
public int getFrameLength() {
        
return frameLength;
    
}

    
/**
     
* 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.
     
*
     
*
 

     
* @since 1.5
     
*/

    
public Object getProperty(String key) {
        
if (properties == null) {
            
return null;
        
}
        
return properties.get(key);
    
}


    
/**
     
* Provides a string representation of the file format.
     
* @return the file format as a string
     
*/

    
public String toString() {

        
StringBuffer buf = new StringBuffer();

        
//$$fb2002-11-01: fix for 4672864: AudioFileFormat.toString() throws unexpected NullPointerException
        
if (type != null) {
            
buf.append(type.toString() + " (." + type.getExtension() + ") file");
        
} else {
            
buf.append("unknown file format");
        
}

        
if (byteLength != AudioSystem.NOT_SPECIFIED) {
            
buf.append(", byte length: " + byteLength);
        
}

        
buf.append(", data format: " + format);

        
if (frameLength != AudioSystem.NOT_SPECIFIED) {
            
buf.append(", frame length: " + frameLength);
        
}

        
return new String(buf);
    
}


    
/**
     
* An instance of the <code>Type</code> class represents one of the
     
* standard types of audio file.
  
Static instances are provided for the
     
* common types.
     
*/

    
public static class Type {

        
// FILE FORMAT TYPE DEFINES

        
/**
         
* Specifies a WAVE file.
         
*/
        
public static final Type WAVE = new Type("WAVE", "wav");

        
/**
         
* Specifies an AU file.
         
*/
        
public static final Type AU = new Type("AU", "au");

        
/**
         
* Specifies an AIFF file.
         
*/
        
public static final Type AIFF = new Type("AIFF", "aif");

        
/**
         
* Specifies an AIFF-C file.
         
*/
        
public static final Type AIFC = new Type("AIFF-C", "aifc");

        
/**
         
* Specifies a SND file.
         
*/
        
public static final Type SND = new Type("SND", "snd");


        
// INSTANCE VARIABLES

        
/**
         
* File type name.
         
*/
        
private final String name;

        
/**
         
* File type extension.
         
*/
        
private final String extension;


        
// CONSTRUCTOR

        
/**
         
* Constructs a file type.
         
* @param name the string that names the file type
         
* @param extension the string that commonly marks the file type
         
* without leading dot.
         
*/

        
public Type(String name, String extension) {

            
this.name = name;
            
this.extension = extension;
        
}


        
// METHODS

        
/**
         
* Finalizes the equals method
         
*/
        
public final boolean equals(Object obj) {
            
if (toString() == null) {
                
return (obj != null) && (obj.toString() == null);
            
}
            
if (obj instanceof Type) {
                
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 file type's name as the <code>String</code> representation
         
* of the file type.
         
* @return the file type's name
         
*/

        
public final String toString() {
            
return name;
        
}

        
/**
         
* Obtains the common file name extension for this file type.
         
* @return file type extension
         
*/

        
public String getExtension() {
            
return extension;
        
}

    
} // class Type

} // class AudioFileFormat