/* * Copyright (c) 1998, 2002, 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)</code></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 * hexidecimal 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. */ 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();}
/*
* Copyright (c) 1998, 2002, 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)</code></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
* hexidecimal 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.
*/
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();
}