jdk-sandbox: comparison jdk/src/java.desktop/share/classes/javax/sound/midi/ShortMessage.java

equal deleted inserted replaced

-:e9b05e933ddd
+:508779ce6619
 /*
-* 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
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 */
 package javax.sound.midi;
 /**
-* A <code>ShortMessage</code> contains a MIDI message that has at most
+* A {@code ShortMessage} contains a MIDI message that has at most two data
-* two data bytes following its status byte.  The types of MIDI message
+* bytes following its status byte. The types of MIDI message that satisfy this
-* that satisfy this criterion are channel voice, channel mode, system common,
+* criterion are channel voice, channel mode, system common, and system
-* and system real-time--in other words, everything except system exclusive
+* real-time--in other words, everything except system exclusive and
-* and meta-events.  The <code>ShortMessage</code> class provides methods
+* meta-events. The {@code ShortMessage} class provides methods for getting and
-* for getting and setting the contents of the MIDI message.
+* setting the contents of the MIDI message.
 * <p>
-* A number of <code>ShortMessage</code> methods have integer parameters by which
+* A number of {@code ShortMessage} methods have integer parameters by which you
-* you specify a MIDI status or data byte.  If you know the numeric value, you
+* specify a MIDI status or data byte. If you know the numeric value, you can
-* can express it directly.  For system common and system real-time messages,
+* express it directly. For system common and system real-time messages, you can
-* you can often use the corresponding fields of <code>ShortMessage</code>, such as
+* often use the corresponding fields of {@code ShortMessage}, such as
-* {@link #SYSTEM_RESET SYSTEM_RESET}.  For channel messages,
+* {@link #SYSTEM_RESET SYSTEM_RESET}. For channel messages, the upper four bits
-* the upper four bits of the status byte are specified by a command value and
+* of the status byte are specified by a command value and the lower four bits
-* the lower four bits are specified by a MIDI channel number. To
+* are specified by a MIDI channel number. To convert incoming MIDI data bytes
-* convert incoming MIDI data bytes that are in the form of Java's signed bytes,
+* that are in the form of Java's signed bytes, you can use the
-* you can use the <A HREF="MidiMessage.html#integersVsBytes">conversion code</A>
+* <a href="MidiMessage.html#integersVsBytes">conversion code</a> given in the
-* given in the <code>{@link MidiMessage}</code> class description.
+* {@link MidiMessage} class description.
-*
-* @see SysexMessage
-* @see MetaMessage
 *
 * @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}. 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.
-* 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.
 * @see #setMessage
 */
 public ShortMessage() {
 this(new byte[3]);
 // Default message data: NOTE_ON on Channel 0 with max volume
 data[2] = (byte) 127;
 length = 3;
 }
 /**
-* Constructs a new {@code ShortMessage} which represents a MIDI
+* Constructs a new {@code ShortMessage} which represents a MIDI message
-* message that takes no data bytes.
+* that takes no data bytes. The contents of the message can be changed by
-* The contents of the message can be changed by using one of
+* using one of the {@code setMessage} methods.
-* the {@code setMessage} methods.
+*
-*
+* @param  status the MIDI status byte
-* @param status the MIDI status byte
+* @throws InvalidMidiDataException if {@code status} does not specify a
-* @throws InvalidMidiDataException if {@code status} does not specify
+*         valid MIDI status byte for a message that requires no data bytes
-*     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)
 * @see #getStatus()
 * @since 1.7
 }
 /**
 * 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
+* the second data byte is ignored. If the message does not take any data
-* any data bytes, both data bytes are ignored.
+* bytes, both data bytes are ignored. The contents of the message can be
-* The contents of the message can be changed by using one of
+* changed by using one of the {@code setMessage} methods.
-* the {@code setMessage} methods.
+*
-*
+* @param  status the MIDI status byte
-* @param status   the MIDI status byte
+* @param  data1 the first data byte
-* @param data1    the first data byte
+* @param  data2 the second 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)
 * @see #getStatus()
 * @see #getData1()
 super(null);
 setMessage(status, data1, data2); // can throw InvalidMidiDataException
 }
 /**
-* Constructs a new {@code ShortMessage} which represents a channel
+* Constructs a new {@code ShortMessage} which represents a channel MIDI
-* MIDI message that takes up to two data bytes. If the message only takes
+* message that takes up to two data bytes. If the message only takes one
-* one data byte, the second data byte is ignored. If the message does not
+* data byte, the second data byte is ignored. If the message does not take
-* take any data bytes, both data bytes are ignored.
+* any data bytes, both data bytes are ignored. The contents of the message
-* The contents of the message can be changed by using one of
+* can be changed by using one of the {@code setMessage} methods.
-* the {@code setMessage} methods.
+*
-*
+* @param  command the MIDI command represented by this message
-* @param command  the MIDI command represented by this message
+* @param  channel the channel associated with the message
-* @param channel  the channel associated with the message
+* @param  data1 the first data byte
-* @param data1    the first data byte
+* @param  data2 the second data byte
-* @param data2    the second data byte
+* @throws InvalidMidiDataException if the command value, channel value or
-* @throws InvalidMidiDataException if the command value, channel value
+*         all data bytes belonging to the message do not specify a valid
-*     or all data bytes belonging to the message do not specify
+*         MIDI message
-*     a valid MIDI message
 * @see #setMessage(int)
 * @see #setMessage(int, int, int)
 * @see #setMessage(int, int, int, int)
 * @see #getCommand()
 * @see #getChannel()
 throws InvalidMidiDataException {
 super(null);
 setMessage(command, channel, data1, data2);
 }
+/**
-/**
+* Constructs a new {@code ShortMessage}.
-* Constructs a new <code>ShortMessage</code>.
+*
-* @param data an array of bytes containing the complete message.
+* @param  data an array of bytes containing the complete message. The
-* The message data may be changed using the <code>setMessage</code>
+*         message data may be changed using the {@code setMessage} method.
-* method.
 * @see #setMessage
 */
 // $$fb this should throw an Exception in case of an illegal message!
 protected ShortMessage(byte[] data) {
 // $$fb this may set an invalid message.
 // Can't correct without compromising compatibility
 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
+* @param  status the MIDI status byte
-* specify a valid MIDI status byte for a message that requires no data bytes.
+* @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)
 */
 public void setMessage(int status) throws InvalidMidiDataException {
 // check for valid values
 throw new InvalidMidiDataException("Status byte; " + status + " requires " + dataLength + " data bytes");
 }
 setMessage(status, 0, 0);
 }
