/*
 * Copyright (c) 1999, 2014, 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.midi.spi;

import java.io.File;
import java.io.InputStream;
import java.io.IOException;
import java.net.URL;

import javax.sound.midi.MidiFileFormat;
import javax.sound.midi.Sequence;
import javax.sound.midi.InvalidMidiDataException;

A MidiFileReader supplies MIDI file-reading services. Classes implementing this interface can parse the format information from one or more types of MIDI file, and can produce a Sequence object from files of these types. 
Author:
Kara Kytle
Since:
1.3/**
 * A {@code MidiFileReader} supplies MIDI file-reading services. Classes
 * implementing this interface can parse the format information from one or more
 * types of MIDI file, and can produce a {@link Sequence} object from files of
 * these types.
 *
 * @author Kara Kytle
 * @since 1.3
 */
public abstract class MidiFileReader {

    
Obtains the MIDI file format of the input stream provided. The stream must point to valid MIDI file data. In general, MIDI file readers may need to read some data from the stream before determining whether they support it. These parsers must be able to mark the stream, read enough data to determine whether they support the stream, and, if not, reset the stream's read pointer to its original position. If the input stream does not support this, this method may fail with an IOException. 
Params:
stream – the input stream from which file format information
        should be extracted
Throws:
InvalidMidiDataException – if the stream does not point to valid
        MIDI file data recognized by the system
IOException – if an I/O exception occurs
See Also:
InputStream.markSupported
InputStream.mark
Returns:
a MidiFileFormat object describing the MIDI file format/**
     * Obtains the MIDI file format of the input stream provided. The stream
     * must point to valid MIDI file data. In general, MIDI file readers may
     * need to read some data from the stream before determining whether they
     * support it. These parsers must be able to mark the stream, read enough
     * data to determine whether they support the stream, and, if not, reset the
     * stream's read pointer to its original position. If the input stream does
     * not support this, this method may fail with an {@code IOException}.
     *
     * @param  stream the input stream from which file format information
     *         should be extracted
     * @return a {@code MidiFileFormat} object describing the MIDI file format
     * @throws InvalidMidiDataException if the stream does not point to valid
     *         MIDI file data recognized by the system
     * @throws IOException if an I/O exception occurs
     * @see InputStream#markSupported
     * @see InputStream#mark
     */
    public abstract MidiFileFormat getMidiFileFormat(InputStream stream)
            throws InvalidMidiDataException, IOException;

    
Obtains the MIDI file format of the URL provided. The URL must point to
valid MIDI file data.
Params:
url – the URL from which file format information should be
        extracted
Throws:
InvalidMidiDataException – if the URL does not point to valid MIDI
        file data recognized by the system
IOException – if an I/O exception occurs
Returns:
a MidiFileFormat object describing the MIDI file format/**
     * Obtains the MIDI file format of the URL provided. The URL must point to
     * valid MIDI file data.
     *
     * @param  url the URL from which file format information should be
     *         extracted
     * @return a {@code MidiFileFormat} object describing the MIDI file format
     * @throws InvalidMidiDataException if the URL does not point to valid MIDI
     *         file data recognized by the system
     * @throws IOException if an I/O exception occurs
     */
    public abstract MidiFileFormat getMidiFileFormat(URL url)
            throws InvalidMidiDataException, IOException;

    
Obtains the MIDI file format of the File provided. The File must point to valid MIDI file data. 
Params:
file – the File from which file format information should be extracted
Throws:
InvalidMidiDataException – if the File does not point to valid MIDI file data recognized by the system
IOException – if an I/O exception occurs
Returns:
a MidiFileFormat object describing the MIDI file format/**
     * Obtains the MIDI file format of the {@code File} provided. The
     * {@code File} must point to valid MIDI file data.
     *
     * @param  file the {@code File} from which file format information should
     *         be extracted
     * @return a {@code MidiFileFormat} object describing the MIDI file format
     * @throws InvalidMidiDataException if the {@code File} does not point to
     *         valid MIDI file data recognized by the system
     * @throws IOException if an I/O exception occurs
     */
    public abstract MidiFileFormat getMidiFileFormat(File file)
            throws InvalidMidiDataException, IOException;

    
Obtains a MIDI sequence from the input stream provided. The stream must
point to valid MIDI file data. In general, MIDI file readers may need to
read some data from the stream before determining whether they support
it. These parsers must be able to mark the stream, read enough data to
determine whether they support the stream, and, if not, reset the
stream's read pointer to its original position. If the input stream does
not support this, this method may fail with an IOException.
Params:
stream – the input stream from which the Sequence should be constructed
Throws:
InvalidMidiDataException – if the stream does not point to valid
        MIDI file data recognized by the system
IOException – if an I/O exception occurs
See Also:
InputStream.markSupported
InputStream.mark
Returns:
a Sequence object based on the MIDI file data contained in the input stream./**
     * Obtains a MIDI sequence from the input stream provided. The stream must
     * point to valid MIDI file data. In general, MIDI file readers may need to
     * read some data from the stream before determining whether they support
     * it. These parsers must be able to mark the stream, read enough data to
     * determine whether they support the stream, and, if not, reset the
     * stream's read pointer to its original position. If the input stream does
     * not support this, this method may fail with an IOException.
     *
     * @param  stream the input stream from which the {@code Sequence} should
     *         be constructed
     * @return a {@code Sequence} object based on the MIDI file data contained
     *         in the input stream.
     * @throws InvalidMidiDataException if the stream does not point to valid
     *         MIDI file data recognized by the system
     * @throws IOException if an I/O exception occurs
     * @see InputStream#markSupported
     * @see InputStream#mark
     */
    public abstract Sequence getSequence(InputStream stream)
            throws InvalidMidiDataException, IOException;

    
Obtains a MIDI sequence from the URL provided. The URL must point to
valid MIDI file data.
Params:
url – the URL for which the Sequence should be constructed
Throws:
InvalidMidiDataException – if the URL does not point to valid MIDI
        file data recognized by the system
IOException – if an I/O exception occurs
Returns:
a Sequence object based on the MIDI file data pointed to by the URL/**
     * Obtains a MIDI sequence from the URL provided. The URL must point to
     * valid MIDI file data.
     *
     * @param  url the URL for which the {@code Sequence} should be constructed
     * @return a {@code Sequence} object based on the MIDI file data pointed to
     *         by the URL
     * @throws InvalidMidiDataException if the URL does not point to valid MIDI
     *         file data recognized by the system
     * @throws IOException if an I/O exception occurs
     */
    public abstract Sequence getSequence(URL url)
            throws InvalidMidiDataException, IOException;

    
Obtains a MIDI sequence from the File provided. The File must point to valid MIDI file data. 
Params:
file – the File from which the Sequence should be constructed
Throws:
InvalidMidiDataException – if the File does not point to valid MIDI file data recognized by the system
IOException – if an I/O exception occurs
Returns:
a Sequence object based on the MIDI file data pointed to by the File/**
     * Obtains a MIDI sequence from the {@code File} provided. The {@code File}
     * must point to valid MIDI file data.
     *
     * @param  file the {@code File} from which the {@code Sequence} should be
     *         constructed
     * @return a {@code Sequence} object based on the MIDI file data pointed to
     *         by the {@code File}
     * @throws InvalidMidiDataException if the {@code File} does not point to
     *         valid MIDI file data recognized by the system
     * @throws IOException if an I/O exception occurs
     */
    public abstract Sequence getSequence(File file)
            throws InvalidMidiDataException, IOException;
}