jdk-sandbox: comparison jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java

equal deleted inserted replaced

-:e9b05e933ddd
+:508779ce6619
 * questions.
 */
 package javax.sound.midi;
-import java.util.Vector;
 import java.util.ArrayList;
 import java.util.HashSet;
 import com.sun.media.sound.MidiUtils;
 /**
-* A MIDI track is an independent stream of MIDI events (time-stamped MIDI
+* A MIDI track is an independent stream of MIDI events (time-stamped MIDI data)
-* data) that can be stored along with other tracks in a standard MIDI file.
+* that can be stored along with other tracks in a standard MIDI file. The MIDI
-* The MIDI specification allows only 16 channels of MIDI data, but tracks
+* specification allows only 16 channels of MIDI data, but tracks are a way to
-* are a way to get around this limitation.  A MIDI file can contain any number
+* get around this limitation. A MIDI file can contain any number of tracks,
-* of tracks, each containing its own stream of up to 16 channels of MIDI data.
+* each containing its own stream of up to 16 channels of MIDI data.
 * <p>
-* A <code>Track</code> occupies a middle level in the hierarchy of data played
+* A {@code Track} occupies a middle level in the hierarchy of data played by a
-* by a <code>{@link Sequencer}</code>: sequencers play sequences, which contain tracks,
+* {@link Sequencer}: sequencers play sequences, which contain tracks, which
-* which contain MIDI events.  A sequencer may provide controls that mute
+* contain MIDI events. A sequencer may provide controls that mute or solo
-* or solo individual tracks.
+* individual tracks.
 * <p>
 * The timing information and resolution for a track is controlled by and stored
-* in the sequence containing the track. A given <code>Track</code>
+* in the sequence containing the track. A given {@code Track} is considered to
-* is considered to belong to the particular <code>{@link Sequence}</code> that
+* belong to the particular {@link Sequence} that maintains its timing. For this
-* maintains its timing. For this reason, a new (empty) track is created by calling the
+* reason, a new (empty) track is created by calling the
-* <code>{@link Sequence#createTrack}</code> method, rather than by directly invoking a
+* {@link Sequence#createTrack} method, rather than by directly invoking a
-* <code>Track</code> constructor.
+* {@code Track} constructor.
 * <p>
-* The <code>Track</code> class provides methods to edit the track by adding
+* The {@code Track} class provides methods to edit the track by adding or
-* or removing <code>MidiEvent</code> objects from it.  These operations keep
+* removing {@code MidiEvent} objects from it. These operations keep the event
-* the event list in the correct time order.  Methods are also
+* list in the correct time order. Methods are also included to obtain the
-* included to obtain the track's size, in terms of either the number of events
+* track's size, in terms of either the number of events it contains or its
-* it contains or its duration in ticks.
+* duration in ticks.
 *
+* @author Kara Kytle
+* @author Florian Bomers
 * @see Sequencer#setTrackMute
 * @see Sequencer#setTrackSolo
-*
-* @author Kara Kytle
-* @author Florian Bomers
 */
 public class Track {
 // TODO: use arrays for faster access
 // use a hashset to detect duplicate events in add(MidiEvent)
 private HashSet<MidiEvent> set = new HashSet<>();
 private MidiEvent eotEvent;
+/**
-/**
+* Package-private constructor. Constructs a new, empty Track object, which
-* Package-private constructor.  Constructs a new, empty Track object,
+* initially contains one event, the meta-event End of Track.
-* which initially contains one event, the meta-event End of Track.
 */
 Track() {
 // start with the end of track event
 MetaMessage eot = new ImmutableEndOfTrack();
 eotEvent = new MidiEvent(eot, 0);
 eventsList.add(eotEvent);
 set.add(eotEvent);
 }
 /**
-* Adds a new event to the track.  However, if the event is already
+* Adds a new event to the track. However, if the event is already contained
-* contained in the track, it is not added again.  The list of events
+* in the track, it is not added again. The list of events is kept in time
-* is kept in time order, meaning that this event inserted at the
+* order, meaning that this event inserted at the appropriate place in the
-* appropriate place in the list, not necessarily at the end.
+* list, not necessarily at the end.
 *
-* @param event the event to add
+* @param  event the event to add
-* @return <code>true</code> if the event did not already exist in the
+* @return {@code true} if the event did not already exist in the track and
-* track and was added, otherwise <code>false</code>
+*         was added, otherwise {@code false}
 */
 public boolean add(MidiEvent event) {
 if (event == null) {
 return false;
 }
 }
 return false;
 }
 /**
 * Removes the specified event from the track.
-* @param event the event to remove
+*
-* @return <code>true</code> if the event existed in the track and was removed,
+* @param  event the event to remove
-* otherwise <code>false</code>
+* @return {@code true} if the event existed in the track and was removed,
+*         otherwise {@code false}
 */
 public boolean remove(MidiEvent event) {
 // this implementation allows removing the EOT event.
 // pretty bad, but would probably be too risky to
 }
 }
 return false;
 }
 /**
 * Obtains the event at the specified index.
-* @param index the location of the desired event in the event vector
+*
-* @throws ArrayIndexOutOfBoundsException  if the
+* @param  index the location of the desired event in the event vector
-* specified index is negative or not less than the current size of
+* @return the event at the specified index
-* this track.
+* @throws ArrayIndexOutOfBoundsException if the specified index is negative
+*         or not less than the current size of this track
 * @see #size
-* @return the event at the specified index
 */
 public MidiEvent get(int index) throws ArrayIndexOutOfBoundsException {
 try {
 synchronized(eventsList) {
 return eventsList.get(index);
 } catch (IndexOutOfBoundsException ioobe) {
 throw new ArrayIndexOutOfBoundsException(ioobe.getMessage());
 }
 }
 /**
 * Obtains the number of events in this track.
+*
 * @return the size of the track's event vector
 */
 public int size() {
 synchronized(eventsList) {
 return eventsList.size();
 }
 }
+/**
-/**
+* Obtains the length of the track, expressed in MIDI ticks. (The duration
-* Obtains the length of the track, expressed in MIDI ticks.  (The
+* of a tick in seconds is determined by the timing resolution of the
-* duration of a tick in seconds is determined by the timing resolution
+* {@code Sequence} containing this track, and also by the tempo of the
-* of the <code>Sequence</code> containing this track, and also by
+* music as set by the sequencer.)
-* the tempo of the music as set by the sequencer.)
+*
 * @return the duration, in ticks
 * @see Sequence#Sequence(float, int)
 * @see Sequencer#setTempoInBPM(float)
 * @see Sequencer#getTickPosition()
 */
 public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException {
 throw new InvalidMidiDataException("cannot modify end of track message");
 }
 }
 }

changeset 26037	508779ce6619
parent 26003	d630c97424bd
parent 25859	3317bb8137f4
child 40444	afabcfc2f3ef