javax.sound.midi: public class: SysexMessage

javax.sound.midi
public class: SysexMessage [javadoc | source]

java.lang.Object
   javax.sound.midi.MidiMessage
      javax.sound.midi.SysexMessage

All Implemented Interfaces:
Cloneable

A SysexMessage object represents a MIDI system exclusive message.

When a system exclusive message is read from a MIDI file, it always has a defined length. Data from a system exclusive message from a MIDI file should be stored in the data array of a SysexMessage as follows: the system exclusive message status byte (0xF0 or 0xF7), all message data bytes, and finally the end-of-exclusive flag (0xF7). The length reported by the SysexMessage object is therefore the length of the system exclusive data plus two: one byte for the status byte and one for the end-of-exclusive flag.

As dictated by the Standard MIDI Files specification, two status byte values are legal for a SysexMessage read from a MIDI file:

0xF0: System Exclusive message (same as in MIDI wire protocol)
0xF7: Special System Exclusive message

When Java Sound is used to handle system exclusive data that is being received using MIDI wire protocol, it should place the data in one or more SysexMessages. In this case, the length of the system exclusive data is not known in advance; the end of the system exclusive data is marked by an end-of-exclusive flag (0xF7) in the MIDI wire byte stream.

0xF0: System Exclusive message (same as in MIDI wire protocol)
0xF7: End of Exclusive (EOX)

The first SysexMessage object containing data for a particular system exclusive message should have the status value 0xF0. If this message contains all the system exclusive data for the message, it should end with the status byte 0xF7 (EOX). Otherwise, additional system exclusive data should be sent in one or more SysexMessages with a status value of 0xF7. The SysexMessage containing the last of the data for the system exclusive message should end with the value 0xF7 (EOX) to mark the end of the system exclusive message.

If system exclusive data from SysexMessages objects is being transmitted using MIDI wire protocol, only the initial 0xF0 status byte, the system exclusive data itself, and the final 0xF7 (EOX) byte should be propagated; any 0xF7 status bytes used to indicate that a SysexMessage contains continuing system exclusive data should not be propagated via MIDI wire protocol.

author: David - Rivas

author: Kara - Kytle

author: Florian - Bomers

Field Summary
public static final int	SYSTEM_EXCLUSIVE	Status byte for System Exclusive message (0xF0, or 240). Also see: MidiMessage#getStatus
public static final int	SPECIAL_SYSTEM_EXCLUSIVE	Status byte for Special System Exclusive message (0xF7, or 247), which is used in MIDI files. It has the same value as END_OF_EXCLUSIVE, which is used in the real-time "MIDI wire" protocol. Also see: MidiMessage#getStatus

Fields inherited from javax.sound.midi.MidiMessage:
data, length

Constructor:

