--- old/src/share/classes/javax/sound/midi/SysexMessage.java 2014-07-16 20:39:31.562299100 +0400 +++ new/src/share/classes/javax/sound/midi/SysexMessage.java 2014-07-16 20:39:31.391289300 +0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,47 +26,47 @@ package javax.sound.midi; /** - * A SysexMessage object represents a MIDI system exclusive message. + * A {@code 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. + * 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 {@code 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 + * {@code 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: + * As dictated by the Standard MIDI Files specification, two status byte values + * are legal for a {@code SysexMessage} read from a MIDI file: *

- *

- * 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 + * 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 + * {@code 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. *

- * 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. + * The first {@code 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 {@code SysexMessages} with a status value of 0xF7. The + * {@code 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. + * If system exclusive data from {@code 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 + * {@code SysexMessage} contains continuing system exclusive data should not be + * propagated via MIDI wire protocol. * * @author David Rivas * @author Kara Kytle @@ -74,43 +74,36 @@ */ public class SysexMessage extends MidiMessage { - // Status byte defines - /** * Status byte for System Exclusive message (0xF0, or 240). + * * @see MidiMessage#getStatus */ public static final int SYSTEM_EXCLUSIVE = 0xF0; // 240 - /** - * 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. + * 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. + * * @see MidiMessage#getStatus */ public static final int SPECIAL_SYSTEM_EXCLUSIVE = 0xF7; // 247 - - // Instance variables - - - /* - * The data bytes for this system exclusive message. These are - * initialized to null and are set explicitly - * by {@link #setMessage(int, byte[], int, long) setMessage}. + /** + * The data bytes for this system exclusive message. These are initialized + * to {@code null} and are set explicitly by + * {@link #setMessage(int, byte[], int, long) setMessage}. */ //protected byte[] data = null; - /** - * 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. + * Constructs a new {@code 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 {@code setMessage} methods. + * * @see #setMessage */ public SysexMessage() { @@ -121,18 +114,17 @@ } /** - * Constructs a new {@code SysexMessage} and sets the data for - * the message. The first byte of the data array must be a valid system - * exclusive status byte (0xF0 or 0xF7). - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. - * - * @param data the system exclusive message data including the status byte - * @param length the length of the valid message data in the array, - * including the status byte; it should be non-negative and less than - * or equal to {@code data.length} - * @throws InvalidMidiDataException if the parameter values - * do not specify a valid MIDI meta message. + * Constructs a new {@code SysexMessage} and sets the data for the message. + * The first byte of the data array must be a valid system exclusive status + * byte (0xF0 or 0xF7). The contents of the message can be changed by using + * one of the {@code setMessage} methods. + * + * @param data the system exclusive message data including the status byte + * @param length the length of the valid message data in the array, + * including the status byte; it should be non-negative and less + * than or equal to {@code data.length} + * @throws InvalidMidiDataException if the parameter values do not specify a + * valid MIDI meta message. * @see #setMessage(byte[], int) * @see #setMessage(int, byte[], int) * @see #getData() @@ -146,17 +138,17 @@ /** * Constructs a new {@code SysexMessage} and sets the data for the message. - * The contents of the message can be changed by using one of - * the {@code setMessage} methods. + * The contents of the message can be changed by using one of the + * {@code setMessage} methods. * - * @param status the status byte for the message; it must be a valid system - * exclusive status byte (0xF0 or 0xF7) - * @param data the system exclusive message data (without the status byte) - * @param length the length of the valid message data in the array; - * it should be non-negative and less than or equal to - * {@code data.length} - * @throws InvalidMidiDataException if the parameter values - * do not specify a valid MIDI meta message. + * @param status the status byte for the message; it must be a valid system + * exclusive status byte (0xF0 or 0xF7) + * @param data the system exclusive message data (without the status byte) + * @param length the length of the valid message data in the array; it + * should be non-negative and less than or equal to + * {@code data.length} + * @throws InvalidMidiDataException if the parameter values do not specify a + * valid MIDI meta message * @see #setMessage(byte[], int) * @see #setMessage(int, byte[], int) * @see #getData() @@ -168,26 +160,24 @@ setMessage(status, data, length); } - /** - * Constructs a new SysexMessage. - * @param data an array of bytes containing the complete message. - * The message data may be changed using the setMessage - * method. + * Constructs a new {@code SysexMessage}. + * + * @param data an array of bytes containing the complete message. The + * message data may be changed using the {@code setMessage} method. * @see #setMessage */ protected SysexMessage(byte[] data) { super(data); } - /** - * 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). - * @param data the system exclusive message data - * @param length the length of the valid message data in - * the array, including the status byte. + * 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). + * + * @param data the system exclusive message data + * @param length the length of the valid message data in the array, + * including the status byte */ public void setMessage(byte[] data, int length) throws InvalidMidiDataException { int status = (data[0] & 0xFF); @@ -197,14 +187,14 @@ super.setMessage(data, length); } - /** * Sets the data for the system exclusive message. - * @param status the status byte for the message (0xF0 or 0xF7) - * @param data the system exclusive message data - * @param length the length of the valid message data in - * the array - * @throws InvalidMidiDataException if the status byte is invalid for a sysex message + * + * @param status the status byte for the message (0xF0 or 0xF7) + * @param data the system exclusive message data + * @param length the length of the valid message data in the array + * @throws InvalidMidiDataException if the status byte is invalid for a + * sysex message */ public void setMessage(int status, byte[] data, int length) throws InvalidMidiDataException { if ( (status != 0xF0) && (status != 0xF7) ) { @@ -225,11 +215,11 @@ } } - /** - * Obtains a copy of the data for the system exclusive message. - * The returned array of bytes does not include the status byte. - * @return array containing the system exclusive message data. + * Obtains a copy of the data for the system exclusive message. The returned + * array of bytes does not include the status byte. + * + * @return array containing the system exclusive message data */ public byte[] getData() { byte[] returnedArray = new byte[length - 1]; @@ -237,10 +227,10 @@ return returnedArray; } - /** - * Creates a new object of the same class and with the same contents - * as this object. + * Creates a new object of the same class and with the same contents as this + * object. + * * @return a clone of this instance */ public Object clone() {