--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/InvalidMidiDataException.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/InvalidMidiDataException.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -39,6 +39,9 @@
*/
public class InvalidMidiDataException extends Exception {
+ /**
+ * Use serialVersionUID from JDK 1.3 for interoperability.
+ */
private static final long serialVersionUID = 2780771756789932067L;
/**
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MetaMessage.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MetaMessage.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -54,8 +54,8 @@
/**
* Status byte for {@code MetaMessage} (0xFF, or 255), which is used in MIDI
- * files. It has the same value as SYSTEM_RESET, which is used in the
- * real-time "MIDI wire" protocol.
+ * files. It has the same value as {@link ShortMessage#SYSTEM_RESET}, which
+ * is used in the real-time "MIDI wire" protocol.
*
* @see MidiMessage#getStatus
*/
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDevice.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDevice.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -64,11 +64,11 @@
* {@code MidiDevice} instance, the following rules apply:
*
* <ul>
- * <li>After an explicit open (either before or after implicit opens), the
- * device will not be closed by implicit closing. The only way to close an
- * explicitly opened device is an explicit close.</li>
- * <li>An explicit close always closes the device, even if it also has been
- * opened implicitly. A subsequent implicit close has no further effect.</li>
+ * <li>After an explicit open (either before or after implicit opens), the
+ * device will not be closed by implicit closing. The only way to close an
+ * explicitly opened device is an explicit close.
+ * <li>An explicit close always closes the device, even if it also has been
+ * opened implicitly. A subsequent implicit close has no further effect.
* </ul>
*
* To detect if a MidiDevice represents a hardware MIDI port, the following
@@ -76,7 +76,7 @@
*
* <pre>{@code
* MidiDevice device = ...;
- * if ( ! (device instanceof Sequencer) && ! (device instanceof Synthesizer)) {
+ * if (!(device instanceof Sequencer) && !(device instanceof Synthesizer)) {
* // we're now sure that device represents a MIDI port
* // ...
* }
@@ -112,7 +112,8 @@
* resources and allow applications to exit cleanly.
* <p>
* Note that some devices, once closed, cannot be reopened. Attempts to
- * reopen such a device will always result in a MidiUnavailableException.
+ * reopen such a device will always result in a
+ * {@code MidiUnavailableException}.
*
* @throws MidiUnavailableException thrown if the device cannot be opened
* due to resource restrictions
@@ -198,7 +199,8 @@
/**
* Returns all currently active, non-closed receivers connected with this
- * MidiDevice. A receiver can be removed from the device by closing it.
+ * {@code MidiDevice}. A receiver can be removed from the device by closing
+ * it.
* <p>
* Usually the returned receivers implement the {@code MidiDeviceReceiver}
* interface.
@@ -231,7 +233,8 @@
/**
* Returns all currently active, non-closed transmitters connected with this
- * MidiDevice. A transmitter can be removed from the device by closing it.
+ * {@code MidiDevice}. A transmitter can be removed from the device by
+ * closing it.
* <p>
* Usually the returned transmitters implement the
* {@code MidiDeviceTransmitter} interface.
@@ -288,12 +291,12 @@
}
/**
- * Reports whether two objects are equal. Returns {@code true} if the
- * objects are identical.
+ * Indicates whether the specified object is equal to this info object,
+ * returning {@code true} if the objects are the same.
*
- * @param obj the reference object with which to compare this object
- * @return {@code true} if this object is the same as the {@code obj}
- * argument; {@code false} otherwise
+ * @param obj the reference object with which to compare
+ * @return {@code true} if the specified object is equal to this info
+ * object; {@code false} otherwise
*/
@Override
public final boolean equals(Object obj) {
@@ -301,7 +304,9 @@
}
/**
- * Finalizes the hashcode method.
+ * Returns a hash code value for this info object.
+ *
+ * @return a hash code value for this info object
*/
@Override
public final int hashCode() {
@@ -353,5 +358,5 @@
public final String toString() {
return name;
}
- } // class Info
+ }
}
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceReceiver.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceReceiver.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2017, 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
@@ -35,9 +35,11 @@
public interface MidiDeviceReceiver extends Receiver {
/**
- * Obtains a MidiDevice object which is an owner of this Receiver.
+ * Obtains a {@code MidiDevice} object which is an owner of this
+ * {@code Receiver}.
*
- * @return a MidiDevice object which is an owner of this Receiver
+ * @return a {@code MidiDevice} object which is an owner of this
+ * {@code Receiver}
*/
MidiDevice getMidiDevice();
}
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceTransmitter.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiDeviceTransmitter.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2017, 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
@@ -35,9 +35,11 @@
public interface MidiDeviceTransmitter extends Transmitter {
/**
- * Obtains a MidiDevice object which is an owner of this Transmitter.
+ * Obtains a {@code MidiDevice} object which is an owner of this
+ * {@code Transmitter}.
*
- * @return a MidiDevice object which is an owner of this Transmitter
+ * @return a {@code MidiDevice} object which is an owner of this
+ * {@code Transmitter}
*/
MidiDevice getMidiDevice();
}
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiFileFormat.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiFileFormat.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -44,37 +44,31 @@
* implementations:
*
* <table border=1>
- <caption>MIDI File Format Properties</caption>
- * <tr>
- * <th>Property key</th>
- * <th>Value type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>"author"</td>
- * <td>{@link java.lang.String String}</td>
- * <td>name of the author of this file</td>
- * </tr>
- * <tr>
- * <td>"title"</td>
- * <td>{@link java.lang.String String}</td>
- * <td>title of this file</td>
- * </tr>
- * <tr>
- * <td>"copyright"</td>
- * <td>{@link java.lang.String String}</td>
- * <td>copyright message</td>
- * </tr>
- * <tr>
- * <td>"date"</td>
- * <td>{@link java.util.Date Date}</td>
- * <td>date of the recording or release</td>
- * </tr>
- * <tr>
- * <td>"comment"</td>
- * <td>{@link java.lang.String String}</td>
- * <td>an arbitrary text</td>
- * </tr>
+ * <caption>MIDI File Format Properties</caption>
+ * <tr>
+ * <th>Property key
+ * <th>Value type
+ * <th>Description
+ * <tr>
+ * <td>"author"
+ * <td>{@link String String}
+ * <td>name of the author of this file
+ * <tr>
+ * <td>"title"
+ * <td>{@link String String}
+ * <td>title of this file
+ * <tr>
+ * <td>"copyright"
+ * <td>{@link String String}
+ * <td>copyright message
+ * <tr>
+ * <td>"date"
+ * <td>{@link java.util.Date Date}
+ * <td>date of the recording or release
+ * <tr>
+ * <td>"comment"
+ * <td>{@link String String}
+ * <td>an arbitrary text
* </table>
*
* @author Kara Kytle
@@ -135,10 +129,10 @@
* @param divisionType the timing division type (PPQ or one of the SMPTE
* types)
* @param resolution the timing resolution
- * @param bytes the length of the MIDI file in bytes, or UNKNOWN_LENGTH if
- * not known
+ * @param bytes the length of the MIDI file in bytes, or
+ * {@link #UNKNOWN_LENGTH} if not known
* @param microseconds the duration of the file in microseconds, or
- * UNKNOWN_LENGTH if not known
+ * {@link #UNKNOWN_LENGTH} if not known
* @see #UNKNOWN_LENGTH
* @see Sequence#PPQ
* @see Sequence#SMPTE_24
@@ -163,10 +157,10 @@
* @param divisionType the timing division type (PPQ or one of the SMPTE
* types)
* @param resolution the timing resolution
- * @param bytes the length of the MIDI file in bytes, or UNKNOWN_LENGTH if
- * not known
+ * @param bytes the length of the MIDI file in bytes, or
+ * {@code UNKNOWN_LENGTH} if not known
* @param microseconds the duration of the file in microseconds, or
- * UNKNOWN_LENGTH if not known
+ * {@code UNKNOWN_LENGTH} if not known
* @param properties a {@code Map<String,Object>} object with properties
* @see #UNKNOWN_LENGTH
* @see Sequence#PPQ
@@ -224,7 +218,8 @@
/**
* Obtains the length of the MIDI file, expressed in 8-bit bytes.
*
- * @return the number of bytes in the file, or UNKNOWN_LENGTH if not known
+ * @return the number of bytes in the file, or {@code UNKNOWN_LENGTH} if not
+ * known
* @see #UNKNOWN_LENGTH
*/
public int getByteLength() {
@@ -234,8 +229,8 @@
/**
* Obtains the length of the MIDI file, expressed in microseconds.
*
- * @return the file's duration in microseconds, or UNKNOWN_LENGTH if not
- * known
+ * @return the file's duration in microseconds, or {@code UNKNOWN_LENGTH} if
+ * not known
* @see Sequence#getMicrosecondLength()
* @see #getByteLength
* @see #UNKNOWN_LENGTH
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java Thu Aug 31 13:00:23 2017 -0700
@@ -38,29 +38,29 @@
* The base {@code MidiMessage} class provides access to three types of
* information about a MIDI message:
* <ul>
- * <li>The messages's status byte</li>
- * <li>The total length of the message in bytes (the status byte plus any data
- * bytes)</li>
- * <li>A byte array containing the complete message</li>
+ * <li>The messages's status byte
+ * <li>The total length of the message in bytes (the status byte plus any data
+ * bytes)
+ * <li>A byte array containing the complete message
* </ul>
*
* {@code MidiMessage} includes methods to get, but not set, these values.
* Setting them is a subclass responsibility.
* <p>
- * <a id="integersVsBytes"></a> The MIDI standard expresses MIDI data in
- * bytes. However, because Java<sup>TM</sup> uses signed bytes, the Java Sound
- * API uses integers instead of bytes when expressing MIDI data. For example,
- * the {@link #getStatus()} method of {@code MidiMessage} returns MIDI status
- * bytes as integers. If you are processing MIDI data that originated outside
- * Java Sound and now is encoded as signed bytes, the bytes can be
- * converted to integers using this conversion:
+ * <a id="integersVsBytes"></a>The MIDI standard expresses MIDI data in bytes.
+ * However, because Java™ uses signed bytes, the Java Sound API uses
+ * integers instead of bytes when expressing MIDI data. For example, the
+ * {@link #getStatus()} method of {@code MidiMessage} returns MIDI status bytes
+ * as integers. If you are processing MIDI data that originated outside Java
+ * Sound and now is encoded as signed bytes, the bytes can be converted to
+ * integers using this conversion:
* <p style="text-align:center">
* {@code int i = (int)(byte & 0xFF)}
* <p>
* If you simply need to pass a known MIDI byte value as a method parameter, it
* can be expressed directly as an integer, using (for example) decimal or
* hexadecimal notation. For instance, to pass the "active sensing" status byte
- * as the first argument to ShortMessage's
+ * as the first argument to {@code ShortMessage}'s
* {@link ShortMessage#setMessage(int) setMessage(int)} method, you can express
* it as 254 or 0xFE.
*
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiSystem.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiSystem.java Thu Aug 31 13:00:23 2017 -0700
@@ -57,7 +57,7 @@
* one or more {@code MidiSystem} methods to learn what devices are installed
* and to obtain the ones needed in that application.
* <p>
- * The class also has methods for reading files, streams, and URLs that contain
+ * The class also has methods for reading files, streams, and URLs that contain
* standard MIDI file data or soundbanks. You can query the {@code MidiSystem}
* for the format of a specified MIDI file.
* <p>
@@ -77,33 +77,28 @@
* <table class="striped">
* <caption>MIDI System Property Keys</caption>
* <thead>
- * <tr>
- * <th>Property Key</th>
- * <th>Interface</th>
- * <th>Affected Method</th>
- * </tr>
+ * <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>
- * <tr>
- * <td>{@code javax.sound.midi.Sequencer}</td>
- * <td>{@link Sequencer}</td>
- * <td>{@link #getSequencer}</td>
- * </tr>
- * <tr>
- * <td>{@code javax.sound.midi.Synthesizer}</td>
- * <td>{@link Synthesizer}</td>
- * <td>{@link #getSynthesizer}</td>
- * </tr>
- * <tr>
- * <td>{@code javax.sound.midi.Transmitter}</td>
- * <td>{@link Transmitter}</td>
- * <td>{@link #getTransmitter}</td>
- * </tr>
+ * <tr>
+ * <td>{@code javax.sound.midi.Receiver}
+ * <td>{@link Receiver}
+ * <td>{@link #getReceiver}
+ * <tr>
+ * <td>{@code javax.sound.midi.Sequencer}
+ * <td>{@link Sequencer}
+ * <td>{@link #getSequencer}
+ * <tr>
+ * <td>{@code javax.sound.midi.Synthesizer}
+ * <td>{@link Synthesizer}
+ * <td>{@link #getSynthesizer}
+ * <tr>
+ * <td>{@code javax.sound.midi.Transmitter}
+ * <td>{@link Transmitter}
+ * <td>{@link #getTransmitter}
* </tbody>
* </table>
*
@@ -567,8 +562,7 @@
* @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)
@@ -1027,21 +1021,42 @@
}
// 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);
@@ -1056,6 +1071,7 @@
*
* @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)
@@ -1074,6 +1090,7 @@
*
* @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) {
@@ -1098,9 +1115,12 @@
}
}
- /* 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) {
@@ -1108,8 +1128,10 @@
}
}
- /* No default are specified, or if something is specified, everything
- failed. */
+ /*
+ * No defaults are specified, or if something is specified, everything
+ * failed
+ */
device = getFirstDevice(providers, deviceClass);
if (device != null) {
return device;
@@ -1176,6 +1198,17 @@
* @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,
@@ -1237,6 +1270,17 @@
* 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,
@@ -1294,6 +1338,17 @@
* @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
*/
@@ -1351,6 +1406,17 @@
* @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
*/
@@ -1379,6 +1445,8 @@
* 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
@@ -1429,10 +1497,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);
+ private static List<?> getProviders(Class<?> providerClass) {
+ return JDK13Services.getProviders(providerClass);
}
}
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiUnavailableException.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiUnavailableException.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -39,6 +39,9 @@
*/
public class MidiUnavailableException extends Exception {
+ /**
+ * Use serialVersionUID from JDK 1.3 for interoperability.
+ */
private static final long serialVersionUID = 6093809578628944323L;
/**
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Receiver.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Receiver.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -64,7 +64,7 @@
* closed, too. For a detailed description of open/close behaviour see the
* class description of {@link MidiDevice MidiDevice}.
*
- * @see javax.sound.midi.MidiSystem#getReceiver
+ * @see MidiSystem#getReceiver
*/
@Override
void close();
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Sequencer.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Sequencer.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -38,22 +38,22 @@
* The {@code Sequencer} interface includes methods for the following basic MIDI
* sequencer operations:
* <ul>
- * <li>obtaining a sequence from MIDI file data</li>
- * <li>starting and stopping playback</li>
- * <li>moving to an arbitrary position in the sequence</li>
- * <li>changing the tempo (speed) of playback</li>
- * <li>synchronizing playback to an internal clock or to received MIDI
- * messages</li>
- * <li>controlling the timing of another device</li>
+ * <li>obtaining a sequence from MIDI file data
+ * <li>starting and stopping playback
+ * <li>moving to an arbitrary position in the sequence
+ * <li>changing the tempo (speed) of playback
+ * <li>synchronizing playback to an internal clock or to received MIDI
+ * messages
+ * <li>controlling the timing of another device
* </ul>
* In addition, the following operations are supported, either directly, or
* indirectly through objects that the {@code Sequencer} has access to:
* <ul>
- * <li>editing the data by adding or deleting individual MIDI events or entire
- * tracks</li>
- * <li>muting or soloing individual tracks in the sequence</li>
- * <li>notifying listener objects about any meta-events or control-change events
- * encountered while playing back the sequence.</li>
+ * <li>editing the data by adding or deleting individual MIDI events or entire
+ * tracks
+ * <li>muting or soloing individual tracks in the sequence
+ * <li>notifying listener objects about any meta-events or control-change
+ * events encountered while playing back the sequence
* </ul>
*
* @author Kara Kytle
@@ -694,12 +694,13 @@
}
/**
- * Determines whether two objects are equal. Returns {@code true} if the
- * objects are identical.
+ * Indicates whether the specified object is equal to this
+ * synchronization mode, returning {@code true} if the objects are the
+ * same.
*
* @param obj the reference object with which to compare
- * @return {@code true} if this object is the same as the {@code obj}
- * argument, {@code false} otherwise
+ * @return {@code true} if the specified object is equal to this
+ * synchronization mode; {@code false} otherwise
*/
@Override
public final boolean equals(Object obj) {
@@ -708,7 +709,9 @@
}
/**
- * Finalizes the hashcode method.
+ * Returns a hash code value for this synchronization mode.
+ *
+ * @return a hash code value for this synchronization mode
*/
@Override
public final int hashCode() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/ShortMessage.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/ShortMessage.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2017, 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
@@ -303,9 +303,8 @@
* @param status the MIDI status byte
* @param data1 the first data byte
* @param data2 the second data byte
- * @throws InvalidMidiDataException if the status byte, or all data
- * bytes belonging to the message, do not specify a valid MIDI
- * message
+ * @throws InvalidMidiDataException if the status byte, or all data bytes
+ * belonging to the message, do not specify a valid MIDI message
* @see #setMessage(int, int, int, int)
* @see #setMessage(int)
*/
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/SoundbankResource.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/SoundbankResource.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -31,24 +31,24 @@
* A {@code SoundbankResource} represents any audio resource stored in a
* {@link Soundbank}. Common soundbank resources include:
* <ul>
- * <li>Instruments. An instrument may be specified in a variety of ways.
- * However, all soundbanks have some mechanism for defining instruments. In
- * doing so, they may reference other resources stored in the soundbank. Each
- * instrument has a {@code Patch} which specifies the MIDI program and bank by
- * which it may be referenced in MIDI messages. Instrument information may be
- * stored in {@link Instrument} objects.</li>
- * <li>Audio samples. A sample typically is a sampled audio waveform which
- * contains a short sound recording whose duration is a fraction of a second, or
- * at most a few seconds. These audio samples may be used by a
- * {@link Synthesizer} to synthesize sound in response to MIDI commands, or
- * extracted for use by an application. (The terminology reflects musicians' use
- * of the word "sample" to refer collectively to a series of contiguous audio
- * samples or frames, rather than to a single, instantaneous sample.) The data
- * class for an audio sample will be an object that encapsulates the audio
- * sample data itself and information about how to interpret it (the format of
- * the audio data), such as an {@link AudioInputStream}.</li>
- * <li>Embedded sequences. A sound bank may contain built-in song data stored in
- * a data object such as a {@link Sequence}.</li>
+ * <li>Instruments. An instrument may be specified in a variety of ways.
+ * However, all soundbanks have some mechanism for defining instruments. In
+ * doing so, they may reference other resources stored in the soundbank.
+ * Each instrument has a {@code Patch} which specifies the MIDI program and
+ * bank by which it may be referenced in MIDI messages. Instrument information
+ * may be stored in {@link Instrument} objects.
+ * <li>Audio samples. A sample typically is a sampled audio waveform which
+ * contains a short sound recording whose duration is a fraction of a
+ * second, or at most a few seconds. These audio samples may be used by a
+ * {@link Synthesizer} to synthesize sound in response to MIDI commands, or
+ * extracted for use by an application. (The terminology reflects musicians'
+ * use of the word "sample" to refer collectively to a series of contiguous
+ * audio samples or frames, rather than to a single, instantaneous sample.)
+ * The data class for an audio sample will be an object that encapsulates
+ * the audio sample data itself and information about how to interpret it
+ * (the format of the audio data), such as an {@link AudioInputStream}.
+ * <li>Embedded sequences. A sound bank may contain built-in song data stored
+ * in a data object such as a {@link Sequence}.
* </ul>
* Synthesizers that use wavetable synthesis or related techniques play back the
* audio in a sample when synthesizing notes, often when emulating the
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Synthesizer.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Synthesizer.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -49,8 +49,8 @@
* be used by every synthesizer, even if the synthesis technique is compatible.
* To see whether the instruments from a certain soundbank can be played by a
* given synthesizer, invoke the
- * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported}
- * method of {@code Synthesizer}.
+ * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} method of
+ * {@code Synthesizer}.
* <p>
* "Loading" an instrument means that that instrument becomes available for
* synthesizing notes. The instrument is loaded into the bank and program
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/SysexMessage.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/SysexMessage.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2017, 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
@@ -40,8 +40,8 @@
* As dictated by the Standard MIDI Files specification, two status byte values
* are legal for a {@code SysexMessage} read from a MIDI file:
* <ul>
- * <li>0xF0: System Exclusive message (same as in MIDI wire protocol)</li>
- * <li>0xF7: Special System Exclusive message</li>
+ * <li>0xF0: System Exclusive message (same as in MIDI wire protocol)
+ * <li>0xF7: Special System Exclusive message
* </ul>
* When Java Sound is used to handle system exclusive data that is being
* received using MIDI wire protocol, it should place the data in one or more
@@ -49,8 +49,8 @@
* is not known in advance; the end of the system exclusive data is marked by an
* end-of-exclusive flag (0xF7) in the MIDI wire byte stream.
* <ul>
- * <li>0xF0: System Exclusive message (same as in MIDI wire protocol)</li>
- * <li>0xF7: End of Exclusive (EOX)</li>
+ * <li>0xF0: System Exclusive message (same as in MIDI wire protocol)
+ * <li>0xF7: End of Exclusive (EOX)
* </ul>
* The first {@code SysexMessage} object containing data for a particular system
* exclusive message should have the status value 0xF0. If this message contains
@@ -148,7 +148,7 @@
* should be non-negative and less than or equal to
* {@code data.length}
* @throws InvalidMidiDataException if the parameter values do not specify a
- * valid MIDI meta message
+ * valid MIDI system exclusive message
* @see #setMessage(byte[], int)
* @see #setMessage(int, byte[], int)
* @see #getData()
@@ -178,6 +178,8 @@
* @param data the system exclusive message data
* @param length the length of the valid message data in the array,
* including the status byte
+ * @throws InvalidMidiDataException if the parameter values do not specify a
+ * valid MIDI system exclusive message
*/
@Override
public void setMessage(byte[] data, int length) throws InvalidMidiDataException {
@@ -195,7 +197,7 @@
* @param data the system exclusive message data
* @param length the length of the valid message data in the array
* @throws InvalidMidiDataException if the status byte is invalid for a
- * sysex message
+ * system exclusive message
*/
public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException {
if ( (status != 0xF0) && (status != 0xF7) ) {
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -64,10 +64,14 @@
// TODO: use arrays for faster access
- // the list containing the events
+ /**
+ * The list containing the events.
+ */
private final ArrayList<MidiEvent> eventsList = new ArrayList<>();
- // use a hashset to detect duplicate events in add(MidiEvent)
+ /**
+ * Use a hashset to detect duplicate events in add(MidiEvent).
+ */
private final HashSet<MidiEvent> set = new HashSet<>();
private final MidiEvent eotEvent;
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/Transmitter.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Transmitter.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -67,7 +67,7 @@
* open/close behaviour see the class description of
* {@link MidiDevice MidiDevice}.
*
- * @see javax.sound.midi.MidiSystem#getTransmitter
+ * @see MidiSystem#getTransmitter
*/
@Override
void close();
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/VoiceStatus.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/VoiceStatus.java Thu Aug 31 13:00:23 2017 -0700
@@ -51,8 +51,8 @@
* given type of {@code Synthesizer} always has a fixed number of voices, equal
* to the maximum number of simultaneous notes it is capable of sounding.
* <p>
- * <a id="description_of_active"></a> If the voice is not currently processing
- * a MIDI note, it is considered inactive. A voice is inactive when it has been
+ * <a id="description_of_active"></a>If the voice is not currently processing a
+ * MIDI note, it is considered inactive. A voice is inactive when it has been
* given no note-on commands, or when every note-on command received has been
* terminated by a corresponding note-off (or by an "all notes off" message).
* For example, this happens when a synthesizer capable of playing 16
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/package-info.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/package-info.java Thu Aug 31 13:00:23 2017 -0700
@@ -30,8 +30,8 @@
* <h2>Related Documentation</h2>
* For more information on using Java Sound see:
* <ul>
- * <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
- * The Java Sound Tutorial</a></li>
+ * <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
+ * The Java Sound Tutorial</a>
* </ul>
*
* @since 1.3
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileReader.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileReader.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -54,8 +54,8 @@
* 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
+ * @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
@@ -68,14 +68,14 @@
throws InvalidMidiDataException, IOException;
/**
- * Obtains the MIDI file format of the URL provided. The URL must point to
- * valid MIDI file data.
+ * Obtains the MIDI file format of the {@code URL} provided. The {@code URL}
+ * must point to valid MIDI file data.
*
- * @param url the URL from which file format information should be
+ * @param url the {@code 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 InvalidMidiDataException if the {@code URL} does not point to
+ * valid MIDI file data recognized by the system
* @throws IOException if an I/O exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
@@ -104,10 +104,10 @@
* 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.
+ * not support this, this method may fail with an {@code IOException}.
*
- * @param stream the input stream from which the {@code Sequence} should
- * be constructed
+ * @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
@@ -121,14 +121,15 @@
throws InvalidMidiDataException, IOException;
/**
- * Obtains a MIDI sequence from the URL provided. The URL must point to
- * valid MIDI file data.
+ * Obtains a MIDI sequence from the {@code URL} provided. The {@code URL}
+ * must point to valid MIDI file data.
*
- * @param url the URL for which the {@code Sequence} should be constructed
+ * @param url the {@code 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
+ * by the {@code URL}
+ * @throws InvalidMidiDataException if the {@code URL} does not point to
+ * valid MIDI file data recognized by the system
* @throws IOException if an I/O exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileWriter.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/MidiFileWriter.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -54,8 +54,7 @@
* Obtains the file types that this file writer can write from the sequence
* specified.
*
- * @param sequence the sequence for which MIDI file type support is
- * queried
+ * @param sequence the sequence for which MIDI file type support is queried
* @return array of file types. If no file types are supported, returns an
* array of length 0.
* @throws NullPointerException if {@code sequence} is {@code null}
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/SoundbankReader.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/SoundbankReader.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -39,18 +39,18 @@
* subclasses of {@code SoundbankReader} parse a given soundbank file, producing
* a {@link Soundbank} object that can be loaded into a {@link Synthesizer}.
*
+ * @author Kara Kytle
* @since 1.3
- * @author Kara Kytle
*/
public abstract class SoundbankReader {
/**
- * Obtains a soundbank object from the URL provided.
+ * Obtains a soundbank object from the {@code URL} provided.
*
- * @param url URL representing the soundbank
+ * @param url {@code URL} representing the soundbank
* @return soundbank object
- * @throws InvalidMidiDataException if the URL does not point to valid MIDI
- * soundbank data recognized by this soundbank reader
+ * @throws InvalidMidiDataException if the {@code URL} does not point to
+ * valid MIDI soundbank data recognized by this soundbank reader
* @throws IOException if an I/O error occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/package-info.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/spi/package-info.java Thu Aug 31 13:00:23 2017 -0700
@@ -30,8 +30,8 @@
* <h2>Related Documentation</h2>
* For more information on using Java Sound see:
* <ul>
- * <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
- * The Java Sound Tutorial</a></li>
+ * <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
+ * The Java Sound Tutorial</a>
* </ul>
*
* @since 1.3
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFileFormat.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFileFormat.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -51,45 +51,37 @@
* implementations:
*
* <table border=1>
- * <caption>Audio File Format Properties</caption>
- * <tr>
- * <th>Property key</th>
- * <th>Value type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>"duration"</td>
- * <td>{@link java.lang.Long Long}</td>
- * <td>playback duration of the file in microseconds</td>
- * </tr>
- * <tr>
- * <td>"author"</td>
- * <td>{@link java.lang.String String}</td>
- * <td>name of the author of this file</td>
- * </tr>
- * <tr>
- * <td>"title"</td>
- * <td>{@link java.lang.String String}</td>
- * <td>title of this file</td>
- * </tr>
- * <tr>
- * <td>"copyright"</td>
- * <td>{@link java.lang.String String}</td>
- * <td>copyright message</td>
- * </tr>
- * <tr>
- * <td>"date"</td>
- * <td>{@link java.util.Date Date}</td>
- * <td>date of the recording or release</td>
- * </tr>
- * <tr>
- * <td>"comment"</td>
- * <td>{@link java.lang.String String}</td>
- * <td>an arbitrary text</td>
- * </tr>
+ * <caption>Audio File Format Properties</caption>
+ * <tr>
+ * <th>Property key
+ * <th>Value type
+ * <th>Description
+ * <tr>
+ * <td>"duration"
+ * <td>{@link Long Long}
+ * <td>playback duration of the file in microseconds
+ * <tr>
+ * <td>"author"
+ * <td>{@link String String}
+ * <td>name of the author of this file
+ * <tr>
+ * <td>"title"
+ * <td>{@link String String}
+ * <td>title of this file
+ * <tr>
+ * <td>"copyright"
+ * <td>{@link String String}
+ * <td>copyright message
+ * <tr>
+ * <td>"date"
+ * <td>{@link java.util.Date Date}
+ * <td>date of the recording or release
+ * <tr>
+ * <td>"comment"
+ * <td>{@link String String}
+ * <td>an arbitrary text
* </table>
*
- *
* @author David Rivas
* @author Kara Kytle
* @author Florian Bomers
@@ -351,7 +343,12 @@
}
/**
- * Finalizes the equals method.
+ * Indicates whether the specified object is equal to this file type,
+ * returning {@code true} if the objects are equal.
+ *
+ * @param obj the reference object with which to compare
+ * @return {@code true} if the specified object is equal to this file
+ * type; {@code false} otherwise
*/
@Override
public final boolean equals(final Object obj) {
@@ -365,7 +362,9 @@
}
/**
- * Finalizes the hashCode method.
+ * Returns a hash code value for this file type.
+ *
+ * @return a hash code value for this file type
*/
@Override
public final int hashCode() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFormat.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioFormat.java Thu Aug 31 13:00:23 2017 -0700
@@ -40,6 +40,7 @@
* data line expects to receive for output. For a target (capture) data line,
* the audio format specifies the kind of the data that can be read from the
* line.
+ * <p>
* Sound files also have audio formats, of course. The {@link AudioFileFormat}
* class encapsulates an {@code AudioFormat} in addition to other, file-specific
* information. Similarly, an {@link AudioInputStream} has an
@@ -92,29 +93,24 @@
* <table class="striped">
* <caption>Audio Format Properties</caption>
* <thead>
- * <tr>
- * <th>Property key</th>
- * <th>Value type</th>
- * <th>Description</th>
- * </tr>
+ * <tr>
+ * <th>Property key
+ * <th>Value type
+ * <th>Description
* </thead>
* <tbody>
- * <tr>
- * <td>"bitrate"</td>
- * <td>{@link java.lang.Integer Integer}</td>
- * <td>average bit rate in bits per second</td>
- * </tr>
- * <tr>
- * <td>"vbr"</td>
- * <td>{@link java.lang.Boolean Boolean}</td>
- * <td>{@code true}, if the file is encoded in variable bit
- * rate (VBR)</td>
- * </tr>
- * <tr>
- * <td>"quality"</td>
- * <td>{@link java.lang.Integer Integer}</td>
- * <td>encoding/conversion quality, 1..100</td>
- * </tr>
+ * <tr>
+ * <td>"bitrate"
+ * <td>{@link java.lang.Integer Integer}
+ * <td>average bit rate in bits per second
+ * <tr>
+ * <td>"vbr"
+ * <td>{@link java.lang.Boolean Boolean}
+ * <td>{@code true}, if the file is encoded in variable bit rate (VBR)
+ * <tr>
+ * <td>"quality"
+ * <td>{@link java.lang.Integer Integer}
+ * <td>encoding/conversion quality, 1..100
* </tbody>
* </table>
* <p>
@@ -183,8 +179,8 @@
* @param encoding the audio encoding technique
* @param sampleRate the number of samples per second
* @param sampleSizeInBits the number of bits in each sample
- * @param channels the number of channels (1 for mono, 2 for stereo,
- * and so on)
+ * @param channels the number of channels (1 for mono, 2 for stereo, and so
+ * on)
* @param frameSize the number of bytes in each frame
* @param frameRate the number of frames per second
* @param bigEndian indicates whether the data for a single sample is
@@ -217,7 +213,8 @@
* @param frameSize the number of bytes in each frame
* @param frameRate the number of frames per second
* @param bigEndian indicates whether the data for a single sample is
- * stored in big-endian byte order ({@code false} means little-endian)
+ * stored in big-endian byte order ({@code false} means
+ * little-endian)
* @param properties a {@code Map<String, Object>} object containing format
* properties
* @since 1.5
@@ -276,9 +273,10 @@
/**
* Obtains the sample rate. For compressed formats, the return value is the
- * sample rate of the uncompressed audio data. When this AudioFormat is used
- * for queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
- * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
+ * sample rate of the uncompressed audio data. When this {@code AudioFormat}
+ * is used for queries (e.g.
+ * {@link AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
+ * AudioSystem.isConversionSupported}) or capabilities (e.g.
* {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample rate
* of {@code AudioSystem.NOT_SPECIFIED} means that any sample rate is
* acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
@@ -296,10 +294,10 @@
/**
* Obtains the size of a sample. For compressed formats, the return value is
- * the sample size of the uncompressed audio data. When this AudioFormat is
- * used for queries (e.g. {@link AudioSystem#isConversionSupported(
- * AudioFormat,AudioFormat) AudioSystem.isConversionSupported}) or
- * capabilities (e.g.
+ * the sample size of the uncompressed audio data. When this
+ * {@code AudioFormat} is used for queries (e.g.
+ * {@link AudioSystem#isConversionSupported(AudioFormat,AudioFormat)
+ * AudioSystem.isConversionSupported}) or capabilities (e.g.
* {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a sample size
* of {@code AudioSystem.NOT_SPECIFIED} means that any sample size is
* acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
@@ -316,9 +314,9 @@
}
/**
- * Obtains the number of channels. When this AudioFormat is used for queries
- * (e.g. {@link AudioSystem#isConversionSupported(AudioFormat, AudioFormat)
- * AudioSystem.isConversionSupported}) or capabilities (e.g.
+ * Obtains the number of channels. When this {@code AudioFormat} is used for
+ * queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
+ * AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
* {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a return
* value of {@code AudioSystem.NOT_SPECIFIED} means that any (positive)
* number of channels is acceptable.
@@ -333,8 +331,8 @@
}
/**
- * Obtains the frame size in bytes. When this AudioFormat is used for
- * queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
+ * Obtains the frame size in bytes. When this {@code AudioFormat} is used
+ * for queries (e.g. {@link AudioSystem#isConversionSupported(AudioFormat,
* AudioFormat) AudioSystem.isConversionSupported}) or capabilities (e.g.
* {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame size
* of {@code AudioSystem.NOT_SPECIFIED} means that any frame size is
@@ -352,10 +350,10 @@
}
/**
- * Obtains the frame rate in frames per second. When this AudioFormat is
- * used for queries (e.g. {@link AudioSystem#isConversionSupported(
- * AudioFormat,AudioFormat) AudioSystem.isConversionSupported}) or
- * capabilities (e.g.
+ * Obtains the frame rate in frames per second. When this
+ * {@code AudioFormat} is used for queries (e.g.
+ * {@link AudioSystem#isConversionSupported(AudioFormat,AudioFormat)
+ * AudioSystem.isConversionSupported}) or capabilities (e.g.
* {@link DataLine.Info#getFormats DataLine.Info.getFormats}), a frame rate
* of {@code AudioSystem.NOT_SPECIFIED} means that any frame rate is
* acceptable. {@code AudioSystem.NOT_SPECIFIED} is also returned when the
@@ -551,9 +549,10 @@
* the sound amplitude that are often used for recording speech.
* <p>
* You can use a predefined encoding by referring to one of the static
- * objects created by this class, such as PCM_SIGNED or PCM_UNSIGNED.
- * Service providers can create new encodings, such as compressed audio
- * formats, and make these available through the {@link AudioSystem} class.
+ * objects created by this class, such as {@code PCM_SIGNED} or
+ * {@code PCM_UNSIGNED}. Service providers can create new encodings, such as
+ * compressed audio formats, and make these available through the
+ * {@link AudioSystem} class.
* <p>
* The {@code Encoding} class is static, so that all {@code AudioFormat}
* objects that have the same encoding will refer to the same object (rather
@@ -609,7 +608,12 @@
}
/**
- * Finalizes the equals method.
+ * Indicates whether the specified object is equal to this encoding,
+ * returning {@code true} if the objects are equal.
+ *
+ * @param obj the reference object with which to compare
+ * @return {@code true} if the specified object is equal to this
+ * encoding; {@code false} otherwise
*/
@Override
public final boolean equals(final Object obj) {
@@ -623,7 +627,9 @@
}
/**
- * Finalizes the hashCode method.
+ * Returns a hash code value for this encoding.
+ *
+ * @return a hash code value for this encoding
*/
@Override
public final int hashCode() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioInputStream.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioInputStream.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -28,7 +28,6 @@
import java.io.IOException;
import java.io.InputStream;
-
/**
* An audio input stream is an input stream with a specified audio format and
* length. The length is expressed in sample frames, not bytes. Several methods
@@ -42,9 +41,10 @@
* The {@code AudioSystem} class includes many methods that manipulate
* {@code AudioInputStream} objects. For example, the methods let you:
* <ul>
- * <li> obtain an audio input stream from an external audio file, stream, or URL
- * <li> write an external file from an audio input stream
- * <li> convert an audio input stream to a different audio format
+ * <li>obtain an audio input stream from an external audio file, stream, or
+ * {@code URL}
+ * <li>write an external file from an audio input stream
+ * <li>convert an audio input stream to a different audio format
* </ul>
*
* @author David Rivas
@@ -139,7 +139,7 @@
/**
* Constructs an audio input stream that reads its data from the target data
* line indicated. The format of the stream is the same as that of the
- * target data line, and the length is AudioSystem#NOT_SPECIFIED.
+ * target data line, and the length is {@code AudioSystem#NOT_SPECIFIED}.
*
* @param line the target data line from which this stream obtains its data
* @see AudioSystem#NOT_SPECIFIED
@@ -370,11 +370,11 @@
/**
* Returns the maximum number of bytes that can be read (or skipped over)
- * from this audio input stream without blocking. This limit applies only
- * to the next invocation of a {@code read} or {@code skip} method for this
+ * from this audio input stream without blocking. This limit applies only to
+ * the next invocation of a {@code read} or {@code skip} method for this
* audio input stream; the limit can vary each time these methods are
- * invoked. Depending on the underlying stream, an IOException may be thrown
- * if this stream is closed.
+ * invoked. Depending on the underlying stream, an {@code IOException} may
+ * be thrown if this stream is closed.
*
* @return the number of bytes that can be read from this audio input stream
* without blocking
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioPermission.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioPermission.java Thu Aug 31 13:00:23 2017 -0700
@@ -45,34 +45,30 @@
* <caption>Permission target name, what the permission allows, and associated
* risks</caption>
* <thead>
- * <tr>
- * <th>Permission Target Name</th>
- * <th>What the Permission Allows</th>
- * <th>Risks of Allowing this Permission</th>
- * </tr>
+ * <tr>
+ * <th>Permission Target Name
+ * <th>What the Permission Allows
+ * <th>Risks of Allowing this Permission
* </thead>
* <tbody>
- * <tr>
- * <td>play</td>
- * <td>Audio playback through the audio device or devices on the system.
- * Allows the application to obtain and manipulate lines and mixers for
- * audio playback (rendering).</td>
- * <td>In some cases use of this permission may affect other
- * applications because the audio from one line may be mixed with other audio
- * being played on the system, or because manipulation of a mixer affects the
- * audio for all lines using that mixer.</td>
- * </tr>
- *
- * <tr>
- * <td>record</td>
- * <td>Audio recording through the audio device or devices on the system.
- * Allows the application to obtain and manipulate lines and mixers for
- * audio recording (capture).</td>
- * <td>In some cases use of this permission may affect other
- * applications because manipulation of a mixer affects the audio for all lines
- * using that mixer.
- * This permission can enable an applet or application to eavesdrop on a user.</td>
- * </tr>
+ * <tr>
+ * <td>play
+ * <td>Audio playback through the audio device or devices on the system.
+ * Allows the application to obtain and manipulate lines and mixers for
+ * audio playback (rendering).
+ * <td>In some cases use of this permission may affect other
+ * applications because the audio from one line may be mixed with other
+ * audio being played on the system, or because manipulation of a mixer
+ * affects the audio for all lines using that mixer.
+ * <tr>
+ * <td>record
+ * <td>Audio recording through the audio device or devices on the system.
+ * Allows the application to obtain and manipulate lines and mixers for
+ * audio recording (capture).
+ * <td>In some cases use of this permission may affect other applications
+ * because manipulation of a mixer affects the audio for all lines using
+ * that mixer. This permission can enable an applet or application to
+ * eavesdrop on a user.
* </tbody>
* </table>
*
@@ -81,6 +77,9 @@
*/
public class AudioPermission extends BasicPermission {
+ /**
+ * Use serialVersionUID from JDK 1.3 for interoperability.
+ */
private static final long serialVersionUID = -5518053473477801126L;
/**
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioSystem.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/AudioSystem.java Thu Aug 31 13:00:23 2017 -0700
@@ -25,7 +25,6 @@
package javax.sound.sampled;
-import java.io.EOFException;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
@@ -75,33 +74,28 @@
* <table class="striped">
* <caption>Audio System Property Keys</caption>
* <thead>
- * <tr>
- * <th>Property Key</th>
- * <th>Interface</th>
- * <th>Affected Method(s)</th>
- * </tr>
+ * <tr>
+ * <th>Property Key
+ * <th>Interface
+ * <th>Affected Method(s)
* </thead>
* <tbody>
- * <tr>
- * <td>{@code javax.sound.sampled.Clip}</td>
- * <td>{@link Clip}</td>
- * <td>{@link #getLine}, {@link #getClip}</td>
- * </tr>
- * <tr>
- * <td>{@code javax.sound.sampled.Port}</td>
- * <td>{@link Port}</td>
- * <td>{@link #getLine}</td>
- * </tr>
- * <tr>
- * <td>{@code javax.sound.sampled.SourceDataLine}</td>
- * <td>{@link SourceDataLine}</td>
- * <td>{@link #getLine}, {@link #getSourceDataLine}</td>
- * </tr>
- * <tr>
- * <td>{@code javax.sound.sampled.TargetDataLine}</td>
- * <td>{@link TargetDataLine}</td>
- * <td>{@link #getLine}, {@link #getTargetDataLine}</td>
- * </tr>
+ * <tr>
+ * <td>{@code javax.sound.sampled.Clip}
+ * <td>{@link Clip}
+ * <td>{@link #getLine}, {@link #getClip}
+ * <tr>
+ * <td>{@code javax.sound.sampled.Port}
+ * <td>{@link Port}
+ * <td>{@link #getLine}
+ * <tr>
+ * <td>{@code javax.sound.sampled.SourceDataLine}
+ * <td>{@link SourceDataLine}
+ * <td>{@link #getLine}, {@link #getSourceDataLine}
+ * <tr>
+ * <td>{@code javax.sound.sampled.TargetDataLine}
+ * <td>{@link TargetDataLine}
+ * <td>{@link #getLine}, {@link #getTargetDataLine}
* </tbody>
* </table>
*
@@ -125,20 +119,19 @@
* matching {@code Mixer.Info} object is found, or the mixer name is not
* specified, the first mixer from the resulting list, which provides the
* respective line interface, will be returned.
- *
+ * <p>
* For example, the property {@code javax.sound.sampled.Clip} with a value
- * {@code "com.sun.media.sound.MixerProvider#SunClip"}
- * will have the following consequences when {@code getLine} is called
- * requesting a {@code Clip} instance: if the class
- * {@code com.sun.media.sound.MixerProvider} exists in the list of installed
- * mixer providers, the first {@code Clip} from the first mixer with name
- * {@code "SunClip"} will be returned. If it cannot be found, the
- * first {@code Clip} from the first mixer of the specified provider will be
+ * {@code "com.sun.media.sound.MixerProvider#SunClip"} will have the following
+ * consequences when {@code getLine} is called requesting a {@code Clip}
+ * instance: if the class {@code com.sun.media.sound.MixerProvider} exists in
+ * the list of installed mixer providers, the first {@code Clip} from the first
+ * mixer with name {@code "SunClip"} will be returned. If it cannot be found,
+ * the first {@code Clip} from the first mixer of the specified provider will be
* returned, regardless of name. If there is none, the first {@code Clip} from
- * the first {@code Mixer} with name {@code "SunClip"} in the list of
- * all mixers (as returned by {@code getMixerInfo}) will be returned, or, if not
- * found, the first {@code Clip} of the first {@code Mixer} that can be found in
- * the list of all mixers is returned. If that fails, too, an
+ * the first {@code Mixer} with name {@code "SunClip"} in the list of all mixers
+ * (as returned by {@code getMixerInfo}) will be returned, or, if not found, the
+ * first {@code Clip} of the first {@code Mixer} that can be found in the list
+ * of all mixers is returned. If that fails, too, an
* {@code IllegalArgumentException} is thrown.
*
* @author Kara Kytle
@@ -479,7 +472,6 @@
* @param mixerInfo a {@code Mixer.Info} object representing the desired
* mixer, or {@code null} for the system default mixer
* @return a clip object from the specified mixer
- *
* @throws LineUnavailableException if a clip is not available from this
* mixer due to resource restrictions
* @throws SecurityException if a clip is not available from this mixer due
@@ -670,9 +662,9 @@
*
* @param sourceEncoding the encoding for which conversion support is
* queried
- * @return array of encodings. If {@code sourceEncoding}is not supported, an
- * array of length 0 is returned. Otherwise, the array will have a
- * length of at least 1, representing {@code sourceEncoding}
+ * @return array of encodings. If {@code sourceEncoding} is not supported,
+ * an array of length 0 is returned. Otherwise, the array will have
+ * a length of at least 1, representing {@code sourceEncoding}
* (no conversion).
* @throws NullPointerException if {@code sourceEncoding} is {@code null}
*/
@@ -935,15 +927,15 @@
}
/**
- * Obtains the audio file format of the specified URL. The URL must point to
- * valid audio file data.
+ * Obtains the audio file format of the specified {@code URL}. The
+ * {@code URL} must point to valid audio file data.
*
- * @param url the URL from which file format information should be
+ * @param url the {@code URL} from which file format information should be
* extracted
* @return an {@code AudioFileFormat} object describing the audio file
* format
- * @throws UnsupportedAudioFileException if the URL does not point to valid
- * audio file data recognized by the system
+ * @throws UnsupportedAudioFileException if the {@code URL} does not point
+ * to valid audio file data recognized by the system
* @throws IOException if an input/output exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
@@ -1021,15 +1013,15 @@
}
/**
- * Obtains an audio input stream from the URL provided. The URL must point
- * to valid audio file data.
+ * Obtains an audio input stream from the {@code URL} provided. The
+ * {@code URL} must point to valid audio file data.
*
- * @param url the URL for which the {@code AudioInputStream} should be
- * constructed
+ * @param url the {@code URL} for which the {@code AudioInputStream} should
+ * be constructed
* @return an {@code AudioInputStream} object based on the audio file data
- * pointed to by the URL
- * @throws UnsupportedAudioFileException if the URL does not point to valid
- * audio file data recognized by the system
+ * pointed to by the {@code URL}
+ * @throws UnsupportedAudioFileException if the {@code URL} does not point
+ * to valid audio file data recognized by the system
* @throws IOException if an I/O exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
@@ -1121,8 +1113,8 @@
* Obtains the file types that the system can write from the audio input
* stream specified.
*
- * @param stream the audio input stream for which audio file type
- * support is queried
+ * @param stream the audio input stream for which audio file type support
+ * is queried
* @return array of file types. If no file types are supported, an array of
* length 0 is returned.
* @throws NullPointerException if {@code stream} is {@code null}
@@ -1175,8 +1167,8 @@
* type to the output stream provided. Some file types require that the
* length be written into the file header; such files cannot be written from
* start to finish unless the length is known in advance. An attempt to
- * write a file of such a type will fail with an IOException if the length
- * in the audio file type is {@code AudioSystem.NOT_SPECIFIED}.
+ * write a file of such a type will fail with an {@code IOException} if the
+ * length in the audio file type is {@code AudioSystem.NOT_SPECIFIED}.
*
* @param stream the audio input stream containing audio data to be written
* to the file
@@ -1250,7 +1242,9 @@
// METHODS FOR INTERNAL IMPLEMENTATION USE
/**
- * Obtains the set of MixerProviders on the system.
+ * Obtains the list of MixerProviders currently installed on the system.
+ *
+ * @return the list of MixerProviders currently installed on the system
*/
@SuppressWarnings("unchecked")
private static List<MixerProvider> getMixerProviders() {
@@ -1331,9 +1325,12 @@
}
}
- /* Provider class not specified or
- provider class cannot be found, or
- provider class and instance specified and instance cannot be found or is not appropriate */
+ /*
+ * - Provider class not specified, or
+ * - provider class cannot be found, or
+ * - provider class and instance specified and instance cannot be found
+ * or is not appropriate
+ */
if (instanceName != null) {
mixer = getNamedMixer(instanceName, providers, info);
if (mixer != null) {
@@ -1342,8 +1339,10 @@
}
- /* No default are specified, or if something is specified, everything
- failed. */
+ /*
+ * No defaults are specified, or if something is specified, everything
+ * failed
+ */
return null;
}
@@ -1436,10 +1435,14 @@
/**
* Checks if a Mixer is appropriate. A Mixer is considered appropriate if it
- * support the given line type. If isMixingRequired is true and the line
- * type is an output one (SourceDataLine, Clip), the mixer is appropriate if
- * it supports at least 2 (concurrent) lines of the given type.
+ * support the given line type. If isMixingRequired is {@code true} and the
+ * line type is an output one (SourceDataLine, Clip), the mixer is
+ * appropriate if it supports at least 2 (concurrent) lines of the given
+ * type.
*
+ * @param mixer The mixer to check
+ * @param lineInfo The line to check
+ * @param isMixingRequired Is the mixing required or not
* @return {@code true} if the mixer is considered appropriate according to
* the rules given above, {@code false} otherwise
*/
@@ -1461,6 +1464,10 @@
/**
* Like getMixerInfo, but return List.
+ *
+ * @return a List of info objects for the currently installed mixers. If no
+ * mixers are available on the system, an empty List is returned.
+ * @see #getMixerInfo()
*/
private static List<Mixer.Info> getMixerInfoList() {
List<MixerProvider> providers = getMixerProviders();
@@ -1469,6 +1476,11 @@
/**
* Like getMixerInfo, but return List.
+ *
+ * @param providers The list of MixerProviders
+ * @return a List of info objects for the currently installed mixers. If no
+ * mixers are available on the system, an empty List is returned.
+ * @see #getMixerInfo()
*/
private static List<Mixer.Info> getMixerInfoList(List<MixerProvider> providers) {
List<Mixer.Info> infos = new ArrayList<>();
@@ -1491,6 +1503,11 @@
* 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 vector of length 0 will be returned.
*/
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/BooleanControl.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/BooleanControl.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -121,7 +121,7 @@
/**
* Provides a string representation of the control.
*
- * @return a string description
+ * @return a string representation of the control
*/
@Override
public String toString() {
@@ -153,7 +153,7 @@
/**
* Constructs a new boolean control type.
*
- * @param name the name of the new boolean control type
+ * @param name the name of the new boolean control type
*/
protected Type(final String name) {
super(name);
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Clip.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Clip.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -178,13 +178,13 @@
/**
* Sets the first and last sample frames that will be played in the loop.
* The ending point must be greater than or equal to the starting point, and
- * both must fall within the size of the loaded media. A value of 0 for
- * the starting point means the beginning of the loaded media. Similarly, a
+ * both must fall within the size of the loaded media. A value of 0 for the
+ * starting point means the beginning of the loaded media. Similarly, a
* value of -1 for the ending point indicates the last frame of the media.
*
* @param start the loop's starting position, in sample frames (zero-based)
- * @param end the loop's ending position, in sample frames (zero-based),
- * or -1 to indicate the final frame
+ * @param end the loop's ending position, in sample frames (zero-based), or
+ * -1 to indicate the final frame
* @throws IllegalArgumentException if the requested loop points cannot be
* set, usually because one or both falls outside the media's
* duration or because the ending point is before the starting point
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/CompoundControl.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/CompoundControl.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -90,8 +90,7 @@
/**
* An instance of the {@code CompoundControl.Type} inner class identifies
- * one kind of compound control. Static instances are provided for the
- * common types.
+ * one kind of compound control.
*
* @author Kara Kytle
* @since 1.3
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Control.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Control.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -48,7 +48,7 @@
private final Type type;
/**
- * Constructs a Control with the specified type.
+ * Constructs a control with the specified type.
*
* @param type the kind of control desired
*/
@@ -66,9 +66,9 @@
}
/**
- * Obtains a String describing the control type and its current state.
+ * Obtains a string describing the control type and its current state.
*
- * @return a String representation of the Control
+ * @return a string representation of the control
*/
@Override
public String toString() {
@@ -77,7 +77,6 @@
/**
* An instance of the {@code Type} class represents the type of the control.
- * Static instances are provided for the common types.
*/
public static class Type {
@@ -98,7 +97,12 @@
}
/**
- * Finalizes the equals method.
+ * Indicates whether the specified object is equal to this control type,
+ * returning {@code true} if the objects are the same.
+ *
+ * @param obj the reference object with which to compare
+ * @return {@code true} if the specified object is equal to this control
+ * type; {@code false} otherwise
*/
@Override
public final boolean equals(Object obj) {
@@ -106,7 +110,9 @@
}
/**
- * Finalizes the hashCode method.
+ * Returns a hash code value for this control type.
+ *
+ * @return a hash code value for this control type
*/
@Override
public final int hashCode() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/DataLine.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/DataLine.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -54,7 +54,7 @@
* data, a {@code STOP} event is generated.
* <p>
* Mixers often support synchronized control of multiple data lines.
- * Synchronization can be established through the Mixer interface's
+ * Synchronization can be established through the {@code Mixer} interface's
* {@link Mixer#synchronize synchronize} method. See the description of the
* {@link Mixer Mixer} interface for a more complete description.
*
@@ -181,7 +181,7 @@
* are bytes, but will always correspond to an integral number of sample
* frames of audio data.
*
- * @return the size of the buffer in bytes
+ * @return the size of the buffer, in bytes
*/
int getBufferSize();
@@ -260,8 +260,8 @@
* {@code DataLine.Info} provides additional information specific to data
* lines. This information includes:
* <ul>
- * <li> the audio formats supported by the data line
- * <li> the minimum and maximum sizes of its internal buffer
+ * <li>the audio formats supported by the data line
+ * <li>the minimum and maximum sizes of its internal buffer
* </ul>
* Because a {@code Line.Info} knows the class of the line its describes, a
* {@code DataLine.Info} object can describe {@code DataLine} subinterfaces
@@ -270,14 +270,25 @@
* appropriate instance of {@code DataLine.Info} as the argument to a method
* such as {@link Mixer#getLine(Line.Info)}.
*
+ * @author Kara Kytle
* @see Line.Info
- * @author Kara Kytle
* @since 1.3
*/
class Info extends Line.Info {
+ /**
+ * The set of supported formats.
+ */
private final AudioFormat[] formats;
+
+ /**
+ * Minimum buffer size supported by the data line, in bytes.
+ */
private final int minBufferSize;
+
+ /**
+ * Maximum buffer size supported by the data line, in bytes.
+ */
private final int maxBufferSize;
/**
@@ -289,10 +300,10 @@
* @param lineClass the class of the data line described by the info
* object
* @param formats set of formats supported
- * @param minBufferSize minimum buffer size supported by the data
- * line, in bytes
- * @param maxBufferSize maximum buffer size supported by the data
- * line, in bytes
+ * @param minBufferSize minimum buffer size supported by the data line,
+ * in bytes
+ * @param maxBufferSize maximum buffer size supported by the data line,
+ * in bytes
*/
public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize) {
@@ -317,7 +328,7 @@
* @param lineClass the class of the data line described by the info
* object
* @param format desired format
- * @param bufferSize desired buffer size in bytes
+ * @param bufferSize desired buffer size, in bytes
*/
public Info(Class<?> lineClass, AudioFormat format, int bufferSize) {
@@ -354,7 +365,7 @@
* {@code isFormatSupported(AudioFormat)} is guaranteed to return
* {@code true} for all formats returned by {@code getFormats()}.
* <p>
- * Some fields in the AudioFormat instances can be set to
+ * Some fields in the {@code AudioFormat} instances can be set to
* {@link AudioSystem#NOT_SPECIFIED NOT_SPECIFIED} if that field does
* not apply to the format, or if the format supports a wide range of
* values for that field. For example, a multi-channel device supporting
@@ -419,6 +430,7 @@
* large as that of the object specified, and all of its formats must
* match formats supported by the object specified.
*
+ * @param info the info object which is being compared to this one
* @return {@code true} if this object matches the one specified,
* otherwise {@code false}
*/
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Line.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Line.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -237,8 +237,8 @@
* class. This constructor is typically used by an application to
* describe a desired line.
*
- * @param lineClass the class of the line that the new Line.Info object
- * describes
+ * @param lineClass the class of the line that the new
+ * {@code Line.Info} object describes
*/
public Info(Class<?> lineClass) {
@@ -250,7 +250,8 @@
}
/**
- * Obtains the class of the line that this Line.Info object describes.
+ * Obtains the class of the line that this {@code Line.Info} object
+ * describes.
*
* @return the described line's class
*/
@@ -261,13 +262,13 @@
/**
* Indicates whether the specified info object matches this one. To
* match, the specified object must be identical to or a special case of
- * this one. The specified info object must be either an instance of
- * the same class as this one, or an instance of a sub-type of this one.
- * In addition, the attributes of the specified object must be
- * compatible with the capabilities of this one. Specifically, the
- * routing configuration for the specified info object must be
- * compatible with that of this one. Subclasses may add other criteria
- * to determine whether the two objects match.
+ * this one. The specified info object must be either an instance of the
+ * same class as this one, or an instance of a sub-type of this one. In
+ * addition, the attributes of the specified object must be compatible
+ * with the capabilities of this one. Specifically, the routing
+ * configuration for the specified info object must be compatible with
+ * that of this one. Subclasses may add other criteria to determine
+ * whether the two objects match.
*
* @param info the info object which is being compared to this one
* @return {@code true} if the specified object matches this one,
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/LineEvent.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/LineEvent.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -48,14 +48,17 @@
*/
public class LineEvent extends EventObject {
+ /**
+ * Use serialVersionUID from JDK 1.3 for interoperability.
+ */
private static final long serialVersionUID = -1274246333383880410L;
/**
* The kind of line event ({@code OPEN}, {@code CLOSE}, {@code START}, or
* {@code STOP}).
*
+ * @see #getType
* @serial
- * @see #getType
*/
private final Type type;
@@ -67,8 +70,8 @@
* this value is not known, the position value should be
* {@link AudioSystem#NOT_SPECIFIED}.
*
+ * @see #getFramePosition
* @serial
- * @see #getFramePosition
*/
private final long position;
@@ -184,11 +187,11 @@
/**
* Indicates whether the specified object is equal to this event type,
- * returning {@code true} if the objects are identical.
+ * returning {@code true} if the objects are the same.
*
* @param obj the reference object with which to compare
- * @return {@code true} if this event type is the same as {@code obj};
- * {@code false} otherwise
+ * @return {@code true} if the specified object is equal to this event
+ * type; {@code false} otherwise
*/
@Override
public final boolean equals(Object obj) {
@@ -196,7 +199,9 @@
}
/**
- * Finalizes the hashcode method.
+ * Returns a hash code value for this event type.
+ *
+ * @return a hash code value for this event type
*/
@Override
public final int hashCode() {
@@ -205,6 +210,8 @@
/**
* Returns the type name as the string representation.
+ *
+ * @return the type name as the string representation
*/
@Override
public String toString() {
@@ -253,22 +260,24 @@
/**
* A type of event that is sent when a line ceases to engage in active
- * input or output of audio data because the end of media has been reached.
+ * input or output of audio data because the end of media has been
+ * reached.
*/
/*
- * ISSUE: we may want to get rid of this. Is JavaSound
- * responsible for reporting this??
+ * ISSUE: we may want to get rid of this. Is JavaSound responsible for
+ * reporting this??
*
- * [If it's decided to keep this API, the docs will need to be updated to include mention
- * of EOM events elsewhere.]
+ * [If it's decided to keep this API, the docs will need to be updated
+ * to include mention of EOM events elsewhere.]
*/
//public static final Type EOM = new Type("EOM");
/**
* A type of event that is sent when a line begins to engage in active
- * input or output of audio data. Examples of when this happens are
- * when a source line begins or resumes writing data to its mixer, and
- * when a target line begins or resumes reading data from its mixer.
+ * input or output of audio data. Examples of when this happens are when
+ * a source line begins or resumes writing data to its mixer, and when a
+ * target line begins or resumes reading data from its mixer.
+ *
* @see #STOP
* @see SourceDataLine#write
* @see TargetDataLine#read
@@ -277,8 +286,9 @@
//public static final Type ACTIVE = new Type("ACTIVE");
/**
- * A type of event that is sent when a line ceases active input or output
- * of audio data.
+ * A type of event that is sent when a line ceases active input or
+ * output of audio data.
+ *
* @see #START
* @see DataLine#stop
*/
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/LineUnavailableException.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/LineUnavailableException.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -35,6 +35,9 @@
*/
public class LineUnavailableException extends Exception {
+ /**
+ * Use serialVersionUID from JDK 1.3 for interoperability.
+ */
private static final long serialVersionUID = -2046718279487432130L;
/**
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Mixer.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Mixer.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -58,7 +58,7 @@
* version, vendor, etc.
*
* @return a mixer info object that describes this mixer
- * @see Mixer.Info
+ * @see Info
*/
Info getMixerInfo();
@@ -144,19 +144,19 @@
/**
* Obtains the approximate maximum number of lines of the requested type
* that can be open simultaneously on the mixer.
- *
+ * <p>
* Certain types of mixers do not have a hard bound and may allow opening
* more lines. Since certain lines are a shared resource, a mixer may not be
* able to open the maximum number of lines if another process has opened
* lines of this mixer.
- *
+ * <p>
* The requested type is any line that matches the description in the
* provided {@code Line.Info} object. For example, if the info object
* represents a speaker port, and the mixer supports exactly one speaker
- * port, this method should return 1. If the info object represents a
- * source data line and the mixer supports the use of 32 source data lines
+ * port, this method should return 1. If the info object represents a source
+ * data line and the mixer supports the use of 32 source data lines
* simultaneously, the return value should be 32. If there is no limit, this
- * function returns {@code AudioSystem.NOT_SPECIFIED}.
+ * function returns {@link AudioSystem#NOT_SPECIFIED}.
*
* @param info a {@code Line.Info} that describes the line for which the
* number of supported instances is queried
@@ -215,11 +215,10 @@
* this mixer are unsynchronized.
*
* @param lines the synchronized lines for which synchronization should be
- * released, or {@code null} for all this mixer's synchronized
- * lines
+ * released, or {@code null} for all this mixer's synchronized lines
* @throws IllegalArgumentException if the lines cannot be unsynchronized.
- * This may occur if the argument specified does not exactly match
- * a set of lines for which synchronization has already been
+ * This may occur if the argument specified does not exactly match a
+ * set of lines for which synchronization has already been
* established.
*/
void unsynchronize(Line[] lines);
@@ -277,8 +276,8 @@
* information.
*
* @param name the name of the mixer
- * @param vendor the company who manufactures or creates the
- * hardware or software mixer
+ * @param vendor the company who manufactures or creates the hardware
+ * or software mixer
* @param description descriptive text about the mixer
* @param version version information for the mixer
*/
@@ -291,13 +290,12 @@
}
/**
- * Indicates whether two info objects are equal, returning {@code true}
- * if they are identical.
+ * Indicates whether the specified object is equal to this info object,
+ * returning {@code true} if the objects are the same.
*
- * @param obj the reference object with which to compare this info
- * object
- * @return {@code true} if this info object is the same as the
- * {@code obj} argument; {@code false} otherwise
+ * @param obj the reference object with which to compare
+ * @return {@code true} if the specified object is equal to this info
+ * object; {@code false} otherwise
*/
@Override
public final boolean equals(Object obj) {
@@ -305,9 +303,9 @@
}
/**
- * Finalizes the hashcode method.
+ * Returns a hash code value for this info object.
*
- * @return the hashcode for this object
+ * @return a hash code value for this info object
*/
@Override
public final int hashCode() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/Port.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/Port.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -100,7 +100,14 @@
// DAT
// DVD
+ /**
+ * The string that names the port.
+ */
private final String name;
+
+ /**
+ * Whether this port is source or not.
+ */
private final boolean isSource;
/**
@@ -111,8 +118,8 @@
* @param lineClass the class of the port described by the info object
* @param name the string that names the port
* @param isSource {@code true} if the port is a source port (such as a
- * microphone), {@code false} if the port is a target port
- * (such as a speaker)
+ * microphone), {@code false} if the port is a target port (such
+ * as a speaker)
*/
public Info(Class<?> lineClass, String name, boolean isSource) {
@@ -134,8 +141,8 @@
* Indicates whether the port is a source or a target for its mixer.
*
* @return {@code true} if the port is a source port (such as a
- * microphone), {@code false} if the port is a target port
- * (such as a speaker)
+ * microphone), {@code false} if the port is a target port (such
+ * as a speaker)
*/
public boolean isSource() {
return isSource;
@@ -147,6 +154,8 @@
* types must be equal.
*
* @param info the info object for which the match is queried
+ * @return {@code true} if the specified object matches this one,
+ * {@code false} otherwise
*/
@Override
public boolean matches(Line.Info info) {
@@ -167,7 +176,12 @@
}
/**
- * Finalizes the equals method.
+ * Indicates whether the specified object is equal to this info object,
+ * returning {@code true} if the objects are the same.
+ *
+ * @param obj the reference object with which to compare
+ * @return {@code true} if the specified object is equal to this info
+ * object; {@code false} otherwise
*/
@Override
public final boolean equals(Object obj) {
@@ -175,7 +189,9 @@
}
/**
- * Finalizes the hashCode method.
+ * Returns a hash code value for this info object.
+ *
+ * @return a hash code value for this info object
*/
@Override
public final int hashCode() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/ReverbType.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/ReverbType.java Thu Aug 31 13:00:23 2017 -0700
@@ -38,7 +38,7 @@
* delay time and intensity of early reflections, the delay time and intensity
* of late reflections, and an overall decay time. Early reflections are the
* initial individual low-order reflections of the direct signal off the
- * surfaces in the room. The late Reflections are the dense, high-order
+ * surfaces in the room. The late reflections are the dense, high-order
* reflections that characterize the room's reverberation. The delay times for
* the start of these two reflection types give the listener a sense of the
* overall size and complexity of the room's shape and contents. The larger the
@@ -63,8 +63,8 @@
* <p>
* If implementing JavaSound on a I3DL2-compliant device:
* <ul>
- * <li>Filtering is disabled (high-frequency attenuations are set to 0.0 dB)
- * <li>Density parameters are set to midway between minimum and maximum
+ * <li>Filtering is disabled (high-frequency attenuations are set to 0.0 dB)
+ * <li>Density parameters are set to midway between minimum and maximum
* </ul>
* <p>
* The following table shows what parameter values an implementation might use
@@ -74,60 +74,50 @@
* <caption>Reverb types and params: decay time, late intensity, late delay,
* early intensity, and early delay</caption>
* <thead>
- * <tr>
- * <th>Type</th>
- * <th>Decay Time (ms)</th>
- * <th>Late Intensity (dB)</th>
- * <th>Late Delay (ms)</th>
- * <th>Early Intensity (dB)</th>
- * <th>Early Delay(ms)</th>
- * </tr>
+ * <tr>
+ * <th>Type
+ * <th>Decay Time (ms)
+ * <th>Late Intensity (dB)
+ * <th>Late Delay (ms)
+ * <th>Early Intensity (dB)
+ * <th>Early Delay(ms)
* </thead>
* <tbody>
- * <tr>
- * <td>Cavern</td>
- * <td>2250</td>
- * <td>-2.0</td>
- * <td>41.3</td>
- * <td>-1.4</td>
- * <td>10.3</td>
- * </tr>
- *
- * <tr>
- * <td>Dungeon</td>
- * <td>1600</td>
- * <td>-1.0</td>
- * <td>10.3</td>
- * <td>-0.7</td>
- * <td>2.6</td>
- * </tr>
- *
- * <tr>
- * <td>Garage</td>
- * <td>900</td>
- * <td>-6.0</td>
- * <td>14.7</td>
- * <td>-4.0</td>
- * <td>3.9</td>
- * </tr>
- *
- * <tr>
- * <td>Acoustic Lab</td>
- * <td>280</td>
- * <td>-3.0</td>
- * <td>8.0</td>
- * <td>-2.0</td>
- * <td>2.0</td>
- * </tr>
- *
- * <tr>
- * <td>Closet</td>
- * <td>150</td>
- * <td>-10.0</td>
- * <td>2.5</td>
- * <td>-7.0</td>
- * <td>0.6</td>
- * </tr>
+ * <tr>
+ * <td>Cavern
+ * <td>2250
+ * <td>-2.0
+ * <td>41.3
+ * <td>-1.4
+ * <td>10.3
+ * <tr>
+ * <td>Dungeon
+ * <td>1600
+ * <td>-1.0
+ * <td>10.3
+ * <td>-0.7
+ * <td>2.6
+ * <tr>
+ * <td>Garage
+ * <td>900
+ * <td>-6.0
+ * <td>14.7
+ * <td>-4.0
+ * <td>3.9
+ * <tr>
+ * <td>Acoustic Lab
+ * <td>280
+ * <td>-3.0
+ * <td>8.0
+ * <td>-2.0
+ * <td>2.0
+ * <tr>
+ * <td>Closet
+ * <td>150
+ * <td>-10.0
+ * <td>2.5
+ * <td>-7.0
+ * <td>0.6
* </tbody>
* </table>
*
@@ -199,7 +189,7 @@
* @since 1.5
*/
public String getName() {
- return name;
+ return name;
}
/**
@@ -257,11 +247,11 @@
/**
* Indicates whether the specified object is equal to this reverb type,
- * returning {@code true} if the objects are identical.
+ * returning {@code true} if the objects are the same.
*
* @param obj the reference object with which to compare
- * @return {@code true} if this reverb type is the same as {@code obj};
- * {@code false} otherwise
+ * @return {@code true} if the specified object is equal to this reverb
+ * type; {@code false} otherwise
*/
@Override
public final boolean equals(Object obj) {
@@ -269,7 +259,9 @@
}
/**
- * Finalizes the hashcode method.
+ * Returns a hash code value for this reverb type.
+ *
+ * @return a hash code value for this reverb type
*/
@Override
public final int hashCode() {
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/SourceDataLine.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/SourceDataLine.java Thu Aug 31 13:00:23 2017 -0700
@@ -168,9 +168,9 @@
* {@code IllegalArgumentException}.
*
* @param b a byte array containing data to be written to the data line
+ * @param off the offset from the beginning of the array, in bytes
* @param len the length, in bytes, of the valid data in the array (in
* other words, the requested amount of data to write, in bytes)
- * @param off the offset from the beginning of the array, in bytes
* @return the number of bytes actually written
* @throws IllegalArgumentException if the requested number of bytes does
* not represent an integral number of sample frames, or if
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/UnsupportedAudioFileException.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/UnsupportedAudioFileException.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -35,11 +35,14 @@
*/
public class UnsupportedAudioFileException extends Exception {
+ /**
+ * Use serialVersionUID from JDK 1.3 for interoperability.
+ */
private static final long serialVersionUID = -139127412623160368L;
/**
- * Constructs an {@code UnsupportedAudioFileException} that has
- * {@code null} as its error detail message.
+ * Constructs an {@code UnsupportedAudioFileException} that has {@code null}
+ * as its error detail message.
*/
public UnsupportedAudioFileException() {
super();
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/package-info.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/package-info.java Thu Aug 31 13:00:23 2017 -0700
@@ -30,8 +30,8 @@
* <h2>Related Documentation</h2>
* For more information on using Java Sound see:
* <ul>
- * <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
- * The Java Sound Tutorial</a></li>
+ * <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
+ * The Java Sound Tutorial</a>
* </ul>
*
* @since 1.3
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileReader.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileReader.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -68,15 +68,15 @@
throws UnsupportedAudioFileException, IOException;
/**
- * Obtains the audio file format of the URL provided. The URL must point to
- * valid audio file data.
+ * Obtains the audio file format of the {@code URL} provided. The
+ * {@code URL} must point to valid audio file data.
*
- * @param url the URL from which file format information should be
+ * @param url the {@code URL} from which file format information should be
* extracted
* @return an {@code AudioFileFormat} object describing the audio file
* format
- * @throws UnsupportedAudioFileException if the URL does not point to valid
- * audio file data recognized by the system
+ * @throws UnsupportedAudioFileException if the {@code URL} does not point
+ * to valid audio file data recognized by the system
* @throws IOException if an I/O exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
@@ -84,11 +84,11 @@
throws UnsupportedAudioFileException, IOException;
/**
- * Obtains the audio file format of the {@code File} provided.
- * The {@code File} must point to valid audio file data.
+ * Obtains the audio file format of the {@code File} provided. The
+ * {@code File} must point to valid audio file data.
*
- * @param file the {@code File} from which file format information
- * should be extracted
+ * @param file the {@code File} from which file format information should
+ * be extracted
* @return an {@code AudioFileFormat} object describing the audio file
* format
* @throws UnsupportedAudioFileException if the {@code File} does not point
@@ -123,15 +123,15 @@
throws UnsupportedAudioFileException, IOException;
/**
- * Obtains an audio input stream from the URL provided. The URL must point
- * to valid audio file data.
+ * Obtains an audio input stream from the {@code URL} provided. The
+ * {@code URL} must point to valid audio file data.
*
- * @param url the URL for which the {@code AudioInputStream} should be
- * constructed
+ * @param url the {@code URL} for which the {@code AudioInputStream} should
+ * be constructed
* @return an {@code AudioInputStream} object based on the audio file data
- * pointed to by the URL
- * @throws UnsupportedAudioFileException if the URL does not point to valid
- * audio file data recognized by the system
+ * pointed to by the {@code URL}
+ * @throws UnsupportedAudioFileException if the {@code URL} does not point
+ * to valid audio file data recognized by the system
* @throws IOException if an I/O exception occurs
* @throws NullPointerException if {@code url} is {@code null}
*/
@@ -139,8 +139,8 @@
throws UnsupportedAudioFileException, IOException;
/**
- * Obtains an audio input stream from the {@code File} provided.
- * The {@code File} must point to valid audio file data.
+ * Obtains an audio input stream from the {@code File} provided. The
+ * {@code File} must point to valid audio file data.
*
* @param file the {@code File} for which the {@code AudioInputStream}
* should be constructed
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileWriter.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/AudioFileWriter.java Thu Aug 31 13:00:23 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, 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
@@ -113,10 +113,10 @@
/**
* Writes a stream of bytes representing an audio file of the file type
- * indicated to the output stream provided. Some file types require that
- * the length be written into the file header, and cannot be written from
- * start to finish unless the length is known in advance. An attempt to
- * write such a file type will fail with an IOException if the length in the
+ * indicated to the output stream provided. Some file types require that the
+ * length be written into the file header, and cannot be written from start
+ * to finish unless the length is known in advance. An attempt to write such
+ * a file type will fail with an {@code IOException} if the length in the
* audio file format is {@link AudioSystem#NOT_SPECIFIED}.
*
* @param stream the audio input stream containing audio data to be written
--- a/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/package-info.java Thu Aug 31 13:09:31 2017 -0700
+++ b/jdk/src/java.desktop/share/classes/javax/sound/sampled/spi/package-info.java Thu Aug 31 13:00:23 2017 -0700
@@ -30,8 +30,8 @@
* <h2>Related Documentation</h2>
* For more information on using Java Sound see:
* <ul>
- * <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
- * The Java Sound Tutorial</a></li>
+ * <li><a href="https://docs.oracle.com/javase/tutorial/sound/">
+ * The Java Sound Tutorial</a>
* </ul>
*
* @since 1.3