0N/A/*
2362N/A * Copyright (c) 1998, 2002, Oracle and/or its affiliates. All rights reserved.
0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A *
0N/A * This code is free software; you can redistribute it and/or modify it
0N/A * under the terms of the GNU General Public License version 2 only, as
2362N/A * published by the Free Software Foundation. Oracle designates this
0N/A * particular file as subject to the "Classpath" exception as provided
2362N/A * by Oracle in the LICENSE file that accompanied this code.
0N/A *
0N/A * This code is distributed in the hope that it will be useful, but WITHOUT
0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/A * version 2 for more details (a copy is included in the LICENSE file that
0N/A * accompanied this code).
0N/A *
0N/A * You should have received a copy of the GNU General Public License version
0N/A * 2 along with this work; if not, write to the Free Software Foundation,
0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A *
2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2362N/A * or visit www.oracle.com if you need additional information or have any
2362N/A * questions.
0N/A */
0N/A
0N/Apackage javax.sound.midi;
0N/A
0N/A/**
0N/A * <code>MidiMessage</code> is the base class for MIDI messages. They include
0N/A * not only the standard MIDI messages that a synthesizer can respond to, but also
0N/A * "meta-events" that can be used by sequencer programs. There are meta-events
0N/A * for such information as lyrics, copyrights, tempo indications, time and key
0N/A * signatures, markers, etc. For more information, see the Standard MIDI Files 1.0
0N/A * specification, which is part of the Complete MIDI 1.0 Detailed Specification
0N/A * published by the MIDI Manufacturer's Association
0N/A * (<a href = http://www.midi.org>http://www.midi.org</a>).
0N/A * <p>
0N/A * The base <code>MidiMessage</code> class provides access to three types of
0N/A * information about a MIDI message:
0N/A * <ul>
0N/A * <li>The messages's status byte</li>
0N/A * <li>The total length of the message in bytes (the status byte plus any data bytes)</li>
0N/A * <li>A byte array containing the complete message</li>
0N/A * </ul>
0N/A *
0N/A * <code>MidiMessage</code> includes methods to get, but not set, these values.
0N/A * Setting them is a subclass responsibility.
0N/A * <p>
0N/A * <a name="integersVsBytes"></a>
0N/A * The MIDI standard expresses MIDI data in bytes. However, because
0N/A * Java<sup>TM</sup> uses signed bytes, the Java Sound API uses integers
0N/A * instead of bytes when expressing MIDI data. For example, the
0N/A * {@link #getStatus()} method of
0N/A * <code>MidiMessage</code> returns MIDI status bytes as integers. If you are
0N/A * processing MIDI data that originated outside Java Sound and now
0N/A * is encoded as signed bytes, the bytes can
0N/A * can be converted to integers using this conversion:
0N/A * <center><code>int i = (int)(byte & 0xFF)</code></center>
0N/A * <p>
0N/A * If you simply need to pass a known MIDI byte value as a method parameter,
0N/A * it can be expressed directly as an integer, using (for example) decimal or
0N/A * hexidecimal notation. For instance, to pass the "active sensing" status byte
0N/A * as the first argument to ShortMessage's
0N/A * {@link ShortMessage#setMessage(int) setMessage(int)}
0N/A * method, you can express it as 254 or 0xFE.
0N/A *
0N/A * @see Track
0N/A * @see Sequence
0N/A * @see Receiver
0N/A *
0N/A * @author David Rivas
0N/A * @author Kara Kytle
0N/A */
0N/A
0N/Apublic abstract class MidiMessage implements Cloneable {
0N/A
0N/A // Instance variables
0N/A
0N/A /**
0N/A * The MIDI message data. The first byte is the status
0N/A * byte for the message; subsequent bytes up to the length
0N/A * of the message are data bytes for this message.
0N/A * @see #getLength
0N/A */
0N/A protected byte[] data;
0N/A
0N/A
0N/A /**
0N/A * The number of bytes in the MIDI message, including the
0N/A * status byte and any data bytes.
0N/A * @see #getLength
0N/A */
0N/A protected int length = 0;
0N/A
0N/A
0N/A /**
0N/A * Constructs a new <code>MidiMessage</code>. This protected
0N/A * constructor is called by concrete subclasses, which should
0N/A * ensure that the data array specifies a complete, valid MIDI
0N/A * message.
0N/A *
0N/A * @param data an array of bytes containing the complete message.
0N/A * The message data may be changed using the <code>setMessage</code>
0N/A * method.
0N/A *
0N/A * @see #setMessage
0N/A */
0N/A protected MidiMessage(byte[] data) {
0N/A this.data = data;
0N/A if (data != null) {
0N/A this.length = data.length;
0N/A }
0N/A }
0N/A
0N/A
0N/A /**
0N/A * Sets the data for the MIDI message. This protected
0N/A * method is called by concrete subclasses, which should
0N/A * ensure that the data array specifies a complete, valid MIDI
0N/A * message.
0N/A */
0N/A protected void setMessage(byte[] data, int length) throws InvalidMidiDataException {
0N/A if (length < 0 || (length > 0 && length > data.length)) {
0N/A throw new IndexOutOfBoundsException("length out of bounds: "+length);
0N/A }
0N/A this.length = length;
0N/A
0N/A if (this.data == null || this.data.length < this.length) {
0N/A this.data = new byte[this.length];
0N/A }
0N/A System.arraycopy(data, 0, this.data, 0, length);
0N/A }
0N/A
0N/A
0N/A /**
0N/A * Obtains the MIDI message data. The first byte of the returned byte
0N/A * array is the status byte of the message. Any subsequent bytes up to
0N/A * the length of the message are data bytes. The byte array may have a
0N/A * length which is greater than that of the actual message; the total
0N/A * length of the message in bytes is reported by the <code>{@link #getLength}</code>
0N/A * method.
0N/A *
0N/A * @return the byte array containing the complete <code>MidiMessage</code> data
0N/A */
0N/A public byte[] getMessage() {
0N/A byte[] returnedArray = new byte[length];
0N/A System.arraycopy(data, 0, returnedArray, 0, length);
0N/A return returnedArray;
0N/A }
0N/A
0N/A
0N/A /**
0N/A * Obtains the status byte for the MIDI message. The status "byte" is
0N/A * represented as an integer; see the
0N/A * <a href="#integersVsBytes">discussion</a> in the
0N/A * <code>MidiMessage</code> class description.
0N/A *
0N/A * @return the integer representation of this event's status byte
0N/A */
0N/A public int getStatus() {
0N/A if (length > 0) {
0N/A return (data[0] & 0xFF);
0N/A }
0N/A return 0;
0N/A }
0N/A
0N/A
0N/A /**
0N/A * Obtains the total length of the MIDI message in bytes. A
0N/A * MIDI message consists of one status byte and zero or more
0N/A * data bytes. The return value ranges from 1 for system real-time messages,
0N/A * to 2 or 3 for channel messages, to any value for meta and system
0N/A * exclusive messages.
0N/A *
0N/A * @return the length of the message in bytes
0N/A */
0N/A public int getLength() {
0N/A return length;
0N/A }
0N/A
0N/A
0N/A /**
0N/A * Creates a new object of the same class and with the same contents
0N/A * as this object.
0N/A * @return a clone of this instance.
0N/A */
0N/A public abstract Object clone();
0N/A}