1. /*
  2. * @(#)AudioFileReader.java 1.15 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.sampled.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.sampled.AudioFileFormat;
  13. import javax.sound.sampled.AudioInputStream;
  14. import javax.sound.sampled.UnsupportedAudioFileException;
  15. /**
  16. * Provider for audio file reading services. Classes providing concrete
  17. * implementations can parse the format information from one or more types of
  18. * audio file, and can produce audio input streams from files of these types.
  19. *
  20. * @author Kara Kytle
  21. * @version 1.15 03/12/19
  22. * @since 1.3
  23. */
  24. public abstract class AudioFileReader {
  25. /**
  26. * Obtains the audio file format of the input stream provided. The stream must
  27. * point to valid audio file data. In general, audio 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 an <code>AudioFileFormat</code> object describing the audio file format
  37. * @throws UnsupportedAudioFileException if the stream does not point to valid audio
  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 AudioFileFormat getAudioFileFormat(InputStream stream) throws UnsupportedAudioFileException, IOException;
  44. /**
  45. * Obtains the audio file format of the URL provided. The URL must
  46. * point to valid audio file data.
  47. * @param url the URL from which file format information should be
  48. * extracted
  49. * @return an <code>AudioFileFormat</code> object describing the audio file format
  50. * @throws UnsupportedAudioFileException if the URL does not point to valid audio
  51. * file data recognized by the system
  52. * @throws IOException if an I/O exception occurs
  53. */
  54. public abstract AudioFileFormat getAudioFileFormat(URL url) throws UnsupportedAudioFileException, IOException;
  55. /**
  56. * Obtains the audio file format of the <code>File</code> provided. The <code>File</code> must
  57. * point to valid audio file data.
  58. * @param file the <code>File</code> from which file format information should be
  59. * extracted
  60. * @return an <code>AudioFileFormat</code> object describing the audio file format
  61. * @throws UnsupportedAudioFileException if the <code>File</code> does not point to valid audio
  62. * file data recognized by the system
  63. * @throws IOException if an I/O exception occurs
  64. */
  65. public abstract AudioFileFormat getAudioFileFormat(File file) throws UnsupportedAudioFileException, IOException;
  66. /**
  67. * Obtains an audio input stream from the input stream provided. The stream must
  68. * point to valid audio file data. In general, audio 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 <code>IOException</code>.
  75. * @param stream the input stream from which the <code>AudioInputStream</code> should be
  76. * constructed
  77. * @return an <code>AudioInputStream</code> object based on the audio file data contained
  78. * in the input stream.
  79. * @throws UnsupportedAudioFileException if the stream does not point to valid audio
  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 AudioInputStream getAudioInputStream(InputStream stream) throws UnsupportedAudioFileException, IOException;
  86. /**
  87. * Obtains an audio input stream from the URL provided. The URL must
  88. * point to valid audio file data.
  89. * @param url the URL for which the <code>AudioInputStream</code> should be
  90. * constructed
  91. * @return an <code>AudioInputStream</code> object based on the audio file data pointed
  92. * to by the URL
  93. * @throws UnsupportedAudioFileException if the URL does not point to valid audio
  94. * file data recognized by the system
  95. * @throws IOException if an I/O exception occurs
  96. */
  97. public abstract AudioInputStream getAudioInputStream(URL url) throws UnsupportedAudioFileException, IOException;
  98. /**
  99. * Obtains an audio input stream from the <code>File</code> provided. The <code>File</code> must
  100. * point to valid audio file data.
  101. * @param file the <code>File</code> for which the <code>AudioInputStream</code> should be
  102. * constructed
  103. * @return an <code>AudioInputStream</code> object based on the audio file data pointed
  104. * to by the File
  105. * @throws UnsupportedAudioFileException if the <code>File</code> does not point to valid audio
  106. * file data recognized by the system
  107. * @throws IOException if an I/O exception occurs
  108. */
  109. public abstract AudioInputStream getAudioInputStream(File file) throws UnsupportedAudioFileException, IOException;
  110. }