Back to index...

	/*
	* 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
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	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
	* 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>
	* The base <code>MidiMessage</code> class provides access to three types of
	* information about a MIDI message:
	* <ul>
	* <li>The messages's status byte</li>
	* <li>The total length of the message in bytes (the status byte plus any data bytes)</li>
	* <li>A byte array containing the complete message</li>
	* </ul>
	*
	* <code>MidiMessage</code> 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:
	* <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
	* as the first argument to ShortMessage's
	* {@link ShortMessage#setMessage(int) setMessage(int)}
	* method, you can express it as 254 or 0xFE.
	*
	* @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.
	* @see #getLength
	*/
	protected byte[] data;


	/**
	* 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.
	*
	* @param data an array of bytes containing the complete message.
	* The message data may be changed using the <code>setMessage</code>
	* method.
	*
	* @see #setMessage
	*/
	protected MidiMessage(byte[] data) {
	this.data = data;
	if (data != null) {
	this.length = data.length;
	}
	}


	/**
	* 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
	*/
	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);
	}
	this.length = length;

	if (this.data == null \|\| this.data.length < this.length) {
	this.data = new byte[this.length];
	}
	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.
	*
	* @return the byte array containing the complete <code>MidiMessage</code> data
	*/
	public byte[] getMessage() {
	byte[] returnedArray = new byte[length];
	System.arraycopy(data, 0, returnedArray, 0, length);
	return returnedArray;
	}


	/**
	* 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.
	*
	* @return the integer representation of this event's status byte
	*/
	public int getStatus() {
	if (length > 0) {
	return (data[0] & 0xFF);
	}
	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.
	*
	* @return the length of the message in bytes
	*/
	public int getLength() {
	return length;
	}


	/**
	* 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();
	}

Back to index...