KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > sound > midi > MidiMessage


1 /*
2  * @(#)MidiMessage.java 1.29 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.sound.midi;
9
10 /**
11  * <code>MidiMessage</code> is the base class for MIDI messages. They include
12  * not only the standard MIDI messages that a synthesizer can respond to, but also
13  * "meta-events" that can be used by sequencer programs. There are meta-events
14  * for such information as lyrics, copyrights, tempo indications, time and key
15  * signatures, markers, etc. For more information, see the Standard MIDI Files 1.0
16  * specification, which is part of the Complete MIDI 1.0 Detailed Specification
17  * published by the MIDI Manufacturer's Association
18  * (<a href = http://www.midi.org>http://www.midi.org</a>).
19  * <p>
20  * The base <code>MidiMessage</code> class provides access to three types of
21  * information about a MIDI message:
22  * <ul>
23  * <li>The messages's status byte</li>
24  * <li>The total length of the message in bytes (the status byte plus any data bytes)</li>
25  * <li>A byte array containing the complete message</li>
26  * </ul>
27  *
28  * <code>MidiMessage</code> includes methods to get, but not set, these values.
29  * Setting them is a subclass responsibility.
30  * <p>
31  * <a name="integersVsBytes"></a>
32  * The MIDI standard expresses MIDI data in bytes. However, because
33  * Java<sup>TM</sup> uses signed bytes, the Java Sound API uses integers
34  * instead of bytes when expressing MIDI data. For example, the
35  * {@link #getStatus()} method of
36  * <code>MidiMessage</code> returns MIDI status bytes as integers. If you are
37  * processing MIDI data that originated outside Java Sound and now
38  * is encoded as signed bytes, the bytes can
39  * can be converted to integers using this conversion:
40  * <center><code>int i = (int)(byte & 0xFF)</code></center>
41  * <p>
42  * If you simply need to pass a known MIDI byte value as a method parameter,
43  * it can be expressed directly as an integer, using (for example) decimal or
44  * hexidecimal notation. For instance, to pass the "active sensing" status byte
45  * as the first argument to ShortMessage's
46  * {@link ShortMessage#setMessage(int) setMessage(int)}
47  * method, you can express it as 254 or 0xFE.
48  *
49  * @see Track
50  * @see Sequence
51  * @see Receiver
52  *
53  * @version 1.29, 03/12/19
54  * @author David Rivas
55  * @author Kara Kytle
56  */
57
58 public abstract class MidiMessage implements Cloneable JavaDoc {
59
60     // Instance variables
61
62     /**
63      * The MIDI message data. The first byte is the status
64      * byte for the message; subsequent bytes up to the length
65      * of the message are data bytes for this message.
66      * @see #getLength
67      */
68     protected byte[] data;
69
70
71     /**
72      * The number of bytes in the MIDI message, including the
73      * status byte and any data bytes.
74      * @see #getLength
75      */
76     protected int length = 0;
77
78
79     /**
80      * Constructs a new <code>MidiMessage</code>. This protected
81      * constructor is called by concrete subclasses, which should
82      * ensure that the data array specifies a complete, valid MIDI
83      * message.
84      *
85      * @param data an array of bytes containing the complete message.
86      * The message data may be changed using the <code>setMessage</code>
87      * method.
88      *
89      * @see #setMessage
90      */
91     protected MidiMessage(byte[] data) {
92     this.data = data;
93     if (data != null) {
94         this.length = data.length;
95     }
96     }
97
98
99     /**
100      * Sets the data for the MIDI message. This protected
101      * method is called by concrete subclasses, which should
102      * ensure that the data array specifies a complete, valid MIDI
103      * message.
104      */
105     protected void setMessage(byte[] data, int length) throws InvalidMidiDataException JavaDoc {
106     if (length < 0 || (length > 0 && length > data.length)) {
107         throw new IndexOutOfBoundsException JavaDoc("length out of bounds: "+length);
108     }
109     this.length = length;
110
111     if (this.data == null || this.data.length < this.length) {
112         this.data = new byte[this.length];
113     }
114     System.arraycopy(data, 0, this.data, 0, length);
115     }
116
117
118     /**
119      * Obtains the MIDI message data. The first byte of the returned byte
120      * array is the status byte of the message. Any subsequent bytes up to
121      * the length of the message are data bytes. The byte array may have a
122      * length which is greater than that of the actual message; the total
123      * length of the message in bytes is reported by the <code>{@link #getLength}</code>
124      * method.
125      *
126      * @return the byte array containing the complete <code>MidiMessage</code> data
127      */
128     public byte[] getMessage() {
129     byte[] returnedArray = new byte[length];
130     System.arraycopy(data, 0, returnedArray, 0, length);
131     return returnedArray;
132     }
133
134
135     /**
136      * Obtains the status byte for the MIDI message. The status "byte" is
137      * represented as an integer; see the
138      * <a HREF="#integersVsBytes">discussion</a> in the
139      * <code>MidiMessage</code> class description.
140      *
141      * @return the integer representation of this event's status byte
142      */
143     public int getStatus() {
144     if (length > 0) {
145         return (data[0] & 0xFF);
146     }
147     return 0;
148     }
149
150
151     /**
152      * Obtains the total length of the MIDI message in bytes. A
153      * MIDI message consists of one status byte and zero or more
154      * data bytes. The return value ranges from 1 for system real-time messages,
155      * to 2 or 3 for channel messages, to any value for meta and system
156      * exclusive messages.
157      *
158      * @return the length of the message in bytes
159      */
160     public int getLength() {
161     return length;
162     }
163
164
165     /**
166      * Creates a new object of the same class and with the same contents
167      * as this object.
168      * @return a clone of this instance.
169      */
170     public abstract Object JavaDoc clone();
171 }
172
Popular Tags