Constructor:
public SysexMessage() { // 247 // Instance variables /* * The data bytes for this system exclusive message. These are * initialized to < code >null< /code > and are set explicitly * by {@link #setMessage(int, byte[], int, long) setMessage}. / //protected byte[] data = null; this(new byte[2]); // Default sysex message data: SOX followed by EOX data[0] = (byte) (SYSTEM_EXCLUSIVE & 0xFF); data[1] = (byte) (ShortMessage.END_OF_EXCLUSIVE & 0xFF); } Constructs a new `SysexMessage`. The contents of the new message are guaranteed to specify a valid MIDI message. Subsequently, you may set the contents of the message using one of the `setMessage` methods. Also see:* setMessage
protected SysexMessage(byte[] data) { super(data); } Constructs a new `SysexMessage`. Parameters: `data` - an array of bytes containing the complete message. The message data may be changed using the `setMessage` method. Also see: setMessage

 public SysexMessage() {
 // 247
    // Instance variables
    /*
     * The data bytes for this system exclusive message.  These are
     * initialized to < code >null< /code > and are set explicitly
     * by {@link #setMessage(int, byte[], int, long) setMessage}.
     */
    //protected byte[] data = null;
        this(new byte[2]);
        // Default sysex message data: SOX followed by EOX
        data[0] = (byte) (SYSTEM_EXCLUSIVE & 0xFF);
        data[1] = (byte) (ShortMessage.END_OF_EXCLUSIVE & 0xFF);
}

Constructs a new SysexMessage. The contents of the new message are guaranteed to specify a valid MIDI message. Subsequently, you may set the contents of the message using one of the setMessage methods.

Also see:

setMessage

 protected SysexMessage(byte[] data) {
        super(data);
}

Constructs a new SysexMessage.

Parameters:

data - an array of bytes containing the complete message. The message data may be changed using the setMessage method.

Also see:

setMessage

Method from javax.sound.midi.SysexMessage Summary:
clone, getData, setMessage, setMessage

Methods from javax.sound.midi.MidiMessage:
clone, getLength, getMessage, getStatus, setMessage

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from javax.sound.midi.SysexMessage Detail:
public Object clone() { byte[] newData = new byte[length]; System.arraycopy(data, 0, newData, 0, newData.length); SysexMessage event = new SysexMessage(newData); return event; } Creates a new object of the same class and with the same contents as this object.
public byte[] getData() { byte[] returnedArray = new byte[length - 1]; System.arraycopy(data, 1, returnedArray, 0, (length - 1)); return returnedArray; } Obtains a copy of the data for the system exclusive message. The returned array of bytes does not include the status byte.
public void setMessage(byte[] data, int length) throws InvalidMidiDataException { int status = (data[0] & 0xFF); if ((status != 0xF0) && (status != 0xF7)) { throw new InvalidMidiDataException("Invalid status byte for sysex message: 0x" + Integer.toHexString(status)); } super.setMessage(data, length); } Sets the data for the system exclusive message. The first byte of the data array must be a valid system exclusive status byte (0xF0 or 0xF7).
public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException { if ( (status != 0xF0) && (status != 0xF7) ) { throw new InvalidMidiDataException("Invalid status byte for sysex message: 0x" + Integer.toHexString(status)); } if (length < 0 \|\| length > data.length) { throw new IndexOutOfBoundsException("length out of bounds: "+length); } this.length = length + 1; if (this.data==null \|\| this.data.length < this.length) { this.data = new byte[this.length]; } this.data[0] = (byte) (status & 0xFF); if (length > 0) { System.arraycopy(data, 0, this.data, 1, length); } } Sets the data for the system exclusive message.

Method from javax.sound.midi.SysexMessage Detail:

 public Object clone() {
        byte[] newData = new byte[length];
        System.arraycopy(data, 0, newData, 0, newData.length);
        SysexMessage event = new SysexMessage(newData);
        return event;
}

Creates a new object of the same class and with the same contents as this object.

 public byte[] getData() {
        byte[] returnedArray = new byte[length - 1];
        System.arraycopy(data, 1, returnedArray, 0, (length - 1));
        return returnedArray;
}

Obtains a copy of the data for the system exclusive message. The returned array of bytes does not include the status byte.

 public  void setMessage(byte[] data,
    int length) throws InvalidMidiDataException {
        int status = (data[0] & 0xFF);
        if ((status != 0xF0) && (status != 0xF7)) {
            throw new InvalidMidiDataException("Invalid status byte for sysex message: 0x" + Integer.toHexString(status));
        }
        super.setMessage(data, length);
}

Sets the data for the system exclusive message. The first byte of the data array must be a valid system exclusive status byte (0xF0 or 0xF7).

 public  void setMessage(int status,
    byte[] data,
    int length) throws InvalidMidiDataException {
        if ( (status != 0xF0) && (status != 0xF7) ) {
            throw new InvalidMidiDataException("Invalid status byte for sysex message: 0x" + Integer.toHexString(status));
        }
        if (length <  0 || length  > data.length) {
            throw new IndexOutOfBoundsException("length out of bounds: "+length);
        }
        this.length = length + 1;
        if (this.data==null || this.data.length <  this.length) {
            this.data = new byte[this.length];
        }
        this.data[0] = (byte) (status & 0xFF);
        if (length  > 0) {
            System.arraycopy(data, 0, this.data, 1, length);
        }
}

Sets the data for the system exclusive message.