001 /*
002 * Copyright 1998-2002 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.sound.midi;
027
028 /**
029 * <code>MidiMessage</code> is the base class for MIDI messages. They include
030 * not only the standard MIDI messages that a synthesizer can respond to, but also
031 * "meta-events" that can be used by sequencer programs. There are meta-events
032 * for such information as lyrics, copyrights, tempo indications, time and key
033 * signatures, markers, etc. For more information, see the Standard MIDI Files 1.0
034 * specification, which is part of the Complete MIDI 1.0 Detailed Specification
035 * published by the MIDI Manufacturer's Association
036 * (<a href = http://www.midi.org>http://www.midi.org</a>).
037 * <p>
038 * The base <code>MidiMessage</code> class provides access to three types of
039 * information about a MIDI message:
040 * <ul>
041 * <li>The messages's status byte</li>
042 * <li>The total length of the message in bytes (the status byte plus any data bytes)</li>
043 * <li>A byte array containing the complete message</li>
044 * </ul>
045 *
046 * <code>MidiMessage</code> includes methods to get, but not set, these values.
047 * Setting them is a subclass responsibility.
048 * <p>
049 * <a name="integersVsBytes"></a>
050 * The MIDI standard expresses MIDI data in bytes. However, because
051 * Java<sup>TM</sup> uses signed bytes, the Java Sound API uses integers
052 * instead of bytes when expressing MIDI data. For example, the
053 * {@link #getStatus()} method of
054 * <code>MidiMessage</code> returns MIDI status bytes as integers. If you are
055 * processing MIDI data that originated outside Java Sound and now
056 * is encoded as signed bytes, the bytes can
057 * can be converted to integers using this conversion:
058 * <center><code>int i = (int)(byte & 0xFF)</code></center>
059 * <p>
060 * If you simply need to pass a known MIDI byte value as a method parameter,
061 * it can be expressed directly as an integer, using (for example) decimal or
062 * hexidecimal notation. For instance, to pass the "active sensing" status byte
063 * as the first argument to ShortMessage's
064 * {@link ShortMessage#setMessage(int) setMessage(int)}
065 * method, you can express it as 254 or 0xFE.
066 *
067 * @see Track
068 * @see Sequence
069 * @see Receiver
070 *
071 * @version 1.36, 07/05/05
072 * @author David Rivas
073 * @author Kara Kytle
074 */
075
076 public abstract class MidiMessage implements Cloneable {
077
078 // Instance variables
079
080 /**
081 * The MIDI message data. The first byte is the status
082 * byte for the message; subsequent bytes up to the length
083 * of the message are data bytes for this message.
084 * @see #getLength
085 */
086 protected byte[] data;
087
088 /**
089 * The number of bytes in the MIDI message, including the
090 * status byte and any data bytes.
091 * @see #getLength
092 */
093 protected int length = 0;
094
095 /**
096 * Constructs a new <code>MidiMessage</code>. This protected
097 * constructor is called by concrete subclasses, which should
098 * ensure that the data array specifies a complete, valid MIDI
099 * message.
100 *
101 * @param data an array of bytes containing the complete message.
102 * The message data may be changed using the <code>setMessage</code>
103 * method.
104 *
105 * @see #setMessage
106 */
107 protected MidiMessage(byte[] data) {
108 this .data = data;
109 if (data != null) {
110 this .length = data.length;
111 }
112 }
113
114 /**
115 * Sets the data for the MIDI message. This protected
116 * method is called by concrete subclasses, which should
117 * ensure that the data array specifies a complete, valid MIDI
118 * message.
119 */
120 protected void setMessage(byte[] data, int length)
121 throws InvalidMidiDataException {
122 if (length < 0 || (length > 0 && length > data.length)) {
123 throw new IndexOutOfBoundsException(
124 "length out of bounds: " + length);
125 }
126 this .length = length;
127
128 if (this .data == null || this .data.length < this .length) {
129 this .data = new byte[this .length];
130 }
131 System.arraycopy(data, 0, this .data, 0, length);
132 }
133
134 /**
135 * Obtains the MIDI message data. The first byte of the returned byte
136 * array is the status byte of the message. Any subsequent bytes up to
137 * the length of the message are data bytes. The byte array may have a
138 * length which is greater than that of the actual message; the total
139 * length of the message in bytes is reported by the <code>{@link #getLength}</code>
140 * method.
141 *
142 * @return the byte array containing the complete <code>MidiMessage</code> data
143 */
144 public byte[] getMessage() {
145 byte[] returnedArray = new byte[length];
146 System.arraycopy(data, 0, returnedArray, 0, length);
147 return returnedArray;
148 }
149
150 /**
151 * Obtains the status byte for the MIDI message. The status "byte" is
152 * represented as an integer; see the
153 * <a href="#integersVsBytes">discussion</a> in the
154 * <code>MidiMessage</code> class description.
155 *
156 * @return the integer representation of this event's status byte
157 */
158 public int getStatus() {
159 if (length > 0) {
160 return (data[0] & 0xFF);
161 }
162 return 0;
163 }
164
165 /**
166 * Obtains the total length of the MIDI message in bytes. A
167 * MIDI message consists of one status byte and zero or more
168 * data bytes. The return value ranges from 1 for system real-time messages,
169 * to 2 or 3 for channel messages, to any value for meta and system
170 * exclusive messages.
171 *
172 * @return the length of the message in bytes
173 */
174 public int getLength() {
175 return length;
176 }
177
178 /**
179 * Creates a new object of the same class and with the same contents
180 * as this object.
181 * @return a clone of this instance.
182 */
183 public abstract Object clone();
184 }
|