javax.sound.midi
Class MidiMessage

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by javax.sound.midi.MidiMessage
All Implemented Interfaces:
Cloneable sample code for java.lang.Cloneable definition code for java.lang.Cloneable
Direct Known Subclasses:
MetaMessage sample code for javax.sound.midi.MetaMessage definition code for javax.sound.midi.MetaMessage , ShortMessage sample code for javax.sound.midi.ShortMessage definition code for javax.sound.midi.ShortMessage , SysexMessage sample code for javax.sound.midi.SysexMessage definition code for javax.sound.midi.SysexMessage

public abstract class MidiMessage
extends Object sample code for java.lang.Object definition code for java.lang.Object
implements Cloneable sample code for java.lang.Cloneable definition code for java.lang.Cloneable

MidiMessage 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 (http://www.midi.org).

The base MidiMessage class provides access to three types of information about a MIDI message:

MidiMessage includes methods to get, but not set, these values. Setting them is a subclass responsibility.

The MIDI standard expresses MIDI data in bytes. However, because JavaTM uses signed bytes, the Java Sound API uses integers instead of bytes when expressing MIDI data. For example, the getStatus() sample code for javax.sound.midi.MidiMessage.getStatus() definition code for javax.sound.midi.MidiMessage.getStatus() method of MidiMessage 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:

int i = (int)(byte & 0xFF)

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 setMessage(int) sample code for javax.sound.midi.ShortMessage.setMessage(int) definition code for javax.sound.midi.ShortMessage.setMessage(int) method, you can express it as 254 or 0xFE.

See Also:
Track sample code for javax.sound.midi.Track definition code for javax.sound.midi.Track , Sequence sample code for javax.sound.midi.Sequence definition code for javax.sound.midi.Sequence , Receiver sample code for javax.sound.midi.Receiver definition code for javax.sound.midi.Receiver

Field Summary
protected  byte[] data sample code for javax.sound.midi.MidiMessage.data definition code for javax.sound.midi.MidiMessage.data
          The MIDI message data.
protected  int length sample code for javax.sound.midi.MidiMessage.length definition code for javax.sound.midi.MidiMessage.length
          The number of bytes in the MIDI message, including the status byte and any data bytes.
 
Constructor Summary
protected MidiMessage sample code for javax.sound.midi.MidiMessage.MidiMessage(byte[]) definition code for javax.sound.midi.MidiMessage.MidiMessage(byte[]) (byte[] data)
          Constructs a new MidiMessage.
 
Method Summary
abstract  Object sample code for java.lang.Object definition code for java.lang.Object clone sample code for javax.sound.midi.MidiMessage.clone() definition code for javax.sound.midi.MidiMessage.clone() ()
          Creates a new object of the same class and with the same contents as this object.
 int getLength sample code for javax.sound.midi.MidiMessage.getLength() definition code for javax.sound.midi.MidiMessage.getLength() ()
          Obtains the total length of the MIDI message in bytes.
 byte[] getMessage sample code for javax.sound.midi.MidiMessage.getMessage() definition code for javax.sound.midi.MidiMessage.getMessage() ()
          Obtains the MIDI message data.
 int getStatus sample code for javax.sound.midi.MidiMessage.getStatus() definition code for javax.sound.midi.MidiMessage.getStatus() ()
          Obtains the status byte for the MIDI message.
protected  void setMessage sample code for javax.sound.midi.MidiMessage.setMessage(byte[], int) definition code for javax.sound.midi.MidiMessage.setMessage(byte[], int) (byte[] data, int length)
          Sets the data for the MIDI message.
 
Methods inherited from class java.lang.Object sample code for java.lang.Object definition code for java.lang.Object
equals sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) , finalize sample code for java.lang.Object.finalize() definition code for java.lang.Object.finalize() , getClass sample code for java.lang.Object.getClass() definition code for java.lang.Object.getClass() , hashCode sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode() , notify sample code for java.lang.Object.notify() definition code for java.lang.Object.notify() , notifyAll sample code for java.lang.Object.notifyAll() definition code for java.lang.Object.notifyAll() , toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() , wait sample code for java.lang.Object.wait() definition code for java.lang.Object.wait() , wait sample code for java.lang.Object.wait(long) definition code for java.lang.Object.wait(long) , wait sample code for java.lang.Object.wait(long, int) definition code for java.lang.Object.wait(long, int)
 

Field Detail

data sample code for javax.sound.midi.MidiMessage.data

protected byte[] data
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 Also:
getLength() sample code for javax.sound.midi.MidiMessage.getLength() definition code for javax.sound.midi.MidiMessage.getLength()

length sample code for javax.sound.midi.MidiMessage.length

protected int length
The number of bytes in the MIDI message, including the status byte and any data bytes.

See Also:
getLength() sample code for javax.sound.midi.MidiMessage.getLength() definition code for javax.sound.midi.MidiMessage.getLength()
Constructor Detail

MidiMessage sample code for javax.sound.midi.MidiMessage(byte[]) definition code for javax.sound.midi.MidiMessage(byte[])

protected MidiMessage(byte[] data)
Constructs a new MidiMessage. This protected constructor is called by concrete subclasses, which should ensure that the data array specifies a complete, valid MIDI message.

Parameters:
data - an array of bytes containing the complete message. The message data may be changed using the setMessage method.
See Also:
setMessage(byte[], int) sample code for javax.sound.midi.MidiMessage.setMessage(byte[], int) definition code for javax.sound.midi.MidiMessage.setMessage(byte[], int)
Method Detail

setMessage sample code for javax.sound.midi.MidiMessage.setMessage(byte[], int) definition code for javax.sound.midi.MidiMessage.setMessage(byte[], int)

protected void setMessage(byte[] data,
                          int length)
                   throws InvalidMidiDataException sample code for javax.sound.midi.InvalidMidiDataException definition code for javax.sound.midi.InvalidMidiDataException 
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.

Throws:
InvalidMidiDataException sample code for javax.sound.midi.InvalidMidiDataException definition code for javax.sound.midi.InvalidMidiDataException

getMessage sample code for javax.sound.midi.MidiMessage.getMessage() definition code for javax.sound.midi.MidiMessage.getMessage()

public byte[] getMessage()
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 getLength() sample code for javax.sound.midi.MidiMessage.getLength() definition code for javax.sound.midi.MidiMessage.getLength() method.

Returns:
the byte array containing the complete MidiMessage data

getStatus sample code for javax.sound.midi.MidiMessage.getStatus() definition code for javax.sound.midi.MidiMessage.getStatus()

public int getStatus()
Obtains the status byte for the MIDI message. The status "byte" is represented as an integer; see the discussion in the MidiMessage class description.

Returns:
the integer representation of this event's status byte

getLength sample code for javax.sound.midi.MidiMessage.getLength() definition code for javax.sound.midi.MidiMessage.getLength()

public int getLength()
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.

Returns:
the length of the message in bytes

clone sample code for javax.sound.midi.MidiMessage.clone() definition code for javax.sound.midi.MidiMessage.clone()

public abstract Object sample code for java.lang.Object definition code for java.lang.Object  clone()
Creates a new object of the same class and with the same contents as this object.

Overrides:
clone sample code for java.lang.Object.clone() definition code for java.lang.Object.clone() in class Object sample code for java.lang.Object definition code for java.lang.Object
Returns:
a clone of this instance.
See Also:
Cloneable sample code for java.lang.Cloneable definition code for java.lang.Cloneable