--- a/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java Mon Aug 18 14:03:21 2014 +0100
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/MidiMessage.java Tue Aug 19 10:32:16 2014 -0700
@@ -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,83 +26,76 @@
package javax.sound.midi;
/**
- * <code>MidiMessage</code> 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
+ * {@code 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
+ * 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
* (<a href = http://www.midi.org>http://www.midi.org</a>).
* <p>
- * The base <code>MidiMessage</code> class provides access to three types of
+ * The base {@code MidiMessage} class provides access to three types of
* information about a MIDI message:
* <ul>
* <li>The messages's status byte</li>
- * <li>The total length of the message in bytes (the status byte plus any data bytes)</li>
+ * <li>The total length of the message in bytes (the status byte plus any data
+ * bytes)</li>
* <li>A byte array containing the complete message</li>
* </ul>
*
- * <code>MidiMessage</code> includes methods to get, but not set, these values.
+ * {@code MidiMessage} includes methods to get, but not set, these values.
* Setting them is a subclass responsibility.
* <p>
- * <a name="integersVsBytes"></a>
- * The MIDI standard expresses MIDI data in bytes. However, because
- * Java<sup>TM</sup> uses signed bytes, the Java Sound API uses integers
- * instead of bytes when expressing MIDI data. For example, the
- * {@link #getStatus()} method of
- * <code>MidiMessage</code> 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:
+ * <a name="integersVsBytes"></a> The MIDI standard expresses MIDI data in
+ * bytes. However, because Java<sup>TM</sup> uses signed bytes, the Java Sound
+ * API uses integers instead of bytes when expressing MIDI data. For example,
+ * the {@link #getStatus()} method of {@code 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:
+ *
* <center>{@code int i = (int)(byte & 0xFF)}</center>
* <p>
- * 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
- * hexadecimal notation. For instance, to pass the "active sensing" status byte
+ * 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
+ * hexadecimal notation. For instance, to pass the "active sensing" status byte
* as the first argument to ShortMessage's
- * {@link ShortMessage#setMessage(int) setMessage(int)}
- * method, you can express it as 254 or 0xFE.
+ * {@link ShortMessage#setMessage(int) setMessage(int)} method, you can express
+ * it as 254 or 0xFE.
*
+ * @author David Rivas
+ * @author Kara Kytle
* @see Track
* @see Sequence
* @see Receiver
- *
- * @author David Rivas
- * @author Kara Kytle
*/
-
public abstract class MidiMessage implements Cloneable {
- // Instance variables
-
/**
- * 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.
+ * 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 #getLength
*/
protected byte[] data;
-
/**
- * The number of bytes in the MIDI message, including the
- * status byte and any data bytes.
+ * The number of bytes in the MIDI message, including the status byte and
+ * any data bytes.
+ *
* @see #getLength
*/
protected int length = 0;
-
/**
- * Constructs a new <code>MidiMessage</code>. This protected
- * constructor is called by concrete subclasses, which should
- * ensure that the data array specifies a complete, valid MIDI
- * message.
+ * Constructs a new {@code MidiMessage}. This protected constructor is
+ * called by concrete subclasses, which should ensure that the data array
+ * specifies a complete, valid MIDI message.
*
- * @param data an array of bytes containing the complete message.
- * The message data may be changed using the <code>setMessage</code>
- * method.
- *
+ * @param data an array of bytes containing the complete message. The
+ * message data may be changed using the {@code setMessage} method.
* @see #setMessage
*/
protected MidiMessage(byte[] data) {
@@ -112,20 +105,21 @@
}
}
-
/**
- * 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.
+ * 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.
*
- * @param data the data bytes in the MIDI message
- * @param length the number of bytes in the data byte array
- * @throws InvalidMidiDataException if the parameter values do not specify a valid MIDI meta message
+ * @param data the data bytes in the MIDI message
+ * @param length the number of bytes in the data byte array
+ * @throws InvalidMidiDataException if the parameter values do not specify a
+ * valid MIDI meta message
*/
- protected void setMessage(byte[] data, int length) throws InvalidMidiDataException {
+ protected void setMessage(byte[] data, int length)
+ throws InvalidMidiDataException {
if (length < 0 || (length > 0 && length > data.length)) {
- throw new IndexOutOfBoundsException("length out of bounds: "+length);
+ throw new IndexOutOfBoundsException(
+ "length out of bounds: " + length);
}
this.length = length;
@@ -135,16 +129,14 @@
System.arraycopy(data, 0, this.data, 0, length);
}
-
/**
- * 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 <code>{@link #getLength}</code>
- * method.
+ * 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 {@link #getLength} method.
*
- * @return the byte array containing the complete <code>MidiMessage</code> data
+ * @return the byte array containing the complete {@code MidiMessage} data
*/
public byte[] getMessage() {
byte[] returnedArray = new byte[length];
@@ -152,12 +144,11 @@
return returnedArray;
}
-
/**
- * Obtains the status byte for the MIDI message. The status "byte" is
+ * Obtains the status byte for the MIDI message. The status "byte" is
* represented as an integer; see the
- * <a href="#integersVsBytes">discussion</a> in the
- * <code>MidiMessage</code> class description.
+ * <a href="#integersVsBytes">discussion</a> in the {@code MidiMessage}
+ * class description.
*
* @return the integer representation of this event's status byte
*/
@@ -168,13 +159,11 @@
return 0;
}
-
/**
- * 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.
+ * 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.
*
* @return the length of the message in bytes
*/
@@ -182,11 +171,11 @@
return length;
}
-
/**
- * Creates a new object of the same class and with the same contents
- * as this object.
- * @return a clone of this instance.
+ * Creates a new object of the same class and with the same contents as this
+ * object.
+ *
+ * @return a clone of this instance
*/
public abstract Object clone();
}