+/**
-/**
+* Sets the parameters for a MIDI message that takes one or two data bytes.
-* Sets the  parameters for a MIDI message that takes one or two data
+* If the message takes only one data byte, the second data byte is ignored;
-* bytes.  If the message takes only one data byte, the second data
+* if the message does not take any data bytes, both data bytes are ignored.
-* 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 status    the MIDI status byte
+* @param  data2 the second data byte
-* @param data1             the first data byte
+* @throws InvalidMidiDataException if the the status byte, or all data
-* @param data2             the second data byte
+*         bytes belonging to the message, do not specify a valid MIDI
-* @throws  InvalidMidiDataException if the
+*         message
-* 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)
 */
 public void setMessage(int status, int data1, int data2) throws InvalidMidiDataException {
 // check for valid values
 data[2] = (byte) (data2 & 0xFF);
 }
 }
 }
+/**
-/**
+* Sets the short message parameters for a channel message which takes up to
-* Sets the short message parameters for a  channel message
+* two data bytes. If the message only takes one data byte, the second data
-* which takes up to two data bytes.  If the message only
+* byte is ignored; if the message does not take any data bytes, both data
-* takes one data byte, the second data byte is ignored; if
+* bytes are ignored.
-* 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 command   the MIDI command represented by this message
+* @param  data1 the first data byte
-* @param channel   the channel associated with the message
+* @param  data2 the second data byte
-* @param data1             the first data byte
+* @throws InvalidMidiDataException if the status byte or all data bytes
-* @param data2             the second data byte
+*         belonging to the message, do not specify a valid MIDI message
-* @throws          InvalidMidiDataException if the
-* status byte or all data bytes belonging to the message, do
-* not specify a valid MIDI message
-*
 * @see #setMessage(int, int, int)
 * @see #setMessage(int)
 * @see #getCommand
 * @see #getChannel
 * @see #getData1
 throw new InvalidMidiDataException("channel out of range: " + channel);
 }
 setMessage((command & 0xF0) | (channel & 0x0F), data1, data2);
 }
+/**
-/**
+* Obtains the MIDI channel associated with this event. This method assumes
-* Obtains the MIDI channel associated with this event.  This method
+* that the event is a MIDI channel message; if not, the return value will
-* assumes that the event is a MIDI channel message; if not, the return
+* not be meaningful.
-* value will not be meaningful.
+*
-* @return MIDI channel associated with the message.
+* @return MIDI channel associated with the message
 * @see #setMessage(int, int, int, int)
 */
 public int getChannel() {
 // this returns 0 if an invalid message is set
 return (getStatus() & 0x0F);
 }
+/**
-/**
+* Obtains the MIDI command associated with this event. This method assumes
-* Obtains the MIDI command associated with this event.  This method
+* that the event is a MIDI channel message; if not, the return value will
-* assumes that the event is a MIDI channel message; if not, the return
+* not be meaningful.
-* value will not be meaningful.
+*
 * @return the MIDI command associated with this event
 * @see #setMessage(int, int, int, int)
 */
 public int getCommand() {
 // this returns 0 if an invalid message is set
 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() {
 if (length > 1) {
 return (data[1] & 0xFF);
 }
 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() {
 if (length > 2) {
 return (data[2] & 0xFF);
 }
 return 0;
 }
+/**
-/**
+* Creates a new object of the same class and with the same contents as this
-* Creates a new object of the same class and with the same contents
+* object.
-* as this object.
+*
-* @return a clone of this instance.
+* @return a clone of this instance
 */
 public Object clone() {
 byte[] newData = new byte[length];
 System.arraycopy(data, 0, newData, 0, newData.length);
 ShortMessage msg = new ShortMessage(newData);
 return msg;
 }
+/**
-/**
+* Retrieves the number of data bytes associated with a particular status
-* Retrieves the number of data bytes associated with a particular
+* byte value.
-* status byte value.
+*
-* @param status status byte value, which must represent a short MIDI message
+* @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
+* @throws InvalidMidiDataException if the {@code status} argument does not
-* <code>status</code> argument does not represent the status byte for any
+*         represent the status byte for any short message
-* short message
 */
 protected final int getDataLength(int status) throws InvalidMidiDataException {
 // system common and system real-time messages
 switch(status) {
 case 0xF6:                      // Tune Request

changeset 26037	508779ce6619
parent 26003	d630c97424bd
parent 25859	3317bb8137f4
child 28059	e576535359cc