OpenJDK / jdk / jdk10
changeset 26003:d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
Reviewed-by: pchelko, azvegint
line wrap: on
line diff
--- a/jdk/src/share/classes/javax/sound/midi/ControllerEventListener.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/ControllerEventListener.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -27,38 +27,35 @@ import java.util.EventListener; - /** - * The <code>ControllerEventListener</code> interface should be implemented - * by classes whose instances need to be notified when a <code>Sequencer</code> - * has processed a requested type of MIDI control-change event. - * To register a <code>ControllerEventListener</code> object to receive such - * notifications, invoke the + * The {@code ControllerEventListener} interface should be implemented by + * classes whose instances need to be notified when a {@link Sequencer} has + * processed a requested type of MIDI control-change event. To register a + * {@code ControllerEventListener} object to receive such notifications, invoke + * the * {@link Sequencer#addControllerEventListener(ControllerEventListener, int[]) - * addControllerEventListener} method of <code>Sequencer</code>, - * specifying the types of MIDI controllers about which you are interested in - * getting control-change notifications. - * - * @see MidiChannel#controlChange(int, int) + * addControllerEventListener} method of {@code Sequencer}, specifying the types + * of MIDI controllers about which you are interested in getting control-change + * notifications. * * @author Kara Kytle + * @see MidiChannel#controlChange(int, int) */ public interface ControllerEventListener extends EventListener { /** - * Invoked when a <code>Sequencer</code> has encountered and processed - * a control-change event of interest to this listener. The event passed - * in is a <code>ShortMessage</code> whose first data byte indicates - * the controller number and whose second data byte is the value to which - * the controller was set. + * Invoked when a {@link Sequencer} has encountered and processed a + * control-change event of interest to this listener. The event passed in is + * a {@code ShortMessage} whose first data byte indicates the controller + * number and whose second data byte is the value to which the controller + * was set. * - * @param event the control-change event that the sequencer encountered in - * the sequence it is processing - * + * @param event the control-change event that the sequencer encountered in + * the sequence it is processing * @see Sequencer#addControllerEventListener(ControllerEventListener, int[]) * @see MidiChannel#controlChange(int, int) * @see ShortMessage#getData1 * @see ShortMessage#getData2 */ - public void controlChange(ShortMessage event); + void controlChange(ShortMessage event); }
--- a/jdk/src/share/classes/javax/sound/midi/Instrument.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/Instrument.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -25,49 +25,41 @@ package javax.sound.midi; -import java.net.URL; - - - /** - * An instrument is a sound-synthesis algorithm with certain parameter - * settings, usually designed to emulate a specific real-world - * musical instrument or to achieve a specific sort of sound effect. - * Instruments are typically stored in collections called soundbanks. - * Before the instrument can be used to play notes, it must first be loaded - * onto a synthesizer, and then it must be selected for use on - * one or more channels, via a program-change command. MIDI notes - * that are subsequently received on those channels will be played using + * An instrument is a sound-synthesis algorithm with certain parameter settings, + * usually designed to emulate a specific real-world musical instrument or to + * achieve a specific sort of sound effect. Instruments are typically stored in + * collections called soundbanks. Before the instrument can be used to play + * notes, it must first be loaded onto a synthesizer, and then it must be + * selected for use on one or more channels, via a program-change command. MIDI + * notes that are subsequently received on those channels will be played using * the sound of the selected instrument. * + * @author Kara Kytle * @see Soundbank * @see Soundbank#getInstruments * @see Patch * @see Synthesizer#loadInstrument(Instrument) * @see MidiChannel#programChange(int, int) - * @author Kara Kytle */ - public abstract class Instrument extends SoundbankResource { - /** - * Instrument patch + * Instrument patch. */ private final Patch patch; - /** - * Constructs a new MIDI instrument from the specified <code>Patch</code>. - * When a subsequent request is made to load the - * instrument, the sound bank will search its contents for this instrument's <code>Patch</code>, - * and the instrument will be loaded into the synthesizer at the - * bank and program location indicated by the <code>Patch</code> object. - * @param soundbank sound bank containing the instrument - * @param patch the patch of this instrument - * @param name the name of this instrument - * @param dataClass the class used to represent the sample's data. + * Constructs a new MIDI instrument from the specified {@code Patch}. When a + * subsequent request is made to load the instrument, the sound bank will + * search its contents for this instrument's {@code Patch}, and the + * instrument will be loaded into the synthesizer at the bank and program + * location indicated by the {@code Patch} object. * + * @param soundbank sound bank containing the instrument + * @param patch the patch of this instrument + * @param name the name of this instrument + * @param dataClass the class used to represent the sample's data * @see Synthesizer#loadInstrument(Instrument) */ protected Instrument(Soundbank soundbank, Patch patch, String name, Class<?> dataClass) { @@ -76,10 +68,10 @@ this.patch = patch; } - /** - * Obtains the <code>Patch</code> object that indicates the bank and program + * Obtains the {@code Patch} object that indicates the bank and program * numbers where this instrument is to be stored in the synthesizer. + * * @return this instrument's patch */ public Patch getPatch() {
--- a/jdk/src/share/classes/javax/sound/midi/InvalidMidiDataException.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/InvalidMidiDataException.java Wed Jul 23 16:19:26 2014 +0400 @@ -25,25 +25,25 @@ package javax.sound.midi; - /** - * An <code>InvalidMidiDataException</code> indicates that inappropriate MIDI - * data was encountered. This often means that the data is invalid in and of - * itself, from the perspective of the MIDI specification. An example would - * be an undefined status byte. However, the exception might simply - * mean that the data was invalid in the context it was used, or that - * the object to which the data was given was unable to parse or use it. - * For example, a file reader might not be able to parse a Type 2 MIDI file, even - * though that format is defined in the MIDI specification. + * An {@code InvalidMidiDataException} indicates that inappropriate MIDI data + * was encountered. This often means that the data is invalid in and of itself, + * from the perspective of the MIDI specification. An example would be an + * undefined status byte. However, the exception might simply mean that the data + * was invalid in the context it was used, or that the object to which the data + * was given was unable to parse or use it. For example, a file reader might not + * be able to parse a Type 2 MIDI file, even though that format is defined in + * the MIDI specification. * * @author Kara Kytle */ public class InvalidMidiDataException extends Exception { + private static final long serialVersionUID = 2780771756789932067L; /** - * Constructs an <code>InvalidMidiDataException</code> with - * <code>null</code> for its error detail message. + * Constructs an {@code InvalidMidiDataException} with {@code null} for its + * error detail message. */ public InvalidMidiDataException() { @@ -51,10 +51,10 @@ } /** - * Constructs an <code>InvalidMidiDataException</code> with the - * specified detail message. + * Constructs an {@code InvalidMidiDataException} with the specified detail + * message. * - * @param message the string to display as an error detail message + * @param message the string to display as an error detail message */ public InvalidMidiDataException(String message) {
--- a/jdk/src/share/classes/javax/sound/midi/MetaEventListener.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MetaEventListener.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -27,24 +27,23 @@ import java.util.EventListener; - /** - * The <code>MetaEventListener</code> interface should be implemented - * by classes whose instances need to be notified when a <code>{@link Sequencer}</code> - * has processed a <code>{@link MetaMessage}</code>. - * To register a <code>MetaEventListener</code> object to receive such - * notifications, pass it as the argument to the - * <code>{@link Sequencer#addMetaEventListener(MetaEventListener) addMetaEventListener}</code> - * method of <code>Sequencer</code>. + * The {@code MetaEventListener} interface should be implemented by classes + * whose instances need to be notified when a {@link Sequencer} has processed a + * {@link MetaMessage}. To register a {@code MetaEventListener} object to + * receive such notifications, pass it as the argument to the + * {@link Sequencer#addMetaEventListener(MetaEventListener) + * addMetaEventListener} method of {@code Sequencer}. * * @author Kara Kytle */ public interface MetaEventListener extends EventListener { /** - * Invoked when a <code>{@link Sequencer}</code> has encountered and processed - * a <code>MetaMessage</code> in the <code>{@link Sequence}</code> it is processing. - * @param meta the meta-message that the sequencer encountered + * Invoked when a {@link Sequencer} has encountered and processed a + * {@code MetaMessage} in the {@code Sequence} it is processing. + * + * @param meta the meta-message that the sequencer encountered */ - public void meta(MetaMessage meta); + void meta(MetaMessage meta); }
--- a/jdk/src/share/classes/javax/sound/midi/MetaMessage.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MetaMessage.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -25,65 +25,54 @@ package javax.sound.midi; - /** - * A <code>MetaMessage</code> is a <code>{@link MidiMessage}</code> that is not meaningful to synthesizers, but - * that can be stored in a MIDI file and interpreted by a sequencer program. - * (See the discussion in the <code>MidiMessage</code> - * class description.) The Standard MIDI Files specification defines - * various types of meta-events, such as sequence number, lyric, cue point, - * and set tempo. There are also meta-events - * for such information as lyrics, copyrights, tempo indications, time and key - * signatures, markers, etc. For more information, see the Standard MIDI Files 1.0 - * specification, which is part of the Complete MIDI 1.0 Detailed Specification - * published by the MIDI Manufacturer's Association + * A {@code MetaMessage} is a {@link MidiMessage} that is not meaningful to + * synthesizers, but that can be stored in a MIDI file and interpreted by a + * sequencer program. (See the discussion in the {@code MidiMessage} class + * description.) The Standard MIDI Files specification defines various types of + * meta-events, such as sequence number, lyric, cue point, and set tempo. There + * are also meta-events for such information as lyrics, copyrights, tempo + * indications, time and key signatures, markers, etc. For more information, see + * the Standard MIDI Files 1.0 specification, which is part of the Complete MIDI + * 1.0 Detailed Specification published by the MIDI Manufacturer's Association * (<a href = http://www.midi.org>http://www.midi.org</a>). - * * <p> - * When data is being transported using MIDI wire protocol, - * a <code>{@link ShortMessage}</code> with the status value <code>0xFF</code> represents - * a system reset message. In MIDI files, this same status value denotes a <code>MetaMessage</code>. - * The types of meta-message are distinguished from each other by the first byte - * that follows the status byte <code>0xFF</code>. The subsequent bytes are data - * bytes. As with system exclusive messages, there are an arbitrary number of - * data bytes, depending on the type of <code>MetaMessage</code>. - * - * @see MetaEventListener + * When data is being transported using MIDI wire protocol, a + * {@link ShortMessage} with the status value {@code 0xFF} represents a system + * reset message. In MIDI files, this same status value denotes a + * {@code MetaMessage}. The types of meta-message are distinguished from each + * other by the first byte that follows the status byte {@code 0xFF}. The + * subsequent bytes are data bytes. As with system exclusive messages, there are + * an arbitrary number of data bytes, depending on the type of + * {@code MetaMessage}. * * @author David Rivas * @author Kara Kytle + * @see MetaEventListener */ - public class MetaMessage extends MidiMessage { - - // Status byte defines - /** - * Status byte for <code>MetaMessage</code> (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. + * 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. + * * @see MidiMessage#getStatus */ public static final int META = 0xFF; // 255 - // Instance variables - /** - * The length of the actual message in the data array. - * This is used to determine how many bytes of the data array - * is the message, and how many are the status byte, the - * type byte, and the variable-length-int describing the - * length of the message. + * The length of the actual message in the data array. This is used to + * determine how many bytes of the data array is the message, and how many + * are the status byte, the type byte, and the variable-length-int + * describing the length of the message. */ private int dataLength = 0; - /** - * Constructs a new <code>MetaMessage</code>. The contents of - * the message are not set here; use - * {@link #setMessage(int, byte[], int) setMessage} - * to set them subsequently. + * Constructs a new {@code MetaMessage}. The contents of the message are not + * set here; use {@link #setMessage(int, byte[], int) setMessage} to set + * them subsequently. */ public MetaMessage() { // Default meta message data: just the META status byte value @@ -91,17 +80,17 @@ } /** - * Constructs a new {@code MetaMessage} and sets the message parameters. - * The contents of the message can be changed by using - * the {@code setMessage} method. + * Constructs a new {@code MetaMessage} and sets the message parameters. The + * contents of the message can be changed by using the {@code setMessage} + * method. * - * @param type meta-message type (must be less than 128) - * @param data the data bytes in the MIDI message - * @param length an amount of bytes in the {@code data} byte array; - * it 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 + * @param type meta-message type (must be less than 128) + * @param data the data bytes in the MIDI message + * @param length an amount of bytes in the {@code data} byte array; it + * 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 * @see #setMessage(int, byte[], int) * @see #getType() * @see #getData() @@ -113,12 +102,11 @@ setMessage(type, data, length); // can throw InvalidMidiDataException } - /** - * Constructs a new <code>MetaMessage</code>. - * @param data an array of bytes containing the complete message. - * The message data may be changed using the <code>setMessage</code> - * method. + * Constructs a new {@code MetaMessage}. + * + * @param data an array of bytes containing the complete message. The + * message data may be changed using the {@code setMessage} method. * @see #setMessage */ protected MetaMessage(byte[] data) { @@ -133,24 +121,24 @@ } } - /** - * Sets the message parameters for a <code>MetaMessage</code>. - * Since only one status byte value, <code>0xFF</code>, is allowed for meta-messages, - * it does not need to be specified here. Calls to <code>{@link MidiMessage#getStatus getStatus}</code> return - * <code>0xFF</code> for all meta-messages. + * Sets the message parameters for a {@code MetaMessage}. Since only one + * status byte value, {@code 0xFF}, is allowed for meta-messages, it does + * not need to be specified here. Calls to + * {@link MidiMessage#getStatus getStatus} return {@code 0xFF} for all + * meta-messages. * <p> - * The <code>type</code> argument should be a valid value for the byte that - * follows the status byte in the <code>MetaMessage</code>. The <code>data</code> argument - * should contain all the subsequent bytes of the <code>MetaMessage</code>. In other words, - * the byte that specifies the type of <code>MetaMessage</code> is not considered a data byte. + * The {@code type} argument should be a valid value for the byte that + * follows the status byte in the {@code MetaMessage}. The {@code data} + * argument should contain all the subsequent bytes of the + * {@code MetaMessage}. In other words, the byte that specifies the type of + * {@code MetaMessage} is not considered a data byte. * - * @param type meta-message type (must be less than 128) - * @param data the data bytes in the MIDI message - * @param length the number of bytes in the <code>data</code> - * byte array - * @throws InvalidMidiDataException if the - * parameter values do not specify a valid MIDI meta message + * @param type meta-message type (must be less than 128) + * @param data the data bytes in the MIDI message + * @param length the number of bytes in the {@code data} byte array + * @throws InvalidMidiDataException if the parameter values do not specify a + * valid MIDI meta message */ public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException { @@ -172,10 +160,10 @@ } } - /** - * Obtains the type of the <code>MetaMessage</code>. - * @return an integer representing the <code>MetaMessage</code> type + * Obtains the type of the {@code MetaMessage}. + * + * @return an integer representing the {@code MetaMessage} type */ public int getType() { if (length>=2) { @@ -184,16 +172,15 @@ return 0; } - - /** - * Obtains a copy of the data for the meta message. The returned - * array of bytes does not include the status byte or the message - * length data. The length of the data for the meta message is - * the length of the array. Note that the length of the entire - * message includes the status byte and the meta message type - * byte, and therefore may be longer than the returned array. - * @return array containing the meta message data. + * Obtains a copy of the data for the meta message. The returned array of + * bytes does not include the status byte or the message length data. The + * length of the data for the meta message is the length of the array. Note + * that the length of the entire message includes the status byte and the + * meta message type byte, and therefore may be longer than the returned + * array. + * + * @return array containing the meta message data * @see MidiMessage#getLength */ public byte[] getData() { @@ -202,10 +189,10 @@ return returnedArray; } - /** - * Creates a new object of the same class and with the same contents - * as this object. + * Creates a new object of the same class and with the same contents as this + * object. + * * @return a clone of this instance */ public Object clone() { @@ -240,5 +227,4 @@ } data[off] = (byte) (value & mask); } - }
--- a/jdk/src/share/classes/javax/sound/midi/MidiChannel.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MidiChannel.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, 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 @@ -25,513 +25,450 @@ package javax.sound.midi; - /** - * A <code>MidiChannel</code> object represents a single MIDI channel. - * Generally, each <code>MidiChannel</code> method processes a like-named MIDI - * "channel voice" or "channel mode" message as defined by the MIDI specification. However, - * <code>MidiChannel</code> adds some "get" methods that retrieve the value - * most recently set by one of the standard MIDI channel messages. Similarly, - * methods for per-channel solo and mute have been added. + * A {@code MidiChannel} object represents a single MIDI channel. Generally, + * each {@code MidiChannel} method processes a like-named MIDI "channel voice" + * or "channel mode" message as defined by the MIDI specification. However, + * {@code MidiChannel} adds some "get" methods that retrieve the value most + * recently set by one of the standard MIDI channel messages. Similarly, methods + * for per-channel solo and mute have been added. * <p> - * A <code>{@link Synthesizer}</code> object has a collection - * of <code>MidiChannels</code>, usually one for each of the 16 channels - * prescribed by the MIDI 1.0 specification. The <code>Synthesizer</code> - * generates sound when its <code>MidiChannels</code> receive - * <code>noteOn</code> messages. + * A {@link Synthesizer} object has a collection of {@code MidiChannels}, + * usually one for each of the 16 channels prescribed by the MIDI 1.0 + * specification. The {@code Synthesizer} generates sound when its + * {@code MidiChannels} receive {@code noteOn} messages. * <p> * See the MIDI 1.0 Specification for more information about the prescribed - * behavior of the MIDI channel messages, which are not exhaustively - * documented here. The specification is titled <code>MIDI Reference: - * The Complete MIDI 1.0 Detailed Specification</code>, and is published by - * the MIDI Manufacturer's Association (<a href = http://www.midi.org> - * http://www.midi.org</a>). + * behavior of the MIDI channel messages, which are not exhaustively documented + * here. The specification is titled + * {@code MIDI Reference: The Complete MIDI 1.0 Detailed Specification}, and is + * published by the MIDI Manufacturer's Association + * (<a href = http://www.midi.org>http://www.midi.org</a>). * <p> * MIDI was originally a protocol for reporting the gestures of a keyboard - * musician. This genesis is visible in the <code>MidiChannel</code> API, which + * musician. This genesis is visible in the {@code MidiChannel} API, which * preserves such MIDI concepts as key number, key velocity, and key pressure. * It should be understood that the MIDI data does not necessarily originate * with a keyboard player (the source could be a different kind of musician, or - * software). Some devices might generate constant values for velocity - * and pressure, regardless of how the note was performed. - * Also, the MIDI specification often leaves it up to the - * synthesizer to use the data in the way the implementor sees fit. For - * example, velocity data need not always be mapped to volume and/or brightness. - * - * @see Synthesizer#getChannels + * software). Some devices might generate constant values for velocity and + * pressure, regardless of how the note was performed. Also, the MIDI + * specification often leaves it up to the synthesizer to use the data in the + * way the implementor sees fit. For example, velocity data need not always be + * mapped to volume and/or brightness. * * @author David Rivas * @author Kara Kytle + * @see Synthesizer#getChannels */ - public interface MidiChannel { /** - * Starts the specified note sounding. The key-down velocity - * usually controls the note's volume and/or brightness. - * If <code>velocity</code> is zero, this method instead acts like - * {@link #noteOff(int)}, terminating the note. + * Starts the specified note sounding. The key-down velocity usually + * controls the note's volume and/or brightness. If {@code velocity} is + * zero, this method instead acts like {@link #noteOff(int)}, terminating + * the note. * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) - * @param velocity the speed with which the key was depressed - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) + * @param velocity the speed with which the key was depressed * @see #noteOff(int, int) */ - public void noteOn(int noteNumber, int velocity); + void noteOn(int noteNumber, int velocity); /** - * Turns the specified note off. The key-up velocity, if not ignored, can - * be used to affect how quickly the note decays. - * In any case, the note might not die away instantaneously; its decay - * rate is determined by the internals of the <code>Instrument</code>. - * If the Hold Pedal (a controller; see - * {@link #controlChange(int, int) controlChange}) - * is down, the effect of this method is deferred until the pedal is - * released. + * Turns the specified note off. The key-up velocity, if not ignored, can be + * used to affect how quickly the note decays. In any case, the note might + * not die away instantaneously; its decay rate is determined by the + * internals of the {@code Instrument}. If the Hold Pedal (a controller; see + * {@link #controlChange(int, int) controlChange}) is down, the effect of + * this method is deferred until the pedal is released. * - * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) - * @param velocity the speed with which the key was released - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) + * @param velocity the speed with which the key was released * @see #noteOff(int) * @see #noteOn * @see #allNotesOff * @see #allSoundOff */ - public void noteOff(int noteNumber, int velocity); + void noteOff(int noteNumber, int velocity); /** * Turns the specified note off. * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) * @see #noteOff(int, int) */ - public void noteOff(int noteNumber); + void noteOff(int noteNumber); /** - * Reacts to a change in the specified note's key pressure. - * Polyphonic key pressure - * allows a keyboard player to press multiple keys simultaneously, each - * with a different amount of pressure. The pressure, if not ignored, - * is typically used to vary such features as the volume, brightness, - * or vibrato of the note. + * Reacts to a change in the specified note's key pressure. Polyphonic key + * pressure allows a keyboard player to press multiple keys simultaneously, + * each with a different amount of pressure. The pressure, if not ignored, + * is typically used to vary such features as the volume, brightness, or + * vibrato of the note. + * <p> + * It is possible that the underlying synthesizer does not support this MIDI + * message. In order to verify that {@code setPolyPressure} was successful, + * use {@code getPolyPressure}. * - * It is possible that the underlying synthesizer - * does not support this MIDI message. In order - * to verify that <code>setPolyPressure</code> - * was successful, use <code>getPolyPressure</code>. - * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) - * @param pressure value for the specified key, from 0 to 127 (127 = - * maximum pressure) - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) + * @param pressure value for the specified key, from 0 to 127 + * (127 = maximum pressure) * @see #getPolyPressure(int) */ - public void setPolyPressure(int noteNumber, int pressure); + void setPolyPressure(int noteNumber, int pressure); /** * Obtains the pressure with which the specified key is being depressed. - * - * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) + * <p> + * If the device does not support setting poly pressure, this method always + * returns 0. Calling {@code setPolyPressure} will have no effect then. * - * If the device does not support setting poly pressure, - * this method always returns 0. Calling - * <code>setPolyPressure</code> will have no effect then. - * + * @param noteNumber the MIDI note number, from 0 to 127 (60 = Middle C) * @return the amount of pressure for that note, from 0 to 127 - * (127 = maximum pressure) - * + * (127 = maximum pressure) * @see #setPolyPressure(int, int) */ - public int getPolyPressure(int noteNumber); + int getPolyPressure(int noteNumber); /** - * Reacts to a change in the keyboard pressure. Channel - * pressure indicates how hard the keyboard player is depressing - * the entire keyboard. This can be the maximum or - * average of the per-key pressure-sensor values, as set by - * <code>setPolyPressure</code>. More commonly, it is a measurement of - * a single sensor on a device that doesn't implement polyphonic key - * pressure. Pressure can be used to control various aspects of the sound, - * as described under {@link #setPolyPressure(int, int) setPolyPressure}. + * Reacts to a change in the keyboard pressure. Channel pressure indicates + * how hard the keyboard player is depressing the entire keyboard. This can + * be the maximum or average of the per-key pressure-sensor values, as set + * by {@code setPolyPressure}. More commonly, it is a measurement of a + * single sensor on a device that doesn't implement polyphonic key pressure. + * Pressure can be used to control various aspects of the sound, as + * described under {@link #setPolyPressure(int, int) setPolyPressure}. + * <p> + * It is possible that the underlying synthesizer does not support this MIDI + * message. In order to verify that {@code setChannelPressure} was + * successful, use {@code getChannelPressure}. * - * It is possible that the underlying synthesizer - * does not support this MIDI message. In order - * to verify that <code>setChannelPressure</code> - * was successful, use <code>getChannelPressure</code>. - * - * @param pressure the pressure with which the keyboard is being depressed, - * from 0 to 127 (127 = maximum pressure) + * @param pressure the pressure with which the keyboard is being depressed, + * from 0 to 127 (127 = maximum pressure) * @see #setPolyPressure(int, int) * @see #getChannelPressure */ - public void setChannelPressure(int pressure); + void setChannelPressure(int pressure); /** * Obtains the channel's keyboard pressure. - * If the device does not support setting channel pressure, - * this method always returns 0. Calling - * <code>setChannelPressure</code> will have no effect then. + * <p> + * If the device does not support setting channel pressure, this method + * always returns 0. Calling {@code setChannelPressure} will have no effect + * then. * - * @return the amount of pressure for that note, - * from 0 to 127 (127 = maximum pressure) - * + * @return the amount of pressure for that note, from 0 to 127 + * (127 = maximum pressure) * @see #setChannelPressure(int) */ - public int getChannelPressure(); + int getChannelPressure(); /** - * Reacts to a change in the specified controller's value. A controller - * is some control other than a keyboard key, such as a - * switch, slider, pedal, wheel, or breath-pressure sensor. - * The MIDI 1.0 Specification provides standard numbers for typical - * controllers on MIDI devices, and describes the intended effect - * for some of the controllers. - * The way in which an - * <code>Instrument</code> reacts to a controller change may be - * specific to the <code>Instrument</code>. + * Reacts to a change in the specified controller's value. A controller is + * some control other than a keyboard key, such as a switch, slider, pedal, + * wheel, or breath-pressure sensor. The MIDI 1.0 Specification provides + * standard numbers for typical controllers on MIDI devices, and describes + * the intended effect for some of the controllers. The way in which an + * {@code Instrument} reacts to a controller change may be specific to the + * {@code Instrument}. * <p> - * The MIDI 1.0 Specification defines both 7-bit controllers - * and 14-bit controllers. Continuous controllers, such - * as wheels and sliders, typically have 14 bits (two MIDI bytes), - * while discrete controllers, such as switches, typically have 7 bits - * (one MIDI byte). Refer to the specification to see the - * expected resolution for each type of control. + * The MIDI 1.0 Specification defines both 7-bit controllers and 14-bit + * controllers. Continuous controllers, such as wheels and sliders, + * typically have 14 bits (two MIDI bytes), while discrete controllers, such + * as switches, typically have 7 bits (one MIDI byte). Refer to the + * specification to see the expected resolution for each type of control. * <p> - * Controllers 64 through 95 (0x40 - 0x5F) allow 7-bit precision. - * The value of a 7-bit controller is set completely by the - * <code>value</code> argument. An additional set of controllers - * provide 14-bit precision by using two controller numbers, one - * for the most significant 7 bits and another for the least significant - * 7 bits. Controller numbers 0 through 31 (0x00 - 0x1F) control the - * most significant 7 bits of 14-bit controllers; controller numbers - * 32 through 63 (0x20 - 0x3F) control the least significant 7 bits of - * these controllers. For example, controller number 7 (0x07) controls - * the upper 7 bits of the channel volume controller, and controller - * number 39 (0x27) controls the lower 7 bits. - * The value of a 14-bit controller is determined - * by the interaction of the two halves. When the most significant 7 bits - * of a controller are set (using controller numbers 0 through 31), the - * lower 7 bits are automatically set to 0. The corresponding controller - * number for the lower 7 bits may then be used to further modulate the - * controller value. + * Controllers 64 through 95 (0x40 - 0x5F) allow 7-bit precision. The value + * of a 7-bit controller is set completely by the {@code value} argument. An + * additional set of controllers provide 14-bit precision by using two + * controller numbers, one for the most significant 7 bits and another for + * the least significant 7 bits. Controller numbers 0 through 31 + * (0x00 - 0x1F) control the most significant 7 bits of 14-bit controllers; + * controller numbers 32 through 63 (0x20 - 0x3F) control the least + * significant 7 bits of these controllers. For example, controller number 7 + * (0x07) controls the upper 7 bits of the channel volume controller, and + * controller number 39 (0x27) controls the lower 7 bits. The value of a + * 14-bit controller is determined by the interaction of the two halves. + * When the most significant 7 bits of a controller are set (using + * controller numbers 0 through 31), the lower 7 bits are automatically set + * to 0. The corresponding controller number for the lower 7 bits may then + * be used to further modulate the controller value. + * <p> + * It is possible that the underlying synthesizer does not support a + * specific controller message. In order to verify that a call to + * {@code controlChange} was successful, use {@code getController}. * - * It is possible that the underlying synthesizer - * does not support a specific controller message. In order - * to verify that a call to <code>controlChange</code> - * was successful, use <code>getController</code>. - * - * @param controller the controller number (0 to 127; see the MIDI - * 1.0 Specification for the interpretation) - * @param value the value to which the specified controller is changed (0 to 127) - * + * @param controller the controller number (0 to 127; see the MIDI 1.0 + * Specification for the interpretation) + * @param value the value to which the specified controller is changed + * (0 to 127) * @see #getController(int) */ - public void controlChange(int controller, int value); + void controlChange(int controller, int value); /** - * Obtains the current value of the specified controller. The return - * value is represented with 7 bits. For 14-bit controllers, the MSB and - * LSB controller value needs to be obtained separately. For example, - * the 14-bit value of the volume controller can be calculated by - * multiplying the value of controller 7 (0x07, channel volume MSB) - * with 128 and adding the - * value of controller 39 (0x27, channel volume LSB). + * Obtains the current value of the specified controller. The return value + * is represented with 7 bits. For 14-bit controllers, the MSB and LSB + * controller value needs to be obtained separately. For example, the 14-bit + * value of the volume controller can be calculated by multiplying the value + * of controller 7 (0x07, channel volume MSB) with 128 and adding the value + * of controller 39 (0x27, channel volume LSB). + * <p> + * If the device does not support setting a specific controller, this method + * returns 0 for that controller. Calling {@code controlChange} will have no + * effect then. * - * If the device does not support setting a specific controller, - * this method returns 0 for that controller. - * Calling <code>controlChange</code> will have no effect then. - * - * @param controller the number of the controller whose value is desired. - * The allowed range is 0-127; see the MIDI - * 1.0 Specification for the interpretation. - * + * @param controller the number of the controller whose value is desired. + * The allowed range is 0-127; see the MIDI 1.0 Specification for + * the interpretation. * @return the current value of the specified controller (0 to 127) - * * @see #controlChange(int, int) */ - public int getController(int controller); + int getController(int controller); /** - * Changes a program (patch). This selects a specific - * instrument from the currently selected bank of instruments. + * Changes a program (patch). This selects a specific instrument from the + * currently selected bank of instruments. * <p> - * The MIDI specification does not - * dictate whether notes that are already sounding should switch - * to the new instrument (timbre) or continue with their original timbre - * until terminated by a note-off. + * The MIDI specification does not dictate whether notes that are already + * sounding should switch to the new instrument (timbre) or continue with + * their original timbre until terminated by a note-off. * <p> - * The program number is zero-based (expressed from 0 to 127). - * Note that MIDI hardware displays and literature about MIDI - * typically use the range 1 to 128 instead. + * The program number is zero-based (expressed from 0 to 127). Note that + * MIDI hardware displays and literature about MIDI typically use the range + * 1 to 128 instead. + * <p> + * It is possible that the underlying synthesizer does not support a + * specific program. In order to verify that a call to {@code programChange} + * was successful, use {@code getProgram}. * - * It is possible that the underlying synthesizer - * does not support a specific program. In order - * to verify that a call to <code>programChange</code> - * was successful, use <code>getProgram</code>. - * - * @param program the program number to switch to (0 to 127) - * + * @param program the program number to switch to (0 to 127) * @see #programChange(int, int) * @see #getProgram() */ - public void programChange(int program); + void programChange(int program); /** * Changes the program using bank and program (patch) numbers. - * - * It is possible that the underlying synthesizer - * does not support a specific bank, or program. In order - * to verify that a call to <code>programChange</code> - * was successful, use <code>getProgram</code> and - * <code>getController</code>. - * Since banks are changed by way of control changes, - * you can verify the current bank with the following - * statement: + * <p> + * It is possible that the underlying synthesizer does not support a + * specific bank, or program. In order to verify that a call to + * {@code programChange} was successful, use {@code getProgram} and + * {@code getController}. Since banks are changed by way of control changes, + * you can verify the current bank with the following statement: * <pre> - * int bank = (getController(0) * 128) - * + getController(32); + * int bank = (getController(0) * 128) + getController(32); * </pre> * - * @param bank the bank number to switch to (0 to 16383) - * @param program the program (patch) to use in the specified bank (0 to 127) + * @param bank the bank number to switch to (0 to 16383) + * @param program the program (patch) to use in the specified bank + * (0 to 127) * @see #programChange(int) * @see #getProgram() */ - public void programChange(int bank, int program); + void programChange(int bank, int program); /** * Obtains the current program number for this channel. + * * @return the program number of the currently selected patch * @see Patch#getProgram * @see Synthesizer#loadInstrument * @see #programChange(int) */ - public int getProgram(); + int getProgram(); /** - * Changes the pitch offset for all notes on this channel. - * This affects all currently sounding notes as well as subsequent ones. - * (For pitch bend to cease, the value needs to be reset to the - * center position.) - * <p> The MIDI specification - * stipulates that pitch bend be a 14-bit value, where zero - * is maximum downward bend, 16383 is maximum upward bend, and - * 8192 is the center (no pitch bend). The actual - * amount of pitch change is not specified; it can be changed by - * a pitch-bend sensitivity setting. However, the General MIDI - * specification says that the default range should be two semitones - * up and down from center. + * Changes the pitch offset for all notes on this channel. This affects all + * currently sounding notes as well as subsequent ones. (For pitch bend to + * cease, the value needs to be reset to the center position.) + * <p> + * The MIDI specification stipulates that pitch bend be a 14-bit value, + * where zero is maximum downward bend, 16383 is maximum upward bend, and + * 8192 is the center (no pitch bend). The actual amount of pitch change is + * not specified; it can be changed by a pitch-bend sensitivity setting. + * However, the General MIDI specification says that the default range + * should be two semitones up and down from center. + * <p> + * It is possible that the underlying synthesizer does not support this MIDI + * message. In order to verify that {@code setPitchBend} was successful, use + * {@code getPitchBend}. * - * It is possible that the underlying synthesizer - * does not support this MIDI message. In order - * to verify that <code>setPitchBend</code> - * was successful, use <code>getPitchBend</code>. - * - * @param bend the amount of pitch change, as a nonnegative 14-bit value - * (8192 = no bend) - * + * @param bend the amount of pitch change, as a nonnegative 14-bit value + * (8192 = no bend) * @see #getPitchBend */ - public void setPitchBend(int bend); + void setPitchBend(int bend); /** - * Obtains the upward or downward pitch offset for this channel. - * If the device does not support setting pitch bend, - * this method always returns 8192. Calling - * <code>setPitchBend</code> will have no effect then. + * Obtains the upward or downward pitch offset for this channel. If the + * device does not support setting pitch bend, this method always returns + * 8192. Calling {@code setPitchBend} will have no effect then. * * @return bend amount, as a nonnegative 14-bit value (8192 = no bend) - * * @see #setPitchBend(int) */ - public int getPitchBend(); + int getPitchBend(); /** * Resets all the implemented controllers to their default values. * * @see #controlChange(int, int) */ - public void resetAllControllers(); + void resetAllControllers(); /** - * Turns off all notes that are currently sounding on this channel. - * The notes might not die away instantaneously; their decay - * rate is determined by the internals of the <code>Instrument</code>. - * If the Hold Pedal controller (see - * {@link #controlChange(int, int) controlChange}) - * is down, the effect of this method is deferred until the pedal is - * released. + * Turns off all notes that are currently sounding on this channel. The + * notes might not die away instantaneously; their decay rate is determined + * by the internals of the {@code Instrument}. If the Hold Pedal controller + * (see {@link #controlChange(int, int) controlChange}) is down, the effect + * of this method is deferred until the pedal is released. * * @see #allSoundOff * @see #noteOff(int) */ - public void allNotesOff(); + void allNotesOff(); /** * Immediately turns off all sounding notes on this channel, ignoring the * state of the Hold Pedal and the internal decay rate of the current - * <code>Instrument</code>. + * {@code Instrument}. * * @see #allNotesOff */ - public void allSoundOff(); + void allSoundOff(); /** - * Turns local control on or off. The default is for local control - * to be on. The "on" setting means that if a device is capable - * of both synthesizing sound and transmitting MIDI messages, - * it will synthesize sound in response to the note-on and - * note-off messages that it itself transmits. It will also respond - * to messages received from other transmitting devices. - * The "off" setting means that the synthesizer will ignore its - * own transmitted MIDI messages, but not those received from other devices. + * Turns local control on or off. The default is for local control to be on. + * The "on" setting means that if a device is capable of both synthesizing + * sound and transmitting MIDI messages, it will synthesize sound in + * response to the note-on and note-off messages that it itself transmits. + * It will also respond to messages received from other transmitting + * devices. The "off" setting means that the synthesizer will ignore its own + * transmitted MIDI messages, but not those received from other devices. + * <p> + * It is possible that the underlying synthesizer does not support local + * control. In order to verify that a call to {@code localControl} was + * successful, check the return value. * - * It is possible that the underlying synthesizer - * does not support local control. In order - * to verify that a call to <code>localControl</code> - * was successful, check the return value. - * - * @param on <code>true</code> to turn local control on, <code>false</code> - * to turn local control off - * @return the new local-control value, or false - * if local control is not supported - * + * @param on {@code true} to turn local control on, {@code false} to turn + * local control off + * @return the new local-control value, or false if local control is not + * supported */ - public boolean localControl(boolean on); + boolean localControl(boolean on); /** - * Turns mono mode on or off. In mono mode, the channel synthesizes - * only one note at a time. In poly mode (identical to mono mode off), - * the channel can synthesize multiple notes simultaneously. - * The default is mono off (poly mode on). + * Turns mono mode on or off. In mono mode, the channel synthesizes only one + * note at a time. In poly mode (identical to mono mode off), the channel + * can synthesize multiple notes simultaneously. The default is mono off + * (poly mode on). * <p> - * "Mono" is short for the word "monophonic," which in this context - * is opposed to the word "polyphonic" and refers to a single synthesizer - * voice per MIDI channel. It - * has nothing to do with how many audio channels there might be - * (as in "monophonic" versus "stereophonic" recordings). + * "Mono" is short for the word "monophonic," which in this context is + * opposed to the word "polyphonic" and refers to a single synthesizer voice + * per MIDI channel. It has nothing to do with how many audio channels there + * might be (as in "monophonic" versus "stereophonic" recordings). + * <p> + * It is possible that the underlying synthesizer does not support mono + * mode. In order to verify that a call to {@code setMono} was successful, + * use {@code getMono}. * - * It is possible that the underlying synthesizer - * does not support mono mode. In order - * to verify that a call to <code>setMono</code> - * was successful, use <code>getMono</code>. - * - * @param on <code>true</code> to turn mono mode on, <code>false</code> to - * turn it off (which means turning poly mode on). - * + * @param on {@code true} to turn mono mode on, {@code false} to turn it + * off (which means turning poly mode on) * @see #getMono * @see VoiceStatus */ - public void setMono(boolean on); + void setMono(boolean on); /** - * Obtains the current mono/poly mode. - * Synthesizers that do not allow changing mono/poly mode - * will always return the same value, regardless - * of calls to <code>setMono</code>. - * @return <code>true</code> if mono mode is on, otherwise - * <code>false</code> (meaning poly mode is on). + * Obtains the current mono/poly mode. Synthesizers that do not allow + * changing mono/poly mode will always return the same value, regardless of + * calls to {@code setMono}. * + * @return {@code true} if mono mode is on, otherwise {@code false} (meaning + * poly mode is on) * @see #setMono(boolean) */ - public boolean getMono(); + boolean getMono(); /** - * Turns omni mode on or off. In omni mode, the channel responds - * to messages sent on all channels. When omni is off, the channel - * responds only to messages sent on its channel number. - * The default is omni off. + * Turns omni mode on or off. In omni mode, the channel responds to messages + * sent on all channels. When omni is off, the channel responds only to + * messages sent on its channel number. The default is omni off. + * <p> + * It is possible that the underlying synthesizer does not support omni + * mode. In order to verify that {@code setOmni} was successful, use + * {@code getOmni}. * - * It is possible that the underlying synthesizer - * does not support omni mode. In order - * to verify that <code>setOmni</code> - * was successful, use <code>getOmni</code>. - * - * @param on <code>true</code> to turn omni mode on, <code>false</code> to - * turn it off. - * + * @param on {@code true} to turn omni mode on, {@code false} to turn it + * off * @see #getOmni * @see VoiceStatus */ - public void setOmni(boolean on); + void setOmni(boolean on); /** - * Obtains the current omni mode. - * Synthesizers that do not allow changing the omni mode - * will always return the same value, regardless - * of calls to <code>setOmni</code>. - * @return <code>true</code> if omni mode is on, otherwise - * <code>false</code> (meaning omni mode is off). + * Obtains the current omni mode. Synthesizers that do not allow changing + * the omni mode will always return the same value, regardless of calls to + * {@code setOmni}. * + * @return {@code true} if omni mode is on, otherwise {@code false} (meaning + * omni mode is off) * @see #setOmni(boolean) */ - public boolean getOmni(); + boolean getOmni(); /** - * Sets the mute state for this channel. A value of - * <code>true</code> means the channel is to be muted, <code>false</code> - * means the channel can sound (if other channels are not soloed). + * Sets the mute state for this channel. A value of {@code true} means the + * channel is to be muted, {@code false} means the channel can sound (if + * other channels are not soloed). * <p> - * Unlike {@link #allSoundOff()}, this method - * applies to only a specific channel, not to all channels. Further, it - * silences not only currently sounding notes, but also subsequently - * received notes. + * Unlike {@link #allSoundOff()}, this method applies to only a specific + * channel, not to all channels. Further, it silences not only currently + * sounding notes, but also subsequently received notes. + * <p> + * It is possible that the underlying synthesizer does not support muting + * channels. In order to verify that a call to {@code setMute} was + * successful, use {@code getMute}. * - * It is possible that the underlying synthesizer - * does not support muting channels. In order - * to verify that a call to <code>setMute</code> - * was successful, use <code>getMute</code>. - * - * @param mute the new mute state - * + * @param mute the new mute state * @see #getMute * @see #setSolo(boolean) */ - public void setMute(boolean mute); + void setMute(boolean mute); /** - * Obtains the current mute state for this channel. - * If the underlying synthesizer does not support - * muting this channel, this method always returns - * <code>false</code>. + * Obtains the current mute state for this channel. If the underlying + * synthesizer does not support muting this channel, this method always + * returns {@code false}. * - * @return <code>true</code> the channel is muted, - * or <code>false</code> if not - * + * @return {@code true} the channel is muted, or {@code false} if not * @see #setMute(boolean) */ - public boolean getMute(); + boolean getMute(); /** - * Sets the solo state for this channel. - * If <code>solo</code> is <code>true</code> only this channel - * and other soloed channels will sound. If <code>solo</code> - * is <code>false</code> then only other soloed channels will - * sound, unless no channels are soloed, in which case all - * unmuted channels will sound. + * Sets the solo state for this channel. If {@code solo} is {@code true} + * only this channel and other soloed channels will sound. If {@code solo} + * is {@code false} then only other soloed channels will sound, unless no + * channels are soloed, in which case all unmuted channels will sound. + * <p> + * It is possible that the underlying synthesizer does not support solo + * channels. In order to verify that a call to {@code setSolo} was + * successful, use {@code getSolo}. * - * It is possible that the underlying synthesizer - * does not support solo channels. In order - * to verify that a call to <code>setSolo</code> - * was successful, use <code>getSolo</code>. - * - * @param soloState new solo state for the channel + * @param soloState new solo state for the channel * @see #getSolo() */ - public void setSolo(boolean soloState); + void setSolo(boolean soloState); /** - * Obtains the current solo state for this channel. - * If the underlying synthesizer does not support - * solo on this channel, this method always returns - * <code>false</code>. + * Obtains the current solo state for this channel. If the underlying + * synthesizer does not support solo on this channel, this method always + * returns {@code false}. * - * @return <code>true</code> the channel is solo, - * or <code>false</code> if not - * + * @return {@code true} the channel is solo, or {@code false} if not * @see #setSolo(boolean) */ - public boolean getSolo(); + boolean getSolo(); }
--- a/jdk/src/share/classes/javax/sound/midi/MidiDevice.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MidiDevice.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -27,64 +27,52 @@ import java.util.List; - /** - * <code>MidiDevice</code> is the base interface for all MIDI devices. - * Common devices include synthesizers, sequencers, MIDI input ports, and MIDI - * output ports. - * - * <p>A <code>MidiDevice</code> can be a transmitter or a receiver of - * MIDI events, or both. Therefore, it can provide {@link Transmitter} - * or {@link Receiver} instances (or both). Typically, MIDI IN ports - * provide transmitters, MIDI OUT ports and synthesizers provide - * receivers. A Sequencer typically provides transmitters for playback - * and receivers for recording. - * - * <p>A <code>MidiDevice</code> can be opened and closed explicitly as - * well as implicitly. Explicit opening is accomplished by calling - * {@link #open}, explicit closing is done by calling {@link - * #close} on the <code>MidiDevice</code> instance. - * If an application opens a <code>MidiDevice</code> - * explicitly, it has to close it explicitly to free system resources - * and enable the application to exit cleanly. Implicit opening is - * done by calling {@link javax.sound.midi.MidiSystem#getReceiver - * MidiSystem.getReceiver} and {@link - * javax.sound.midi.MidiSystem#getTransmitter - * MidiSystem.getTransmitter}. The <code>MidiDevice</code> used by - * <code>MidiSystem.getReceiver</code> and - * <code>MidiSystem.getTransmitter</code> is implementation-dependant - * unless the properties <code>javax.sound.midi.Receiver</code> - * and <code>javax.sound.midi.Transmitter</code> are used (see the - * description of properties to select default providers in - * {@link javax.sound.midi.MidiSystem}). A <code>MidiDevice</code> - * that was opened implicitly, is closed implicitly by closing the - * <code>Receiver</code> or <code>Transmitter</code> that resulted in - * opening it. If more than one implicitly opening - * <code>Receiver</code> or <code>Transmitter</code> were obtained by - * the application, the device is closed after the last - * <code>Receiver</code> or <code>Transmitter</code> has been - * closed. On the other hand, calling <code>getReceiver</code> or - * <code>getTransmitter</code> on the device instance directly does - * not open the device implicitly. Closing these - * <code>Transmitter</code>s and <code>Receiver</code>s does not close - * the device implicitly. To use a device with <code>Receiver</code>s - * or <code>Transmitter</code>s obtained this way, the device has to - * be opened and closed explicitly. - * - * <p>If implicit and explicit opening and closing are mixed on the - * same <code>MidiDevice</code> instance, the following rules apply: +/** + * {@code MidiDevice} is the base interface for all MIDI devices. Common devices + * include synthesizers, sequencers, MIDI input ports, and MIDI output ports. + * <p> + * A {@code MidiDevice} can be a transmitter or a receiver of MIDI events, or + * both. Therefore, it can provide {@link Transmitter} or {@link Receiver} + * instances (or both). Typically, MIDI IN ports provide transmitters, MIDI OUT + * ports and synthesizers provide receivers. A Sequencer typically provides + * transmitters for playback and receivers for recording. + * <p> + * A {@code MidiDevice} can be opened and closed explicitly as well as + * implicitly. Explicit opening is accomplished by calling {@link #open}, + * explicit closing is done by calling {@link #close} on the {@code MidiDevice} + * instance. If an application opens a {@code MidiDevice} explicitly, it has to + * close it explicitly to free system resources and enable the application to + * exit cleanly. Implicit opening is done by calling + * {@link MidiSystem#getReceiver} and {@link MidiSystem#getTransmitter}. The + * {@code MidiDevice} used by {@code MidiSystem.getReceiver} and + * {@code MidiSystem.getTransmitter} is implementation-dependant unless the + * properties {@code javax.sound.midi.Receiver} and + * {@code javax.sound.midi.Transmitter} are used (see the description of + * properties to select default providers in {@link MidiSystem}). A + * {@code MidiDevice} that was opened implicitly, is closed implicitly by + * closing the {@code Receiver} or {@code Transmitter} that resulted in opening + * it. If more than one implicitly opening {@code Receiver} or + * {@code Transmitter} were obtained by the application, the device is closed + * after the last {@code Receiver} or {@code Transmitter} has been closed. On + * the other hand, calling {@code getReceiver} or {@code getTransmitter} on the + * device instance directly does not open the device implicitly. Closing these + * {@code Transmitter}s and {@code Receiver}s does not close the device + * implicitly. To use a device with {@code Receiver}s or {@code Transmitter}s + * obtained this way, the device has to be opened and closed explicitly. + * <p> + * If implicit and explicit opening and closing are mixed on the same + * {@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> + * <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> * </ul> * - * To detect if a MidiDevice represents a hardware MIDI port, the - * following programming technique can be used: + * To detect if a MidiDevice represents a hardware MIDI port, the following + * programming technique can be used: * * <pre>{@code * MidiDevice device = ...; @@ -95,193 +83,171 @@ * }</pre> * * <p> - * A <code>MidiDevice</code> includes a <code>{@link MidiDevice.Info}</code> object - * to provide manufacturer information and so on. + * A {@code MidiDevice} includes a {@link Info} object to provide manufacturer + * information and so on. * + * @author Kara Kytle + * @author Florian Bomers * @see Synthesizer * @see Sequencer * @see Receiver * @see Transmitter - * - * @author Kara Kytle - * @author Florian Bomers */ - public interface MidiDevice extends AutoCloseable { - /** * Obtains information about the device, including its Java class and - * <code>Strings</code> containing its name, vendor, and description. + * {@code Strings} containing its name, vendor, and description. * * @return device info */ - public Info getDeviceInfo(); - + Info getDeviceInfo(); /** - * Opens the device, indicating that it should now acquire any - * system resources it requires and become operational. - * - * <p>An application opening a device explicitly with this call - * has to close the device by calling {@link #close}. This is - * necessary to release system resources and allow applications to - * exit cleanly. - * + * Opens the device, indicating that it should now acquire any system + * resources it requires and become operational. + * <p> + * An application opening a device explicitly with this call has to close + * the device by calling {@link #close}. This is necessary to release system + * 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. + * Note that some devices, once closed, cannot be reopened. Attempts to + * reopen such a device will always result in a MidiUnavailableException. * - * @throws MidiUnavailableException thrown if the device cannot be - * opened due to resource restrictions. - * @throws SecurityException thrown if the device cannot be - * opened due to security restrictions. - * + * @throws MidiUnavailableException thrown if the device cannot be opened + * due to resource restrictions + * @throws SecurityException thrown if the device cannot be opened due to + * security restrictions * @see #close * @see #isOpen */ - public void open() throws MidiUnavailableException; - + void open() throws MidiUnavailableException; /** - * Closes the device, indicating that the device should now release - * any system resources it is using. - * - * <p>All <code>Receiver</code> and <code>Transmitter</code> instances - * open from this device are closed. This includes instances retrieved - * via <code>MidiSystem</code>. + * Closes the device, indicating that the device should now release any + * system resources it is using. + * <p> + * All {@code Receiver} and {@code Transmitter} instances open from this + * device are closed. This includes instances retrieved via + * {@code MidiSystem}. * * @see #open * @see #isOpen */ - public void close(); - + void close(); /** * Reports whether the device is open. * - * @return <code>true</code> if the device is open, otherwise - * <code>false</code> + * @return {@code true} if the device is open, otherwise {@code false} * @see #open * @see #close */ - public boolean isOpen(); - + boolean isOpen(); /** - * Obtains the current time-stamp of the device, in microseconds. - * If a device supports time-stamps, it should start counting at - * 0 when the device is opened and continue incrementing its - * time-stamp in microseconds until the device is closed. - * If it does not support time-stamps, it should always return - * -1. - * @return the current time-stamp of the device in microseconds, - * or -1 if time-stamping is not supported by the device. + * Obtains the current time-stamp of the device, in microseconds. If a + * device supports time-stamps, it should start counting at 0 when the + * device is opened and continue incrementing its time-stamp in microseconds + * until the device is closed. If it does not support time-stamps, it should + * always return -1. + * + * @return the current time-stamp of the device in microseconds, or -1 if + * time-stamping is not supported by the device */ - public long getMicrosecondPosition(); - + long getMicrosecondPosition(); /** - * Obtains the maximum number of MIDI IN connections available on this - * MIDI device for receiving MIDI data. - * @return maximum number of MIDI IN connections, - * or -1 if an unlimited number of connections is available. + * Obtains the maximum number of MIDI IN connections available on this MIDI + * device for receiving MIDI data. + * + * @return maximum number of MIDI IN connections, or -1 if an unlimited + * number of connections is available */ - public int getMaxReceivers(); - + int getMaxReceivers(); /** - * Obtains the maximum number of MIDI OUT connections available on this - * MIDI device for transmitting MIDI data. - * @return maximum number of MIDI OUT connections, - * or -1 if an unlimited number of connections is available. + * Obtains the maximum number of MIDI OUT connections available on this MIDI + * device for transmitting MIDI data. + * + * @return maximum number of MIDI OUT connections, or -1 if an unlimited + * number of connections is available */ - public int getMaxTransmitters(); - + int getMaxTransmitters(); /** - * Obtains a MIDI IN receiver through which the MIDI device may receive - * MIDI data. The returned receiver must be closed when the application - * has finished using it. - * - * <p>Usually the returned receiver implements - * the {@code MidiDeviceReceiver} interface. + * Obtains a MIDI IN receiver through which the MIDI device may receive MIDI + * data. The returned receiver must be closed when the application has + * finished using it. + * <p> + * Usually the returned receiver implements the {@code MidiDeviceReceiver} + * interface. + * <p> + * Obtaining a {@code Receiver} with this method does not open the device. + * To be able to use the device, it has to be opened explicitly by calling + * {@link #open}. Also, closing the {@code Receiver} does not close the + * device. It has to be closed explicitly by calling {@link #close}. * - * <p>Obtaining a <code>Receiver</code> with this method does not - * open the device. To be able to use the device, it has to be - * opened explicitly by calling {@link #open}. Also, closing the - * <code>Receiver</code> does not close the device. It has to be - * closed explicitly by calling {@link #close}. - * - * @return a receiver for the device. + * @return a receiver for the device * @throws MidiUnavailableException thrown if a receiver is not available - * due to resource restrictions + * due to resource restrictions * @see Receiver#close() */ - public Receiver getReceiver() throws MidiUnavailableException; - + Receiver getReceiver() throws MidiUnavailableException; /** - * Returns all currently active, non-closed receivers - * connected with this MidiDevice. - * A receiver can be removed - * from the device by closing it. - * - * <p>Usually the returned receivers implement - * the {@code MidiDeviceReceiver} interface. + * Returns all currently active, non-closed receivers connected with this + * MidiDevice. A receiver can be removed from the device by closing it. + * <p> + * Usually the returned receivers implement the {@code MidiDeviceReceiver} + * interface. * * @return an unmodifiable list of the open receivers * @since 1.5 */ List<Receiver> getReceivers(); - /** * Obtains a MIDI OUT connection from which the MIDI device will transmit - * MIDI data The returned transmitter must be closed when the application + * MIDI data. The returned transmitter must be closed when the application * has finished using it. - * - * <p>Usually the returned transmitter implements - * the {@code MidiDeviceTransmitter} interface. + * <p> + * Usually the returned transmitter implements the + * {@code MidiDeviceTransmitter} interface. + * <p> + * Obtaining a {@code Transmitter} with this method does not open the + * device. To be able to use the device, it has to be opened explicitly by + * calling {@link #open}. Also, closing the {@code Transmitter} does not + * close the device. It has to be closed explicitly by calling + * {@link #close}. * - * <p>Obtaining a <code>Transmitter</code> with this method does not - * open the device. To be able to use the device, it has to be - * opened explicitly by calling {@link #open}. Also, closing the - * <code>Transmitter</code> does not close the device. It has to be - * closed explicitly by calling {@link #close}. - * - * @return a MIDI OUT transmitter for the device. + * @return a MIDI OUT transmitter for the device * @throws MidiUnavailableException thrown if a transmitter is not available - * due to resource restrictions + * due to resource restrictions * @see Transmitter#close() */ - public Transmitter getTransmitter() throws MidiUnavailableException; - + Transmitter getTransmitter() throws MidiUnavailableException; /** - * Returns all currently active, non-closed transmitters - * connected with this MidiDevice. - * A transmitter can be removed - * from the device by closing it. - * - * <p>Usually the returned transmitters implement - * the {@code MidiDeviceTransmitter} interface. + * Returns all currently active, non-closed transmitters connected with this + * MidiDevice. A transmitter can be removed from the device by closing it. + * <p> + * Usually the returned transmitters implement the + * {@code MidiDeviceTransmitter} interface. * * @return an unmodifiable list of the open transmitters * @since 1.5 */ List<Transmitter> getTransmitters(); - - /** - * A <code>MidiDevice.Info</code> object contains assorted - * data about a <code>{@link MidiDevice}</code>, including its - * name, the company who created it, and descriptive text. + * A {@code MidiDevice.Info} object contains assorted data about a + * {@link MidiDevice}, including its name, the company who created it, and + * descriptive text. * * @see MidiDevice#getDeviceInfo */ - public static class Info { + class Info { /** * The device's name. @@ -303,16 +269,16 @@ */ private String version; - /** * Constructs a device info object. * - * @param name the name of the device - * @param vendor the name of the company who provides the device - * @param description a description of the device - * @param version version information for the device + * @param name the name of the device + * @param vendor the name of the company who provides the device + * @param description a description of the device + * @param version version information for the device */ - protected Info(String name, String vendor, String description, String version) { + protected Info(String name, String vendor, String description, + String version) { this.name = name; this.vendor = vendor; @@ -320,20 +286,18 @@ this.version = version; } - /** - * Reports whether two objects are equal. - * Returns <code>true</code> if the objects are identical. - * @param obj the reference object with which to compare this - * object - * @return <code>true</code> if this object is the same as the - * <code>obj</code> argument; <code>false</code> otherwise + * Reports whether two objects are equal. Returns {@code true} if the + * objects are identical. + * + * @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 */ public final boolean equals(Object obj) { return super.equals(obj); } - /** * Finalizes the hashcode method. */ @@ -341,7 +305,6 @@ return super.hashCode(); } - /** * Obtains the name of the device. * @@ -351,43 +314,40 @@ return name; } - /** * Obtains the name of the company who supplies the device. + * * @return device the vendor's name */ public final String getVendor() { return vendor; } - /** * Obtains the description of the device. + * * @return a description of the device */ public final String getDescription() { return description; } - /** * Obtains the version of the device. + * * @return textual version information for the device. */ public final String getVersion() { return version; } - /** * Provides a string representation of the device information. - + * * @return a description of the info object */ public final String toString() { return name; } } // class Info - - }
--- a/jdk/src/share/classes/javax/sound/midi/MidiDeviceReceiver.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MidiDeviceReceiver.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2010, 2014, 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 @@ -26,16 +26,18 @@ package javax.sound.midi; /** - * <p>{@code MidiDeviceReceiver} is a {@code Receiver} which represents - * a MIDI input connector of a {@code MidiDevice} - * (see {@link MidiDevice#getReceiver()}). + * {@code MidiDeviceReceiver} is a {@code Receiver} which represents a MIDI + * input connector of a {@code MidiDevice} (see + * {@link MidiDevice#getReceiver()}). * * @since 1.7 */ public interface MidiDeviceReceiver extends Receiver { + /** * Obtains a MidiDevice object which is an owner of this Receiver. + * * @return a MidiDevice object which is an owner of this Receiver */ - public MidiDevice getMidiDevice(); + MidiDevice getMidiDevice(); }
--- a/jdk/src/share/classes/javax/sound/midi/MidiDeviceTransmitter.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MidiDeviceTransmitter.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2010, 2014, 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 @@ -25,11 +25,10 @@ package javax.sound.midi; - /** - * <p>{@code MidiDeviceTransmitter} is a {@code Transmitter} which represents - * a MIDI input connector of a {@code MidiDevice} - * (see {@link MidiDevice#getTransmitter()}). + * {@code MidiDeviceTransmitter} is a {@code Transmitter} which represents a + * MIDI input connector of a {@code MidiDevice} (see + * {@link MidiDevice#getTransmitter()}). * * @since 1.7 */ @@ -37,7 +36,8 @@ /** * Obtains a MidiDevice object which is an owner of this Transmitter. + * * @return a MidiDevice object which is an owner of this Transmitter */ - public MidiDevice getMidiDevice(); + MidiDevice getMidiDevice(); }
--- a/jdk/src/share/classes/javax/sound/midi/MidiEvent.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MidiEvent.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -26,41 +26,35 @@ package javax.sound.midi; /** - * MIDI events contain a MIDI message and a corresponding time-stamp - * expressed in ticks, and can represent the MIDI event information - * stored in a MIDI file or a <code>{@link Sequence}</code> object. The - * duration of a tick is specified by the timing information contained - * in the MIDI file or <code>Sequence</code> object. + * MIDI events contain a MIDI message and a corresponding time-stamp expressed + * in ticks, and can represent the MIDI event information stored in a MIDI file + * or a {@link Sequence} object. The duration of a tick is specified by the + * timing information contained in the MIDI file or {@code Sequence} object. * <p> - * In Java Sound, <code>MidiEvent</code> objects are typically contained in a - * <code>{@link Track}</code>, and <code>Tracks</code> are likewise - * contained in a <code>Sequence</code>. - * + * In Java Sound, {@code MidiEvent} objects are typically contained in a + * {@link Track}, and {@code Tracks} are likewise contained in a + * {@code Sequence}. * * @author David Rivas * @author Kara Kytle */ public class MidiEvent { - - // Instance variables - /** * The MIDI message for this event. */ private final MidiMessage message; - /** * The tick value for this event. */ private long tick; - /** - * Constructs a new <code>MidiEvent</code>. - * @param message the MIDI message contained in the event - * @param tick the time-stamp for the event, in MIDI ticks + * Constructs a new {@code MidiEvent}. + * + * @param message the MIDI message contained in the event + * @param tick the time-stamp for the event, in MIDI ticks */ public MidiEvent(MidiMessage message, long tick) { @@ -70,24 +64,25 @@ /** * Obtains the MIDI message contained in the event. + * * @return the MIDI message */ public MidiMessage getMessage() { return message; } - /** - * Sets the time-stamp for the event, in MIDI ticks - * @param tick the new time-stamp, in MIDI ticks + * Sets the time-stamp for the event, in MIDI ticks. + * + * @param tick the new time-stamp, in MIDI ticks */ public void setTick(long tick) { this.tick = tick; } - /** - * Obtains the time-stamp for the event, in MIDI ticks + * Obtains the time-stamp for the event, in MIDI ticks. + * * @return the time-stamp for the event, in MIDI ticks */ public long getTick() {
--- a/jdk/src/share/classes/javax/sound/midi/MidiFileFormat.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MidiFileFormat.java Wed Jul 23 16:19:26 2014 +0400 @@ -25,29 +25,23 @@ package javax.sound.midi; -import java.io.InputStream; -import java.io.IOException; import java.util.Collections; import java.util.HashMap; import java.util.Map; - /** - * A <code>MidiFileFormat</code> object encapsulates a MIDI file's - * type, as well as its length and timing information. - * - * <p>A <code>MidiFileFormat</code> object can - * include a set of properties. A property is a pair of key and value: - * the key is of type <code>String</code>, the associated property - * value is an arbitrary object. - * Properties specify additional informational - * meta data (like a author, or copyright). - * Properties are optional information, and file reader and file - * writer implementations are not required to provide or - * recognize properties. - * - * <p>The following table lists some common properties that should - * be used in implementations: + * A {@code MidiFileFormat} object encapsulates a MIDI file's type, as well as + * its length and timing information. + * <p> + * A {@code MidiFileFormat} object can include a set of properties. A property + * is a pair of key and value: the key is of type {@code String}, the associated + * property value is an arbitrary object. Properties specify additional + * informational meta data (like a author, or copyright). Properties are + * optional information, and file reader and file writer implementations are not + * required to provide or recognize properties. + * <p> + * The following table lists some common properties that should be used in + * implementations: * * <table border=1> <caption>MIDI File Format Properties</caption> @@ -83,24 +77,21 @@ * </tr> * </table> * - * @see MidiSystem#getMidiFileFormat(java.io.File) - * @see Sequencer#setSequence(java.io.InputStream stream) - * * @author Kara Kytle * @author Florian Bomers + * @see MidiSystem#getMidiFileFormat(java.io.File) + * @see Sequencer#setSequence(java.io.InputStream stream) */ - public class MidiFileFormat { - /** * Represents unknown length. + * * @see #getByteLength * @see #getMicrosecondLength */ public static final int UNKNOWN_LENGTH = -1; - /** * The type of MIDI file. */ @@ -132,19 +123,22 @@ */ protected long microsecondLength; - - /** The set of properties */ + /** + * The set of properties. + */ private HashMap<String, Object> properties; - /** - * Constructs a <code>MidiFileFormat</code>. + * Constructs a {@code MidiFileFormat}. * - * @param type the MIDI file type (0, 1, or 2) - * @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 microseconds the duration of the file in microseconds, or UNKNOWN_LENGTH if not known + * @param type the MIDI file type (0, 1, or 2) + * @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 microseconds the duration of the file in microseconds, or + * UNKNOWN_LENGTH if not known * @see #UNKNOWN_LENGTH * @see Sequence#PPQ * @see Sequence#SMPTE_24 @@ -162,21 +156,18 @@ this.properties = null; } - /** - * Construct a <code>MidiFileFormat</code> with a set of properties. + * Construct a {@code MidiFileFormat} with a set of properties. * - * @param type the MIDI file type (0, 1, or 2) - * @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 microseconds the duration of the file in microseconds, - * or UNKNOWN_LENGTH if not known - * @param properties a <code>Map<String,Object></code> object - * with properties - * + * @param type the MIDI file type (0, 1, or 2) + * @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 microseconds the duration of the file in microseconds, or + * UNKNOWN_LENGTH if not known + * @param properties a {@code Map<String,Object>} object with properties * @see #UNKNOWN_LENGTH * @see Sequence#PPQ * @see Sequence#SMPTE_24 @@ -192,10 +183,9 @@ this.properties = new HashMap<String, Object>(properties); } - - /** * Obtains the MIDI file type. + * * @return the file's type (0, 1, or 2) */ public int getType() { @@ -206,7 +196,6 @@ * Obtains the timing division type for the MIDI file. * * @return the division type (PPQ or one of the SMPTE types) - * * @see Sequence#Sequence(float, int) * @see Sequence#PPQ * @see Sequence#SMPTE_24 @@ -219,11 +208,10 @@ return divisionType; } - /** - * Obtains the timing resolution for the MIDI file. - * If the division type is PPQ, the resolution is specified in ticks per beat. - * For SMTPE timing, the resolution is specified in ticks per frame. + * Obtains the timing resolution for the MIDI file. If the division type is + * PPQ, the resolution is specified in ticks per beat. For SMTPE timing, the + * resolution is specified in ticks per frame. * * @return the number of ticks per beat (PPQ) or per frame (SMPTE) * @see #getDivisionType @@ -233,9 +221,9 @@ return resolution; } - /** * 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 * @see #UNKNOWN_LENGTH */ @@ -245,7 +233,9 @@ /** * 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 UNKNOWN_LENGTH if not + * known * @see Sequence#getMicrosecondLength() * @see #getByteLength * @see #UNKNOWN_LENGTH @@ -255,14 +245,11 @@ } /** - * Obtain an unmodifiable map of properties. - * The concept of properties is further explained in - * the {@link MidiFileFormat class description}. + * Obtain an unmodifiable map of properties. The concept of properties is + * further explained in the {@link MidiFileFormat class description}. * - * @return a <code>Map<String,Object></code> object containing - * all properties. If no properties are recognized, an empty map is - * returned. - * + * @return a {@code Map<String,Object>} object containing all properties. If + * no properties are recognized, an empty map is returned. * @see #getProperty(String) * @since 1.5 */ @@ -277,20 +264,16 @@ return Collections.unmodifiableMap(ret); } - /** - * Obtain the property value specified by the key. - * The concept of properties is further explained in - * the {@link MidiFileFormat class description}. + * Obtain the property value specified by the key. The concept of properties + * is further explained in the {@link MidiFileFormat class description}. + * <p> + * If the specified property is not defined for a particular file format, + * this method returns {@code null}. * - * <p>If the specified property is not defined for a - * particular file format, this method returns - * <code>null</code>. - * - * @param key the key of the desired property - * @return the value of the property with the specified key, - * or <code>null</code> if the property does not exist. - * + * @param key the key of the desired property + * @return the value of the property with the specified key, or {@code null} + * if the property does not exist * @see #properties() * @since 1.5 */ @@ -300,6 +283,4 @@ } return properties.get(key); } - - }
--- a/jdk/src/share/classes/javax/sound/midi/MidiMessage.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MidiMessage.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, 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 @@ -26,83 +26,76 @@ package javax.sound.midi; /** - * <code>MidiMessage</code> is the base class for MIDI messages. They include - * not only the standard MIDI messages that a synthesizer can respond to, but also - * "meta-events" that can be used by sequencer programs. There are meta-events + * {@code MidiMessage} is the base class for MIDI messages. They include not + * only the standard MIDI messages that a synthesizer can respond to, but also + * "meta-events" that can be used by sequencer programs. There are meta-events * for such information as lyrics, copyrights, tempo indications, time and key - * signatures, markers, etc. For more information, see the Standard MIDI Files 1.0 - * specification, which is part of the Complete MIDI 1.0 Detailed Specification - * published by the MIDI Manufacturer's Association + * signatures, markers, etc. For more information, see the Standard MIDI Files + * 1.0 specification, which is part of the Complete MIDI 1.0 Detailed + * Specification published by the MIDI Manufacturer's Association * (<a href = http://www.midi.org>http://www.midi.org</a>). * <p> - * The base <code>MidiMessage</code> class provides access to three types of + * 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>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> * </ul> * - * <code>MidiMessage</code> includes methods to get, but not set, these values. + * {@code MidiMessage} includes methods to get, but not set, these values. * Setting them is a subclass responsibility. * <p> - * <a name="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</code> 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 - * can be converted to integers using this conversion: + * <a name="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 can be + * converted to integers using this conversion: + * * <center>{@code int i = (int)(byte & 0xFF)}</center> * <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 + * 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 - * {@link ShortMessage#setMessage(int) setMessage(int)} - * method, you can express it as 254 or 0xFE. + * {@link ShortMessage#setMessage(int) setMessage(int)} method, you can express + * it as 254 or 0xFE. * + * @author David Rivas + * @author Kara Kytle * @see Track * @see Sequence * @see Receiver - * - * @author David Rivas - * @author Kara Kytle */ - public abstract class MidiMessage implements Cloneable { - // Instance variables - /** - * The MIDI message data. The first byte is the status - * byte for the message; subsequent bytes up to the length - * of the message are data bytes for this message. + * The MIDI message data. The first byte is the status byte for the message; + * subsequent bytes up to the length of the message are data bytes for this + * message. + * * @see #getLength */ protected byte[] data; - /** - * The number of bytes in the MIDI message, including the - * status byte and any data bytes. + * The number of bytes in the MIDI message, including the status byte and + * any data bytes. + * * @see #getLength */ protected int length = 0; - /** - * Constructs a new <code>MidiMessage</code>. This protected - * constructor is called by concrete subclasses, which should - * ensure that the data array specifies a complete, valid MIDI - * message. + * Constructs a new {@code MidiMessage}. This protected constructor is + * called by concrete subclasses, which should ensure that the data array + * specifies a complete, valid MIDI message. * - * @param data an array of bytes containing the complete message. - * The message data may be changed using the <code>setMessage</code> - * method. - * + * @param data an array of bytes containing the complete message. The + * message data may be changed using the {@code setMessage} method. * @see #setMessage */ protected MidiMessage(byte[] data) { @@ -112,20 +105,21 @@ } } - /** - * Sets the data for the MIDI message. This protected - * method is called by concrete subclasses, which should - * ensure that the data array specifies a complete, valid MIDI - * message. + * Sets the data for the MIDI message. This protected method is called by + * concrete subclasses, which should ensure that the data array specifies a + * complete, valid MIDI message. * - * @param data the data bytes in the MIDI message - * @param length the number of bytes in the data byte array - * @throws InvalidMidiDataException if the parameter values do not specify a valid MIDI meta message + * @param data the data bytes in the MIDI message + * @param length the number of bytes in the data byte array + * @throws InvalidMidiDataException if the parameter values do not specify a + * valid MIDI meta message */ - protected void setMessage(byte[] data, int length) throws InvalidMidiDataException { + protected void setMessage(byte[] data, int length) + throws InvalidMidiDataException { if (length < 0 || (length > 0 && length > data.length)) { - throw new IndexOutOfBoundsException("length out of bounds: "+length); + throw new IndexOutOfBoundsException( + "length out of bounds: " + length); } this.length = length; @@ -135,16 +129,14 @@ System.arraycopy(data, 0, this.data, 0, length); } - /** - * Obtains the MIDI message data. The first byte of the returned byte - * array is the status byte of the message. Any subsequent bytes up to - * the length of the message are data bytes. The byte array may have a - * length which is greater than that of the actual message; the total - * length of the message in bytes is reported by the <code>{@link #getLength}</code> - * method. + * Obtains the MIDI message data. The first byte of the returned byte array + * is the status byte of the message. Any subsequent bytes up to the length + * of the message are data bytes. The byte array may have a length which is + * greater than that of the actual message; the total length of the message + * in bytes is reported by the {@link #getLength} method. * - * @return the byte array containing the complete <code>MidiMessage</code> data + * @return the byte array containing the complete {@code MidiMessage} data */ public byte[] getMessage() { byte[] returnedArray = new byte[length]; @@ -152,12 +144,11 @@ return returnedArray; } - /** - * Obtains the status byte for the MIDI message. The status "byte" is + * Obtains the status byte for the MIDI message. The status "byte" is * represented as an integer; see the - * <a href="#integersVsBytes">discussion</a> in the - * <code>MidiMessage</code> class description. + * <a href="#integersVsBytes">discussion</a> in the {@code MidiMessage} + * class description. * * @return the integer representation of this event's status byte */ @@ -168,13 +159,11 @@ return 0; } - /** - * Obtains the total length of the MIDI message in bytes. A - * MIDI message consists of one status byte and zero or more - * data bytes. The return value ranges from 1 for system real-time messages, - * to 2 or 3 for channel messages, to any value for meta and system - * exclusive messages. + * Obtains the total length of the MIDI message in bytes. A MIDI message + * consists of one status byte and zero or more data bytes. The return value + * ranges from 1 for system real-time messages, to 2 or 3 for channel + * messages, to any value for meta and system exclusive messages. * * @return the length of the message in bytes */ @@ -182,11 +171,11 @@ return length; } - /** - * Creates a new object of the same class and with the same contents - * as this object. - * @return a clone of this instance. + * Creates a new object of the same class and with the same contents as this + * object. + * + * @return a clone of this instance */ public abstract Object clone(); }
--- a/jdk/src/share/classes/javax/sound/midi/MidiSystem.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MidiSystem.java Wed Jul 23 16:19:26 2014 +0400 @@ -25,59 +25,52 @@ package javax.sound.midi; -import java.io.FileInputStream; import java.io.File; +import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; -import java.io.IOException; - +import java.net.URL; import java.util.ArrayList; import java.util.HashSet; import java.util.Iterator; import java.util.List; +import java.util.Properties; import java.util.Set; -import java.net.URL; - +import javax.sound.midi.spi.MidiDeviceProvider; +import javax.sound.midi.spi.MidiFileReader; import javax.sound.midi.spi.MidiFileWriter; -import javax.sound.midi.spi.MidiFileReader; import javax.sound.midi.spi.SoundbankReader; -import javax.sound.midi.spi.MidiDeviceProvider; +import com.sun.media.sound.AutoConnectSequencer; import com.sun.media.sound.JDK13Services; -import com.sun.media.sound.ReferenceCountingDevice; -import com.sun.media.sound.AutoConnectSequencer; import com.sun.media.sound.MidiDeviceReceiverEnvelope; import com.sun.media.sound.MidiDeviceTransmitterEnvelope; - +import com.sun.media.sound.ReferenceCountingDevice; /** - * The <code>MidiSystem</code> class provides access to the installed MIDI - * system resources, including devices such as synthesizers, sequencers, and - * MIDI input and output ports. A typical simple MIDI application might - * begin by invoking one or more <code>MidiSystem</code> methods to learn - * what devices are installed and to obtain the ones needed in that - * application. + * The {@code MidiSystem} class provides access to the installed MIDI system + * resources, including devices such as synthesizers, sequencers, and MIDI input + * and output ports. A typical simple MIDI application might begin by invoking + * 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 standard MIDI file data or soundbanks. You can query the - * <code>MidiSystem</code> for the format of a specified MIDI file. + * 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> - * You cannot instantiate a <code>MidiSystem</code>; all the methods are - * static. - * - * <p>Properties can be used to specify default MIDI devices. - * Both system properties and a properties file are considered. - * The <code>sound.properties</code> properties file is read from - * an implementation-specific location (typically it is the <code>lib</code> - * directory in the Java installation directory). - * If a property exists both as a system property and in the - * properties file, the system property takes precedence. If none is - * specified, a suitable default is chosen among the available devices. - * The syntax of the properties file is specified in - * {@link java.util.Properties#load(InputStream) Properties.load}. The - * following table lists the available property keys and which methods - * consider them: + * You cannot instantiate a {@code MidiSystem}; all the methods are static. + * <p> + * Properties can be used to specify default MIDI devices. Both system + * properties and a properties file are considered. The "sound.properties" + * properties file is read from an implementation-specific location (typically + * it is the {@code lib} directory in the Java installation directory). If a + * property exists both as a system property and in the properties file, the + * system property takes precedence. If none is specified, a suitable default is + * chosen among the available devices. The syntax of the properties file is + * specified in {@link Properties#load(InputStream) Properties.load}. The + * following table lists the available property keys and which methods consider + * them: * * <table border=0> * <caption>MIDI System Property Keys</caption> @@ -87,80 +80,64 @@ * <th>Affected Method</th> * </tr> * <tr> - * <td><code>javax.sound.midi.Receiver</code></td> + * <td>{@code javax.sound.midi.Receiver}</td> * <td>{@link Receiver}</td> * <td>{@link #getReceiver}</td> * </tr> * <tr> - * <td><code>javax.sound.midi.Sequencer</code></td> + * <td>{@code javax.sound.midi.Sequencer}</td> * <td>{@link Sequencer}</td> * <td>{@link #getSequencer}</td> * </tr> * <tr> - * <td><code>javax.sound.midi.Synthesizer</code></td> + * <td>{@code javax.sound.midi.Synthesizer}</td> * <td>{@link Synthesizer}</td> * <td>{@link #getSynthesizer}</td> * </tr> * <tr> - * <td><code>javax.sound.midi.Transmitter</code></td> + * <td>{@code javax.sound.midi.Transmitter}</td> * <td>{@link Transmitter}</td> * <td>{@link #getTransmitter}</td> * </tr> * </table> * - * The property value consists of the provider class name - * and the device name, separated by the hash mark ("#"). - * The provider class name is the fully-qualified - * name of a concrete {@link javax.sound.midi.spi.MidiDeviceProvider - * MIDI device provider} class. The device name is matched against - * the <code>String</code> returned by the <code>getName</code> - * method of <code>MidiDevice.Info</code>. - * Either the class name, or the device name may be omitted. - * If only the class name is specified, the trailing hash mark - * is optional. - * - * <p>If the provider class is specified, and it can be - * successfully retrieved from the installed providers, - * the list of - * <code>MidiDevice.Info</code> objects is retrieved - * from the provider. Otherwise, or when these devices - * do not provide a subsequent match, the list is retrieved - * from {@link #getMidiDeviceInfo} to contain - * all available <code>MidiDevice.Info</code> objects. - * - * <p>If a device name is specified, the resulting list of - * <code>MidiDevice.Info</code> objects is searched: - * the first one with a matching name, and whose - * <code>MidiDevice</code> implements the - * respective interface, will be returned. - * If no matching <code>MidiDevice.Info</code> object - * is found, or the device name is not specified, - * the first suitable device from the resulting - * list will be returned. For Sequencer and Synthesizer, - * a device is suitable if it implements the respective - * interface; whereas for Receiver and Transmitter, a device is - * suitable if it - * implements neither Sequencer nor Synthesizer and provides - * at least one Receiver or Transmitter, respectively. - * - * For example, the property <code>javax.sound.midi.Receiver</code> - * with a value - * <code>"com.sun.media.sound.MidiProvider#SunMIDI1"</code> - * will have the following consequences when - * <code>getReceiver</code> is called: - * if the class <code>com.sun.media.sound.MidiProvider</code> exists - * in the list of installed MIDI device providers, - * the first <code>Receiver</code> device with name - * <code>"SunMIDI1"</code> will be returned. If it cannot - * be found, the first <code>Receiver</code> from that provider - * will be returned, regardless of name. - * If there is none, the first <code>Receiver</code> with name - * <code>"SunMIDI1"</code> in the list of all devices - * (as returned by <code>getMidiDeviceInfo</code>) will be returned, - * or, if not found, the first <code>Receiver</code> that can - * be found in the list of all devices is returned. - * If that fails, too, a <code>MidiUnavailableException</code> - * is thrown. + * The property value consists of the provider class name and the device name, + * separated by the hash mark ("#"). The provider class name is the + * fully-qualified name of a concrete + * {@link MidiDeviceProvider MIDI device provider} class. The device name is + * matched against the {@code String} returned by the {@code getName} method of + * {@code MidiDevice.Info}. Either the class name, or the device name may be + * omitted. If only the class name is specified, the trailing hash mark is + * optional. + * <p> + * If the provider class is specified, and it can be successfully retrieved from + * the installed providers, the list of {@code MidiDevice.Info} objects is + * retrieved from the provider. Otherwise, or when these devices do not provide + * a subsequent match, the list is retrieved from {@link #getMidiDeviceInfo} to + * contain all available {@code MidiDevice.Info} objects. + * <p> + * If a device name is specified, the resulting list of {@code MidiDevice.Info} + * objects is searched: the first one with a matching name, and whose + * {@code MidiDevice} implements the respective interface, will be returned. If + * no matching {@code MidiDevice.Info} object is found, or the device name is + * not specified, the first suitable device from the resulting list will be + * returned. For Sequencer and Synthesizer, a device is suitable if it + * implements the respective interface; whereas for Receiver and Transmitter, a + * device is suitable if it implements neither Sequencer nor Synthesizer and + * provides at least one Receiver or Transmitter, respectively. + * <p> + * For example, the property {@code javax.sound.midi.Receiver} with a value + * {@code "com.sun.media.sound.MidiProvider#SunMIDI1"} will have the following + * consequences when {@code getReceiver} is called: if the class + * {@code com.sun.media.sound.MidiProvider} exists in the list of installed MIDI + * device providers, the first {@code Receiver} device with name + * {@code "SunMIDI1"} will be returned. If it cannot be found, the first + * {@code Receiver} from that provider will be returned, regardless of name. If + * there is none, the first {@code Receiver} with name {@code "SunMIDI1"} in the + * list of all devices (as returned by {@code getMidiDeviceInfo}) will be + * returned, or, if not found, the first {@code Receiver} that can be found in + * the list of all devices is returned. If that fails, too, a + * {@code MidiUnavailableException} is thrown. * * @author Kara Kytle * @author Florian Bomers @@ -174,17 +151,15 @@ private MidiSystem() { } - /** - * Obtains an array of information objects representing - * the set of all MIDI devices available on the system. - * A returned information object can then be used to obtain the - * corresponding device object, by invoking + * Obtains an array of information objects representing the set of all MIDI + * devices available on the system. A returned information object can then + * be used to obtain the corresponding device object, by invoking * {@link #getMidiDevice(MidiDevice.Info) getMidiDevice}. * - * @return an array of <code>MidiDevice.Info</code> objects, one - * for each installed MIDI device. If no such devices are installed, - * an array of length 0 is returned. + * @return an array of {@code MidiDevice.Info} objects, one for each + * installed MIDI device. If no such devices are installed, an array + * of length 0 is returned. */ public static MidiDevice.Info[] getMidiDeviceInfo() { List<MidiDevice.Info> allInfos = new ArrayList<>(); @@ -201,16 +176,15 @@ return infosArray; } - /** * Obtains the requested MIDI device. * - * @param info a device information object representing the desired device. + * @param info a device information object representing the desired device * @return the requested device * @throws MidiUnavailableException if the requested device is not available - * due to resource restrictions - * @throws IllegalArgumentException if the info object does not represent - * a MIDI device installed on the system + * due to resource restrictions + * @throws IllegalArgumentException if the info object does not represent a + * MIDI device installed on the system * @see #getMidiDeviceInfo */ public static MidiDevice getMidiDevice(MidiDevice.Info info) throws MidiUnavailableException { @@ -226,44 +200,38 @@ throw new IllegalArgumentException("Requested device not installed: " + info); } - /** - * Obtains a MIDI receiver from an external MIDI port - * or other default device. - * The returned receiver always implements - * the {@code MidiDeviceReceiver} interface. - * - * <p>If the system property - * <code>javax.sound.midi.Receiver</code> - * is defined or it is defined in the file "sound.properties", - * it is used to identify the device that provides the default receiver. - * For details, refer to the {@link MidiSystem class description}. - * - * If a suitable MIDI port is not available, the Receiver is - * retrieved from an installed synthesizer. - * - * <p>If a native receiver provided by the default device does not implement - * the {@code MidiDeviceReceiver} interface, it will be wrapped in a - * wrapper class that implements the {@code MidiDeviceReceiver} interface. - * The corresponding {@code Receiver} method calls will be forwarded - * to the native receiver. - * - * <p>If this method returns successfully, the {@link - * javax.sound.midi.MidiDevice MidiDevice} the - * <code>Receiver</code> belongs to is opened implicitly, if it is - * not already open. It is possible to close an implicitly opened - * device by calling {@link javax.sound.midi.Receiver#close close} - * on the returned <code>Receiver</code>. All open <code>Receiver</code> - * instances have to be closed in order to release system resources - * hold by the <code>MidiDevice</code>. For a - * detailed description of open/close behaviour see the class - * description of {@link javax.sound.midi.MidiDevice MidiDevice}. - * + * Obtains a MIDI receiver from an external MIDI port or other default + * device. The returned receiver always implements the + * {@code MidiDeviceReceiver} interface. + * <p> + * If the system property {@code javax.sound.midi.Receiver} is defined or it + * is defined in the file "sound.properties", it is used to identify the + * device that provides the default receiver. For details, refer to the + * {@link MidiSystem class description}. + * <p> + * If a suitable MIDI port is not available, the Receiver is retrieved from + * an installed synthesizer. + * <p> + * If a native receiver provided by the default device does not implement + * the {@code MidiDeviceReceiver} interface, it will be wrapped in a wrapper + * class that implements the {@code MidiDeviceReceiver} interface. The + * corresponding {@code Receiver} method calls will be forwarded to the + * native receiver. + * <p> + * If this method returns successfully, the {@link MidiDevice MidiDevice} + * the {@code Receiver} belongs to is opened implicitly, if it is not + * already open. It is possible to close an implicitly opened device by + * calling {@link Receiver#close close} on the returned {@code Receiver}. + * All open {@code Receiver} instances have to be closed in order to release + * system resources hold by the {@code MidiDevice}. For a detailed + * description of open/close behaviour see the class description of + * {@link MidiDevice MidiDevice}. * * @return the default MIDI receiver - * @throws MidiUnavailableException if the default receiver is not - * available due to resource restrictions, - * or no device providing receivers is installed in the system + * @throws MidiUnavailableException if the default receiver is not available + * due to resource restrictions, or no device providing receivers is + * installed in the system */ public static Receiver getReceiver() throws MidiUnavailableException { // may throw MidiUnavailableException @@ -280,41 +248,35 @@ return receiver; } - /** - * Obtains a MIDI transmitter from an external MIDI port - * or other default source. - * The returned transmitter always implements - * the {@code MidiDeviceTransmitter} interface. - * - * <p>If the system property - * <code>javax.sound.midi.Transmitter</code> - * is defined or it is defined in the file "sound.properties", - * it is used to identify the device that provides the default transmitter. - * For details, refer to the {@link MidiSystem class description}. - * - * <p>If a native transmitter provided by the default device does not implement + * Obtains a MIDI transmitter from an external MIDI port or other default + * source. The returned transmitter always implements the + * {@code MidiDeviceTransmitter} interface. + * <p> + * If the system property {@code javax.sound.midi.Transmitter} is defined or + * it is defined in the file "sound.properties", it is used to identify the + * device that provides the default transmitter. For details, refer to the + * {@link MidiSystem class description}. + * <p> + * If a native transmitter provided by the default device does not implement * the {@code MidiDeviceTransmitter} interface, it will be wrapped in a - * wrapper class that implements the {@code MidiDeviceTransmitter} interface. - * The corresponding {@code Transmitter} method calls will be forwarded - * to the native transmitter. - * - * <p>If this method returns successfully, the {@link - * javax.sound.midi.MidiDevice MidiDevice} the - * <code>Transmitter</code> belongs to is opened implicitly, if it - * is not already open. It is possible to close an implicitly - * opened device by calling {@link - * javax.sound.midi.Transmitter#close close} on the returned - * <code>Transmitter</code>. All open <code>Transmitter</code> - * instances have to be closed in order to release system resources - * hold by the <code>MidiDevice</code>. For a detailed description - * of open/close behaviour see the class description of {@link - * javax.sound.midi.MidiDevice MidiDevice}. + * wrapper class that implements the {@code MidiDeviceTransmitter} + * interface. The corresponding {@code Transmitter} method calls will be + * forwarded to the native transmitter. + * <p> + * If this method returns successfully, the {@link MidiDevice MidiDevice} + * the {@code Transmitter} belongs to is opened implicitly, if it is not + * already open. It is possible to close an implicitly opened device by + * calling {@link Transmitter#close close} on the returned + * {@code Transmitter}. All open {@code Transmitter} instances have to be + * closed in order to release system resources hold by the + * {@code MidiDevice}. For a detailed description of open/close behaviour + * see the class description of {@link MidiDevice MidiDevice}. * * @return the default MIDI transmitter * @throws MidiUnavailableException if the default transmitter is not - * available due to resource restrictions, - * or no device providing transmitters is installed in the system + * available due to resource restrictions, or no device providing + * transmitters is installed in the system */ public static Transmitter getTransmitter() throws MidiUnavailableException { // may throw MidiUnavailableException @@ -331,59 +293,48 @@ return transmitter; } - /** * Obtains the default synthesizer. - * - * <p>If the system property - * <code>javax.sound.midi.Synthesizer</code> - * is defined or it is defined in the file "sound.properties", - * it is used to identify the default synthesizer. - * For details, refer to the {@link MidiSystem class description}. + * <p> + * If the system property {@code javax.sound.midi.Synthesizer} is defined or + * it is defined in the file "sound.properties", it is used to identify the + * default synthesizer. For details, refer to the + * {@link MidiSystem class description}. * * @return the default synthesizer - * @throws MidiUnavailableException if the synthesizer is not - * available due to resource restrictions, - * or no synthesizer is installed in the system + * @throws MidiUnavailableException if the synthesizer is not available due + * to resource restrictions, or no synthesizer is installed in the + * system */ public static Synthesizer getSynthesizer() throws MidiUnavailableException { // may throw MidiUnavailableException return (Synthesizer) getDefaultDeviceWrapper(Synthesizer.class); } - /** - * Obtains the default <code>Sequencer</code>, connected to - * a default device. - * The returned <code>Sequencer</code> instance is - * connected to the default <code>Synthesizer</code>, - * as returned by {@link #getSynthesizer}. - * If there is no <code>Synthesizer</code> - * available, or the default <code>Synthesizer</code> - * cannot be opened, the <code>sequencer</code> is connected - * to the default <code>Receiver</code>, as returned - * by {@link #getReceiver}. - * The connection is made by retrieving a <code>Transmitter</code> - * instance from the <code>Sequencer</code> and setting its - * <code>Receiver</code>. - * Closing and re-opening the sequencer will restore the - * connection to the default device. - * - * <p>This method is equivalent to calling - * <code>getSequencer(true)</code>. - * - * <p>If the system property - * <code>javax.sound.midi.Sequencer</code> - * is defined or it is defined in the file "sound.properties", - * it is used to identify the default sequencer. - * For details, refer to the {@link MidiSystem class description}. + * Obtains the default {@code Sequencer}, connected to a default device. The + * returned {@code Sequencer} instance is connected to the default + * {@code Synthesizer}, as returned by {@link #getSynthesizer}. If there is + * no {@code Synthesizer} available, or the default {@code Synthesizer} + * cannot be opened, the {@code sequencer} is connected to the default + * {@code Receiver}, as returned by {@link #getReceiver}. The connection is + * made by retrieving a {@code Transmitter} instance from the + * {@code Sequencer} and setting its {@code Receiver}. Closing and + * re-opening the sequencer will restore the connection to the default + * device. + * <p> + * This method is equivalent to calling {@code getSequencer(true)}. + * <p> + * If the system property {@code javax.sound.midi.Sequencer} is defined or + * it is defined in the file "sound.properties", it is used to identify the + * default sequencer. For details, refer to the + * {@link MidiSystem class description}. * * @return the default sequencer, connected to a default Receiver - * @throws MidiUnavailableException if the sequencer is not - * available due to resource restrictions, - * or there is no <code>Receiver</code> available by any - * installed <code>MidiDevice</code>, - * or no sequencer is installed in the system. + * @throws MidiUnavailableException if the sequencer is not available due to + * resource restrictions, or there is no {@code Receiver} available + * by any installed {@code MidiDevice}, or no sequencer is installed + * in the system * @see #getSequencer(boolean) * @see #getSynthesizer * @see #getReceiver @@ -392,49 +343,37 @@ return getSequencer(true); } - - /** - * Obtains the default <code>Sequencer</code>, optionally - * connected to a default device. - * - * <p>If <code>connected</code> is true, the returned - * <code>Sequencer</code> instance is - * connected to the default <code>Synthesizer</code>, - * as returned by {@link #getSynthesizer}. - * If there is no <code>Synthesizer</code> - * available, or the default <code>Synthesizer</code> - * cannot be opened, the <code>sequencer</code> is connected - * to the default <code>Receiver</code>, as returned - * by {@link #getReceiver}. - * The connection is made by retrieving a <code>Transmitter</code> - * instance from the <code>Sequencer</code> and setting its - * <code>Receiver</code>. - * Closing and re-opening the sequencer will restore the + * Obtains the default {@code Sequencer}, optionally connected to a default + * device. + * <p> + * If {@code connected} is true, the returned {@code Sequencer} instance is + * connected to the default {@code Synthesizer}, as returned by + * {@link #getSynthesizer}. If there is no {@code Synthesizer} available, or + * the default {@code Synthesizer} cannot be opened, the {@code sequencer} + * is connected to the default {@code Receiver}, as returned by + * {@link #getReceiver}. The connection is made by retrieving a + * {@code Transmitter} instance from the {@code Sequencer} and setting its + * {@code Receiver}. Closing and re-opening the sequencer will restore the * connection to the default device. + * <p> + * If {@code connected} is false, the returned {@code Sequencer} instance is + * not connected, it has no open {@code Transmitters}. In order to play the + * sequencer on a MIDI device, or a {@code Synthesizer}, it is necessary to + * get a {@code Transmitter} and set its {@code Receiver}. + * <p> + * If the system property {@code javax.sound.midi.Sequencer} is defined or + * it is defined in the file "sound.properties", it is used to identify the + * default sequencer. For details, refer to the + * {@link MidiSystem class description}. * - * <p>If <code>connected</code> is false, the returned - * <code>Sequencer</code> instance is not connected, it - * has no open <code>Transmitters</code>. In order to - * play the sequencer on a MIDI device, or a <code>Synthesizer</code>, - * it is necessary to get a <code>Transmitter</code> and set its - * <code>Receiver</code>. - * - * <p>If the system property - * <code>javax.sound.midi.Sequencer</code> - * is defined or it is defined in the file "sound.properties", - * it is used to identify the default sequencer. - * For details, refer to the {@link MidiSystem class description}. - * - * @param connected whether or not the returned {@code Sequencer} - * is connected to the default {@code Synthesizer} + * @param connected whether or not the returned {@code Sequencer} is + * connected to the default {@code Synthesizer} * @return the default sequencer - * @throws MidiUnavailableException if the sequencer is not - * available due to resource restrictions, - * or no sequencer is installed in the system, - * or if <code>connected</code> is true, and there is - * no <code>Receiver</code> available by any installed - * <code>MidiDevice</code> + * @throws MidiUnavailableException if the sequencer is not available due to + * resource restrictions, or no sequencer is installed in the + * system, or if {@code connected} is true, and there is no + * {@code Receiver} available by any installed {@code MidiDevice} * @see #getSynthesizer * @see #getReceiver * @since 1.5 @@ -501,23 +440,20 @@ return seq; } - - - /** - * Constructs a MIDI sound bank by reading it from the specified stream. - * The stream must point to - * a valid MIDI soundbank file. In general, MIDI soundbank providers may - * need to read some data from the stream before determining whether they - * support 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. - * @param stream the source of the sound bank data. + * Constructs a MIDI sound bank by reading it from the specified stream. The + * stream must point to a valid MIDI soundbank file. In general, MIDI + * soundbank providers may need to read some data from the stream before + * determining whether they support 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 {@code IOException}. + * + * @param stream the source of the sound bank data * @return the sound bank - * @throws InvalidMidiDataException if the stream does not point to - * valid MIDI soundbank data recognized by the system + * @throws InvalidMidiDataException if the stream does not point to valid + * MIDI soundbank data recognized by the system * @throws IOException if an I/O error occurred when loading the soundbank * @see InputStream#markSupported * @see InputStream#mark @@ -542,15 +478,14 @@ } - /** - * Constructs a <code>Soundbank</code> by reading it from the specified URL. - * The URL must point to a valid MIDI soundbank file. + * Constructs a {@code Soundbank} by reading it from the specified URL. The + * URL must point to a valid MIDI soundbank file. * - * @param url the source of the sound bank data + * @param url the source of the sound bank data * @return the sound bank * @throws InvalidMidiDataException if the URL does not point to valid MIDI - * soundbank data recognized by the system + * soundbank data recognized by the system * @throws IOException if an I/O error occurred when loading the soundbank */ public static Soundbank getSoundbank(URL url) @@ -573,16 +508,14 @@ } - /** - * Constructs a <code>Soundbank</code> by reading it from the specified - * <code>File</code>. - * The <code>File</code> must point to a valid MIDI soundbank file. + * Constructs a {@code Soundbank} by reading it from the specified + * {@code File}. The {@code File} must point to a valid MIDI soundbank file. * - * @param file the source of the sound bank data + * @param file the source of the sound bank data * @return the sound bank - * @throws InvalidMidiDataException if the <code>File</code> does not - * point to valid MIDI soundbank data recognized by the system + * @throws InvalidMidiDataException if the {@code File} does not point to + * valid MIDI soundbank data recognized by the system * @throws IOException if an I/O error occurred when loading the soundbank */ public static Soundbank getSoundbank(File file) @@ -604,35 +537,33 @@ throw new InvalidMidiDataException("cannot get soundbank from stream"); } - - /** * Obtains the MIDI file format of the data in the specified input stream. * The stream must point to valid MIDI file data for a file type recognized * by the system. * <p> * This method and/or the code it invokes may need to read some data from - * the stream to determine whether its data format is supported. The - * implementation may therefore - * need to mark the stream, read enough data to determine whether it is in - * a supported format, and reset the stream's read pointer to its original - * position. If the input stream does not permit this set of operations, - * this method may fail with an <code>IOException</code>. + * the stream to determine whether its data format is supported. The + * implementation may therefore need to mark the stream, read enough data to + * determine whether it is in a supported format, and reset the stream's + * read pointer to its original position. If the input stream does not + * permit this set of operations, this method may fail with an + * {@code IOException}. * <p> * This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while determining the file format. + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while determining the file format. * - * @param stream the input stream from which file format information - * should be extracted - * @return an <code>MidiFileFormat</code> object describing the MIDI file - * format + * @param stream the input stream from which file format information should + * be extracted + * @return an {@code MidiFileFormat} object describing the MIDI file format * @throws InvalidMidiDataException if the stream does not point to valid - * MIDI file data recognized by the system + * MIDI file data recognized by the system * @throws IOException if an I/O exception occurs while accessing the - * stream + * stream * @see #getMidiFileFormat(URL) * @see #getMidiFileFormat(File) * @see InputStream#markSupported @@ -661,26 +592,24 @@ } } - /** - * Obtains the MIDI file format of the data in the specified URL. The URL - * must point to valid MIDI file data for a file type recognized - * by the system. + * Obtains the MIDI file format of the data in the specified URL. The URL + * must point to valid MIDI file data for a file type recognized by the + * system. * <p> * This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while determining the file format. + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while determining the file format. * - * @param url the URL from which file format information should be - * extracted - * @return a <code>MidiFileFormat</code> object describing the MIDI file - * format + * @param url the 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 + * file data recognized by the system * @throws IOException if an I/O exception occurs while accessing the URL - * * @see #getMidiFileFormat(InputStream) * @see #getMidiFileFormat(File) */ @@ -707,26 +636,24 @@ } } - /** - * Obtains the MIDI file format of the specified <code>File</code>. The - * <code>File</code> must point to valid MIDI file data for a file type + * Obtains the MIDI file format of the specified {@code File}. The + * {@code File} must point to valid MIDI file data for a file type * recognized by the system. * <p> * This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while determining the file format. + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while determining the file format. * - * @param file the <code>File</code> from which file format information - * should be extracted - * @return a <code>MidiFileFormat</code> object describing the MIDI file - * format - * @throws InvalidMidiDataException if the <code>File</code> does not point - * to valid MIDI file data recognized by the system + * @param file the {@code File} from which file format information should + * be extracted + * @return a {@code MidiFileFormat} object describing the MIDI file format + * @throws InvalidMidiDataException if the {@code File} does not point to + * valid MIDI file data recognized by the system * @throws IOException if an I/O exception occurs while accessing the file - * * @see #getMidiFileFormat(InputStream) * @see #getMidiFileFormat(URL) */ @@ -753,35 +680,33 @@ } } - /** - * Obtains a MIDI sequence from the specified input stream. The stream must - * point to valid MIDI file data for a file type recognized - * by the system. + * Obtains a MIDI sequence from the specified input stream. The stream must + * point to valid MIDI file data for a file type recognized by the system. * <p> - * This method and/or the code it invokes may need to read some data - * from the stream to determine whether - * its data format is supported. The implementation may therefore - * need to mark the stream, read enough data to determine whether it is in - * a supported format, and reset the stream's read pointer to its original - * position. If the input stream does not permit this set of operations, - * this method may fail with an <code>IOException</code>. + * This method and/or the code it invokes may need to read some data from + * the stream to determine whether its data format is supported. The + * implementation may therefore need to mark the stream, read enough data to + * determine whether it is in a supported format, and reset the stream's + * read pointer to its original position. If the input stream does not + * permit this set of operations, this method may fail with an + * {@code IOException}. * <p> * This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while constructing the <code>Sequence</code> + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while constructing the {@code Sequence} * object from the file data. * - * @param stream the input stream from which the <code>Sequence</code> - * should be constructed - * @return a <code>Sequence</code> object based on the MIDI file data - * contained in the input stream - * @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 + * @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 + * MIDI file data recognized by the system + * @throws IOException if an I/O exception occurs while accessing the stream * @see InputStream#markSupported * @see InputStream#mark */ @@ -808,25 +733,23 @@ } } - /** - * Obtains a MIDI sequence from the specified URL. The URL must - * point to valid MIDI file data for a file type recognized - * by the system. + * Obtains a MIDI sequence from the specified URL. The URL must point to + * valid MIDI file data for a file type recognized by the system. * <p> * This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while constructing the <code>Sequence</code> + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while constructing the {@code Sequence} * object from the file data. * - * @param url the URL from which the <code>Sequence</code> should be - * constructed - * @return a <code>Sequence</code> object based on the MIDI file data - * pointed to by the URL + * @param url the URL from 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 + * file data recognized by the system * @throws IOException if an I/O exception occurs while accessing the URL */ public static Sequence getSequence(URL url) @@ -852,25 +775,25 @@ } } - /** - * Obtains a MIDI sequence from the specified <code>File</code>. - * The <code>File</code> must point to valid MIDI file data - * for a file type recognized by the system. + * Obtains a MIDI sequence from the specified {@code File}. The {@code File} + * must point to valid MIDI file data for a file type recognized by the + * system. * <p> * This operation can only succeed for files of a type which can be parsed - * by an installed file reader. It may fail with an InvalidMidiDataException - * even for valid files if no compatible file reader is installed. It - * will also fail with an InvalidMidiDataException if a compatible file reader - * is installed, but encounters errors while constructing the <code>Sequence</code> + * by an installed file reader. It may fail with an + * {@code InvalidMidiDataException} even for valid files if no compatible + * file reader is installed. It will also fail with an + * {@code InvalidMidiDataException} if a compatible file reader is + * installed, but encounters errors while constructing the {@code Sequence} * object from the file data. * - * @param file the <code>File</code> from which the <code>Sequence</code> - * should be constructed - * @return a <code>Sequence</code> object based on the MIDI file data - * pointed to by the File + * @param file the {@code File} from which the {@code Sequence} should be + * constructed + * @return a {@code Sequence} object based on the MIDI file data pointed to + * by the File * @throws InvalidMidiDataException if the File does not point to valid MIDI - * file data recognized by the system + * file data recognized by the system * @throws IOException if an I/O exception occurs */ public static Sequence getSequence(File file) @@ -896,12 +819,12 @@ } } - /** * Obtains the set of MIDI file types for which file writing support is * provided by the system. - * @return array of unique file types. If no file types are supported, - * an array of length 0 is returned. + * + * @return array of unique file types. If no file types are supported, an + * array of length 0 is returned. */ public static int[] getMidiFileTypes() { @@ -927,13 +850,13 @@ return resultTypes; } - /** * Indicates whether file writing support for the specified MIDI file type * is provided by the system. - * @param fileType the file type for which write capabilities are queried - * @return <code>true</code> if the file type is supported, - * otherwise <code>false</code> + * + * @param fileType the file type for which write capabilities are queried + * @return {@code true} if the file type is supported, otherwise + * {@code false} */ public static boolean isFileTypeSupported(int fileType) { @@ -948,14 +871,13 @@ return false; } - /** * Obtains the set of MIDI file types that the system can write from the * sequence specified. - * @param sequence the sequence for which MIDI file type support - * is queried - * @return the set of unique supported file types. If no file types are supported, - * returns an array of length 0. + * + * @param sequence the sequence for which MIDI file type support is queried + * @return the set of unique supported file types. If no file types are + * supported, returns an array of length 0. */ public static int[] getMidiFileTypes(Sequence sequence) { @@ -981,15 +903,14 @@ return resultTypes; } - /** * Indicates whether a MIDI file of the file type specified can be written * from the sequence indicated. - * @param fileType the file type for which write capabilities - * are queried - * @param sequence the sequence for which file writing support is queried - * @return <code>true</code> if the file type is supported for this - * sequence, otherwise <code>false</code> + * + * @param fileType the file type for which write capabilities are queried + * @param sequence the sequence for which file writing support is queried + * @return {@code true} if the file type is supported for this sequence, + * otherwise {@code false} */ public static boolean isFileTypeSupported(int fileType, Sequence sequence) { @@ -1004,19 +925,20 @@ return false; } - /** * Writes a stream of bytes representing a file of the MIDI file type * indicated to the output stream provided. - * @param in sequence containing MIDI data to be written to the file - * @param fileType the file type of the file to be written to the output stream - * @param out stream to which the file data should be written + * + * @param in sequence containing MIDI data to be written to the file + * @param fileType the file type of the file to be written to the output + * stream + * @param out stream to which the file data should be written * @return the number of bytes written to the output stream * @throws IOException if an I/O exception occurs * @throws IllegalArgumentException if the file format is not supported by - * the system + * the system * @see #isFileTypeSupported(int, Sequence) - * @see #getMidiFileTypes(Sequence) + * @see #getMidiFileTypes(Sequence) */ public static int write(Sequence in, int fileType, OutputStream out) throws IOException { @@ -1038,19 +960,19 @@ return bytesWritten; } - /** * Writes a stream of bytes representing a file of the MIDI file type * indicated to the external file provided. - * @param in sequence containing MIDI data to be written to the file - * @param type the file type of the file to be written to the output stream - * @param out external file to which the file data should be written + * + * @param in sequence containing MIDI data to be written to the file + * @param type the file type of the file to be written to the output stream + * @param out external file to which the file data should be written * @return the number of bytes written to the file * @throws IOException if an I/O exception occurs - * @throws IllegalArgumentException if the file type is not supported by - * the system + * @throws IllegalArgumentException if the file type is not supported by the + * system * @see #isFileTypeSupported(int, Sequence) - * @see #getMidiFileTypes(Sequence) + * @see #getMidiFileTypes(Sequence) */ public static int write(Sequence in, int type, File out) throws IOException { @@ -1072,8 +994,6 @@ return bytesWritten; } - - // HELPER METHODS @SuppressWarnings("unchecked") private static List<MidiDeviceProvider> getMidiDeviceProviders() { @@ -1095,19 +1015,16 @@ return (List<MidiFileReader>) getProviders(MidiFileReader.class); } - - /** Attempts to locate and return a default MidiDevice of the specified - * type. - * + /** + * Attempts to locate and return a default MidiDevice of the specified type. * This method wraps {@link #getDefaultDevice}. It catches the - * <code>IllegalArgumentException</code> thrown by - * <code>getDefaultDevice</code> and instead throws a - * <code>MidiUnavailableException</code>, with the catched + * {@code IllegalArgumentException} thrown by {@code getDefaultDevice} and + * instead throws a {@code MidiUnavailableException}, with the catched * exception chained. * - * @param deviceClass The requested device type, one of Synthesizer.class, - * Sequencer.class, Receiver.class or Transmitter.class. - * @throws MidiUnavalableException on failure. + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @throws MidiUnavailableException on failure */ private static MidiDevice getDefaultDeviceWrapper(Class<?> deviceClass) throws MidiUnavailableException{ @@ -1120,13 +1037,12 @@ } } - - /** Attempts to locate and return a default MidiDevice of the specified - * type. + /** + * Attempts to locate and return a default MidiDevice of the specified type. * - * @param deviceClass The requested device type, one of Synthesizer.class, - * Sequencer.class, Receiver.class or Transmitter.class. - * @throws IllegalArgumentException on failure. + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @throws IllegalArgumentException on failure */ private static MidiDevice getDefaultDevice(Class<?> deviceClass) { List<MidiDeviceProvider> providers = getMidiDeviceProviders(); @@ -1169,16 +1085,15 @@ throw new IllegalArgumentException("Requested device not installed"); } - - - /** Return a MidiDeviceProcider of a given class from the list of - MidiDeviceProviders. - - @param providerClassName The class name of the provider to be returned. - @param provider The list of MidiDeviceProviders that is searched. - @return A MidiDeviceProvider of the requested class, or null if none - is found. - */ + /** + * Return a MidiDeviceProvider of a given class from the list of + * MidiDeviceProviders. + * + * @param providerClassName The class name of the provider to be returned + * @param providers The list of MidiDeviceProviders that is searched + * @return A MidiDeviceProvider of the requested class, or null if none is + * found + */ private static MidiDeviceProvider getNamedProvider(String providerClassName, List<MidiDeviceProvider> providers) { for(int i = 0; i < providers.size(); i++) { @@ -1190,15 +1105,15 @@ return null; } - - /** Return a MidiDevice with a given name from a given MidiDeviceProvider. - @param deviceName The name of the MidiDevice to be returned. - @param provider The MidiDeviceProvider to check for MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - - @return A MidiDevice matching the requirements, or null if none is found. - */ + /** + * Return a MidiDevice with a given name from a given MidiDeviceProvider. + * + * @param deviceName The name of the MidiDevice to be returned + * @param provider The MidiDeviceProvider to check for MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice matching the requirements, or null if none is found + */ private static MidiDevice getNamedDevice(String deviceName, MidiDeviceProvider provider, Class<?> deviceClass) { @@ -1222,14 +1137,14 @@ return null; } - - /** Return a MidiDevice with a given name from a given MidiDeviceProvider. - @param deviceName The name of the MidiDevice to be returned. - @param provider The MidiDeviceProvider to check for MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - - @return A MidiDevice matching the requirements, or null if none is found. + /** + * Return a MidiDevice with a given name from a given MidiDeviceProvider. + * + * @param deviceName The name of the MidiDevice to be returned + * @param provider The MidiDeviceProvider to check for MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice matching the requirements, or null if none is found */ private static MidiDevice getNamedDevice(String deviceName, MidiDeviceProvider provider, @@ -1249,16 +1164,16 @@ return null; } - - /** Return a MidiDevice with a given name from a list of - MidiDeviceProviders. - @param deviceName The name of the MidiDevice to be returned. - @param providers The List of MidiDeviceProviders to check for - MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A Mixer matching the requirements, or null if none is found. - */ + /** + * Return a MidiDevice with a given name from a list of MidiDeviceProviders. + * + * @param deviceName The name of the MidiDevice to be returned + * @param providers The List of MidiDeviceProviders to check for + * MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A Mixer matching the requirements, or null if none is found + */ private static MidiDevice getNamedDevice(String deviceName, List<MidiDeviceProvider> providers, Class<?> deviceClass) { @@ -1282,15 +1197,15 @@ return null; } - - /** Return a MidiDevice with a given name from a list of - MidiDeviceProviders. - @param deviceName The name of the MidiDevice to be returned. - @param providers The List of MidiDeviceProviders to check for - MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A Mixer matching the requirements, or null if none is found. + /** + * Return a MidiDevice with a given name from a list of MidiDeviceProviders. + * + * @param deviceName The name of the MidiDevice to be returned + * @param providers The List of MidiDeviceProviders to check for + * MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A Mixer matching the requirements, or null if none is found */ private static MidiDevice getNamedDevice(String deviceName, List<MidiDeviceProvider> providers, @@ -1310,14 +1225,15 @@ return null; } - - /** From a given MidiDeviceProvider, return the first appropriate device. - @param provider The MidiDeviceProvider to check for MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A MidiDevice is considered appropriate, or null if no - appropriate device is found. - */ + /** + * From a given MidiDeviceProvider, return the first appropriate device. + * + * @param provider The MidiDeviceProvider to check for MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice is considered appropriate, or null if no appropriate + * device is found + */ private static MidiDevice getFirstDevice(MidiDeviceProvider provider, Class<?> deviceClass) { MidiDevice device; @@ -1340,13 +1256,14 @@ return null; } - - /** From a given MidiDeviceProvider, return the first appropriate device. - @param provider The MidiDeviceProvider to check for MidiDevices. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A MidiDevice is considered appropriate, or null if no - appropriate device is found. + /** + * From a given MidiDeviceProvider, return the first appropriate device. + * + * @param provider The MidiDeviceProvider to check for MidiDevices + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice is considered appropriate, or null if no appropriate + * device is found */ private static MidiDevice getFirstDevice(MidiDeviceProvider provider, Class<?> deviceClass, @@ -1363,15 +1280,16 @@ return null; } - - /** From a List of MidiDeviceProviders, return the first appropriate - MidiDevice. - @param providers The List of MidiDeviceProviders to search. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A MidiDevice that is considered appropriate, or null - if none is found. - */ + /** + * From a List of MidiDeviceProviders, return the first appropriate + * MidiDevice. + * + * @param providers The List of MidiDeviceProviders to search + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice that is considered appropriate, or null if none is + * found + */ private static MidiDevice getFirstDevice(List<MidiDeviceProvider> providers, Class<?> deviceClass) { MidiDevice device; @@ -1394,14 +1312,15 @@ return null; } - - /** From a List of MidiDeviceProviders, return the first appropriate - MidiDevice. - @param providers The List of MidiDeviceProviders to search. - @param deviceClass The requested device type, one of Synthesizer.class, - Sequencer.class, Receiver.class or Transmitter.class. - @return A MidiDevice that is considered appropriate, or null - if none is found. + /** + * From a List of MidiDeviceProviders, return the first appropriate + * MidiDevice. + * + * @param providers The List of MidiDeviceProviders to search + * @param deviceClass The requested device type, one of Synthesizer.class, + * Sequencer.class, Receiver.class or Transmitter.class + * @return A MidiDevice that is considered appropriate, or null if none is + * found */ private static MidiDevice getFirstDevice(List<MidiDeviceProvider> providers, Class<?> deviceClass, @@ -1419,28 +1338,29 @@ return null; } - - /** Checks if a MidiDevice is appropriate. - If deviceClass is Synthesizer or Sequencer, a device implementing - the respective interface is considered appropriate. If deviceClass - is Receiver or Transmitter, a device is considered appropriate if - it implements neither Synthesizer nor Transmitter, and if it can - provide at least one Receiver or Transmitter, respectively. - - @param device the MidiDevice to test - @param 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 true if the device is considered appropriate according to the - rules given above, false otherwise. - */ + /** + * Checks if a MidiDevice is appropriate. If deviceClass is Synthesizer or + * Sequencer, a device implementing the respective interface is considered + * appropriate. If deviceClass is Receiver or Transmitter, a device is + * considered appropriate if it implements neither Synthesizer nor + * Transmitter, and if it can provide at least one Receiver or Transmitter, + * respectively. + * + * @param device the MidiDevice to test + * @param 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 true if the device is considered appropriate according to the + * rules given above, false otherwise + */ private static boolean isAppropriateDevice(MidiDevice device, Class<?> deviceClass, boolean allowSynthesizer, @@ -1473,12 +1393,12 @@ return false; } - /** - * Obtains the set of services currently installed on the system - * using the SPI mechanism in 1.3. - * @return a List of instances of providers for the requested service. - * If no providers are available, a List of length 0 will be returned. + * Obtains the set of services currently installed on the system using the + * SPI mechanism in 1.3. + * + * @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);
--- a/jdk/src/share/classes/javax/sound/midi/MidiUnavailableException.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/MidiUnavailableException.java Wed Jul 23 16:19:26 2014 +0400 @@ -25,39 +25,37 @@ package javax.sound.midi; - /** - * A <code>MidiUnavailableException</code> is thrown when a requested MIDI - * component cannot be opened or created because it is unavailable. This often - * occurs when a device is in use by another application. More generally, it - * can occur when there is a finite number of a certain kind of resource that can - * be used for some purpose, and all of them are already in use (perhaps all by - * this application). For an example of the latter case, see the + * A {@code MidiUnavailableException} is thrown when a requested MIDI component + * cannot be opened or created because it is unavailable. This often occurs when + * a device is in use by another application. More generally, it can occur when + * there is a finite number of a certain kind of resource that can be used for + * some purpose, and all of them are already in use (perhaps all by this + * application). For an example of the latter case, see the * {@link Transmitter#setReceiver(Receiver) setReceiver} method of - * <code>Transmitter</code>. + * {@code Transmitter}. * * @author Kara Kytle */ public class MidiUnavailableException extends Exception { + private static final long serialVersionUID = 6093809578628944323L; /** - * Constructs a <code>MidiUnavailableException</code> that has - * <code>null</code> as its error detail message. + * Constructs a {@code MidiUnavailableException} that has {@code null} as + * its error detail message. */ public MidiUnavailableException() { - super(); } /** - * Constructs a <code>MidiUnavailableException</code> with the - * specified detail message. + * Constructs a {@code MidiUnavailableException} with the specified detail + * message. * - * @param message the string to display as an error detail message + * @param message the string to display as an error detail message */ - public MidiUnavailableException(String message) { - + public MidiUnavailableException(final String message) { super(message); } }
--- a/jdk/src/share/classes/javax/sound/midi/Patch.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/Patch.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -25,88 +25,77 @@ package javax.sound.midi; - /** - * A <code>Patch</code> object represents a location, on a MIDI - * synthesizer, into which a single instrument is stored (loaded). - * Every <code>Instrument</code> object has its own <code>Patch</code> - * object that specifies the memory location - * into which that instrument should be loaded. The - * location is specified abstractly by a bank index and a program number (not by - * any scheme that directly refers to a specific address or offset in RAM). - * This is a hierarchical indexing scheme: MIDI provides for up to 16384 banks, - * each of which contains up to 128 program locations. For example, a - * minimal sort of synthesizer might have only one bank of instruments, and - * only 32 instruments (programs) in that bank. + * A {@code Patch} object represents a location, on a MIDI synthesizer, into + * which a single instrument is stored (loaded). Every {@code Instrument} object + * has its own {@code Patch} object that specifies the memory location into + * which that instrument should be loaded. The location is specified abstractly + * by a bank index and a program number (not by any scheme that directly refers + * to a specific address or offset in RAM). This is a hierarchical indexing + * scheme: MIDI provides for up to 16384 banks, each of which contains up to 128 + * program locations. For example, a minimal sort of synthesizer might have only + * one bank of instruments, and only 32 instruments (programs) in that bank. * <p> - * To select what instrument should play the notes on a particular MIDI - * channel, two kinds of MIDI message are used that specify a patch location: - * a bank-select command, and a program-change channel command. The Java Sound + * To select what instrument should play the notes on a particular MIDI channel, + * two kinds of MIDI message are used that specify a patch location: a + * bank-select command, and a program-change channel command. The Java Sound * equivalent is the - * {@link MidiChannel#programChange(int, int) programChange(int, int)} - * method of <code>MidiChannel</code>. + * {@link MidiChannel#programChange(int, int) programChange(int, int)} method of + * {@code MidiChannel}. * + * @author Kara Kytle * @see Instrument * @see Instrument#getPatch() * @see MidiChannel#programChange(int, int) * @see Synthesizer#loadInstruments(Soundbank, Patch[]) * @see Soundbank * @see Sequence#getPatchList() - * - * @author Kara Kytle */ - public class Patch { - /** - * Bank index + * Bank index. */ private final int bank; - /** - * Program change number + * Program change number. */ private final int program; - /** * Constructs a new patch object from the specified bank and program * numbers. - * @param bank the bank index (in the range from 0 to 16383) - * @param program the program index (in the range from 0 to 127) + * + * @param bank the bank index (in the range from 0 to 16383) + * @param program the program index (in the range from 0 to 127) */ public Patch(int bank, int program) { - this.bank = bank; this.program = program; } - /** - * Returns the number of the bank that contains the instrument - * whose location this <code>Patch</code> specifies. + * Returns the number of the bank that contains the instrument whose + * location this {@code Patch} specifies. + * * @return the bank number, whose range is from 0 to 16383 * @see MidiChannel#programChange(int, int) */ public int getBank() { - return bank; } - /** - * Returns the index, within - * a bank, of the instrument whose location this <code>Patch</code> specifies. + * Returns the index, within a bank, of the instrument whose location this + * {@code Patch} specifies. + * * @return the instrument's program number, whose range is from 0 to 127 - * * @see MidiChannel#getProgram * @see MidiChannel#programChange(int) * @see MidiChannel#programChange(int, int) */ public int getProgram() { - return program; } }
--- a/jdk/src/share/classes/javax/sound/midi/Receiver.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/Receiver.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -25,50 +25,46 @@ package javax.sound.midi; - /** - * A <code>Receiver</code> receives <code>{@link MidiEvent}</code> objects and - * typically does something useful in response, such as interpreting them to - * generate sound or raw MIDI output. Common MIDI receivers include - * synthesizers and MIDI Out ports. + * A {@code Receiver} receives {@link MidiEvent} objects and typically does + * something useful in response, such as interpreting them to generate sound or + * raw MIDI output. Common MIDI receivers include synthesizers and MIDI Out + * ports. * + * @author Kara Kytle * @see MidiDevice * @see Synthesizer * @see Transmitter - * - * @author Kara Kytle */ public interface Receiver extends AutoCloseable { + //$$fb 2002-04-12: fix for 4662090: Contradiction in Receiver specification - //$$fb 2002-04-12: fix for 4662090: Contradiction in Receiver specification /** - * Sends a MIDI message and time-stamp to this receiver. - * If time-stamping is not supported by this receiver, the time-stamp - * value should be -1. - * @param message the MIDI message to send - * @param timeStamp the time-stamp for the message, in microseconds. + * Sends a MIDI message and time-stamp to this receiver. If time-stamping is + * not supported by this receiver, the time-stamp value should be -1. + * + * @param message the MIDI message to send + * @param timeStamp the time-stamp for the message, in microseconds * @throws IllegalStateException if the receiver is closed */ - public void send(MidiMessage message, long timeStamp); + void send(MidiMessage message, long timeStamp); /** - * Indicates that the application has finished using the receiver, and - * that limited resources it requires may be released or made available. - * - * <p>If the creation of this <code>Receiver</code> resulted in - * implicitly opening the underlying device, the device is - * implicitly closed by this method. This is true unless the device is - * kept open by other <code>Receiver</code> or <code>Transmitter</code> - * instances that opened the device implicitly, and unless the device - * has been opened explicitly. If the device this - * <code>Receiver</code> is retrieved from is closed explicitly by - * calling {@link MidiDevice#close MidiDevice.close}, the - * <code>Receiver</code> is closed, too. For a detailed - * description of open/close behaviour see the class description - * of {@link javax.sound.midi.MidiDevice MidiDevice}. + * Indicates that the application has finished using the receiver, and that + * limited resources it requires may be released or made available. + * <p> + * If the creation of this {@code Receiver} resulted in implicitly opening + * the underlying device, the device is implicitly closed by this method. + * This is true unless the device is kept open by other {@code Receiver} or + * {@code Transmitter} instances that opened the device implicitly, and + * unless the device has been opened explicitly. If the device this + * {@code Receiver} is retrieved from is closed explicitly by calling + * {@link MidiDevice#close MidiDevice.close}, the {@code Receiver} is + * closed, too. For a detailed description of open/close behaviour see the + * class description of {@link MidiDevice MidiDevice}. * * @see javax.sound.midi.MidiSystem#getReceiver */ - public void close(); + void close(); }
--- a/jdk/src/share/classes/javax/sound/midi/Sequence.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/Sequence.java Wed Jul 23 16:19:26 2014 +0400 @@ -26,72 +26,77 @@ package javax.sound.midi; import java.util.Vector; -import com.sun.media.sound.MidiUtils; - /** - * A <code>Sequence</code> is a data structure containing musical - * information (often an entire song or composition) that can be played - * back by a <code>{@link Sequencer}</code> object. Specifically, the - * <code>Sequence</code> contains timing - * information and one or more tracks. Each <code>{@link Track track}</code> consists of a - * series of MIDI events (such as note-ons, note-offs, program changes, and meta-events). - * The sequence's timing information specifies the type of unit that is used - * to time-stamp the events in the sequence. + * A {@code Sequence} is a data structure containing musical information (often + * an entire song or composition) that can be played back by a {@link Sequencer} + * object. Specifically, the {@code Sequence} contains timing information and + * one or more tracks. Each {@link Track track} consists of a series of MIDI + * events (such as note-ons, note-offs, program changes, and meta-events). The + * sequence's timing information specifies the type of unit that is used to + * time-stamp the events in the sequence. * <p> - * A <code>Sequence</code> can be created from a MIDI file by reading the file - * into an input stream and invoking one of the <code>getSequence</code> methods of - * {@link MidiSystem}. A sequence can also be built from scratch by adding new - * <code>Tracks</code> to an empty <code>Sequence</code>, and adding - * <code>{@link MidiEvent}</code> objects to these <code>Tracks</code>. + * A {@code Sequence} can be created from a MIDI file by reading the file into + * an input stream and invoking one of the {@code getSequence} methods of + * {@link MidiSystem}. A sequence can also be built from scratch by adding new + * {@code Tracks} to an empty {@code Sequence}, and adding {@link MidiEvent} + * objects to these {@code Tracks}. * + * @author Kara Kytle * @see Sequencer#setSequence(java.io.InputStream stream) * @see Sequencer#setSequence(Sequence sequence) * @see Track#add(MidiEvent) * @see MidiFileFormat - * - * @author Kara Kytle */ public class Sequence { - // Timing types /** - * The tempo-based timing type, for which the resolution is expressed in pulses (ticks) per quarter note. + * The tempo-based timing type, for which the resolution is expressed in + * pulses (ticks) per quarter note. + * * @see #Sequence(float, int) */ public static final float PPQ = 0.0f; /** - * The SMPTE-based timing type with 24 frames per second (resolution is expressed in ticks per frame). + * The SMPTE-based timing type with 24 frames per second (resolution is + * expressed in ticks per frame). + * * @see #Sequence(float, int) */ public static final float SMPTE_24 = 24.0f; /** - * The SMPTE-based timing type with 25 frames per second (resolution is expressed in ticks per frame). + * The SMPTE-based timing type with 25 frames per second (resolution is + * expressed in ticks per frame). + * * @see #Sequence(float, int) */ public static final float SMPTE_25 = 25.0f; /** - * The SMPTE-based timing type with 29.97 frames per second (resolution is expressed in ticks per frame). + * The SMPTE-based timing type with 29.97 frames per second (resolution is + * expressed in ticks per frame). + * * @see #Sequence(float, int) */ public static final float SMPTE_30DROP = 29.97f; /** - * The SMPTE-based timing type with 30 frames per second (resolution is expressed in ticks per frame). + * The SMPTE-based timing type with 30 frames per second (resolution is + * expressed in ticks per frame). + * * @see #Sequence(float, int) */ public static final float SMPTE_30 = 30.0f; - // Variables /** * The timing division type of the sequence. + * * @see #PPQ * @see #SMPTE_24 * @see #SMPTE_25 @@ -103,33 +108,33 @@ /** * The timing resolution of the sequence. + * * @see #getResolution */ protected int resolution; /** * The MIDI tracks in this sequence. + * * @see #getTracks */ protected Vector<Track> tracks = new Vector<Track>(); - /** - * Constructs a new MIDI sequence with the specified timing division - * type and timing resolution. The division type must be one of the - * recognized MIDI timing types. For tempo-based timing, - * <code>divisionType</code> is PPQ (pulses per quarter note) and - * the resolution is specified in ticks per beat. For SMTPE timing, - * <code>divisionType</code> specifies the number of frames per - * second and the resolution is specified in ticks per frame. - * The sequence will contain no initial tracks. Tracks may be - * added to or removed from the sequence using <code>{@link #createTrack}</code> - * and <code>{@link #deleteTrack}</code>. + * Constructs a new MIDI sequence with the specified timing division type + * and timing resolution. The division type must be one of the recognized + * MIDI timing types. For tempo-based timing, {@code divisionType} is PPQ + * (pulses per quarter note) and the resolution is specified in ticks per + * beat. For SMTPE timing, {@code divisionType} specifies the number of + * frames per second and the resolution is specified in ticks per frame. The + * sequence will contain no initial tracks. Tracks may be added to or + * removed from the sequence using {@link #createTrack} and + * {@link #deleteTrack}. * - * @param divisionType the timing division type (PPQ or one of the SMPTE types) - * @param resolution the timing resolution - * @throws InvalidMidiDataException if <code>divisionType</code> is not valid - * + * @param divisionType the timing division type (PPQ or one of the SMPTE + * types) + * @param resolution the timing resolution + * @throws InvalidMidiDataException if {@code divisionType} is not valid * @see #PPQ * @see #SMPTE_24 * @see #SMPTE_25 @@ -156,27 +161,25 @@ this.resolution = resolution; } - /** - * Constructs a new MIDI sequence with the specified timing division - * type, timing resolution, and number of tracks. The division type must be one of the - * recognized MIDI timing types. For tempo-based timing, - * <code>divisionType</code> is PPQ (pulses per quarter note) and - * the resolution is specified in ticks per beat. For SMTPE timing, - * <code>divisionType</code> specifies the number of frames per - * second and the resolution is specified in ticks per frame. - * The sequence will be initialized with the number of tracks specified by - * <code>numTracks</code>. These tracks are initially empty (i.e. - * they contain only the meta-event End of Track). - * The tracks may be retrieved for editing using the <code>{@link #getTracks}</code> - * method. Additional tracks may be added, or existing tracks removed, - * using <code>{@link #createTrack}</code> and <code>{@link #deleteTrack}</code>. + * Constructs a new MIDI sequence with the specified timing division type, + * timing resolution, and number of tracks. The division type must be one of + * the recognized MIDI timing types. For tempo-based timing, + * {@code divisionType} is PPQ (pulses per quarter note) and the resolution + * is specified in ticks per beat. For SMTPE timing, {@code divisionType} + * specifies the number of frames per second and the resolution is specified + * in ticks per frame. The sequence will be initialized with the number of + * tracks specified by {@code numTracks}. These tracks are initially empty + * (i.e. they contain only the meta-event End of Track). The tracks may be + * retrieved for editing using the {@link #getTracks} method. Additional + * tracks may be added, or existing tracks removed, using + * {@link #createTrack} and {@link #deleteTrack}. * - * @param divisionType the timing division type (PPQ or one of the SMPTE types) - * @param resolution the timing resolution - * @param numTracks the initial number of tracks in the sequence. - * @throws InvalidMidiDataException if <code>divisionType</code> is not valid - * + * @param divisionType the timing division type (PPQ or one of the SMPTE + * types) + * @param resolution the timing resolution + * @param numTracks the initial number of tracks in the sequence + * @throws InvalidMidiDataException if {@code divisionType} is not valid * @see #PPQ * @see #SMPTE_24 * @see #SMPTE_25 @@ -206,11 +209,10 @@ } } - /** * Obtains the timing division type for this sequence. + * * @return the division type (PPQ or one of the SMPTE types) - * * @see #PPQ * @see #SMPTE_24 * @see #SMPTE_25 @@ -223,11 +225,10 @@ return divisionType; } - /** - * Obtains the timing resolution for this sequence. - * If the sequence's division type is PPQ, the resolution is specified in ticks per beat. - * For SMTPE timing, the resolution is specified in ticks per frame. + * Obtains the timing resolution for this sequence. If the sequence's + * division type is PPQ, the resolution is specified in ticks per beat. For + * SMTPE timing, the resolution is specified in ticks per frame. * * @return the number of ticks per beat (PPQ) or per frame (SMPTE) * @see #getDivisionType @@ -238,13 +239,13 @@ return resolution; } - /** - * Creates a new, initially empty track as part of this sequence. - * The track initially contains the meta-event End of Track. - * The newly created track is returned. All tracks in the sequence - * may be retrieved using <code>{@link #getTracks}</code>. Tracks may be - * removed from the sequence using <code>{@link #deleteTrack}</code>. + * Creates a new, initially empty track as part of this sequence. The track + * initially contains the meta-event End of Track. The newly created track + * is returned. All tracks in the sequence may be retrieved using + * {@link #getTracks}. Tracks may be removed from the sequence using + * {@link #deleteTrack}. + * * @return the newly created track */ public Track createTrack() { @@ -255,13 +256,12 @@ return track; } - /** * Removes the specified track from the sequence. - * @param track the track to remove - * @return <code>true</code> if the track existed in the track and was removed, - * otherwise <code>false</code>. * + * @param track the track to remove + * @return {@code true} if the track existed in the track and was removed, + * otherwise {@code false} * @see #createTrack * @see #getTracks */ @@ -273,12 +273,11 @@ } } - /** - * Obtains an array containing all the tracks in this sequence. - * If the sequence contains no tracks, an array of length 0 is returned. + * Obtains an array containing all the tracks in this sequence. If the + * sequence contains no tracks, an array of length 0 is returned. + * * @return the array of tracks - * * @see #createTrack * @see #deleteTrack */ @@ -287,22 +286,20 @@ return tracks.toArray(new Track[tracks.size()]); } - /** * Obtains the duration of this sequence, expressed in microseconds. - * @return this sequence's duration in microseconds. + * + * @return this sequence's duration in microseconds */ public long getMicrosecondLength() { return com.sun.media.sound.MidiUtils.tick2microsecond(this, getTickLength(), null); } - /** * Obtains the duration of this sequence, expressed in MIDI ticks. * * @return this sequence's length in ticks - * * @see #getMicrosecondLength */ public long getTickLength() { @@ -321,15 +318,12 @@ } } - /** - * Obtains a list of patches referenced in this sequence. - * This patch list may be used to load the required - * <code>{@link Instrument}</code> objects - * into a <code>{@link Synthesizer}</code>. + * Obtains a list of patches referenced in this sequence. This patch list + * may be used to load the required {@link Instrument} objects into a + * {@link Synthesizer}. * - * @return an array of <code>{@link Patch}</code> objects used in this sequence - * + * @return an array of {@link Patch} objects used in this sequence * @see Synthesizer#loadInstruments(Soundbank, Patch[]) */ public Patch[] getPatchList() {
--- a/jdk/src/share/classes/javax/sound/midi/Sequencer.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/Sequencer.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -25,19 +25,18 @@ package javax.sound.midi; +import java.io.IOException; import java.io.InputStream; -import java.io.IOException; - /** * A hardware or software device that plays back a MIDI - * <code>{@link Sequence sequence}</code> is known as a <em>sequencer</em>. - * A MIDI sequence contains lists of time-stamped MIDI data, such as - * might be read from a standard MIDI file. Most - * sequencers also provide functions for creating and editing sequences. + * {@link Sequence sequence} is known as a <em>sequencer</em>. A MIDI sequence + * contains lists of time-stamped MIDI data, such as might be read from a + * standard MIDI file. Most sequencers also provide functions for creating and + * editing sequences. * <p> - * The <code>Sequencer</code> interface includes methods for the following - * basic MIDI sequencer operations: + * 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> @@ -48,729 +47,635 @@ * <li>controlling the timing of another device</li> * </ul> * In addition, the following operations are supported, either directly, or - * indirectly through objects that the <code>Sequencer</code> has access to: + * 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>notifying listener objects about any meta-events or control-change events + * encountered while playing back the sequence.</li> * </ul> * - * @see Sequencer.SyncMode + * @author Kara Kytle + * @author Florian Bomers + * @see SyncMode * @see #addMetaEventListener * @see ControllerEventListener * @see Receiver * @see Transmitter * @see MidiDevice - * - * @author Kara Kytle - * @author Florian Bomers */ public interface Sequencer extends MidiDevice { - /** - * A value indicating that looping should continue - * indefinitely rather than complete after a specific - * number of loops. + * A value indicating that looping should continue indefinitely rather than + * complete after a specific number of loops. * * @see #setLoopCount * @since 1.5 */ - public static final int LOOP_CONTINUOUSLY = -1; - - - - /** - * Sets the current sequence on which the sequencer operates. - * - * <p>This method can be called even if the - * <code>Sequencer</code> is closed. - * - * @param sequence the sequence to be loaded. - * @throws InvalidMidiDataException if the sequence contains invalid - * MIDI data, or is not supported. - */ - public void setSequence(Sequence sequence) throws InvalidMidiDataException; - + int LOOP_CONTINUOUSLY = -1; /** * Sets the current sequence on which the sequencer operates. - * The stream must point to MIDI file data. - * - * <p>This method can be called even if the - * <code>Sequencer</code> is closed. + * <p> + * This method can be called even if the {@code Sequencer} is closed. * - * @param stream stream containing MIDI file data. - * @throws IOException if an I/O exception occurs during reading of the stream. - * @throws InvalidMidiDataException if invalid data is encountered - * in the stream, or the stream is not supported. + * @param sequence the sequence to be loaded + * @throws InvalidMidiDataException if the sequence contains invalid MIDI + * data, or is not supported */ - public void setSequence(InputStream stream) throws IOException, InvalidMidiDataException; + void setSequence(Sequence sequence) throws InvalidMidiDataException; + /** + * Sets the current sequence on which the sequencer operates. The stream + * must point to MIDI file data. + * <p> + * This method can be called even if the {@code Sequencer} is closed. + * + * @param stream stream containing MIDI file data + * @throws IOException if an I/O exception occurs during reading of the + * stream + * @throws InvalidMidiDataException if invalid data is encountered in the + * stream, or the stream is not supported + */ + void setSequence(InputStream stream) + throws IOException, InvalidMidiDataException; /** * Obtains the sequence on which the Sequencer is currently operating. - * - * <p>This method can be called even if the - * <code>Sequencer</code> is closed. + * <p> + * This method can be called even if the {@code Sequencer} is closed. * - * @return the current sequence, or <code>null</code> if no sequence is currently set. + * @return the current sequence, or {@code null} if no sequence is currently + * set */ - public Sequence getSequence(); - + Sequence getSequence(); /** - * Starts playback of the MIDI data in the currently - * loaded sequence. - * Playback will begin from the current position. - * If the playback position reaches the loop end point, - * and the loop count is greater than 0, playback will - * resume at the loop start point for the number of - * repetitions set with <code>setLoopCount</code>. - * After that, or if the loop count is 0, playback will - * continue to play to the end of the sequence. + * Starts playback of the MIDI data in the currently loaded sequence. + * Playback will begin from the current position. If the playback position + * reaches the loop end point, and the loop count is greater than 0, + * playback will resume at the loop start point for the number of + * repetitions set with {@code setLoopCount}. After that, or if the loop + * count is 0, playback will continue to play to the end of the sequence. + * <p> + * The implementation ensures that the synthesizer is brought to a + * consistent state when jumping to the loop start point by sending + * appropriate controllers, pitch bend, and program change events. * - * <p>The implementation ensures that the synthesizer - * is brought to a consistent state when jumping - * to the loop start point by sending appropriate - * controllers, pitch bend, and program change events. - * - * @throws IllegalStateException if the <code>Sequencer</code> is - * closed. - * + * @throws IllegalStateException if the {@code Sequencer} is closed * @see #setLoopStartPoint * @see #setLoopEndPoint * @see #setLoopCount * @see #stop */ - public void start(); - + void start(); /** - * Stops recording, if active, and playback of the currently loaded sequence, - * if any. + * Stops recording, if active, and playback of the currently loaded + * sequence, if any. * - * @throws IllegalStateException if the <code>Sequencer</code> is - * closed. - * + * @throws IllegalStateException if the {@code Sequencer} is closed * @see #start * @see #isRunning */ - public void stop(); - - - /** - * Indicates whether the Sequencer is currently running. The default is <code>false</code>. - * The Sequencer starts running when either <code>{@link #start}</code> or <code>{@link #startRecording}</code> - * is called. <code>isRunning</code> then returns <code>true</code> until playback of the - * sequence completes or <code>{@link #stop}</code> is called. - * @return <code>true</code> if the Sequencer is running, otherwise <code>false</code> - */ - public boolean isRunning(); - + void stop(); /** - * Starts recording and playback of MIDI data. Data is recorded to all enabled tracks, - * on the channel(s) for which they were enabled. Recording begins at the current position - * of the sequencer. Any events already in the track are overwritten for the duration - * of the recording session. Events from the currently loaded sequence, - * if any, are delivered to the sequencer's transmitter(s) along with messages - * received during recording. + * Indicates whether the Sequencer is currently running. The default is + * {@code false}. The Sequencer starts running when either{@link #start} or + * {@link #startRecording} is called. {@code isRunning} then returns + * {@code true} until playback of the sequence completes or {@link #stop} is + * called. + * + * @return {@code true} if the Sequencer is running, otherwise {@code false} + */ + boolean isRunning(); + + /** + * Starts recording and playback of MIDI data. Data is recorded to all + * enabled tracks, on the channel(s) for which they were enabled. Recording + * begins at the current position of the sequencer. Any events already in + * the track are overwritten for the duration of the recording session. + * Events from the currently loaded sequence, if any, are delivered to the + * sequencer's transmitter(s) along with messages received during recording. * <p> - * Note that tracks are not by default enabled for recording. In order to record MIDI data, - * at least one track must be specifically enabled for recording. + * Note that tracks are not by default enabled for recording. In order to + * record MIDI data, at least one track must be specifically enabled for + * recording. * - * @throws IllegalStateException if the <code>Sequencer</code> is - * closed. - * - * @see #startRecording + * @throws IllegalStateException if the {@code Sequencer} is closed * @see #recordEnable * @see #recordDisable */ - public void startRecording(); - + void startRecording(); /** - * Stops recording, if active. Playback of the current sequence continues. + * Stops recording, if active. Playback of the current sequence continues. * - * @throws IllegalStateException if the <code>Sequencer</code> is - * closed. - * + * @throws IllegalStateException if the {@code Sequencer} is closed * @see #startRecording * @see #isRecording */ - public void stopRecording(); - + void stopRecording(); /** - * Indicates whether the Sequencer is currently recording. The default is <code>false</code>. - * The Sequencer begins recording when <code>{@link #startRecording}</code> is called, - * and then returns <code>true</code> until <code>{@link #stop}</code> or <code>{@link #stopRecording}</code> - * is called. - * @return <code>true</code> if the Sequencer is recording, otherwise <code>false</code> + * Indicates whether the Sequencer is currently recording. The default is + * {@code false}. The Sequencer begins recording when + * {@link #startRecording} is called, and then returns {@code true} until + * {@link #stop} or {@link #stopRecording} is called. + * + * @return {@code true} if the Sequencer is recording, otherwise + * {@code false} */ - public boolean isRecording(); - + boolean isRecording(); /** - * Prepares the specified track for recording events received on a particular channel. - * Once enabled, a track will receive events when recording is active. - * @param track the track to which events will be recorded - * @param channel the channel on which events will be received. If -1 is specified - * for the channel value, the track will receive data from all channels. - * @throws IllegalArgumentException thrown if the track is not part of the current - * sequence. + * Prepares the specified track for recording events received on a + * particular channel. Once enabled, a track will receive events when + * recording is active. + * + * @param track the track to which events will be recorded + * @param channel the channel on which events will be received. If -1 is + * specified for the channel value, the track will receive data from + * all channels. + * @throws IllegalArgumentException thrown if the track is not part of the + * current sequence */ - public void recordEnable(Track track, int channel); - + void recordEnable(Track track, int channel); /** - * Disables recording to the specified track. Events will no longer be recorded - * into this track. - * @param track the track to disable for recording, or <code>null</code> to disable - * recording for all tracks. + * Disables recording to the specified track. Events will no longer be + * recorded into this track. + * + * @param track the track to disable for recording, or {@code null} to + * disable recording for all tracks */ - public void recordDisable(Track track); - + void recordDisable(Track track); /** - * Obtains the current tempo, expressed in beats per minute. The - * actual tempo of playback is the product of the returned value - * and the tempo factor. + * Obtains the current tempo, expressed in beats per minute. The actual + * tempo of playback is the product of the returned value and the tempo + * factor. * * @return the current tempo in beats per minute - * * @see #getTempoFactor * @see #setTempoInBPM(float) * @see #getTempoInMPQ */ - public float getTempoInBPM(); - + float getTempoInBPM(); /** - * Sets the tempo in beats per minute. The actual tempo of playback - * is the product of the specified value and the tempo factor. + * Sets the tempo in beats per minute. The actual tempo of playback is the + * product of the specified value and the tempo factor. * - * @param bpm desired new tempo in beats per minute + * @param bpm desired new tempo in beats per minute * @see #getTempoFactor * @see #setTempoInMPQ(float) * @see #getTempoInBPM */ - public void setTempoInBPM(float bpm); - + void setTempoInBPM(float bpm); /** - * Obtains the current tempo, expressed in microseconds per quarter - * note. The actual tempo of playback is the product of the returned - * value and the tempo factor. + * Obtains the current tempo, expressed in microseconds per quarter note. + * The actual tempo of playback is the product of the returned value and the + * tempo factor. * * @return the current tempo in microseconds per quarter note * @see #getTempoFactor * @see #setTempoInMPQ(float) * @see #getTempoInBPM */ - public float getTempoInMPQ(); - + float getTempoInMPQ(); /** - * Sets the tempo in microseconds per quarter note. The actual tempo - * of playback is the product of the specified value and the tempo - * factor. + * Sets the tempo in microseconds per quarter note. The actual tempo of + * playback is the product of the specified value and the tempo factor. * - * @param mpq desired new tempo in microseconds per quarter note. + * @param mpq desired new tempo in microseconds per quarter note * @see #getTempoFactor * @see #setTempoInBPM(float) * @see #getTempoInMPQ */ - public void setTempoInMPQ(float mpq); - + void setTempoInMPQ(float mpq); /** - * Scales the sequencer's actual playback tempo by the factor provided. - * The default is 1.0. A value of 1.0 represents the natural rate (the - * tempo specified in the sequence), 2.0 means twice as fast, etc. - * The tempo factor does not affect the values returned by - * <code>{@link #getTempoInMPQ}</code> and <code>{@link #getTempoInBPM}</code>. - * Those values indicate the tempo prior to scaling. + * Scales the sequencer's actual playback tempo by the factor provided. The + * default is 1.0. A value of 1.0 represents the natural rate (the tempo + * specified in the sequence), 2.0 means twice as fast, etc. The tempo + * factor does not affect the values returned by {@link #getTempoInMPQ} and + * {@link #getTempoInBPM}. Those values indicate the tempo prior to scaling. * <p> * Note that the tempo factor cannot be adjusted when external - * synchronization is used. In that situation, - * <code>setTempoFactor</code> always sets the tempo factor to 1.0. + * synchronization is used. In that situation, {@code setTempoFactor} always + * sets the tempo factor to 1.0. * - * @param factor the requested tempo scalar + * @param factor the requested tempo scalar * @see #getTempoFactor */ - public void setTempoFactor(float factor); - + void setTempoFactor(float factor); /** - * Returns the current tempo factor for the sequencer. The default is - * 1.0. + * Returns the current tempo factor for the sequencer. The default is 1.0. * - * @return tempo factor. + * @return tempo factor * @see #setTempoFactor(float) */ - public float getTempoFactor(); - + float getTempoFactor(); /** - * Obtains the length of the current sequence, expressed in MIDI ticks, - * or 0 if no sequence is set. + * Obtains the length of the current sequence, expressed in MIDI ticks, or 0 + * if no sequence is set. + * * @return length of the sequence in ticks */ - public long getTickLength(); - + long getTickLength(); /** - * Obtains the current position in the sequence, expressed in MIDI - * ticks. (The duration of a tick in seconds is determined both by - * the tempo and by the timing resolution stored in the - * <code>{@link Sequence}</code>.) + * Obtains the current position in the sequence, expressed in MIDI ticks. + * (The duration of a tick in seconds is determined both by the tempo and by + * the timing resolution stored in the {@link Sequence}.) * * @return current tick * @see #setTickPosition */ - public long getTickPosition(); - + long getTickPosition(); /** - * Sets the current sequencer position in MIDI ticks - * @param tick the desired tick position + * Sets the current sequencer position in MIDI ticks. + * + * @param tick the desired tick position * @see #getTickPosition */ - public void setTickPosition(long tick); - + void setTickPosition(long tick); /** - * Obtains the length of the current sequence, expressed in microseconds, - * or 0 if no sequence is set. - * @return length of the sequence in microseconds. + * Obtains the length of the current sequence, expressed in microseconds, or + * 0 if no sequence is set. + * + * @return length of the sequence in microseconds */ - public long getMicrosecondLength(); - + long getMicrosecondLength(); /** - * Obtains the current position in the sequence, expressed in - * microseconds. + * Obtains the current position in the sequence, expressed in microseconds. + * * @return the current position in microseconds * @see #setMicrosecondPosition */ - public long getMicrosecondPosition(); - + long getMicrosecondPosition(); /** - * Sets the current position in the sequence, expressed in microseconds - * @param microseconds desired position in microseconds + * Sets the current position in the sequence, expressed in microseconds. + * + * @param microseconds desired position in microseconds * @see #getMicrosecondPosition */ - public void setMicrosecondPosition(long microseconds); - + void setMicrosecondPosition(long microseconds); /** - * Sets the source of timing information used by this sequencer. - * The sequencer synchronizes to the master, which is the internal clock, - * MIDI clock, or MIDI time code, depending on the value of - * <code>sync</code>. The <code>sync</code> argument must be one - * of the supported modes, as returned by - * <code>{@link #getMasterSyncModes}</code>. + * Sets the source of timing information used by this sequencer. The + * sequencer synchronizes to the master, which is the internal clock, MIDI + * clock, or MIDI time code, depending on the value of {@code sync}. The + * {@code sync} argument must be one of the supported modes, as returned by + * {@link #getMasterSyncModes}. * - * @param sync the desired master synchronization mode - * + * @param sync the desired master synchronization mode * @see SyncMode#INTERNAL_CLOCK * @see SyncMode#MIDI_SYNC * @see SyncMode#MIDI_TIME_CODE * @see #getMasterSyncMode */ - public void setMasterSyncMode(SyncMode sync); - + void setMasterSyncMode(SyncMode sync); /** * Obtains the current master synchronization mode for this sequencer. * * @return the current master synchronization mode - * - * @see #setMasterSyncMode(Sequencer.SyncMode) + * @see #setMasterSyncMode(SyncMode) * @see #getMasterSyncModes */ - public SyncMode getMasterSyncMode(); - + SyncMode getMasterSyncMode(); /** * Obtains the set of master synchronization modes supported by this * sequencer. * * @return the available master synchronization modes - * * @see SyncMode#INTERNAL_CLOCK * @see SyncMode#MIDI_SYNC * @see SyncMode#MIDI_TIME_CODE * @see #getMasterSyncMode - * @see #setMasterSyncMode(Sequencer.SyncMode) + * @see #setMasterSyncMode(SyncMode) */ - public SyncMode[] getMasterSyncModes(); - + SyncMode[] getMasterSyncModes(); /** - * Sets the slave synchronization mode for the sequencer. - * This indicates the type of timing information sent by the sequencer - * to its receiver. The <code>sync</code> argument must be one - * of the supported modes, as returned by - * <code>{@link #getSlaveSyncModes}</code>. + * Sets the slave synchronization mode for the sequencer. This indicates the + * type of timing information sent by the sequencer to its receiver. The + * {@code sync} argument must be one of the supported modes, as returned by + * {@link #getSlaveSyncModes}. * - * @param sync the desired slave synchronization mode - * + * @param sync the desired slave synchronization mode * @see SyncMode#MIDI_SYNC * @see SyncMode#MIDI_TIME_CODE * @see SyncMode#NO_SYNC * @see #getSlaveSyncModes */ - public void setSlaveSyncMode(SyncMode sync); - + void setSlaveSyncMode(SyncMode sync); /** * Obtains the current slave synchronization mode for this sequencer. * * @return the current slave synchronization mode - * - * @see #setSlaveSyncMode(Sequencer.SyncMode) + * @see #setSlaveSyncMode(SyncMode) * @see #getSlaveSyncModes */ - public SyncMode getSlaveSyncMode(); - + SyncMode getSlaveSyncMode(); /** - * Obtains the set of slave synchronization modes supported by the sequencer. + * Obtains the set of slave synchronization modes supported by the + * sequencer. * * @return the available slave synchronization modes - * * @see SyncMode#MIDI_SYNC * @see SyncMode#MIDI_TIME_CODE * @see SyncMode#NO_SYNC */ - public SyncMode[] getSlaveSyncModes(); - + SyncMode[] getSlaveSyncModes(); /** - * Sets the mute state for a track. This method may fail for a number - * of reasons. For example, the track number specified may not be valid - * for the current sequence, or the sequencer may not support this functionality. - * An application which needs to verify whether this operation succeeded should - * follow this call with a call to <code>{@link #getTrackMute}</code>. + * Sets the mute state for a track. This method may fail for a number of + * reasons. For example, the track number specified may not be valid for the + * current sequence, or the sequencer may not support this functionality. An + * application which needs to verify whether this operation succeeded should + * follow this call with a call to {@link #getTrackMute}. * - * @param track the track number. Tracks in the current sequence are numbered - * from 0 to the number of tracks in the sequence minus 1. - * @param mute the new mute state for the track. <code>true</code> implies the - * track should be muted, <code>false</code> implies the track should be unmuted. + * @param track the track number. Tracks in the current sequence are + * numbered from 0 to the number of tracks in the sequence minus 1. + * @param mute the new mute state for the track. {@code true} implies the + * track should be muted, {@code false} implies the track should be + * unmuted. * @see #getSequence */ - public void setTrackMute(int track, boolean mute); - + void setTrackMute(int track, boolean mute); /** - * Obtains the current mute state for a track. The default mute - * state for all tracks which have not been muted is false. In any - * case where the specified track has not been muted, this method should - * return false. This applies if the sequencer does not support muting - * of tracks, and if the specified track index is not valid. + * Obtains the current mute state for a track. The default mute state for + * all tracks which have not been muted is false. In any case where the + * specified track has not been muted, this method should return false. This + * applies if the sequencer does not support muting of tracks, and if the + * specified track index is not valid. * - * @param track the track number. Tracks in the current sequence are numbered - * from 0 to the number of tracks in the sequence minus 1. - * @return <code>true</code> if muted, <code>false</code> if not. + * @param track the track number. Tracks in the current sequence are + * numbered from 0 to the number of tracks in the sequence minus 1. + * @return {@code true} if muted, {@code false} if not */ - public boolean getTrackMute(int track); + boolean getTrackMute(int track); /** - * Sets the solo state for a track. If <code>solo</code> is <code>true</code> - * only this track and other solo'd tracks will sound. If <code>solo</code> - * is <code>false</code> then only other solo'd tracks will sound, unless no - * tracks are solo'd in which case all un-muted tracks will sound. + * Sets the solo state for a track. If {@code solo} is {@code true} only + * this track and other solo'd tracks will sound. If {@code solo} is + * {@code false} then only other solo'd tracks will sound, unless no tracks + * are solo'd in which case all un-muted tracks will sound. * <p> - * This method may fail for a number - * of reasons. For example, the track number specified may not be valid - * for the current sequence, or the sequencer may not support this functionality. - * An application which needs to verify whether this operation succeeded should - * follow this call with a call to <code>{@link #getTrackSolo}</code>. + * This method may fail for a number of reasons. For example, the track + * number specified may not be valid for the current sequence, or the + * sequencer may not support this functionality. An application which needs + * to verify whether this operation succeeded should follow this call with a + * call to {@link #getTrackSolo}. * - * @param track the track number. Tracks in the current sequence are numbered - * from 0 to the number of tracks in the sequence minus 1. - * @param solo the new solo state for the track. <code>true</code> implies the - * track should be solo'd, <code>false</code> implies the track should not be solo'd. + * @param track the track number. Tracks in the current sequence are + * numbered from 0 to the number of tracks in the sequence minus 1. + * @param solo the new solo state for the track. {@code true} implies the + * track should be solo'd, {@code false} implies the track should + * not be solo'd. * @see #getSequence */ - public void setTrackSolo(int track, boolean solo); - + void setTrackSolo(int track, boolean solo); /** - * Obtains the current solo state for a track. The default mute - * state for all tracks which have not been solo'd is false. In any - * case where the specified track has not been solo'd, this method should - * return false. This applies if the sequencer does not support soloing - * of tracks, and if the specified track index is not valid. + * Obtains the current solo state for a track. The default mute state for + * all tracks which have not been solo'd is false. In any case where the + * specified track has not been solo'd, this method should return false. + * This applies if the sequencer does not support soloing of tracks, and if + * the specified track index is not valid. * - * @param track the track number. Tracks in the current sequence are numbered - * from 0 to the number of tracks in the sequence minus 1. - * @return <code>true</code> if solo'd, <code>false</code> if not. + * @param track the track number. Tracks in the current sequence are + * numbered from 0 to the number of tracks in the sequence minus 1. + * @return {@code true} if solo'd, {@code false} if not */ - public boolean getTrackSolo(int track); - + boolean getTrackSolo(int track); /** - * Registers a meta-event listener to receive - * notification whenever a meta-event is encountered in the sequence - * and processed by the sequencer. This method can fail if, for - * instance,this class of sequencer does not support meta-event - * notification. + * Registers a meta-event listener to receive notification whenever a + * meta-event is encountered in the sequence and processed by the sequencer. + * This method can fail if, for instance,this class of sequencer does not + * support meta-event notification. * - * @param listener listener to add - * @return <code>true</code> if the listener was successfully added, - * otherwise <code>false</code> - * + * @param listener listener to add + * @return {@code true} if the listener was successfully added, otherwise + * {@code false} * @see #removeMetaEventListener * @see MetaEventListener * @see MetaMessage */ - public boolean addMetaEventListener(MetaEventListener listener); - + boolean addMetaEventListener(MetaEventListener listener); /** - * Removes the specified meta-event listener from this sequencer's - * list of registered listeners, if in fact the listener is registered. + * Removes the specified meta-event listener from this sequencer's list of + * registered listeners, if in fact the listener is registered. * - * @param listener the meta-event listener to remove + * @param listener the meta-event listener to remove * @see #addMetaEventListener */ - public void removeMetaEventListener(MetaEventListener listener); - + void removeMetaEventListener(MetaEventListener listener); /** - * Registers a controller event listener to receive notification - * whenever the sequencer processes a control-change event of the - * requested type or types. The types are specified by the - * <code>controllers</code> argument, which should contain an array of - * MIDI controller numbers. (Each number should be between 0 and 127, - * inclusive. See the MIDI 1.0 Specification for the numbers that - * correspond to various types of controllers.) + * Registers a controller event listener to receive notification whenever + * the sequencer processes a control-change event of the requested type or + * types. The types are specified by the {@code controllers} argument, which + * should contain an array of MIDI controller numbers. (Each number should + * be between 0 and 127, inclusive. See the MIDI 1.0 Specification for the + * numbers that correspond to various types of controllers.) * <p> - * The returned array contains the MIDI controller - * numbers for which the listener will now receive events. - * Some sequencers might not support controller event notification, in - * which case the array has a length of 0. Other sequencers might - * support notification for some controllers but not all. - * This method may be invoked repeatedly. - * Each time, the returned array indicates all the controllers - * that the listener will be notified about, not only the controllers - * requested in that particular invocation. + * The returned array contains the MIDI controller numbers for which the + * listener will now receive events. Some sequencers might not support + * controller event notification, in which case the array has a length of 0. + * Other sequencers might support notification for some controllers but not + * all. This method may be invoked repeatedly. Each time, the returned array + * indicates all the controllers that the listener will be notified about, + * not only the controllers requested in that particular invocation. * - * @param listener the controller event listener to add to the list of - * registered listeners - * @param controllers the MIDI controller numbers for which change - * notification is requested - * @return the numbers of all the MIDI controllers whose changes will - * now be reported to the specified listener - * + * @param listener the controller event listener to add to the list of + * registered listeners + * @param controllers the MIDI controller numbers for which change + * notification is requested + * @return the numbers of all the MIDI controllers whose changes will now be + * reported to the specified listener * @see #removeControllerEventListener * @see ControllerEventListener */ - public int[] addControllerEventListener(ControllerEventListener listener, int[] controllers); - + int[] addControllerEventListener(ControllerEventListener listener, + int[] controllers); /** - * Removes a controller event listener's interest in one or more - * types of controller event. The <code>controllers</code> argument - * is an array of MIDI numbers corresponding to the controllers for - * which the listener should no longer receive change notifications. - * To completely remove this listener from the list of registered - * listeners, pass in <code>null</code> for <code>controllers</code>. - * The returned array contains the MIDI controller - * numbers for which the listener will now receive events. The - * array has a length of 0 if the listener will not receive - * change notifications for any controllers. + * Removes a controller event listener's interest in one or more types of + * controller event. The {@code controllers} argument is an array of MIDI + * numbers corresponding to the controllers for which the listener should no + * longer receive change notifications. To completely remove this listener + * from the list of registered listeners, pass in {@code null} for + * {@code controllers}. The returned array contains the MIDI controller + * numbers for which the listener will now receive events. The array has a + * length of 0 if the listener will not receive change notifications for any + * controllers. * - * @param listener old listener - * @param controllers the MIDI controller numbers for which change - * notification should be cancelled, or <code>null</code> to cancel - * for all controllers - * @return the numbers of all the MIDI controllers whose changes will - * now be reported to the specified listener - * + * @param listener old listener + * @param controllers the MIDI controller numbers for which change + * notification should be cancelled, or {@code null} to cancel for + * all controllers + * @return the numbers of all the MIDI controllers whose changes will now be + * reported to the specified listener * @see #addControllerEventListener */ - public int[] removeControllerEventListener(ControllerEventListener listener, int[] controllers); - + int[] removeControllerEventListener(ControllerEventListener listener, + int[] controllers); /** - * Sets the first MIDI tick that will be - * played in the loop. If the loop count is - * greater than 0, playback will jump to this - * point when reaching the loop end point. - * - * <p>A value of 0 for the starting point means the - * beginning of the loaded sequence. The starting - * point must be lower than or equal to the ending - * point, and it must fall within the size of the - * loaded sequence. + * Sets the first MIDI tick that will be played in the loop. If the loop + * count is greater than 0, playback will jump to this point when reaching + * the loop end point. + * <p> + * A value of 0 for the starting point means the beginning of the loaded + * sequence. The starting point must be lower than or equal to the ending + * point, and it must fall within the size of the loaded sequence. + * <p> + * A sequencer's loop start point defaults to start of the sequence. * - * <p>A sequencer's loop start point defaults to - * start of the sequence. - * - * @param tick the loop's starting position, - * in MIDI ticks (zero-based) - * @throws IllegalArgumentException if the requested - * loop start point cannot be set, usually because - * it falls outside the sequence's - * duration or because the start point is - * after the end point - * + * @param tick the loop's starting position, in MIDI ticks (zero-based) + * @throws IllegalArgumentException if the requested loop start point cannot + * be set, usually because it falls outside the sequence's duration + * or because the start point is after the end point * @see #setLoopEndPoint * @see #setLoopCount * @see #getLoopStartPoint * @see #start * @since 1.5 */ - public void setLoopStartPoint(long tick); - + void setLoopStartPoint(long tick); /** - * Obtains the start position of the loop, - * in MIDI ticks. + * Obtains the start position of the loop, in MIDI ticks. * - * @return the start position of the loop, - in MIDI ticks (zero-based) + * @return the start position of the loop, in MIDI ticks (zero-based) * @see #setLoopStartPoint * @since 1.5 */ - public long getLoopStartPoint(); - + long getLoopStartPoint(); /** - * Sets the last MIDI tick that will be played in - * the loop. If the loop count is 0, the loop end - * point has no effect and playback continues to + * Sets the last MIDI tick that will be played in the loop. If the loop + * count is 0, the loop end point has no effect and playback continues to * play when reaching the loop end point. - * - * <p>A value of -1 for the ending point - * indicates the last tick of the sequence. - * Otherwise, the ending point must be greater - * than or equal to the starting point, and it must - * fall within the size of the loaded sequence. + * <p> + * A value of -1 for the ending point indicates the last tick of the + * sequence. Otherwise, the ending point must be greater than or equal to + * the starting point, and it must fall within the size of the loaded + * sequence. + * <p> + * A sequencer's loop end point defaults to -1, meaning the end of the + * sequence. * - * <p>A sequencer's loop end point defaults to -1, - * meaning the end of the sequence. - * - * @param tick the loop's ending position, - * in MIDI ticks (zero-based), or - * -1 to indicate the final tick - * @throws IllegalArgumentException if the requested - * loop point cannot be set, usually because - * it falls outside the sequence's - * duration or because the ending point is - * before the starting point - * + * @param tick the loop's ending position, in MIDI ticks (zero-based), or + * -1 to indicate the final tick + * @throws IllegalArgumentException if the requested loop point cannot be + * set, usually because it falls outside the sequence's duration or + * because the ending point is before the starting point * @see #setLoopStartPoint * @see #setLoopCount * @see #getLoopEndPoint * @see #start * @since 1.5 */ - public void setLoopEndPoint(long tick); - + void setLoopEndPoint(long tick); /** - * Obtains the end position of the loop, - * in MIDI ticks. + * Obtains the end position of the loop, in MIDI ticks. * - * @return the end position of the loop, in MIDI - * ticks (zero-based), or -1 to indicate - * the end of the sequence + * @return the end position of the loop, in MIDI ticks (zero-based), or -1 + * to indicate the end of the sequence * @see #setLoopEndPoint * @since 1.5 */ - public long getLoopEndPoint(); - + long getLoopEndPoint(); /** - * Sets the number of repetitions of the loop for - * playback. - * When the playback position reaches the loop end point, - * it will loop back to the loop start point - * <code>count</code> times, after which playback will - * continue to play to the end of the sequence. + * Sets the number of repetitions of the loop for playback. When the + * playback position reaches the loop end point, it will loop back to the + * loop start point {@code count} times, after which playback will continue + * to play to the end of the sequence. * <p> - * If the current position when this method is invoked - * is greater than the loop end point, playback - * continues to the end of the sequence without looping, - * unless the loop end point is changed subsequently. + * If the current position when this method is invoked is greater than the + * loop end point, playback continues to the end of the sequence without + * looping, unless the loop end point is changed subsequently. * <p> - * A <code>count</code> value of 0 disables looping: - * playback will continue at the loop end point, and it - * will not loop back to the loop start point. + * A {@code count} value of 0 disables looping: playback will continue at + * the loop end point, and it will not loop back to the loop start point. * This is a sequencer's default. - * - * <p>If playback is stopped during looping, the - * current loop status is cleared; subsequent start - * requests are not affected by an interrupted loop - * operation. + * <p> + * If playback is stopped during looping, the current loop status is + * cleared; subsequent start requests are not affected by an interrupted + * loop operation. * - * @param count the number of times playback should - * loop back from the loop's end position - * to the loop's start position, or - * <code>{@link #LOOP_CONTINUOUSLY}</code> - * to indicate that looping should - * continue until interrupted - * - * @throws IllegalArgumentException if <code>count</code> is - * negative and not equal to {@link #LOOP_CONTINUOUSLY} - * + * @param count the number of times playback should loop back from the + * loop's end position to the loop's start position, or + * {@link #LOOP_CONTINUOUSLY} to indicate that looping should + * continue until interrupted + * @throws IllegalArgumentException if {@code count} is negative and not + * equal to {@link #LOOP_CONTINUOUSLY} * @see #setLoopStartPoint * @see #setLoopEndPoint * @see #getLoopCount * @see #start * @since 1.5 */ - public void setLoopCount(int count); - + void setLoopCount(int count); /** - * Obtains the number of repetitions for - * playback. + * Obtains the number of repetitions for playback. * - * @return the number of loops after which - * playback plays to the end of the + * @return the number of loops after which playback plays to the end of the * sequence * @see #setLoopCount * @see #start * @since 1.5 */ - public int getLoopCount(); + int getLoopCount(); /** - * A <code>SyncMode</code> object represents one of the ways in which - * a MIDI sequencer's notion of time can be synchronized with a master - * or slave device. - * If the sequencer is being synchronized to a master, the - * sequencer revises its current time in response to messages from - * the master. If the sequencer has a slave, the sequencer - * similarly sends messages to control the slave's timing. + * A {@code SyncMode} object represents one of the ways in which a MIDI + * sequencer's notion of time can be synchronized with a master or slave + * device. If the sequencer is being synchronized to a master, the sequencer + * revises its current time in response to messages from the master. If the + * sequencer has a slave, the sequencer similarly sends messages to control + * the slave's timing. * <p> - * There are three predefined modes that specify possible masters - * for a sequencer: <code>INTERNAL_CLOCK</code>, - * <code>MIDI_SYNC</code>, and <code>MIDI_TIME_CODE</code>. The - * latter two work if the sequencer receives MIDI messages from - * another device. In these two modes, the sequencer's time gets reset - * based on system real-time timing clock messages or MIDI time code - * (MTC) messages, respectively. These two modes can also be used - * as slave modes, in which case the sequencer sends the corresponding - * types of MIDI messages to its receiver (whether or not the sequencer - * is also receiving them from a master). A fourth mode, - * <code>NO_SYNC</code>, is used to indicate that the sequencer should - * not control its receiver's timing. + * There are three predefined modes that specify possible masters for a + * sequencer: {@code INTERNAL_CLOCK}, {@code MIDI_SYNC}, and + * {@code MIDI_TIME_CODE}. The latter two work if the sequencer receives + * MIDI messages from another device. In these two modes, the sequencer's + * time gets reset based on system real-time timing clock messages or MIDI + * time code (MTC) messages, respectively. These two modes can also be used + * as slave modes, in which case the sequencer sends the corresponding types + * of MIDI messages to its receiver (whether or not the sequencer is also + * receiving them from a master). A fourth mode, {@code NO_SYNC}, is used to + * indicate that the sequencer should not control its receiver's timing. * - * @see Sequencer#setMasterSyncMode(Sequencer.SyncMode) - * @see Sequencer#setSlaveSyncMode(Sequencer.SyncMode) + * @see Sequencer#setMasterSyncMode(SyncMode) + * @see Sequencer#setSlaveSyncMode(SyncMode) */ - public static class SyncMode { + class SyncMode { /** * Synchronization mode name. @@ -779,27 +684,27 @@ /** * Constructs a synchronization mode. - * @param name name of the synchronization mode + * + * @param name name of the synchronization mode */ protected SyncMode(String name) { this.name = name; } - /** - * Determines whether two objects are equal. - * Returns <code>true</code> if the objects are identical - * @param obj the reference object with which to compare - * @return <code>true</code> if this object is the same as the - * <code>obj</code> argument, <code>false</code> otherwise + * Determines whether two objects are equal. Returns {@code true} if the + * objects are identical. + * + * @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 */ public final boolean equals(Object obj) { return super.equals(obj); } - /** * Finalizes the hashcode method. */ @@ -808,10 +713,10 @@ return super.hashCode(); } - /** * Provides this synchronization mode's name as the string * representation of the mode. + * * @return the name of this synchronization mode */ public final String toString() { @@ -819,50 +724,41 @@ return name; } - /** - * A master synchronization mode that makes the sequencer get - * its timing information from its internal clock. This is not - * a legal slave sync mode. + * A master synchronization mode that makes the sequencer get its timing + * information from its internal clock. This is not a legal slave sync + * mode. */ public static final SyncMode INTERNAL_CLOCK = new SyncMode("Internal Clock"); - /** - * A master or slave synchronization mode that specifies the - * use of MIDI clock - * messages. If this mode is used as the master sync mode, - * the sequencer gets its timing information from system real-time - * MIDI clock messages. This mode only applies as the master sync - * mode for sequencers that are also MIDI receivers. If this is the - * slave sync mode, the sequencer sends system real-time MIDI clock - * messages to its receiver. MIDI clock messages are sent at a rate - * of 24 per quarter note. + * A master or slave synchronization mode that specifies the use of MIDI + * clock messages. If this mode is used as the master sync mode, the + * sequencer gets its timing information from system real-time MIDI + * clock messages. This mode only applies as the master sync mode for + * sequencers that are also MIDI receivers. If this is the slave sync + * mode, the sequencer sends system real-time MIDI clock messages to its + * receiver. MIDI clock messages are sent at a rate of 24 per quarter + * note. */ public static final SyncMode MIDI_SYNC = new SyncMode("MIDI Sync"); - /** - * A master or slave synchronization mode that specifies the - * use of MIDI Time Code. - * If this mode is used as the master sync mode, - * the sequencer gets its timing information from MIDI Time Code - * messages. This mode only applies as the master sync - * mode to sequencers that are also MIDI receivers. If this - * mode is used as the - * slave sync mode, the sequencer sends MIDI Time Code - * messages to its receiver. (See the MIDI 1.0 Detailed - * Specification for a description of MIDI Time Code.) + * A master or slave synchronization mode that specifies the use of MIDI + * Time Code. If this mode is used as the master sync mode, the + * sequencer gets its timing information from MIDI Time Code messages. + * This mode only applies as the master sync mode to sequencers that are + * also MIDI receivers. If this mode is used as the slave sync mode, the + * sequencer sends MIDI Time Code messages to its receiver. (See the + * MIDI 1.0 Detailed Specification for a description of MIDI Time Code.) */ public static final SyncMode MIDI_TIME_CODE = new SyncMode("MIDI Time Code"); - /** * A slave synchronization mode indicating that no timing information - * should be sent to the receiver. This is not a legal master sync - * mode. + * should be sent to the receiver. This is not a legal master sync mode. */ public static final SyncMode NO_SYNC = new SyncMode("No Timing"); - } // class SyncMode + } }
--- a/jdk/src/share/classes/javax/sound/midi/ShortMessage.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/ShortMessage.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, 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 @@ -26,156 +26,158 @@ package javax.sound.midi; /** - * A <code>ShortMessage</code> contains a MIDI message that has at most - * two data bytes following its status byte. The types of MIDI message - * that satisfy this criterion are channel voice, channel mode, system common, - * and system real-time--in other words, everything except system exclusive - * and meta-events. The <code>ShortMessage</code> class provides methods - * for getting and setting the contents of the MIDI message. + * A {@code ShortMessage} contains a MIDI message that has at most two data + * bytes following its status byte. The types of MIDI message that satisfy this + * criterion are channel voice, channel mode, system common, and system + * real-time--in other words, everything except system exclusive and + * meta-events. The {@code ShortMessage} class provides methods for getting and + * setting the contents of the MIDI message. * <p> - * A number of <code>ShortMessage</code> methods have integer parameters by which - * you specify a MIDI status or data byte. If you know the numeric value, you - * can express it directly. For system common and system real-time messages, - * you can often use the corresponding fields of <code>ShortMessage</code>, such as - * {@link #SYSTEM_RESET SYSTEM_RESET}. For channel messages, - * the upper four bits of the status byte are specified by a command value and - * the lower four bits are specified by a MIDI channel number. To - * convert incoming MIDI data bytes that are in the form of Java's signed bytes, - * you can use the <A HREF="MidiMessage.html#integersVsBytes">conversion code</A> - * given in the <code>{@link MidiMessage}</code> class description. - * - * @see SysexMessage - * @see MetaMessage + * A number of {@code ShortMessage} methods have integer parameters by which you + * specify a MIDI status or data byte. If you know the numeric value, you can + * express it directly. For system common and system real-time messages, you can + * often use the corresponding fields of {@code ShortMessage}, such as + * {@link #SYSTEM_RESET SYSTEM_RESET}. For channel messages, the upper four bits + * of the status byte are specified by a command value and the lower four bits + * are specified by a MIDI channel number. To convert incoming MIDI data bytes + * that are in the form of Java's signed bytes, you can use the + * <a href="MidiMessage.html#integersVsBytes">conversion code</a> given in the + * {@link MidiMessage} class description. * * @author David Rivas * @author Kara Kytle * @author Florian Bomers + * @see SysexMessage + * @see MetaMessage */ - public class ShortMessage extends MidiMessage { - // Status byte defines - // System common messages /** * Status byte for MIDI Time Code Quarter Frame message (0xF1, or 241). + * * @see MidiMessage#getStatus */ public static final int MIDI_TIME_CODE = 0xF1; // 241 /** * Status byte for Song Position Pointer message (0xF2, or 242). + * * @see MidiMessage#getStatus */ public static final int SONG_POSITION_POINTER = 0xF2; // 242 /** * Status byte for MIDI Song Select message (0xF3, or 243). + * * @see MidiMessage#getStatus */ public static final int SONG_SELECT = 0xF3; // 243 /** * Status byte for Tune Request message (0xF6, or 246). + * * @see MidiMessage#getStatus */ public static final int TUNE_REQUEST = 0xF6; // 246 /** * Status byte for End of System Exclusive message (0xF7, or 247). + * * @see MidiMessage#getStatus */ public static final int END_OF_EXCLUSIVE = 0xF7; // 247 - // System real-time messages /** * Status byte for Timing Clock message (0xF8, or 248). + * * @see MidiMessage#getStatus */ public static final int TIMING_CLOCK = 0xF8; // 248 /** * Status byte for Start message (0xFA, or 250). + * * @see MidiMessage#getStatus */ public static final int START = 0xFA; // 250 /** * Status byte for Continue message (0xFB, or 251). + * * @see MidiMessage#getStatus */ public static final int CONTINUE = 0xFB; // 251 /** * Status byte for Stop message (0xFC, or 252). + * * @see MidiMessage#getStatus */ public static final int STOP = 0xFC; //252 /** * Status byte for Active Sensing message (0xFE, or 254). + * * @see MidiMessage#getStatus */ public static final int ACTIVE_SENSING = 0xFE; // 254 /** * Status byte for System Reset message (0xFF, or 255). + * * @see MidiMessage#getStatus */ public static final int SYSTEM_RESET = 0xFF; // 255 - // Channel voice message upper nibble defines /** - * Command value for Note Off message (0x80, or 128) + * Command value for Note Off message (0x80, or 128). */ public static final int NOTE_OFF = 0x80; // 128 /** - * Command value for Note On message (0x90, or 144) + * Command value for Note On message (0x90, or 144). */ public static final int NOTE_ON = 0x90; // 144 /** - * Command value for Polyphonic Key Pressure (Aftertouch) message (0xA0, or 160) + * Command value for Polyphonic Key Pressure (Aftertouch) message (0xA0, or + * 160). */ public static final int POLY_PRESSURE = 0xA0; // 160 /** - * Command value for Control Change message (0xB0, or 176) + * Command value for Control Change message (0xB0, or 176). */ public static final int CONTROL_CHANGE = 0xB0; // 176 /** - * Command value for Program Change message (0xC0, or 192) + * Command value for Program Change message (0xC0, or 192). */ public static final int PROGRAM_CHANGE = 0xC0; // 192 /** - * Command value for Channel Pressure (Aftertouch) message (0xD0, or 208) + * Command value for Channel Pressure (Aftertouch) message (0xD0, or 208). */ public static final int CHANNEL_PRESSURE = 0xD0; // 208 /** - * Command value for Pitch Bend message (0xE0, or 224) + * Command value for Pitch Bend message (0xE0, or 224). */ public static final int PITCH_BEND = 0xE0; // 224 - - // Instance variables - /** - * Constructs a new <code>ShortMessage</code>. The - * contents of the new message are guaranteed to specify - * a valid MIDI message. Subsequently, you may set the - * contents of the message using one of the <code>setMessage</code> - * methods. + * Constructs a new {@code ShortMessage}. The contents of the new message + * are guaranteed to specify a valid MIDI message. Subsequently, you may set + * the contents of the message using one of the {@code setMessage} methods. + * * @see #setMessage */ public ShortMessage() { @@ -188,14 +190,13 @@ } /** - * Constructs a new {@code ShortMessage} which represents a MIDI - * message that takes no data bytes. - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * Constructs a new {@code ShortMessage} which represents a MIDI message + * that takes no data bytes. The contents of the message can be changed by + * using one of the {@code setMessage} methods. * - * @param status the MIDI status byte - * @throws InvalidMidiDataException if {@code status} does not specify - * a valid MIDI status byte for a message that requires no data bytes + * @param status the MIDI status byte + * @throws InvalidMidiDataException if {@code status} does not specify a + * valid MIDI status byte for a message that requires no data bytes * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) @@ -210,16 +211,15 @@ /** * Constructs a new {@code ShortMessage} which represents a MIDI message * that takes up to two data bytes. If the message only takes one data byte, - * the second data byte is ignored. If the message does not take - * any data bytes, both data bytes are ignored. - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * the second data byte is ignored. If the message does not take any data + * bytes, both data bytes are ignored. The contents of the message can be + * changed by using one of the {@code setMessage} methods. * - * @param status the MIDI status byte - * @param data1 the first data byte - * @param data2 the second data byte + * @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 + * belonging to the message do not specify a valid MIDI message * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) @@ -235,20 +235,19 @@ } /** - * Constructs a new {@code ShortMessage} which represents a channel - * MIDI message that takes up to two data bytes. If the message only takes - * one data byte, the second data byte is ignored. If the message does not - * take any data bytes, both data bytes are ignored. - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * Constructs a new {@code ShortMessage} which represents a channel MIDI + * message that takes up to two data bytes. If the message only takes one + * data byte, the second data byte is ignored. If the message does not take + * any data bytes, both data bytes are ignored. The contents of the message + * can be changed by using one of the {@code setMessage} methods. * - * @param command the MIDI command represented by this message - * @param channel the channel associated with the message - * @param data1 the first data byte - * @param data2 the second data byte - * @throws InvalidMidiDataException if the command value, channel value - * or all data bytes belonging to the message do not specify - * a valid MIDI message + * @param command the MIDI command represented by this message + * @param channel the channel associated with the message + * @param data1 the first data byte + * @param data2 the second data byte + * @throws InvalidMidiDataException if the command value, channel value or + * all data bytes belonging to the message do not specify a valid + * MIDI message * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) @@ -264,12 +263,11 @@ setMessage(command, channel, data1, data2); } - /** - * Constructs a new <code>ShortMessage</code>. - * @param data an array of bytes containing the complete message. - * The message data may be changed using the <code>setMessage</code> - * method. + * Constructs a new {@code ShortMessage}. + * + * @param data an array of bytes containing the complete message. The + * message data may be changed using the {@code setMessage} method. * @see #setMessage */ // $$fb this should throw an Exception in case of an illegal message! @@ -279,12 +277,12 @@ super(data); } - /** * Sets the parameters for a MIDI message that takes no data bytes. - * @param status the MIDI status byte - * @throws InvalidMidiDataException if <code>status</code> does not - * specify a valid MIDI status byte for a message that requires no data bytes. + * + * @param status the MIDI status byte + * @throws InvalidMidiDataException if {@code status} does not specify a + * valid MIDI status byte for a message that requires no data bytes * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) */ @@ -297,19 +295,17 @@ setMessage(status, 0, 0); } - /** - * Sets the parameters for a MIDI message that takes one or two data - * bytes. If the message takes only one data byte, the second data - * byte is ignored; if the message does not take any data bytes, both - * data bytes are ignored. + * Sets the parameters for a MIDI message that takes one or two data bytes. + * If the message takes only one data byte, the second data byte is ignored; + * if the message does not take any data bytes, both data bytes are ignored. * - * @param status the MIDI status byte - * @param data1 the first data byte - * @param data2 the second data byte - * @throws InvalidMidiDataException if the - * the status byte, or all data bytes belonging to the message, do - * not specify a valid MIDI message. + * @param status the MIDI status byte + * @param data1 the first data byte + * @param data2 the second data byte + * @throws InvalidMidiDataException if the 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) */ @@ -345,22 +341,18 @@ } } - /** - * Sets the short message parameters for a channel message - * which takes up to two data bytes. If the message only - * takes one data byte, the second data byte is ignored; if - * the message does not take any data bytes, both data bytes - * are ignored. + * Sets the short message parameters for a channel message which takes up to + * two data bytes. If the message only takes one data byte, the second data + * byte is ignored; if the message does not take any data bytes, both data + * bytes are ignored. * - * @param command the MIDI command represented by this message - * @param channel the channel associated with the message - * @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 - * + * @param command the MIDI command represented by this message + * @param channel the channel associated with the message + * @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 * @see #setMessage(int, int, int) * @see #setMessage(int) * @see #getCommand @@ -379,12 +371,12 @@ setMessage((command & 0xF0) | (channel & 0x0F), data1, data2); } - /** - * Obtains the MIDI channel associated with this event. This method - * assumes that the event is a MIDI channel message; if not, the return - * value will not be meaningful. - * @return MIDI channel associated with the message. + * Obtains the MIDI channel associated with this event. This method assumes + * that the event is a MIDI channel message; if not, the return value will + * not be meaningful. + * + * @return MIDI channel associated with the message * @see #setMessage(int, int, int, int) */ public int getChannel() { @@ -392,11 +384,11 @@ return (getStatus() & 0x0F); } - /** - * Obtains the MIDI command associated with this event. This method - * assumes that the event is a MIDI channel message; if not, the return - * value will not be meaningful. + * Obtains the MIDI command associated with this event. This method assumes + * that the event is a MIDI channel message; if not, the return value will + * not be meaningful. + * * @return the MIDI command associated with this event * @see #setMessage(int, int, int, int) */ @@ -405,10 +397,10 @@ return (getStatus() & 0xF0); } - /** * Obtains the first data byte in the message. - * @return the value of the <code>data1</code> field + * + * @return the value of the {@code data1} field * @see #setMessage(int, int, int) */ public int getData1() { @@ -418,10 +410,10 @@ return 0; } - /** * Obtains the second data byte in the message. - * @return the value of the <code>data2</code> field + * + * @return the value of the {@code data2} field * @see #setMessage(int, int, int) */ public int getData2() { @@ -431,11 +423,11 @@ return 0; } - /** - * Creates a new object of the same class and with the same contents - * as this object. - * @return a clone of this instance. + * Creates a new object of the same class and with the same contents as this + * object. + * + * @return a clone of this instance */ public Object clone() { byte[] newData = new byte[length]; @@ -445,15 +437,15 @@ return msg; } - /** - * Retrieves the number of data bytes associated with a particular - * status byte value. - * @param status status byte value, which must represent a short MIDI message + * Retrieves the number of data bytes associated with a particular status + * byte value. + * + * @param status status byte value, which must represent a short MIDI + * message * @return data length in bytes (0, 1, or 2) - * @throws InvalidMidiDataException if the - * <code>status</code> argument does not represent the status byte for any - * short message + * @throws InvalidMidiDataException if the {@code status} argument does not + * represent the status byte for any short message */ protected final int getDataLength(int status) throws InvalidMidiDataException { // system common and system real-time messages
--- a/jdk/src/share/classes/javax/sound/midi/Soundbank.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/Soundbank.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, 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 @@ -25,109 +25,101 @@ package javax.sound.midi; -import java.net.URL; - - /** - * A <code>Soundbank</code> contains a set of <code>Instruments</code> - * that can be loaded into a <code>Synthesizer</code>. - * Note that a Java Sound <code>Soundbank</code> is different from a MIDI bank. - * MIDI permits up to 16383 banks, each containing up to 128 instruments - * (also sometimes called programs, patches, or timbres). - * However, a <code>Soundbank</code> can contain 16383 times 128 instruments, - * because the instruments within a <code>Soundbank</code> are indexed by both - * a MIDI program number and a MIDI bank number (via a <code>Patch</code> - * object). Thus, a <code>Soundbank</code> can be thought of as a collection - * of MIDI banks. + * A {@code Soundbank} contains a set of {@code Instruments} that can be loaded + * into a {@code Synthesizer}. Note that a Java Sound {@code Soundbank} is + * different from a MIDI bank. MIDI permits up to 16383 banks, each containing + * up to 128 instruments (also sometimes called programs, patches, or timbres). + * However, a {@code Soundbank} can contain 16383 times 128 instruments, because + * the instruments within a {@code Soundbank} are indexed by both a MIDI program + * number and a MIDI bank number (via a {@code Patch} object). Thus, a + * {@code Soundbank} can be thought of as a collection of MIDI banks. + * <p> + * {@code Soundbank} includes methods that return {@code String} objects + * containing the sound bank's name, manufacturer, version number, and + * description. The precise content and format of these strings is left to the + * implementor. * <p> - * <code>Soundbank</code> includes methods that return <code>String</code> - * objects containing the sound bank's name, manufacturer, version number, and - * description. The precise content and format of these strings is left - * to the implementor. - * <p> - * Different synthesizers use a variety of synthesis techniques. A common - * one is wavetable synthesis, in which a segment of recorded sound is - * played back, often with looping and pitch change. The Downloadable Sound - * (DLS) format uses segments of recorded sound, as does the Headspace Engine. - * <code>Soundbanks</code> and <code>Instruments</code> that are based on - * wavetable synthesis (or other uses of stored sound recordings) should - * typically implement the <code>getResources()</code> - * method to provide access to these recorded segments. This is optional, - * however; the method can return an zero-length array if the synthesis technique - * doesn't use sampled sound (FM synthesis and physical modeling are examples - * of such techniques), or if it does but the implementor chooses not to make the - * samples accessible. + * Different synthesizers use a variety of synthesis techniques. A common one is + * wavetable synthesis, in which a segment of recorded sound is played back, + * often with looping and pitch change. The Downloadable Sound (DLS) format uses + * segments of recorded sound, as does the Headspace Engine. {@code Soundbanks} + * and {@code Instruments} that are based on wavetable synthesis (or other uses + * of stored sound recordings) should typically implement the + * {@code getResources()} method to provide access to these recorded segments. + * This is optional, however; the method can return an zero-length array if the + * synthesis technique doesn't use sampled sound (FM synthesis and physical + * modeling are examples of such techniques), or if it does but the implementor + * chooses not to make the samples accessible. * + * @author David Rivas + * @author Kara Kytle * @see Synthesizer#getDefaultSoundbank * @see Synthesizer#isSoundbankSupported * @see Synthesizer#loadInstruments(Soundbank, Patch[]) * @see Patch * @see Instrument * @see SoundbankResource - * - * @author David Rivas - * @author Kara Kytle */ - public interface Soundbank { - /** * Obtains the name of the sound bank. - * @return a <code>String</code> naming the sound bank + * + * @return a {@code String} naming the sound bank */ - public String getName(); + String getName(); /** * Obtains the version string for the sound bank. - * @return a <code>String</code> that indicates the sound bank's version + * + * @return a {@code String} that indicates the sound bank's version */ - public String getVersion(); + String getVersion(); /** - * Obtains a <code>string</code> naming the company that provides the - * sound bank + * Obtains a {@code string} naming the company that provides the sound bank. + * * @return the vendor string */ - public String getVendor(); + String getVendor(); /** * Obtains a textual description of the sound bank, suitable for display. - * @return a <code>String</code> that describes the sound bank + * + * @return a {@code String} that describes the sound bank */ - public String getDescription(); - + String getDescription(); /** * Extracts a list of non-Instrument resources contained in the sound bank. - * @return an array of resources, excluding instruments. If the sound bank contains - * no resources (other than instruments), returns an array of length 0. + * + * @return an array of resources, excluding instruments. If the sound bank + * contains no resources (other than instruments), returns an array + * of length 0. */ - public SoundbankResource[] getResources(); - + SoundbankResource[] getResources(); /** * Obtains a list of instruments contained in this sound bank. - * @return an array of the <code>Instruments</code> in this - * <code>SoundBank</code> - * If the sound bank contains no instruments, returns an array of length 0. * + * @return an array of the {@code Instruments} in this {@code SoundBank}. If + * the sound bank contains no instruments, returns an array of + * length 0. * @see Synthesizer#getLoadedInstruments * @see #getInstrument(Patch) */ - public Instrument[] getInstruments(); + Instrument[] getInstruments(); /** - * Obtains an <code>Instrument</code> from the given <code>Patch</code>. - * @param patch a <code>Patch</code> object specifying the bank index - * and program change number - * @return the requested instrument, or <code>null</code> if the - * sound bank doesn't contain that instrument + * Obtains an {@code Instrument} from the given {@code Patch}. * + * @param patch a {@code Patch} object specifying the bank index and + * program change number + * @return the requested instrument, or {@code null} if the sound bank + * doesn't contain that instrument * @see #getInstruments * @see Synthesizer#loadInstruments(Soundbank, Patch[]) */ - public Instrument getInstrument(Patch patch); - - + Instrument getInstrument(Patch patch); }
--- a/jdk/src/share/classes/javax/sound/midi/SoundbankResource.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/SoundbankResource.java Wed Jul 23 16:19:26 2014 +0400 @@ -25,81 +25,72 @@ package javax.sound.midi; +import javax.sound.sampled.AudioInputStream; + /** - * A <code>SoundbankResource</code> represents any audio resource stored - * in a <code>{@link Soundbank}</code>. Common soundbank resources include: + * 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</code> - * which specifies the MIDI program and bank by which it may be - * referenced in MIDI messages. Instrument information may be - * stored in <code>{@link Instrument}</code> 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 <code>{@link Synthesizer}</code> 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 <code>{@link javax.sound.sampled.AudioInputStream}</code>. </li> - * <li>Embedded sequences. A sound bank may contain built-in - * song data stored in a data object such as a <code>{@link Sequence}</code>. + * <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> * </ul> - * <p> - * Synthesizers that use wavetable synthesis or related - * techniques play back the audio in a sample when - * synthesizing notes, often when emulating the real-world instrument that - * was originally recorded. However, there is not necessarily a one-to-one - * correspondence between the <code>Instruments</code> and samples - * in a <code>Soundbank</code>. A single <code>Instrument</code> can use - * multiple SoundbankResources (typically for notes of dissimilar pitch or - * brightness). Also, more than one <code>Instrument</code> can use the same - * sample. + * Synthesizers that use wavetable synthesis or related techniques play back the + * audio in a sample when synthesizing notes, often when emulating the + * real-world instrument that was originally recorded. However, there is not + * necessarily a one-to-one correspondence between the {@code Instruments} and + * samples in a {@code Soundbank}. A single {@code Instrument} can use multiple + * SoundbankResources (typically for notes of dissimilar pitch or brightness). + * Also, more than one {@code Instrument} can use the same sample. * * @author Kara Kytle */ - public abstract class SoundbankResource { - /** - * The sound bank that contains the <code>SoundbankResources</code> + * The sound bank that contains the {@code SoundbankResources}. */ private final Soundbank soundBank; - /** - * The name of the <code>SoundbankResource</code> + * The name of the {@code SoundbankResource}. */ private final String name; - /** * The class used to represent the sample's data. */ private final Class<?> dataClass; - /** * The wavetable index. */ //private final int index; - /** - * Constructs a new <code>SoundbankResource</code> from the given sound bank - * and wavetable index. (Setting the <code>SoundbankResource's</code> name, - * sampled audio data, and instruments is a subclass responsibility.) - * @param soundBank the sound bank containing this <code>SoundbankResource</code> - * @param name the name of the sample - * @param dataClass the class used to represent the sample's data + * Constructs a new {@code SoundbankResource} from the given sound bank and + * wavetable index. (Setting the {@code SoundbankResource's} name, sampled + * audio data, and instruments is a subclass responsibility.) * + * @param soundBank the sound bank containing this + * {@code SoundbankResource} + * @param name the name of the sample + * @param dataClass the class used to represent the sample's data * @see #getSoundbank * @see #getName * @see #getDataClass @@ -112,65 +103,65 @@ this.dataClass = dataClass; } - /** - * Obtains the sound bank that contains this <code>SoundbankResource</code>. - * @return the sound bank in which this <code>SoundbankResource</code> is stored + * Obtains the sound bank that contains this {@code SoundbankResource}. + * + * @return the sound bank in which this {@code SoundbankResource} is stored */ public Soundbank getSoundbank() { return soundBank; } - /** - * Obtains the name of the resource. This should generally be a string + * Obtains the name of the resource. This should generally be a string * descriptive of the resource. + * * @return the instrument's name */ public String getName() { return name; } - /** - * Obtains the class used by this sample to represent its data. - * The object returned by <code>getData</code> will be of this - * class. If this <code>SoundbankResource</code> object does not support - * direct access to its data, returns <code>null</code>. - * @return the class used to represent the sample's data, or - * null if the data is not accessible + * Obtains the class used by this sample to represent its data. The object + * returned by {@code getData} will be of this class. If this + * {@code SoundbankResource} object does not support direct access to its + * data, returns {@code null}. + * + * @return the class used to represent the sample's data, or null if the + * data is not accessible */ public Class<?> getDataClass() { return dataClass; } - /** - * Obtains the sampled audio that is stored in this <code>SoundbankResource</code>. - * The type of object returned depends on the implementation of the - * concrete class, and may be queried using <code>getDataClass</code>. + * Obtains the sampled audio that is stored in this + * {@code SoundbankResource}. The type of object returned depends on the + * implementation of the concrete class, and may be queried using + * {@code getDataClass}. + * * @return an object containing the sampled audio data * @see #getDataClass */ public abstract Object getData(); - /** - * Obtains the index of this <code>SoundbankResource</code> into the - * <code>Soundbank's</code> set of <code>SoundbankResources</code>. + * Obtains the index of this {@code SoundbankResource} into the + * {@code Soundbank's} set of {@code SoundbankResources}. + * * @return the wavetable index */ //public int getIndex() { // return index; //} - /** * Obtains a list of the instruments in the sound bank that use the - * <code>SoundbankResource</code> for sound synthesis. - * @return an array of <code>Instruments</code> that reference this - * <code>SoundbankResource</code> + * {@code SoundbankResource} for sound synthesis. * + * @return an array of {@code Instruments} that reference this + * {@code SoundbankResource} * @see Instrument#getSamples */ //public abstract Instrument[] getInstruments();
--- a/jdk/src/share/classes/javax/sound/midi/Synthesizer.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/Synthesizer.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -25,46 +25,43 @@ package javax.sound.midi; -import javax.sound.sampled.Control; - - /** - * A <code>Synthesizer</code> generates sound. This usually happens when one of - * the <code>Synthesizer</code>'s {@link MidiChannel} objects receives a - * {@link MidiChannel#noteOn(int, int) noteOn} message, either - * directly or via the <code>Synthesizer</code> object. - * Many <code>Synthesizer</code>s support <code>Receivers</code>, through which - * MIDI events can be delivered to the <code>Synthesizer</code>. - * In such cases, the <code>Synthesizer</code> typically responds by sending - * a corresponding message to the appropriate <code>MidiChannel</code>, or by - * processing the event itself if the event isn't one of the MIDI channel - * messages. + * A {@code Synthesizer} generates sound. This usually happens when one of the + * {@code Synthesizer}'s {@link MidiChannel} objects receives a + * {@link MidiChannel#noteOn(int, int) noteOn} message, either directly or via + * the {@code Synthesizer} object. Many {@code Synthesizer}s support + * {@code Receivers}, through which MIDI events can be delivered to the + * {@code Synthesizer}. In such cases, the {@code Synthesizer} typically + * responds by sending a corresponding message to the appropriate + * {@code MidiChannel}, or by processing the event itself if the event isn't one + * of the MIDI channel messages. * <p> - * The <code>Synthesizer</code> interface includes methods for loading and - * unloading instruments from soundbanks. An instrument is a specification for synthesizing a - * certain type of sound, whether that sound emulates a traditional instrument or is - * some kind of sound effect or other imaginary sound. A soundbank is a collection of instruments, organized - * by bank and program number (via the instrument's <code>Patch</code> object). - * Different <code>Synthesizer</code> classes might implement different sound-synthesis - * techniques, meaning that some instruments and not others might be compatible with a - * given synthesizer. - * Also, synthesizers may have a limited amount of memory for instruments, meaning - * that not every soundbank and instrument can 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</code>. + * The {@code Synthesizer} interface includes methods for loading and unloading + * instruments from soundbanks. An instrument is a specification for + * synthesizing a certain type of sound, whether that sound emulates a + * traditional instrument or is some kind of sound effect or other imaginary + * sound. A soundbank is a collection of instruments, organized by bank and + * program number (via the instrument's {@code Patch} object). Different + * {@code Synthesizer} classes might implement different sound-synthesis + * techniques, meaning that some instruments and not others might be compatible + * with a given synthesizer. Also, synthesizers may have a limited amount of + * memory for instruments, meaning that not every soundbank and instrument can + * 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}. * <p> * "Loading" an instrument means that that instrument becomes available for - * synthesizing notes. The instrument is loaded into the bank and - * program location specified by its <code>Patch</code> object. Loading does - * not necessarily mean that subsequently played notes will immediately have - * the sound of this newly loaded instrument. For the instrument to play notes, - * one of the synthesizer's <code>MidiChannel</code> objects must receive (or have received) - * a program-change message that causes that particular instrument's - * bank and program number to be selected. + * synthesizing notes. The instrument is loaded into the bank and program + * location specified by its {@code Patch} object. Loading does not necessarily + * mean that subsequently played notes will immediately have the sound of this + * newly loaded instrument. For the instrument to play notes, one of the + * synthesizer's {@code MidiChannel} objects must receive (or have received) a + * program-change message that causes that particular instrument's bank and + * program number to be selected. * + * @author Kara Kytle * @see MidiSystem#getSynthesizer * @see Soundbank * @see Instrument @@ -72,107 +69,103 @@ * @see Receiver * @see Transmitter * @see MidiDevice - * - * @author Kara Kytle */ public interface Synthesizer extends MidiDevice { - // SYNTHESIZER METHODS - /** - * Obtains the maximum number of notes that this synthesizer can sound simultaneously. + * Obtains the maximum number of notes that this synthesizer can sound + * simultaneously. + * * @return the maximum number of simultaneous notes * @see #getVoiceStatus */ - public int getMaxPolyphony(); - + int getMaxPolyphony(); /** * Obtains the processing latency incurred by this synthesizer, expressed in - * microseconds. This latency measures the worst-case delay between the - * time a MIDI message is delivered to the synthesizer and the time that the + * microseconds. This latency measures the worst-case delay between the time + * a MIDI message is delivered to the synthesizer and the time that the * synthesizer actually produces the corresponding result. * <p> - * Although the latency is expressed in microseconds, a synthesizer's actual measured - * delay may vary over a wider range than this resolution suggests. For example, - * a synthesizer might have a worst-case delay of a few milliseconds or more. + * Although the latency is expressed in microseconds, a synthesizer's actual + * measured delay may vary over a wider range than this resolution suggests. + * For example, a synthesizer might have a worst-case delay of a few + * milliseconds or more. * * @return the worst-case delay, in microseconds */ - public long getLatency(); - + long getLatency(); /** - * Obtains the set of MIDI channels controlled by this synthesizer. Each - * non-null element in the returned array is a <code>MidiChannel</code> that + * Obtains the set of MIDI channels controlled by this synthesizer. Each + * non-null element in the returned array is a {@code MidiChannel} that * receives the MIDI messages sent on that channel number. * <p> - * The MIDI 1.0 specification provides for 16 channels, so this - * method returns an array of at least 16 elements. However, if this synthesizer + * The MIDI 1.0 specification provides for 16 channels, so this method + * returns an array of at least 16 elements. However, if this synthesizer * doesn't make use of all 16 channels, some of the elements of the array - * might be <code>null</code>, so you should check each element - * before using it. - * @return an array of the <code>MidiChannel</code> objects managed by this - * <code>Synthesizer</code>. Some of the array elements may be <code>null</code>. + * might be {@code null}, so you should check each element before using it. + * + * @return an array of the {@code MidiChannel} objects managed by this + * {@code Synthesizer}. Some of the array elements may be + * {@code null}. */ - public MidiChannel[] getChannels(); - + MidiChannel[] getChannels(); /** - * Obtains the current status of the voices produced by this synthesizer. - * If this class of <code>Synthesizer</code> does not provide voice - * information, the returned array will always be of length 0. Otherwise, - * its length is always equal to the total number of voices, as returned by - * <code>getMaxPolyphony()</code>. (See the <code>VoiceStatus</code> class - * description for an explanation of synthesizer voices.) + * Obtains the current status of the voices produced by this synthesizer. If + * this class of {@code Synthesizer} does not provide voice information, the + * returned array will always be of length 0. Otherwise, its length is + * always equal to the total number of voices, as returned by + * {@code getMaxPolyphony()}. (See the {@code VoiceStatus} class description + * for an explanation of synthesizer voices.) * - * @return an array of <code>VoiceStatus</code> objects that supply - * information about the corresponding synthesizer voices + * @return an array of {@code VoiceStatus} objects that supply information + * about the corresponding synthesizer voices * @see #getMaxPolyphony * @see VoiceStatus */ - public VoiceStatus[] getVoiceStatus(); - + VoiceStatus[] getVoiceStatus(); /** * Informs the caller whether this synthesizer is capable of loading - * instruments from the specified soundbank. - * If the soundbank is unsupported, any attempts to load instruments from - * it will result in an <code>IllegalArgumentException</code>. - * @param soundbank soundbank for which support is queried - * @return <code>true</code> if the soundbank is supported, otherwise <code>false</code> + * instruments from the specified soundbank. If the soundbank is + * unsupported, any attempts to load instruments from it will result in an + * {@code IllegalArgumentException}. + * + * @param soundbank soundbank for which support is queried + * @return {@code true} if the soundbank is supported, otherwise + * {@code false} * @see #loadInstruments * @see #loadAllInstruments * @see #unloadInstruments * @see #unloadAllInstruments * @see #getDefaultSoundbank */ - public boolean isSoundbankSupported(Soundbank soundbank); - + boolean isSoundbankSupported(Soundbank soundbank); /** - * Makes a particular instrument available for synthesis. This instrument - * is loaded into the patch location specified by its <code>Patch</code> - * object, so that if a program-change message is - * received (or has been received) that causes that patch to be selected, - * subsequent notes will be played using the sound of - * <code>instrument</code>. If the specified instrument is already loaded, - * this method does nothing and returns <code>true</code>. + * Makes a particular instrument available for synthesis. This instrument is + * loaded into the patch location specified by its {@code Patch} object, so + * that if a program-change message is received (or has been received) that + * causes that patch to be selected, subsequent notes will be played using + * the sound of {@code instrument}. If the specified instrument is already + * loaded, this method does nothing and returns {@code true}. * <p> - * The instrument must be part of a soundbank - * that this <code>Synthesizer</code> supports. (To make sure, you can use - * the <code>getSoundbank</code> method of <code>Instrument</code> and the - * <code>isSoundbankSupported</code> method of <code>Synthesizer</code>.) - * @param instrument instrument to load - * @return <code>true</code> if the instrument is successfully loaded (or - * already had been), <code>false</code> if the instrument could not be - * loaded (for example, if the synthesizer has insufficient - * memory to load it) - * @throws IllegalArgumentException if this - * <code>Synthesizer</code> doesn't support the specified instrument's - * soundbank + * The instrument must be part of a soundbank that this {@code Synthesizer} + * supports. (To make sure, you can use the {@code getSoundbank} method of + * {@code Instrument} and the {@code isSoundbankSupported} method of + * {@code Synthesizer}.) + * + * @param instrument instrument to load + * @return {@code true} if the instrument is successfully loaded (or already + * had been), {@code false} if the instrument could not be loaded + * (for example, if the synthesizer has insufficient memory to load + * it) + * @throws IllegalArgumentException if this {@code Synthesizer} doesn't + * support the specified instrument's soundbank * @see #unloadInstrument * @see #loadInstruments * @see #loadAllInstruments @@ -180,138 +173,139 @@ * @see SoundbankResource#getSoundbank * @see MidiChannel#programChange(int, int) */ - public boolean loadInstrument(Instrument instrument); - + boolean loadInstrument(Instrument instrument); /** * Unloads a particular instrument. - * @param instrument instrument to unload - * @throws IllegalArgumentException if this - * <code>Synthesizer</code> doesn't support the specified instrument's - * soundbank + * + * @param instrument instrument to unload + * @throws IllegalArgumentException if this {@code Synthesizer} doesn't + * support the specified instrument's soundbank * @see #loadInstrument * @see #unloadInstruments * @see #unloadAllInstruments * @see #getLoadedInstruments * @see #remapInstrument */ - public void unloadInstrument(Instrument instrument); - + void unloadInstrument(Instrument instrument); /** - * Remaps an instrument. Instrument <code>to</code> takes the - * place of instrument <code>from</code>.<br> - * For example, if <code>from</code> was located at bank number 2, - * program number 11, remapping causes that bank and program location - * to be occupied instead by <code>to</code>.<br> - * If the function succeeds, instrument <code>from</code> is unloaded. - * <p>To cancel the remapping reload instrument <code>from</code> by - * invoking one of {@link #loadInstrument}, {@link #loadInstruments} - * or {@link #loadAllInstruments}. + * Remaps an instrument. Instrument {@code to} takes the place of instrument + * {@code from}. + * <br> + * For example, if {@code from} was located at bank number 2, program number + * 11, remapping causes that bank and program location to be occupied + * instead by {@code to}. + * <br> + * If the function succeeds, instrument {@code from} is unloaded. + * <p> + * To cancel the remapping reload instrument {@code from} by invoking one of + * {@link #loadInstrument}, {@link #loadInstruments} or + * {@link #loadAllInstruments}. * - * @param from the <code>Instrument</code> object to be replaced - * @param to the <code>Instrument</code> object to be used in place - * of the old instrument, it should be loaded into the synthesizer - * @return <code>true</code> if the instrument successfully remapped, - * <code>false</code> if feature is not implemented by synthesizer - * @throws IllegalArgumentException if instrument - * <code>from</code> or instrument <code>to</code> aren't supported by - * synthesizer or if instrument <code>to</code> is not loaded - * @throws NullPointerException if <code>from</code> or - * <code>to</code> parameters have null value + * @param from the {@code Instrument} object to be replaced + * @param to the {@code Instrument} object to be used in place of the old + * instrument, it should be loaded into the synthesizer + * @return {@code true} if the instrument successfully remapped, + * {@code false} if feature is not implemented by synthesizer + * @throws IllegalArgumentException if instrument {@code from} or instrument + * {@code to} aren't supported by synthesizer or if instrument + * {@code to} is not loaded + * @throws NullPointerException if {@code from} or {@code to} parameters + * have null value * @see #loadInstrument * @see #loadInstruments * @see #loadAllInstruments */ - public boolean remapInstrument(Instrument from, Instrument to); - + boolean remapInstrument(Instrument from, Instrument to); /** - * Obtains the default soundbank for the synthesizer, if one exists. - * (Some synthesizers provide a default or built-in soundbank.) - * If a synthesizer doesn't have a default soundbank, instruments must - * be loaded explicitly from an external soundbank. - * @return default soundbank, or <code>null</code> if one does not exist. + * Obtains the default soundbank for the synthesizer, if one exists. (Some + * synthesizers provide a default or built-in soundbank.) If a synthesizer + * doesn't have a default soundbank, instruments must be loaded explicitly + * from an external soundbank. + * + * @return default soundbank, or {@code null} if one does not exist * @see #isSoundbankSupported */ - public Soundbank getDefaultSoundbank(); - + Soundbank getDefaultSoundbank(); /** - * Obtains a list of instruments that come with the synthesizer. These - * instruments might be built into the synthesizer, or they might be - * part of a default soundbank provided with the synthesizer, etc. + * Obtains a list of instruments that come with the synthesizer. These + * instruments might be built into the synthesizer, or they might be part of + * a default soundbank provided with the synthesizer, etc. * <p> - * Note that you don't use this method to find out which instruments are + * Note that you don't use this method to find out which instruments are * currently loaded onto the synthesizer; for that purpose, you use - * <code>getLoadedInstruments()</code>. - * Nor does the method indicate all the instruments that can be loaded onto - * the synthesizer; it only indicates the subset that come with the synthesizer. - * To learn whether another instrument can be loaded, you can invoke - * <code>isSoundbankSupported()</code>, and if the instrument's - * <code>Soundbank</code> is supported, you can try loading the instrument. + * {@code getLoadedInstruments()}. Nor does the method indicate all the + * instruments that can be loaded onto the synthesizer; it only indicates + * the subset that come with the synthesizer. To learn whether another + * instrument can be loaded, you can invoke {@code isSoundbankSupported()}, + * and if the instrument's {@code Soundbank} is supported, you can try + * loading the instrument. * - * @return list of available instruments. If the synthesizer - * has no instruments coming with it, an array of length 0 is returned. + * @return list of available instruments. If the synthesizer has no + * instruments coming with it, an array of length 0 is returned. * @see #getLoadedInstruments * @see #isSoundbankSupported(Soundbank) * @see #loadInstrument */ - public Instrument[] getAvailableInstruments(); - + Instrument[] getAvailableInstruments(); /** * Obtains a list of the instruments that are currently loaded onto this - * <code>Synthesizer</code>. + * {@code Synthesizer}. + * * @return a list of currently loaded instruments * @see #loadInstrument * @see #getAvailableInstruments * @see Soundbank#getInstruments */ - public Instrument[] getLoadedInstruments(); - + Instrument[] getLoadedInstruments(); /** - * Loads onto the <code>Synthesizer</code> all instruments contained - * in the specified <code>Soundbank</code>. - * @param soundbank the <code>Soundbank</code> whose are instruments are - * to be loaded - * @return <code>true</code> if the instruments are all successfully loaded (or - * already had been), <code>false</code> if any instrument could not be - * loaded (for example, if the <code>Synthesizer</code> had insufficient memory) + * Loads onto the {@code Synthesizer} all instruments contained in the + * specified {@code Soundbank}. + * + * @param soundbank the {@code Soundbank} whose are instruments are to be + * loaded + * @return {@code true} if the instruments are all successfully loaded (or + * already had been), {@code false} if any instrument could not be + * loaded (for example, if the {@code Synthesizer} had insufficient + * memory) * @throws IllegalArgumentException if the requested soundbank is - * incompatible with this synthesizer. + * incompatible with this synthesizer * @see #isSoundbankSupported * @see #loadInstrument * @see #loadInstruments */ - public boolean loadAllInstruments(Soundbank soundbank); - - + boolean loadAllInstruments(Soundbank soundbank); /** - * Unloads all instruments contained in the specified <code>Soundbank</code>. - * @param soundbank soundbank containing instruments to unload - * @throws IllegalArgumentException thrown if the soundbank is not supported. + * Unloads all instruments contained in the specified {@code Soundbank}. + * + * @param soundbank soundbank containing instruments to unload + * @throws IllegalArgumentException thrown if the soundbank is not supported * @see #isSoundbankSupported * @see #unloadInstrument * @see #unloadInstruments */ - public void unloadAllInstruments(Soundbank soundbank); - + void unloadAllInstruments(Soundbank soundbank); /** * Loads the instruments referenced by the specified patches, from the - * specified <code>Soundbank</code>. Each of the <code>Patch</code> objects - * indicates a bank and program number; the <code>Instrument</code> that - * has the matching <code>Patch</code> is loaded into that bank and program - * location. - * @param soundbank the <code>Soundbank</code> containing the instruments to load - * @param patchList list of patches for which instruments should be loaded - * @return <code>true</code> if the instruments are all successfully loaded (or - * already had been), <code>false</code> if any instrument could not be - * loaded (for example, if the <code>Synthesizer</code> had insufficient memory) - * @throws IllegalArgumentException thrown if the soundbank is not supported. + * specified {@code Soundbank}. Each of the {@code Patch} objects indicates + * a bank and program number; the {@code Instrument} that has the matching + * {@code Patch} is loaded into that bank and program location. + * + * @param soundbank the {@code Soundbank} containing the instruments to + * load + * @param patchList list of patches for which instruments should be loaded + * @return {@code true} if the instruments are all successfully loaded (or + * already had been), {@code false} if any instrument could not be + * loaded (for example, if the {@code Synthesizer} had insufficient + * memory) + * @throws IllegalArgumentException thrown if the soundbank is not supported * @see #isSoundbankSupported * @see Instrument#getPatch * @see #loadAllInstruments @@ -319,76 +313,76 @@ * @see Soundbank#getInstrument(Patch) * @see Sequence#getPatchList() */ - public boolean loadInstruments(Soundbank soundbank, Patch[] patchList); + boolean loadInstruments(Soundbank soundbank, Patch[] patchList); /** - * Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified. - * @param soundbank soundbank containing instruments to unload - * @param patchList list of patches for which instruments should be unloaded - * @throws IllegalArgumentException thrown if the soundbank is not supported. + * Unloads the instruments referenced by the specified patches, from the + * MIDI sound bank specified. * + * @param soundbank soundbank containing instruments to unload + * @param patchList list of patches for which instruments should be + * unloaded + * @throws IllegalArgumentException thrown if the soundbank is not supported * @see #unloadInstrument * @see #unloadAllInstruments * @see #isSoundbankSupported * @see Instrument#getPatch * @see #loadInstruments */ - public void unloadInstruments(Soundbank soundbank, Patch[] patchList); - + void unloadInstruments(Soundbank soundbank, Patch[] patchList); // RECEIVER METHODS /** * Obtains the name of the receiver. + * * @return receiver name */ - // public abstract String getName(); - + // abstract String getName(); /** * Opens the receiver. + * * @throws MidiUnavailableException if the receiver is cannot be opened, - * usually because the MIDI device is in use by another application. - * @throws SecurityException if the receiver cannot be opened due to security - * restrictions. + * usually because the MIDI device is in use by another application. + * @throws SecurityException if the receiver cannot be opened due to + * security restrictions */ - // public abstract void open() throws MidiUnavailableException, SecurityException; - + // abstract void open() throws MidiUnavailableException, SecurityException; /** * Closes the receiver. */ - // public abstract void close(); - + // abstract void close(); /** * Sends a MIDI event to the receiver. - * @param event event to send. - * @throws IllegalStateException if the receiver is not open. + * + * @param event event to send + * @throws IllegalStateException if the receiver is not open */ - // public void send(MidiEvent event) throws IllegalStateException { + // void send(MidiEvent event) throws IllegalStateException { // // } - /** - * Obtains the set of controls supported by the - * element. If no controls are supported, returns an - * array of length 0. + * Obtains the set of controls supported by the element. If no controls are + * supported, returns an array of length 0. + * * @return set of controls */ // $$kk: 03.04.99: josh bloch recommends getting rid of this: // what can you really do with a set of untyped controls?? - // $$kk: 03.05.99: i am putting this back in. for one thing, + // $$kk: 03.05.99: i am putting this back in. for one thing, // you can check the length and know whether you should keep // looking.... - // public Control[] getControls(); + // Control[] getControls(); /** * Obtains the specified control. - * @param controlClass class of the requested control - * @return requested control object, or null if the - * control is not supported. + * + * @param controlClass class of the requested control + * @return requested control object, or null if the control is not supported */ - // public Control getControl(Class controlClass); + // Control getControl(Class controlClass); }
--- a/jdk/src/share/classes/javax/sound/midi/SysexMessage.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/SysexMessage.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, 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 @@ -26,47 +26,47 @@ package javax.sound.midi; /** - * A <code>SysexMessage</code> object represents a MIDI system exclusive message. + * A {@code SysexMessage} object represents a MIDI system exclusive message. * <p> - * When a system exclusive message is read from a MIDI file, it always has - * a defined length. Data from a system exclusive message from a MIDI file - * should be stored in the data array of a <code>SysexMessage</code> as - * follows: the system exclusive message status byte (0xF0 or 0xF7), all - * message data bytes, and finally the end-of-exclusive flag (0xF7). - * The length reported by the <code>SysexMessage</code> object is therefore - * the length of the system exclusive data plus two: one byte for the status - * byte and one for the end-of-exclusive flag. + * When a system exclusive message is read from a MIDI file, it always has a + * defined length. Data from a system exclusive message from a MIDI file should + * be stored in the data array of a {@code SysexMessage} as follows: the system + * exclusive message status byte (0xF0 or 0xF7), all message data bytes, and + * finally the end-of-exclusive flag (0xF7). The length reported by the + * {@code SysexMessage} object is therefore the length of the system exclusive + * data plus two: one byte for the status byte and one for the end-of-exclusive + * flag. * <p> - * As dictated by the Standard MIDI Files specification, two status byte values are legal - * for a <code>SysexMessage</code> read from a MIDI file: + * 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> * </ul> - * <p> - * 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 - * <code>SysexMessages</code>. In this case, the length of the system exclusive data + * 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 + * {@code SysexMessages}. In this case, the length of the system exclusive data * 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> * </ul> - * The first <code>SysexMessage</code> object containing data for a particular system - * exclusive message should have the status value 0xF0. If this message contains all - * the system exclusive data - * for the message, it should end with the status byte 0xF7 (EOX). - * Otherwise, additional system exclusive data should be sent in one or more - * <code>SysexMessages</code> with a status value of 0xF7. The <code>SysexMessage</code> - * containing the last of the data for the system exclusive message should end with the - * value 0xF7 (EOX) to mark the end of the system exclusive message. + * The first {@code SysexMessage} object containing data for a particular system + * exclusive message should have the status value 0xF0. If this message contains + * all the system exclusive data for the message, it should end with the status + * byte 0xF7 (EOX). Otherwise, additional system exclusive data should be sent + * in one or more {@code SysexMessages} with a status value of 0xF7. The + * {@code SysexMessage} containing the last of the data for the system exclusive + * message should end with the value 0xF7 (EOX) to mark the end of the system + * exclusive message. * <p> - * If system exclusive data from <code>SysexMessages</code> objects is being transmitted - * using MIDI wire protocol, only the initial 0xF0 status byte, the system exclusive - * data itself, and the final 0xF7 (EOX) byte should be propagated; any 0xF7 status - * bytes used to indicate that a <code>SysexMessage</code> contains continuing system - * exclusive data should not be propagated via MIDI wire protocol. + * If system exclusive data from {@code SysexMessages} objects is being + * transmitted using MIDI wire protocol, only the initial 0xF0 status byte, the + * system exclusive data itself, and the final 0xF7 (EOX) byte should be + * propagated; any 0xF7 status bytes used to indicate that a + * {@code SysexMessage} contains continuing system exclusive data should not be + * propagated via MIDI wire protocol. * * @author David Rivas * @author Kara Kytle @@ -74,43 +74,36 @@ */ public class SysexMessage extends MidiMessage { - // Status byte defines - /** * Status byte for System Exclusive message (0xF0, or 240). + * * @see MidiMessage#getStatus */ public static final int SYSTEM_EXCLUSIVE = 0xF0; // 240 - /** - * Status byte for Special System Exclusive message (0xF7, or 247), which is used - * in MIDI files. It has the same value as END_OF_EXCLUSIVE, which - * is used in the real-time "MIDI wire" protocol. + * Status byte for Special System Exclusive message (0xF7, or 247), which is + * used in MIDI files. It has the same value as END_OF_EXCLUSIVE, which is + * used in the real-time "MIDI wire" protocol. + * * @see MidiMessage#getStatus */ public static final int SPECIAL_SYSTEM_EXCLUSIVE = 0xF7; // 247 - - // Instance variables - - - /* - * The data bytes for this system exclusive message. These are - * initialized to <code>null</code> and are set explicitly - * by {@link #setMessage(int, byte[], int, long) setMessage}. + /** + * The data bytes for this system exclusive message. These are initialized + * to {@code null} and are set explicitly by + * {@link #setMessage(int, byte[], int, long) setMessage}. */ //protected byte[] data = null; - /** - * Constructs a new <code>SysexMessage</code>. The - * contents of the new message are guaranteed to specify - * a valid MIDI message. Subsequently, you may set the - * contents of the message using one of the <code>setMessage</code> - * methods. + * Constructs a new {@code SysexMessage}. The contents of the new message + * are guaranteed to specify a valid MIDI message. Subsequently, you may set + * the contents of the message using one of the {@code setMessage} methods. + * * @see #setMessage */ public SysexMessage() { @@ -121,18 +114,17 @@ } /** - * Constructs a new {@code SysexMessage} and sets the data for - * the message. The first byte of the data array must be a valid system - * exclusive status byte (0xF0 or 0xF7). - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * Constructs a new {@code SysexMessage} and sets the data for the message. + * The first byte of the data array must be a valid system exclusive status + * byte (0xF0 or 0xF7). The contents of the message can be changed by using + * one of the {@code setMessage} methods. * - * @param data the system exclusive message data including the status byte - * @param length the length of the valid message data in the array, - * including the status byte; it 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. + * @param data the system exclusive message data including the status byte + * @param length the length of the valid message data in the array, + * including the status byte; it 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. * @see #setMessage(byte[], int) * @see #setMessage(int, byte[], int) * @see #getData() @@ -146,17 +138,17 @@ /** * Constructs a new {@code SysexMessage} and sets the data for the message. - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * The contents of the message can be changed by using one of the + * {@code setMessage} methods. * - * @param status the status byte for the message; it must be a valid system - * exclusive status byte (0xF0 or 0xF7) - * @param data the system exclusive message data (without the status byte) - * @param length the length of the valid message data in the array; - * it 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. + * @param status the status byte for the message; it must be a valid system + * exclusive status byte (0xF0 or 0xF7) + * @param data the system exclusive message data (without the status byte) + * @param length the length of the valid message data in the array; it + * 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 * @see #setMessage(byte[], int) * @see #setMessage(int, byte[], int) * @see #getData() @@ -168,26 +160,24 @@ setMessage(status, data, length); } - /** - * Constructs a new <code>SysexMessage</code>. - * @param data an array of bytes containing the complete message. - * The message data may be changed using the <code>setMessage</code> - * method. + * Constructs a new {@code SysexMessage}. + * + * @param data an array of bytes containing the complete message. The + * message data may be changed using the {@code setMessage} method. * @see #setMessage */ protected SysexMessage(byte[] data) { super(data); } - /** - * Sets the data for the system exclusive message. The - * first byte of the data array must be a valid system - * exclusive status byte (0xF0 or 0xF7). - * @param data the system exclusive message data - * @param length the length of the valid message data in - * the array, including the status byte. + * Sets the data for the system exclusive message. The first byte of the + * data array must be a valid system exclusive status byte (0xF0 or 0xF7). + * + * @param data the system exclusive message data + * @param length the length of the valid message data in the array, + * including the status byte */ public void setMessage(byte[] data, int length) throws InvalidMidiDataException { int status = (data[0] & 0xFF); @@ -197,14 +187,14 @@ super.setMessage(data, length); } - /** * Sets the data for the system exclusive message. - * @param status the status byte for the message (0xF0 or 0xF7) - * @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 + * + * @param status the status byte for the message (0xF0 or 0xF7) + * @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 */ public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException { if ( (status != 0xF0) && (status != 0xF7) ) { @@ -225,11 +215,11 @@ } } - /** - * Obtains a copy of the data for the system exclusive message. - * The returned array of bytes does not include the status byte. - * @return array containing the system exclusive message data. + * Obtains a copy of the data for the system exclusive message. The returned + * array of bytes does not include the status byte. + * + * @return array containing the system exclusive message data */ public byte[] getData() { byte[] returnedArray = new byte[length - 1]; @@ -237,10 +227,10 @@ return returnedArray; } - /** - * Creates a new object of the same class and with the same contents - * as this object. + * Creates a new object of the same class and with the same contents as this + * object. + * * @return a clone of this instance */ public Object clone() {
--- a/jdk/src/share/classes/javax/sound/midi/Track.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/Track.java Wed Jul 23 16:19:26 2014 +0400 @@ -25,41 +25,40 @@ package javax.sound.midi; -import java.util.Vector; import java.util.ArrayList; import java.util.HashSet; + import com.sun.media.sound.MidiUtils; /** - * A MIDI track is an independent stream of MIDI events (time-stamped MIDI - * data) that can be stored along with other tracks in a standard MIDI file. - * The MIDI specification allows only 16 channels of MIDI data, but tracks - * are a way to get around this limitation. A MIDI file can contain any number - * of tracks, each containing its own stream of up to 16 channels of MIDI data. + * A MIDI track is an independent stream of MIDI events (time-stamped MIDI data) + * that can be stored along with other tracks in a standard MIDI file. The MIDI + * specification allows only 16 channels of MIDI data, but tracks are a way to + * get around this limitation. A MIDI file can contain any number of tracks, + * each containing its own stream of up to 16 channels of MIDI data. * <p> - * A <code>Track</code> occupies a middle level in the hierarchy of data played - * by a <code>{@link Sequencer}</code>: sequencers play sequences, which contain tracks, - * which contain MIDI events. A sequencer may provide controls that mute - * or solo individual tracks. + * A {@code Track} occupies a middle level in the hierarchy of data played by a + * {@link Sequencer}: sequencers play sequences, which contain tracks, which + * contain MIDI events. A sequencer may provide controls that mute or solo + * individual tracks. * <p> * The timing information and resolution for a track is controlled by and stored - * in the sequence containing the track. A given <code>Track</code> - * is considered to belong to the particular <code>{@link Sequence}</code> that - * maintains its timing. For this reason, a new (empty) track is created by calling the - * <code>{@link Sequence#createTrack}</code> method, rather than by directly invoking a - * <code>Track</code> constructor. + * in the sequence containing the track. A given {@code Track} is considered to + * belong to the particular {@link Sequence} that maintains its timing. For this + * reason, a new (empty) track is created by calling the + * {@link Sequence#createTrack} method, rather than by directly invoking a + * {@code Track} constructor. * <p> - * The <code>Track</code> class provides methods to edit the track by adding - * or removing <code>MidiEvent</code> objects from it. These operations keep - * the event list in the correct time order. Methods are also - * included to obtain the track's size, in terms of either the number of events - * it contains or its duration in ticks. - * - * @see Sequencer#setTrackMute - * @see Sequencer#setTrackSolo + * The {@code Track} class provides methods to edit the track by adding or + * removing {@code MidiEvent} objects from it. These operations keep the event + * list in the correct time order. Methods are also included to obtain the + * track's size, in terms of either the number of events it contains or its + * duration in ticks. * * @author Kara Kytle * @author Florian Bomers + * @see Sequencer#setTrackMute + * @see Sequencer#setTrackSolo */ public class Track { @@ -73,10 +72,9 @@ private MidiEvent eotEvent; - /** - * Package-private constructor. Constructs a new, empty Track object, - * which initially contains one event, the meta-event End of Track. + * Package-private constructor. Constructs a new, empty Track object, which + * initially contains one event, the meta-event End of Track. */ Track() { // start with the end of track event @@ -87,14 +85,14 @@ } /** - * Adds a new event to the track. However, if the event is already - * contained in the track, it is not added again. The list of events - * is kept in time order, meaning that this event inserted at the - * appropriate place in the list, not necessarily at the end. + * Adds a new event to the track. However, if the event is already contained + * in the track, it is not added again. The list of events is kept in time + * order, meaning that this event inserted at the appropriate place in the + * list, not necessarily at the end. * - * @param event the event to add - * @return <code>true</code> if the event did not already exist in the - * track and was added, otherwise <code>false</code> + * @param event the event to add + * @return {@code true} if the event did not already exist in the track and + * was added, otherwise {@code false} */ public boolean add(MidiEvent event) { if (event == null) { @@ -176,12 +174,12 @@ return false; } - /** * Removes the specified event from the track. - * @param event the event to remove - * @return <code>true</code> if the event existed in the track and was removed, - * otherwise <code>false</code> + * + * @param event the event to remove + * @return {@code true} if the event existed in the track and was removed, + * otherwise {@code false} */ public boolean remove(MidiEvent event) { @@ -207,15 +205,14 @@ return false; } - /** * Obtains the event at the specified index. - * @param index the location of the desired event in the event vector - * @throws ArrayIndexOutOfBoundsException if the - * specified index is negative or not less than the current size of - * this track. + * + * @param index the location of the desired event in the event vector + * @return the event at the specified index + * @throws ArrayIndexOutOfBoundsException if the specified index is negative + * or not less than the current size of this track * @see #size - * @return the event at the specified index */ public MidiEvent get(int index) throws ArrayIndexOutOfBoundsException { try { @@ -227,9 +224,9 @@ } } - /** * Obtains the number of events in this track. + * * @return the size of the track's event vector */ public int size() { @@ -238,12 +235,12 @@ } } - /** - * Obtains the length of the track, expressed in MIDI ticks. (The - * duration of a tick in seconds is determined by the timing resolution - * of the <code>Sequence</code> containing this track, and also by - * the tempo of the music as set by the sequencer.) + * Obtains the length of the track, expressed in MIDI ticks. (The duration + * of a tick in seconds is determined by the timing resolution of the + * {@code Sequence} containing this track, and also by the tempo of the + * music as set by the sequencer.) + * * @return the duration, in ticks * @see Sequence#Sequence(float, int) * @see Sequencer#setTempoInBPM(float) @@ -271,5 +268,4 @@ throw new InvalidMidiDataException("cannot modify end of track message"); } } - }
--- a/jdk/src/share/classes/javax/sound/midi/Transmitter.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/Transmitter.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2014, 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 @@ -25,52 +25,49 @@ package javax.sound.midi; - /** - * A <code>Transmitter</code> sends <code>{@link MidiEvent}</code> objects to one or more - * <code>{@link Receiver Receivers}</code>. Common MIDI transmitters include sequencers - * and MIDI input ports. - * - * @see Receiver + * A {@code Transmitter} sends {@link MidiEvent} objects to one or more + * {@link Receiver Receivers}. Common MIDI transmitters include sequencers and + * MIDI input ports. * * @author Kara Kytle + * @see Receiver */ public interface Transmitter extends AutoCloseable { - /** * Sets the receiver to which this transmitter will deliver MIDI messages. * If a receiver is currently set, it is replaced with this one. - * @param receiver the desired receiver. + * + * @param receiver the desired receiver */ - public void setReceiver(Receiver receiver); - + void setReceiver(Receiver receiver); /** - * Obtains the current receiver to which this transmitter will deliver MIDI messages. - * @return the current receiver. If no receiver is currently set, - * returns <code>null</code> + * Obtains the current receiver to which this transmitter will deliver MIDI + * messages. + * + * @return the current receiver. If no receiver is currently set, returns + * {@code null}. */ - public Receiver getReceiver(); - + Receiver getReceiver(); /** * Indicates that the application has finished using the transmitter, and * that limited resources it requires may be released or made available. - * - * <p>If the creation of this <code>Transmitter</code> resulted in - * implicitly opening the underlying device, the device is - * implicitly closed by this method. This is true unless the device is - * kept open by other <code>Receiver</code> or <code>Transmitter</code> - * instances that opened the device implicitly, and unless the device - * has been opened explicitly. If the device this - * <code>Transmitter</code> is retrieved from is closed explicitly - * by calling {@link MidiDevice#close MidiDevice.close}, the - * <code>Transmitter</code> is closed, too. For a detailed - * description of open/close behaviour see the class description - * of {@link javax.sound.midi.MidiDevice MidiDevice}. + * <p> + * If the creation of this {@code Transmitter} resulted in implicitly + * opening the underlying device, the device is implicitly closed by this + * method. This is true unless the device is kept open by other + * {@code Receiver} or {@code Transmitter} instances that opened the device + * implicitly, and unless the device has been opened explicitly. If the + * device this {@code Transmitter} is retrieved from is closed explicitly by + * calling {@link MidiDevice#close MidiDevice.close}, the + * {@code Transmitter} is closed, too. For a detailed description of + * open/close behaviour see the class description of + * {@link MidiDevice MidiDevice}. * * @see javax.sound.midi.MidiSystem#getTransmitter */ - public void close(); + void close(); }
--- a/jdk/src/share/classes/javax/sound/midi/VoiceStatus.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/VoiceStatus.java Wed Jul 23 16:19:26 2014 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, 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 @@ -25,93 +25,83 @@ package javax.sound.midi; - /** - * A <code>VoiceStatus</code> object contains information about the current - * status of one of the voices produced by a {@link Synthesizer}. + * A {@code VoiceStatus} object contains information about the current status of + * one of the voices produced by a {@link Synthesizer}. * <p> * MIDI synthesizers are generally capable of producing some maximum number of - * simultaneous notes, also referred to as voices. A voice is a stream - * of successive single notes, and the process of assigning incoming MIDI notes to - * specific voices is known as voice allocation. - * However, the voice-allocation algorithm and the contents of each voice are - * normally internal to a MIDI synthesizer and hidden from outside view. One can, of - * course, learn from MIDI messages which notes the synthesizer is playing, and - * one might be able deduce something about the assignment of notes to voices. - * But MIDI itself does not provide a means to report which notes a - * synthesizer has assigned to which voice, nor even to report how many voices - * the synthesizer is capable of synthesizing. + * simultaneous notes, also referred to as voices. A voice is a stream of + * successive single notes, and the process of assigning incoming MIDI notes to + * specific voices is known as voice allocation. However, the voice-allocation + * algorithm and the contents of each voice are normally internal to a MIDI + * synthesizer and hidden from outside view. One can, of course, learn from MIDI + * messages which notes the synthesizer is playing, and one might be able deduce + * something about the assignment of notes to voices. But MIDI itself does not + * provide a means to report which notes a synthesizer has assigned to which + * voice, nor even to report how many voices the synthesizer is capable of + * synthesizing. * <p> - * In Java Sound, however, a - * <code>Synthesizer</code> class can expose the contents of its voices through its - * {@link Synthesizer#getVoiceStatus() getVoiceStatus()} method. - * This behavior is recommended but optional; - * synthesizers that don't expose their voice allocation simply return a - * zero-length array. A <code>Synthesizer</code> that does report its voice status - * should maintain this information at - * all times for all of its voices, whether they are currently sounding or - * not. In other words, a given type of <code>Synthesizer</code> always has a fixed - * number of voices, equal to the maximum number of simultaneous notes it is - * capable of sounding. + * In Java Sound, however, a {@code Synthesizer} class can expose the contents + * of its voices through its + * {@link Synthesizer#getVoiceStatus() getVoiceStatus()} method. This behavior + * is recommended but optional; synthesizers that don't expose their voice + * allocation simply return a zero-length array. A {@code Synthesizer} that does + * report its voice status should maintain this information at all times for all + * of its voices, whether they are currently sounding or not. In other words, a + * 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 NAME="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 - * simultaneous notes is told to play a four-note chord; only - * four voices are active in this case (assuming no earlier notes are still playing). - * Usually, a voice whose status is reported as active is producing audible sound, but this - * is not always true; it depends on the details of the instrument (that - * is, the synthesis algorithm) and how long the note has been going on. - * For example, a voice may be synthesizing the sound of a single hand-clap. Because - * this sound dies away so quickly, it may become inaudible before a note-off - * message is received. In such a situation, the voice is still considered active - * even though no sound is currently being produced. + * <a NAME="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 + * simultaneous notes is told to play a four-note chord; only four voices are + * active in this case (assuming no earlier notes are still playing). Usually, a + * voice whose status is reported as active is producing audible sound, but this + * is not always true; it depends on the details of the instrument (that is, the + * synthesis algorithm) and how long the note has been going on. For example, a + * voice may be synthesizing the sound of a single hand-clap. Because this sound + * dies away so quickly, it may become inaudible before a note-off message is + * received. In such a situation, the voice is still considered active even + * though no sound is currently being produced. * <p> - * Besides its active or inactive status, the <code>VoiceStatus</code> class - * provides fields that reveal the voice's current MIDI channel, bank and - * program number, MIDI note number, and MIDI volume. All of these can - * change during the course of a voice. While the voice is inactive, each - * of these fields has an unspecified value, so you should check the active - * field first. - * - * @see Synthesizer#getMaxPolyphony - * @see Synthesizer#getVoiceStatus + * Besides its active or inactive status, the {@code VoiceStatus} class provides + * fields that reveal the voice's current MIDI channel, bank and program number, + * MIDI note number, and MIDI volume. All of these can change during the course + * of a voice. While the voice is inactive, each of these fields has an + * unspecified value, so you should check the active field first. * * @author David Rivas * @author Kara Kytle + * @see Synthesizer#getMaxPolyphony + * @see Synthesizer#getVoiceStatus */ - public class VoiceStatus { - /** - * Indicates whether the voice is currently processing a MIDI note. - * See the explanation of - * <A HREF="#description_of_active">active and inactive voices</A>. + * Indicates whether the voice is currently processing a MIDI note. See the + * explanation of + * <a HREF="#description_of_active">active and inactive voices</a>. */ public boolean active = false; - /** - * The MIDI channel on which this voice is playing. The value is a - * zero-based channel number if the voice is active, or - * unspecified if the voice is inactive. + * The MIDI channel on which this voice is playing. The value is a + * zero-based channel number if the voice is active, or unspecified if the + * voice is inactive. * * @see MidiChannel * @see #active */ public int channel = 0; - /** * The bank number of the instrument that this voice is currently using. * This is a number dictated by the MIDI bank-select message; it does not - * refer to a <code>SoundBank</code> object. - * The value ranges from 0 to 16383 if the voice is active, and is - * unspecified if the voice is inactive. + * refer to a {@code SoundBank} object. The value ranges from 0 to 16383 if + * the voice is active, and is unspecified if the voice is inactive. + * * @see Patch * @see Soundbank * @see #active @@ -119,11 +109,10 @@ */ public int bank = 0; - /** * The program number of the instrument that this voice is currently using. - * The value ranges from 0 to 127 if the voice is active, and is - * unspecified if the voice is inactive. + * The value ranges from 0 to 127 if the voice is active, and is unspecified + * if the voice is inactive. * * @see MidiChannel#getProgram * @see Patch @@ -131,28 +120,24 @@ */ public int program = 0; - /** - * The MIDI note that this voice is playing. The range for an active voice - * is from 0 to 127 in semitones, with 60 referring to Middle C. - * The value is unspecified if the voice is inactive. + * The MIDI note that this voice is playing. The range for an active voice + * is from 0 to 127 in semitones, with 60 referring to Middle C. The value + * is unspecified if the voice is inactive. * * @see MidiChannel#noteOn * @see #active */ public int note = 0; - /** - * The current MIDI volume level for the voice. - * The value ranges from 0 to 127 if the voice is active, and is - * unspecified if the voice is inactive. + * The current MIDI volume level for the voice. The value ranges from 0 to + * 127 if the voice is active, and is unspecified if the voice is inactive. * <p> - * Note that this value does not necessarily reflect - * the instantaneous level of the sound produced by this - * voice; that level is the result of many contributing - * factors, including the current instrument and the - * shape of the amplitude envelope it produces. + * Note that this value does not necessarily reflect the instantaneous level + * of the sound produced by this voice; that level is the result of many + * contributing factors, including the current instrument and the shape of + * the amplitude envelope it produces. * * @see #active */
--- a/jdk/src/share/classes/javax/sound/midi/spi/MidiFileReader.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/spi/MidiFileReader.java Wed Jul 23 16:19:26 2014 +0400 @@ -26,13 +26,13 @@ package javax.sound.midi.spi; import java.io.File; +import java.io.IOException; import java.io.InputStream; -import java.io.IOException; import java.net.URL; +import javax.sound.midi.InvalidMidiDataException; import javax.sound.midi.MidiFileFormat; import javax.sound.midi.Sequence; -import javax.sound.midi.InvalidMidiDataException; /** * A {@code MidiFileReader} supplies MIDI file-reading services. Classes @@ -106,7 +106,7 @@ * @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. + * in the input stream * @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
--- a/jdk/src/share/classes/javax/sound/midi/spi/SoundbankReader.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/midi/spi/SoundbankReader.java Wed Jul 23 16:19:26 2014 +0400 @@ -32,12 +32,12 @@ import javax.sound.midi.InvalidMidiDataException; import javax.sound.midi.Soundbank; +import javax.sound.midi.Synthesizer; /** * A {@code SoundbankReader} supplies soundbank file-reading services. Concrete * subclasses of {@code SoundbankReader} parse a given soundbank file, producing - * a {@link javax.sound.midi.Soundbank} object that can be loaded into a - * {@link javax.sound.midi.Synthesizer}. + * a {@link Soundbank} object that can be loaded into a {@link Synthesizer}. * * @since 1.3 * @author Kara Kytle @@ -47,7 +47,7 @@ /** * Obtains a soundbank object from the URL provided. * - * @param url URL representing the soundbank. + * @param url 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
--- a/jdk/src/share/classes/javax/sound/sampled/AudioSystem.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/sampled/AudioSystem.java Wed Jul 23 16:19:26 2014 +0400 @@ -26,19 +26,19 @@ package javax.sound.sampled; import java.io.File; +import java.io.IOException; import java.io.InputStream; -import java.io.IOException; import java.io.OutputStream; import java.net.URL; - +import java.util.ArrayList; import java.util.HashSet; import java.util.List; +import java.util.Properties; import java.util.Set; import java.util.Vector; -import java.util.ArrayList; +import javax.sound.sampled.spi.AudioFileReader; import javax.sound.sampled.spi.AudioFileWriter; -import javax.sound.sampled.spi.AudioFileReader; import javax.sound.sampled.spi.FormatConversionProvider; import javax.sound.sampled.spi.MixerProvider; @@ -60,14 +60,14 @@ * <p> * Properties can be used to specify the default mixer for specific line types. * Both system properties and a properties file are considered. The - * {@code sound.properties} properties file is read from an - * implementation-specific location (typically it is the {@code lib} directory - * in the Java installation directory). If a property exists both as a system - * property and in the properties file, the system property takes precedence. - * If none is specified, a suitable default is chosen among the available - * devices. The syntax of the properties file is specified in - * {@link java.util.Properties#load(InputStream) Properties.load}. The following - * table lists the available property keys and which methods consider them: + * "sound.properties" properties file is read from an implementation-specific + * location (typically it is the {@code lib} directory in the Java installation + * directory). If a property exists both as a system property and in the + * properties file, the system property takes precedence. If none is specified, + * a suitable default is chosen among the available devices. The syntax of the + * properties file is specified in + * {@link Properties#load(InputStream) Properties.load}. The following table + * lists the available property keys and which methods consider them: * * <table border=0> * <caption>Audio System Property Keys</caption> @@ -100,12 +100,11 @@ * * The property value consists of the provider class name and the mixer name, * separated by the hash mark ("#"). The provider class name is the - * fully-qualified name of a concrete - * {@link javax.sound.sampled.spi.MixerProvider mixer provider} class. The mixer - * name is matched against the {@code String} returned by the {@code getName} - * method of {@code Mixer.Info}. Either the class name, or the mixer name may be - * omitted. If only the class name is specified, the trailing hash mark is - * optional. + * fully-qualified name of a concrete {@link MixerProvider mixer provider} + * class. The mixer name is matched against the {@code String} returned by the + * {@code getName} method of {@code Mixer.Info}. Either the class name, or the + * mixer name may be omitted. If only the class name is specified, the trailing + * hash mark is optional. * <p> * If the provider class is specified, and it can be successfully retrieved from * the installed providers, the list of {@code Mixer.Info} objects is retrieved @@ -1324,10 +1323,9 @@ * Obtains the set of format converters (codecs, transcoders, etc.) that are * currently installed on the system. * - * @return an array of {@link javax.sound.sampled.spi.FormatConversionProvider - * FormatConversionProvider} objects representing the available - * format converters. If no format converters readers are available - * on the system, an array of length 0 is returned. + * @return an array of {@link FormatConversionProvider} objects representing + * the available format converters. If no format converters readers + * are available on the system, an array of length 0 is returned. */ @SuppressWarnings("unchecked") private static List<FormatConversionProvider> getFormatConversionProviders() { @@ -1338,10 +1336,9 @@ * Obtains the set of audio file readers that are currently installed on the * system. * - * @return a List of {@link javax.sound.sampled.spi.AudioFileReader - * AudioFileReader} objects representing the installed audio file - * readers. If no audio file readers are available on the system, an - * empty List is returned. + * @return a List of {@link AudioFileReader} objects representing the + * installed audio file readers. If no audio file readers are + * available on the system, an empty List is returned. */ @SuppressWarnings("unchecked") private static List<AudioFileReader> getAudioFileReaders() { @@ -1352,10 +1349,9 @@ * Obtains the set of audio file writers that are currently installed on the * system. * - * @return a List of {@link javax.sound.sampled.spi.AudioFileWriter - * AudioFileWriter} objects representing the available audio file - * writers. If no audio file writers are available on the system, an - * empty List is returned. + * @return a List of {@link AudioFileWriter} objects representing the + * available audio file writers. If no audio file writers are + * available on the system, an empty List is returned. */ @SuppressWarnings("unchecked") private static List<AudioFileWriter> getAudioFileWriters() {
--- a/jdk/src/share/classes/javax/sound/sampled/DataLine.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/sampled/DataLine.java Wed Jul 23 16:19:26 2014 +0400 @@ -355,11 +355,11 @@ * {@code true} for all formats returned by {@code getFormats()}. * <p> * Some fields in the AudioFormat instances can be set to - * {@link javax.sound.sampled.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 up to 64 channels, could set the channel field in - * the {@code AudioFormat} instances returned by this method 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 + * up to 64 channels, could set the channel field in the + * {@code AudioFormat} instances returned by this method to * {@code NOT_SPECIFIED}. * * @return a set of supported audio formats
--- a/jdk/src/share/classes/javax/sound/sampled/spi/AudioFileReader.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/sampled/spi/AudioFileReader.java Wed Jul 23 16:19:26 2014 +0400 @@ -26,8 +26,8 @@ package javax.sound.sampled.spi; import java.io.File; +import java.io.IOException; import java.io.InputStream; -import java.io.IOException; import java.net.URL; import javax.sound.sampled.AudioFileFormat;
--- a/jdk/src/share/classes/javax/sound/sampled/spi/AudioFileWriter.java Wed Jul 23 15:44:44 2014 +0400 +++ b/jdk/src/share/classes/javax/sound/sampled/spi/AudioFileWriter.java Wed Jul 23 16:19:26 2014 +0400 @@ -30,6 +30,7 @@ import java.io.OutputStream; import javax.sound.sampled.AudioInputStream; +import javax.sound.sampled.AudioSystem; import static javax.sound.sampled.AudioFileFormat.Type; @@ -110,8 +111,7 @@ * 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 - * audio file format is {@link javax.sound.sampled.AudioSystem#NOT_SPECIFIED - * AudioSystem.NOT_SPECIFIED}. + * audio file format is {@link AudioSystem#NOT_SPECIFIED}. * * @param stream the audio input stream containing audio data to be written * to the output stream