1. /*
  2. * @(#)MidiFileReader.java 1.13 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.sound.midi.spi;
  8. import java.io.File;
  9. import java.io.InputStream;
  10. import java.io.IOException;
  11. import java.net.URL;
  12. import javax.sound.midi.MidiFileFormat;
  13. import javax.sound.midi.Sequence;
  14. import javax.sound.midi.InvalidMidiDataException;
  15. /**
  16. * A <code>MidiFileReader</code> supplies MIDI file-reading services. Classes implementing this
  17. * interface can parse the format information from one or more types of
  18. * MIDI file, and can produce a <code>Sequence</code> object from files of these types.
  19. *
  20. * @author Kara Kytle
  21. * @version 1.13 03/12/19
  22. * @since 1.3
  23. */
  24. public abstract class MidiFileReader {
  25. /**
  26. * Obtains the MIDI file format of the input stream provided. The stream must
  27. * point to valid MIDI file data. In general, MIDI file readers may
  28. * need to read some data from the stream before determining whether they
  29. * support it. These parsers must
  30. * be able to mark the stream, read enough data to determine whether they
  31. * support the stream, and, if not, reset the stream's read pointer to its original
  32. * position. If the input stream does not support this, this method may fail
  33. * with an <code>IOException</code>.
  34. * @param stream the input stream from which file format information should be
  35. * extracted
  36. * @return a <code>MidiFileFormat</code> object describing the MIDI file format
  37. * @throws InvalidMidiDataException if the stream does not point to valid MIDI
  38. * file data recognized by the system
  39. * @throws IOException if an I/O exception occurs
  40. * @see InputStream#markSupported
  41. * @see InputStream#mark
  42. */
  43. public abstract MidiFileFormat getMidiFileFormat(InputStream stream) throws InvalidMidiDataException, IOException;
  44. /**
  45. * Obtains the MIDI file format of the URL provided. The URL must
  46. * point to valid MIDI file data.
  47. * @param url the URL from which file format information should be
  48. * extracted
  49. * @return a <code>MidiFileFormat</code> object describing the MIDI file format
  50. * @throws InvalidMidiDataException if the URL does not point to valid MIDI
  51. * file data recognized by the system
  52. * @throws IOException if an I/O exception occurs
  53. */
  54. public abstract MidiFileFormat getMidiFileFormat(URL url) throws InvalidMidiDataException, IOException;
  55. /**
  56. * Obtains the MIDI file format of the <code>File</code> provided.
  57. * The <code>File</code> must point to valid MIDI file data.
  58. * @param file the <code>File</code> from which file format information should be
  59. * extracted
  60. * @return a <code>MidiFileFormat</code> object describing the MIDI file format
  61. * @throws InvalidMidiDataException if the <code>File</code> does not point to valid MIDI
  62. * file data recognized by the system
  63. * @throws IOException if an I/O exception occurs
  64. */
  65. public abstract MidiFileFormat getMidiFileFormat(File file) throws InvalidMidiDataException, IOException;
  66. /**
  67. * Obtains a MIDI sequence from the input stream provided. The stream must
  68. * point to valid MIDI file data. In general, MIDI file readers may
  69. * need to read some data from the stream before determining whether they
  70. * support it. These parsers must
  71. * be able to mark the stream, read enough data to determine whether they
  72. * support the stream, and, if not, reset the stream's read pointer to its original
  73. * position. If the input stream does not support this, this method may fail
  74. * with an IOException.
  75. * @param stream the input stream from which the <code>Sequence</code> should be
  76. * constructed
  77. * @return a <code>Sequence</code> object based on the MIDI file data contained
  78. * in the input stream.
  79. * @throws InvalidMidiDataException if the stream does not point to valid MIDI
  80. * file data recognized by the system
  81. * @throws IOException if an I/O exception occurs
  82. * @see InputStream#markSupported
  83. * @see InputStream#mark
  84. */
  85. public abstract Sequence getSequence(InputStream stream) throws InvalidMidiDataException, IOException;
  86. /**
  87. * Obtains a MIDI sequence from the URL provided. The URL must
  88. * point to valid MIDI file data.
  89. * @param url the URL for which the <code>Sequence</code> should be
  90. * constructed
  91. * @return a <code>Sequence</code> object based on the MIDI file data pointed
  92. * to by the URL
  93. * @throws InvalidMidiDataException if the URL does not point to valid MIDI
  94. * file data recognized by the system
  95. * @throws IOException if an I/O exception occurs
  96. */
  97. public abstract Sequence getSequence(URL url) throws InvalidMidiDataException, IOException;
  98. /**
  99. * Obtains a MIDI sequence from the <code>File</code> provided. The <code>File</code> must
  100. * point to valid MIDI file data.
  101. * @param file the <code>File</code> from which the <code>Sequence</code> should be
  102. * constructed
  103. * @return a <code>Sequence</code> object based on the MIDI file data pointed
  104. * to by the <code>File</code>
  105. * @throws InvalidMidiDataException if the <code>File</code> does not point to valid MIDI
  106. * file data recognized by the system
  107. * @throws IOException if an I/O exception occurs
  108. */
  109. public abstract Sequence getSequence(File file) throws InvalidMidiDataException, IOException;
  110. }