< prev index next >
src/java.desktop/share/classes/javax/sound/midi/MidiSystem.java
Print this page
@@ -76,36 +76,31 @@
*
* <table class="striped">
* <caption>MIDI System Property Keys</caption>
* <thead>
* <tr>
- * <th>Property Key</th>
- * <th>Interface</th>
- * <th>Affected Method</th>
- * </tr>
+ * <th>Property Key
+ * <th>Interface
+ * <th>Affected Method
* </thead>
* <tbody>
* <tr>
- * <td>{@code javax.sound.midi.Receiver}</td>
- * <td>{@link Receiver}</td>
- * <td>{@link #getReceiver}</td>
- * </tr>
+ * <td>{@code javax.sound.midi.Receiver}
+ * <td>{@link Receiver}
+ * <td>{@link #getReceiver}
* <tr>
- * <td>{@code javax.sound.midi.Sequencer}</td>
- * <td>{@link Sequencer}</td>
- * <td>{@link #getSequencer}</td>
- * </tr>
+ * <td>{@code javax.sound.midi.Sequencer}
+ * <td>{@link Sequencer}
+ * <td>{@link #getSequencer}
* <tr>
- * <td>{@code javax.sound.midi.Synthesizer}</td>
- * <td>{@link Synthesizer}</td>
- * <td>{@link #getSynthesizer}</td>
- * </tr>
+ * <td>{@code javax.sound.midi.Synthesizer}
+ * <td>{@link Synthesizer}
+ * <td>{@link #getSynthesizer}
* <tr>
- * <td>{@code javax.sound.midi.Transmitter}</td>
- * <td>{@link Transmitter}</td>
- * <td>{@link #getTransmitter}</td>
- * </tr>
+ * <td>{@code javax.sound.midi.Transmitter}
+ * <td>{@link Transmitter}
+ * <td>{@link #getTransmitter}
* </tbody>
* </table>
*
* The property value consists of the provider class name and the device name,
* separated by the hash mark ("#"). The provider class name is the
@@ -565,12 +560,11 @@
* @param stream the input stream from which file format information should
* be extracted
* @return an {@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 while accessing the
- * stream
+ * @throws IOException if an I/O exception occurs while accessing the stream
* @throws NullPointerException if {@code stream} is {@code null}
* @see #getMidiFileFormat(URL)
* @see #getMidiFileFormat(File)
* @see InputStream#markSupported
* @see InputStream#mark
@@ -1025,25 +1019,46 @@
}
return bytesWritten;
}
// HELPER METHODS
+
+ /**
+ * Obtains the list of MidiDeviceProviders installed on the system.
+ *
+ * @return the list of MidiDeviceProviders installed on the system
+ */
@SuppressWarnings("unchecked")
private static List<MidiDeviceProvider> getMidiDeviceProviders() {
return (List<MidiDeviceProvider>) getProviders(MidiDeviceProvider.class);
}
+ /**
+ * Obtains the list of SoundbankReaders installed on the system.
+ *
+ * @return the list of SoundbankReaders installed on the system
+ */
@SuppressWarnings("unchecked")
private static List<SoundbankReader> getSoundbankReaders() {
return (List<SoundbankReader>) getProviders(SoundbankReader.class);
}
+ /**
+ * Obtains the list of MidiFileWriters installed on the system.
+ *
+ * @return the list of MidiFileWriters installed on the system
+ */
@SuppressWarnings("unchecked")
private static List<MidiFileWriter> getMidiFileWriters() {
return (List<MidiFileWriter>) getProviders(MidiFileWriter.class);
}
+ /**
+ * Obtains the list of MidiFileReaders installed on the system.
+ *
+ * @return the list of MidiFileReaders installed on the system
+ */
@SuppressWarnings("unchecked")
private static List<MidiFileReader> getMidiFileReaders() {
return (List<MidiFileReader>) getProviders(MidiFileReader.class);
}
@@ -1054,10 +1069,11 @@
* instead throws a {@code MidiUnavailableException}, with the catched
* exception chained.
*
* @param deviceClass The requested device type, one of Synthesizer.class,
* Sequencer.class, Receiver.class or Transmitter.class
+ * @return default MidiDevice of the specified type
* @throws MidiUnavailableException on failure
*/
private static MidiDevice getDefaultDeviceWrapper(Class<?> deviceClass)
throws MidiUnavailableException{
try {
@@ -1072,10 +1088,11 @@
/**
* Attempts to locate and return a default MidiDevice of the specified type.
*
* @param deviceClass The requested device type, one of Synthesizer.class,
* Sequencer.class, Receiver.class or Transmitter.class
+ * @return default MidiDevice of the specified type.
* @throws IllegalArgumentException on failure
*/
private static MidiDevice getDefaultDevice(Class<?> deviceClass) {
List<MidiDeviceProvider> providers = getMidiDeviceProviders();
String providerClassName = JDK13Services.getDefaultProviderClassName(deviceClass);
@@ -1096,22 +1113,26 @@
return device;
}
}
}
- /* Provider class not specified or cannot be found, or
- provider class specified, and no appropriate device available or
- provider class and instance specified and instance cannot be found or is not appropriate */
+ /*
+ * Provider class not specified or cannot be found, or provider class
+ * specified, and no appropriate device available or provider class and
+ * instance specified and instance cannot be found or is not appropriate
+ */
if (instanceName != null) {
device = getNamedDevice(instanceName, providers, deviceClass);
if (device != null) {
return device;
}
}
- /* No default are specified, or if something is specified, everything
- failed. */
+ /*
+ * No default are specified, or if something is specified, everything
+ * failed.
+ */
device = getFirstDevice(providers, deviceClass);
if (device != null) {
return device;
}
throw new IllegalArgumentException("Requested device not installed");
@@ -1174,10 +1195,21 @@
*
* @param deviceName The name of the MidiDevice to be returned
* @param provider The MidiDeviceProvider to check for MidiDevices
* @param deviceClass The requested device type, one of Synthesizer.class,
* Sequencer.class, Receiver.class or Transmitter.class
+ * @param allowSynthesizer if true, Synthesizers are considered
+ * appropriate. Otherwise only pure MidiDevices are considered
+ * appropriate (unless allowSequencer is true). This flag only has
+ * an effect for deviceClass Receiver and Transmitter. For other
+ * device classes (Sequencer and Synthesizer), this flag has no
+ * effect.
+ * @param allowSequencer if true, Sequencers are considered appropriate.
+ * Otherwise only pure MidiDevices are considered appropriate
+ * (unless allowSynthesizer is true). This flag only has an effect
+ * for deviceClass Receiver and Transmitter. For other device
+ * classes (Sequencer and Synthesizer), this flag has no effect.
* @return A MidiDevice matching the requirements, or null if none is found
*/
private static MidiDevice getNamedDevice(String deviceName,
MidiDeviceProvider provider,
Class<?> deviceClass,
@@ -1235,10 +1267,21 @@
* @param deviceName The name of the MidiDevice to be returned
* @param providers The List of MidiDeviceProviders to check for
* MidiDevices
* @param deviceClass The requested device type, one of Synthesizer.class,
* Sequencer.class, Receiver.class or Transmitter.class
+ * @param allowSynthesizer if true, Synthesizers are considered
+ * appropriate. Otherwise only pure MidiDevices are considered
+ * appropriate (unless allowSequencer is true). This flag only has
+ * an effect for deviceClass Receiver and Transmitter. For other
+ * device classes (Sequencer and Synthesizer), this flag has no
+ * effect.
+ * @param allowSequencer if true, Sequencers are considered appropriate.
+ * Otherwise only pure MidiDevices are considered appropriate
+ * (unless allowSynthesizer is true). This flag only has an effect
+ * for deviceClass Receiver and Transmitter. For other device
+ * classes (Sequencer and Synthesizer), this flag has no effect.
* @return A Mixer matching the requirements, or null if none is found
*/
private static MidiDevice getNamedDevice(String deviceName,
List<MidiDeviceProvider> providers,
Class<?> deviceClass,
@@ -1292,10 +1335,21 @@
* From a given MidiDeviceProvider, return the first appropriate device.
*
* @param provider The MidiDeviceProvider to check for MidiDevices
* @param deviceClass The requested device type, one of Synthesizer.class,
* Sequencer.class, Receiver.class or Transmitter.class
+ * @param allowSynthesizer if true, Synthesizers are considered
+ * appropriate. Otherwise only pure MidiDevices are considered
+ * appropriate (unless allowSequencer is true). This flag only has
+ * an effect for deviceClass Receiver and Transmitter. For other
+ * device classes (Sequencer and Synthesizer), this flag has no
+ * effect.
+ * @param allowSequencer if true, Sequencers are considered appropriate.
+ * Otherwise only pure MidiDevices are considered appropriate
+ * (unless allowSynthesizer is true). This flag only has an effect
+ * for deviceClass Receiver and Transmitter. For other device
+ * classes (Sequencer and Synthesizer), this flag has no effect.
* @return A MidiDevice is considered appropriate, or null if no appropriate
* device is found
*/
private static MidiDevice getFirstDevice(MidiDeviceProvider provider,
Class<?> deviceClass,
@@ -1349,10 +1403,21 @@
* MidiDevice.
*
* @param providers The List of MidiDeviceProviders to search
* @param deviceClass The requested device type, one of Synthesizer.class,
* Sequencer.class, Receiver.class or Transmitter.class
+ * @param allowSynthesizer if true, Synthesizers are considered
+ * appropriate. Otherwise only pure MidiDevices are considered
+ * appropriate (unless allowSequencer is true). This flag only has
+ * an effect for deviceClass Receiver and Transmitter. For other
+ * device classes (Sequencer and Synthesizer), this flag has no
+ * effect.
+ * @param allowSequencer if true, Sequencers are considered appropriate.
+ * Otherwise only pure MidiDevices are considered appropriate
+ * (unless allowSynthesizer is true). This flag only has an effect
+ * for deviceClass Receiver and Transmitter. For other device
+ * classes (Sequencer and Synthesizer), this flag has no effect.
* @return A MidiDevice that is considered appropriate, or null if none is
* found
*/
private static MidiDevice getFirstDevice(List<MidiDeviceProvider> providers,
Class<?> deviceClass,
@@ -1377,10 +1442,12 @@
* considered appropriate if it implements neither Synthesizer nor
* Transmitter, and if it can provide at least one Receiver or Transmitter,
* respectively.
*
* @param device the MidiDevice to test
+ * @param deviceClass The requested device type, one of Synthesizer.class,
+ * Sequencer.class, Receiver.class or Transmitter.class
* @param allowSynthesizer if true, Synthesizers are considered
* appropriate. Otherwise only pure MidiDevices are considered
* appropriate (unless allowSequencer is true). This flag only has
* an effect for deviceClass Receiver and Transmitter. For other
* device classes (Sequencer and Synthesizer), this flag has no
@@ -1427,10 +1494,15 @@
/**
* Obtains the set of services currently installed on the system using the
* SPI mechanism in 1.3.
*
+ * @param providerClass The type of providers requested. This should be one
+ * of AudioFileReader.class, AudioFileWriter.class,
+ * FormatConversionProvider.class, MixerProvider.class,
+ * MidiDeviceProvider.class, MidiFileReader.class,
+ * MidiFileWriter.class or SoundbankReader.class.
* @return a List of instances of providers for the requested service. If no
* providers are available, a List of length 0 will be returned.
*/
private static List<?> getProviders(Class<?> providerClass) {
return JDK13Services.getProviders(providerClass);
< prev index next >