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.midi.spi; 27 28 import java.io.File; 29 import java.io.IOException; 30 import java.io.InputStream; 31 import java.net.URL; 32 33 import javax.sound.midi.InvalidMidiDataException; 34 import javax.sound.midi.MidiFileFormat; 35 import javax.sound.midi.Sequence; 36 37 /** 38 * A {@code MidiFileReader} supplies MIDI file-reading services. Classes 39 * implementing this interface can parse the format information from one or more 40 * types of MIDI file, and can produce a {@link Sequence} object from files of 41 * these types. 42 * 43 * @author Kara Kytle 44 * @since 1.3 45 */ 46 public abstract class MidiFileReader { 47 48 /** 49 * Obtains the MIDI file format of the input stream provided. The stream 50 * must point to valid MIDI file data. In general, MIDI file readers may 51 * need to read some data from the stream before determining whether they 52 * support it. These parsers must be able to mark the stream, read enough 53 * data to determine whether they support the stream, and, if not, reset the 54 * stream's read pointer to its original position. If the input stream does 55 * not support this, this method may fail with an {@code IOException}. 56 * 57 * @param stream the input stream from which file format information should 58 * be extracted 59 * @return a {@code MidiFileFormat} object describing the MIDI file format 60 * @throws InvalidMidiDataException if the stream does not point to valid 61 * MIDI file data recognized by the system 62 * @throws IOException if an I/O exception occurs 63 * @throws NullPointerException if {@code stream} is {@code null} 64 * @see InputStream#markSupported 65 * @see InputStream#mark 66 */ 67 public abstract MidiFileFormat getMidiFileFormat(InputStream stream) 68 throws InvalidMidiDataException, IOException; 69 70 /** 71 * Obtains the MIDI file format of the {@code URL} provided. The {@code URL} 72 * must point to valid MIDI file data. 73 * 74 * @param url the {@code URL} from which file format information should be 75 * extracted 76 * @return a {@code MidiFileFormat} object describing the MIDI file format 77 * @throws InvalidMidiDataException if the {@code URL} does not point to 78 * valid MIDI file data recognized by the system 79 * @throws IOException if an I/O exception occurs 80 * @throws NullPointerException if {@code url} is {@code null} 81 */ 82 public abstract MidiFileFormat getMidiFileFormat(URL url) 83 throws InvalidMidiDataException, IOException; 84 85 /** 86 * Obtains the MIDI file format of the {@code File} provided. The 87 * {@code File} must point to valid MIDI file data. 88 * 89 * @param file the {@code File} from which file format information should 90 * be extracted 91 * @return a {@code MidiFileFormat} object describing the MIDI file format 92 * @throws InvalidMidiDataException if the {@code File} does not point to 93 * valid MIDI file data recognized by the system 94 * @throws IOException if an I/O exception occurs 95 * @throws NullPointerException if {@code file} is {@code null} 96 */ 97 public abstract MidiFileFormat getMidiFileFormat(File file) 98 throws InvalidMidiDataException, IOException; 99 100 /** 101 * Obtains a MIDI sequence from the input stream provided. The stream must 102 * point to valid MIDI file data. In general, MIDI file readers may need to 103 * read some data from the stream before determining whether they support 104 * it. These parsers must be able to mark the stream, read enough data to 105 * determine whether they support the stream, and, if not, reset the 106 * stream's read pointer to its original position. If the input stream does 107 * not support this, this method may fail with an {@code IOException}. 108 * 109 * @param stream the input stream from which the {@code Sequence} should be 110 * constructed 111 * @return a {@code Sequence} object based on the MIDI file data contained 112 * in the input stream 113 * @throws InvalidMidiDataException if the stream does not point to valid 114 * MIDI file data recognized by the system 115 * @throws IOException if an I/O exception occurs 116 * @throws NullPointerException if {@code stream} is {@code null} 117 * @see InputStream#markSupported 118 * @see InputStream#mark 119 */ 120 public abstract Sequence getSequence(InputStream stream) 121 throws InvalidMidiDataException, IOException; 122 123 /** 124 * Obtains a MIDI sequence from the {@code URL} provided. The {@code URL} 125 * must point to valid MIDI file data. 126 * 127 * @param url the {@code URL} for which the {@code Sequence} should be 128 * constructed 129 * @return a {@code Sequence} object based on the MIDI file data pointed to 130 * by the {@code URL} 131 * @throws InvalidMidiDataException if the {@code URL} does not point to 132 * valid MIDI file data recognized by the system 133 * @throws IOException if an I/O exception occurs 134 * @throws NullPointerException if {@code url} is {@code null} 135 */ 136 public abstract Sequence getSequence(URL url) 137 throws InvalidMidiDataException, IOException; 138 139 /** 140 * Obtains a MIDI sequence from the {@code File} provided. The {@code File} 141 * must point to valid MIDI file data. 142 * 143 * @param file the {@code File} from which the {@code Sequence} should be 144 * constructed 145 * @return a {@code Sequence} object based on the MIDI file data pointed to 146 * by the {@code File} 147 * @throws InvalidMidiDataException if the {@code File} does not point to 148 * valid MIDI file data recognized by the system 149 * @throws IOException if an I/O exception occurs 150 * @throws NullPointerException if {@code file} is {@code null} 151 */ 152 public abstract Sequence getSequence(File file) 153 throws InvalidMidiDataException, IOException; 154 }