< prev index next >

src/java.desktop/share/classes/javax/sound/midi/SysexMessage.java

Print this page


   1 /*
   2  * Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.sound.midi;
  27 
  28 import com.sun.media.sound.MidiUtils;
  29 
  30 /**
  31  * A {@code SysexMessage} object represents a MIDI system exclusive message.
  32  * <p>
  33  * When a system exclusive message is read from a MIDI file, it always has a
  34  * defined length. Data from a system exclusive message from a MIDI file should
  35  * be stored in the data array of a {@code SysexMessage} as follows: the system
  36  * exclusive message status byte (0xF0 or 0xF7), all message data bytes, and
  37  * finally the end-of-exclusive flag (0xF7). The length reported by the
  38  * {@code SysexMessage} object is therefore the length of the system exclusive
  39  * data plus two: one byte for the status byte and one for the end-of-exclusive
  40  * flag.
  41  * <p>
  42  * As dictated by the Standard MIDI Files specification, two status byte values
  43  * are legal for a {@code SysexMessage} read from a MIDI file:
  44  * <ul>
  45  *   <li>0xF0: System Exclusive message (same as in MIDI wire protocol)
  46  *   <li>0xF7: Special System Exclusive message
  47  * </ul>
  48  * When Java Sound is used to handle system exclusive data that is being
  49  * received using MIDI wire protocol, it should place the data in one or more


 168      * @param  data an array of bytes containing the complete message. The
 169      *         message data may be changed using the {@code setMessage} method.
 170      * @see #setMessage
 171      */
 172     protected SysexMessage(byte[] data) {
 173         super(data);
 174     }
 175 
 176     /**
 177      * Sets the data for the system exclusive message. The first byte of the
 178      * data array must be a valid system exclusive status byte (0xF0 or 0xF7).
 179      *
 180      * @param  data the system exclusive message data
 181      * @param  length the length of the valid message data in the array,
 182      *         including the status byte
 183      * @throws InvalidMidiDataException if the parameter values do not specify a
 184      *         valid MIDI system exclusive message
 185      */
 186     @Override
 187     public void setMessage(byte[] data, int length) throws InvalidMidiDataException {
 188         MidiUtils.checkSysexStatus(data, length);



 189         super.setMessage(data, length);
 190     }
 191 
 192     /**
 193      * Sets the data for the system exclusive message.
 194      *
 195      * @param  status the status byte for the message (0xF0 or 0xF7)
 196      * @param  data the system exclusive message data
 197      * @param  length the length of the valid message data in the array
 198      * @throws InvalidMidiDataException if the status byte is invalid for a
 199      *         system exclusive message
 200      */
 201     public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException {
 202         MidiUtils.checkSysexStatus(status);


 203         if (length < 0 || length > data.length) {
 204             throw new IndexOutOfBoundsException("length out of bounds: "+length);
 205         }
 206         this.length = length + 1;
 207 
 208         if (this.data==null || this.data.length < this.length) {
 209             this.data = new byte[this.length];
 210         }
 211 
 212         this.data[0] = (byte) (status & 0xFF);
 213         if (length > 0) {
 214             System.arraycopy(data, 0, this.data, 1, length);
 215         }
 216     }
 217 
 218     /**
 219      * Obtains a copy of the data for the system exclusive message. The returned
 220      * array of bytes does not include the status byte.
 221      *
 222      * @return array containing the system exclusive message data
   1 /*
   2  * Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.sound.midi;
  27 


  28 /**
  29  * A {@code SysexMessage} object represents a MIDI system exclusive message.
  30  * <p>
  31  * When a system exclusive message is read from a MIDI file, it always has a
  32  * defined length. Data from a system exclusive message from a MIDI file should
  33  * be stored in the data array of a {@code SysexMessage} as follows: the system
  34  * exclusive message status byte (0xF0 or 0xF7), all message data bytes, and
  35  * finally the end-of-exclusive flag (0xF7). The length reported by the
  36  * {@code SysexMessage} object is therefore the length of the system exclusive
  37  * data plus two: one byte for the status byte and one for the end-of-exclusive
  38  * flag.
  39  * <p>
  40  * As dictated by the Standard MIDI Files specification, two status byte values
  41  * are legal for a {@code SysexMessage} read from a MIDI file:
  42  * <ul>
  43  *   <li>0xF0: System Exclusive message (same as in MIDI wire protocol)
  44  *   <li>0xF7: Special System Exclusive message
  45  * </ul>
  46  * When Java Sound is used to handle system exclusive data that is being
  47  * received using MIDI wire protocol, it should place the data in one or more


 166      * @param  data an array of bytes containing the complete message. The
 167      *         message data may be changed using the {@code setMessage} method.
 168      * @see #setMessage
 169      */
 170     protected SysexMessage(byte[] data) {
 171         super(data);
 172     }
 173 
 174     /**
 175      * Sets the data for the system exclusive message. The first byte of the
 176      * data array must be a valid system exclusive status byte (0xF0 or 0xF7).
 177      *
 178      * @param  data the system exclusive message data
 179      * @param  length the length of the valid message data in the array,
 180      *         including the status byte
 181      * @throws InvalidMidiDataException if the parameter values do not specify a
 182      *         valid MIDI system exclusive message
 183      */
 184     @Override
 185     public void setMessage(byte[] data, int length) throws InvalidMidiDataException {
 186         int status = (data[0] & 0xFF);
 187         if ((status != 0xF0) && (status != 0xF7)) {
 188             throw new InvalidMidiDataException("Invalid status byte for sysex message: 0x" + Integer.toHexString(status));
 189         }
 190         super.setMessage(data, length);
 191     }
 192 
 193     /**
 194      * Sets the data for the system exclusive message.
 195      *
 196      * @param  status the status byte for the message (0xF0 or 0xF7)
 197      * @param  data the system exclusive message data
 198      * @param  length the length of the valid message data in the array
 199      * @throws InvalidMidiDataException if the status byte is invalid for a
 200      *         system exclusive message
 201      */
 202     public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException {
 203         if ( (status != 0xF0) && (status != 0xF7) ) {
 204             throw new InvalidMidiDataException("Invalid status byte for sysex message: 0x" + Integer.toHexString(status));
 205         }
 206         if (length < 0 || length > data.length) {
 207             throw new IndexOutOfBoundsException("length out of bounds: "+length);
 208         }
 209         this.length = length + 1;
 210 
 211         if (this.data==null || this.data.length < this.length) {
 212             this.data = new byte[this.length];
 213         }
 214 
 215         this.data[0] = (byte) (status & 0xFF);
 216         if (length > 0) {
 217             System.arraycopy(data, 0, this.data, 1, length);
 218         }
 219     }
 220 
 221     /**
 222      * Obtains a copy of the data for the system exclusive message. The returned
 223      * array of bytes does not include the status byte.
 224      *
 225      * @return array containing the system exclusive message data
< prev index next >