MidiMessage.java revision 11099:678faa7d1a6a
1264790Sbapt/* 2264790Sbapt * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. 3264790Sbapt * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4264790Sbapt * 5264790Sbapt * This code is free software; you can redistribute it and/or modify it 6264790Sbapt * under the terms of the GNU General Public License version 2 only, as 7264790Sbapt * published by the Free Software Foundation. Oracle designates this 8264790Sbapt * particular file as subject to the "Classpath" exception as provided 9264790Sbapt * by Oracle in the LICENSE file that accompanied this code. 10264790Sbapt * 11264790Sbapt * This code is distributed in the hope that it will be useful, but WITHOUT 12264790Sbapt * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13264790Sbapt * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14264790Sbapt * version 2 for more details (a copy is included in the LICENSE file that 15264790Sbapt * accompanied this code). 16264790Sbapt * 17264790Sbapt * You should have received a copy of the GNU General Public License version 18264790Sbapt * 2 along with this work; if not, write to the Free Software Foundation, 19264790Sbapt * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20264790Sbapt * 21264790Sbapt * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22264790Sbapt * or visit www.oracle.com if you need additional information or have any 23264790Sbapt * questions. 24264790Sbapt */ 25264790Sbapt 26264790Sbaptpackage javax.sound.midi; 27264790Sbapt 28264790Sbapt/** 29264790Sbapt * {@code MidiMessage} is the base class for MIDI messages. They include not 30264790Sbapt * only the standard MIDI messages that a synthesizer can respond to, but also 31264790Sbapt * "meta-events" that can be used by sequencer programs. There are meta-events 32264790Sbapt * for such information as lyrics, copyrights, tempo indications, time and key 33264790Sbapt * signatures, markers, etc. For more information, see the Standard MIDI Files 34264790Sbapt * 1.0 specification, which is part of the Complete MIDI 1.0 Detailed 35264790Sbapt * Specification published by the MIDI Manufacturer's Association 36264790Sbapt * (<a href = http://www.midi.org>http://www.midi.org</a>). 37264790Sbapt * <p> 38264790Sbapt * The base {@code MidiMessage} class provides access to three types of 39264790Sbapt * information about a MIDI message: 40264790Sbapt * <ul> 41264790Sbapt * <li>The messages's status byte</li> 42264790Sbapt * <li>The total length of the message in bytes (the status byte plus any data 43264790Sbapt * bytes)</li> 44264790Sbapt * <li>A byte array containing the complete message</li> 45264790Sbapt * </ul> 46264790Sbapt * 47264790Sbapt * {@code MidiMessage} includes methods to get, but not set, these values. 48264790Sbapt * Setting them is a subclass responsibility. 49264790Sbapt * <p> 50264790Sbapt * <a name="integersVsBytes"></a> The MIDI standard expresses MIDI data in 51264790Sbapt * bytes. However, because Java<sup>TM</sup> uses signed bytes, the Java Sound 52264790Sbapt * API uses integers instead of bytes when expressing MIDI data. For example, 53264790Sbapt * the {@link #getStatus()} method of {@code MidiMessage} returns MIDI status 54264790Sbapt * bytes as integers. If you are processing MIDI data that originated outside 55264790Sbapt * Java Sound and now is encoded as signed bytes, the bytes can be 56264790Sbapt * converted to integers using this conversion: 57264790Sbapt * 58264790Sbapt * <center>{@code int i = (int)(byte & 0xFF)}</center> 59264790Sbapt * <p> 60264790Sbapt * If you simply need to pass a known MIDI byte value as a method parameter, it 61264790Sbapt * can be expressed directly as an integer, using (for example) decimal or 62264790Sbapt * hexadecimal notation. For instance, to pass the "active sensing" status byte 63264790Sbapt * as the first argument to ShortMessage's 64264790Sbapt * {@link ShortMessage#setMessage(int) setMessage(int)} method, you can express 65264790Sbapt * it as 254 or 0xFE. 66264790Sbapt * 67264790Sbapt * @author David Rivas 68264790Sbapt * @author Kara Kytle 69264790Sbapt * @see Track 70264790Sbapt * @see Sequence 71264790Sbapt * @see Receiver 72264790Sbapt */ 73264790Sbaptpublic abstract class MidiMessage implements Cloneable { 74264790Sbapt 75264790Sbapt /** 76264790Sbapt * The MIDI message data. The first byte is the status byte for the message; 77264790Sbapt * subsequent bytes up to the length of the message are data bytes for this 78264790Sbapt * message. 79264790Sbapt * 80264790Sbapt * @see #getLength 81264790Sbapt */ 82264790Sbapt protected byte[] data; 83264790Sbapt 84264790Sbapt /** 85264790Sbapt * The number of bytes in the MIDI message, including the status byte and 86264790Sbapt * any data bytes. 87264790Sbapt * 88264790Sbapt * @see #getLength 89264790Sbapt */ 90264790Sbapt protected int length = 0; 91264790Sbapt 92264790Sbapt /** 93264790Sbapt * Constructs a new {@code MidiMessage}. This protected constructor is 94264790Sbapt * called by concrete subclasses, which should ensure that the data array 95264790Sbapt * specifies a complete, valid MIDI message. 96264790Sbapt * 97264790Sbapt * @param data an array of bytes containing the complete message. The 98264790Sbapt * message data may be changed using the {@code setMessage} method. 99264790Sbapt * @see #setMessage 100264790Sbapt */ 101264790Sbapt protected MidiMessage(byte[] data) { 102264790Sbapt this.data = data; 103264790Sbapt if (data != null) { 104264790Sbapt this.length = data.length; 105264790Sbapt } 106264790Sbapt } 107264790Sbapt 108264790Sbapt /** 109264790Sbapt * Sets the data for the MIDI message. This protected method is called by 110264790Sbapt * concrete subclasses, which should ensure that the data array specifies a 111264790Sbapt * complete, valid MIDI message. 112264790Sbapt * 113264790Sbapt * @param data the data bytes in the MIDI message 114264790Sbapt * @param length the number of bytes in the data byte array 115264790Sbapt * @throws InvalidMidiDataException if the parameter values do not specify a 116264790Sbapt * valid MIDI meta message 117264790Sbapt */ 118264790Sbapt protected void setMessage(byte[] data, int length) 119264790Sbapt throws InvalidMidiDataException { 120264790Sbapt if (length < 0 || (length > 0 && length > data.length)) { 121264790Sbapt throw new IndexOutOfBoundsException( 122264790Sbapt "length out of bounds: " + length); 123264790Sbapt } 124264790Sbapt this.length = length; 125264790Sbapt 126264790Sbapt if (this.data == null || this.data.length < this.length) { 127264790Sbapt this.data = new byte[this.length]; 128264790Sbapt } 129264790Sbapt System.arraycopy(data, 0, this.data, 0, length); 130264790Sbapt } 131264790Sbapt 132264790Sbapt /** 133264790Sbapt * Obtains the MIDI message data. The first byte of the returned byte array 134264790Sbapt * is the status byte of the message. Any subsequent bytes up to the length 135264790Sbapt * of the message are data bytes. The byte array may have a length which is 136264790Sbapt * greater than that of the actual message; the total length of the message 137264790Sbapt * in bytes is reported by the {@link #getLength} method. 138264790Sbapt * 139264790Sbapt * @return the byte array containing the complete {@code MidiMessage} data 140264790Sbapt */ 141264790Sbapt public byte[] getMessage() { 142264790Sbapt byte[] returnedArray = new byte[length]; 143264790Sbapt System.arraycopy(data, 0, returnedArray, 0, length); 144264790Sbapt return returnedArray; 145264790Sbapt } 146264790Sbapt 147264790Sbapt /** 148264790Sbapt * Obtains the status byte for the MIDI message. The status "byte" is 149264790Sbapt * represented as an integer; see the 150264790Sbapt * <a href="#integersVsBytes">discussion</a> in the {@code MidiMessage} 151264790Sbapt * class description. 152264790Sbapt * 153264790Sbapt * @return the integer representation of this event's status byte 154264790Sbapt */ 155264790Sbapt public int getStatus() { 156264790Sbapt if (length > 0) { 157264790Sbapt return (data[0] & 0xFF); 158264790Sbapt } 159264790Sbapt return 0; 160264790Sbapt } 161264790Sbapt 162264790Sbapt /** 163264790Sbapt * Obtains the total length of the MIDI message in bytes. A MIDI message 164264790Sbapt * consists of one status byte and zero or more data bytes. The return value 165264790Sbapt * ranges from 1 for system real-time messages, to 2 or 3 for channel 166264790Sbapt * messages, to any value for meta and system exclusive messages. 167264790Sbapt * 168264790Sbapt * @return the length of the message in bytes 169264790Sbapt */ 170264790Sbapt public int getLength() { 171264790Sbapt return length; 172264790Sbapt } 173264790Sbapt 174264790Sbapt /** 175264790Sbapt * Creates a new object of the same class and with the same contents as this 176264790Sbapt * object. 177264790Sbapt * 178264790Sbapt * @return a clone of this instance 179264790Sbapt */ 180264790Sbapt public abstract Object clone(); 181264790Sbapt} 182264790Sbapt