src/share/classes/javax/sound/midi/ShortMessage.java

Print this page

        

*** 1,7 **** /* ! * Copyright (c) 1998, 2013, 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 --- 1,7 ---- /* ! * 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
*** 24,183 **** */ 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. * <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 * * @author David Rivas * @author Kara Kytle * @author Florian Bomers */ - 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) */ public static final int NOTE_OFF = 0x80; // 128 /** ! * 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) */ public static final int POLY_PRESSURE = 0xA0; // 160 /** ! * 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) */ public static final int PROGRAM_CHANGE = 0xC0; // 192 /** ! * 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) */ 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. * @see #setMessage */ public ShortMessage() { this(new byte[3]); // Default message data: NOTE_ON on Channel 0 with max volume --- 24,185 ---- */ package javax.sound.midi; /** ! * 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} 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). */ public static final int NOTE_OFF = 0x80; // 128 /** ! * 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). */ public static final int POLY_PRESSURE = 0xA0; // 160 /** ! * 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). */ public static final int PROGRAM_CHANGE = 0xC0; // 192 /** ! * 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). */ public static final int PITCH_BEND = 0xE0; // 224 /** ! * 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() { this(new byte[3]); // Default message data: NOTE_ON on Channel 0 with max volume
*** 186,203 **** data[2] = (byte) 127; length = 3; } /** ! * 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 * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) * @see #getStatus() * @since 1.7 --- 188,204 ---- data[2] = (byte) 127; length = 3; } /** ! * 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 * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) * @see #getStatus() * @since 1.7
*** 208,221 **** } /** * 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. * * @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 --- 209,221 ---- } /** * 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. * * @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
*** 233,256 **** super(null); setMessage(status, data1, data2); // can throw InvalidMidiDataException } /** ! * 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 * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) * @see #getCommand() * @see #getChannel() --- 233,255 ---- super(null); setMessage(status, data1, data2); // can throw InvalidMidiDataException } /** ! * 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 * @see #setMessage(int) * @see #setMessage(int, int, int) * @see #setMessage(int, int, int, int) * @see #getCommand() * @see #getChannel()
*** 262,292 **** throws InvalidMidiDataException { super(null); 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. * @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 ! * 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 --- 261,290 ---- throws InvalidMidiDataException { super(null); setMessage(command, channel, data1, data2); } /** ! * 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! 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} 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
*** 295,317 **** 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. 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. * @see #setMessage(int, int, int, int) * @see #setMessage(int) */ public void setMessage(int status, int data1, int data2) throws InvalidMidiDataException { // check for valid values --- 293,313 ---- 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. ! * 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 * @see #setMessage(int, int, int, int) * @see #setMessage(int) */ public void setMessage(int status, int data1, int data2) throws InvalidMidiDataException { // check for valid values
*** 343,368 **** data[2] = (byte) (data2 & 0xFF); } } } - /** ! * 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 ! * * @see #setMessage(int, int, int) * @see #setMessage(int) * @see #getCommand * @see #getChannel * @see #getData1 --- 339,360 ---- data[2] = (byte) (data2 & 0xFF); } } } /** ! * 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 * @see #setMessage(int, int, int) * @see #setMessage(int) * @see #getCommand * @see #getChannel * @see #getData1
*** 377,461 **** 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 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() { // this returns 0 if an invalid message is set 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. * @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 * @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 * @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 object. ! * @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 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 */ protected final int getDataLength(int status) throws InvalidMidiDataException { // system common and system real-time messages switch(status) { case 0xF6: // Tune Request --- 369,453 ---- 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 ! * 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() { // this returns 0 if an invalid message is set 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. ! * * @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} 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} 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 ! * object. ! * ! * @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 ! * 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} 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 switch(status) { case 0xF6: // Tune Request