--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.desktop/share/classes/javax/sound/midi/Track.java Sun Aug 17 15:54:13 2014 +0100
@@ -0,0 +1,275 @@
+/*
+ * Copyright (c) 1999, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * 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
+ * data) that can be stored along with other tracks in a standard MIDI file.
+ * The MIDI specification allows only 16 channels of MIDI data, but tracks
+ * are a way to get around this limitation. A MIDI file can contain any number
+ * of tracks, 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
+ * by a <code>{@link Sequencer}</code>: sequencers play sequences, which contain tracks,
+ * which contain MIDI events. A sequencer may provide controls that mute
+ * or solo 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>
+ * is considered to belong to the particular <code>{@link Sequence}</code> that
+ * maintains its timing. For this reason, a new (empty) track is created by calling the
+ * <code>{@link Sequence#createTrack}</code> method, rather than by directly invoking a
+ * <code>Track</code> constructor.
+ * <p>
+ * The <code>Track</code> class provides methods to edit the track by adding
+ * or removing <code>MidiEvent</code> objects from it. These operations keep
+ * the event list in the correct time order. Methods are also
+ * included to obtain the track's size, in terms of either the number of events
+ * it contains or its duration in ticks.
+ *
+ * @see Sequencer#setTrackMute
+ * @see Sequencer#setTrackSolo
+ *
+ * @author Kara Kytle
+ * @author Florian Bomers
+ */
+public class Track {
+
+ // TODO: use arrays for faster access
+
+ // the list containing the events
+ private ArrayList<MidiEvent> eventsList = new ArrayList<>();
+
+ // 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 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
+ * contained in the track, it is not added again. The list of events
+ * is kept in time order, meaning that this event inserted at the
+ * appropriate place in the list, not necessarily at the end.
+ *
+ * @param event the event to add
+ * @return <code>true</code> if the event did not already exist in the
+ * track and was added, otherwise <code>false</code>
+ */
+ public boolean add(MidiEvent event) {
+ if (event == null) {
+ return false;
+ }
+ synchronized(eventsList) {
+
+ if (!set.contains(event)) {
+ int eventsCount = eventsList.size();
+
+ // get the last event
+ MidiEvent lastEvent = null;
+ if (eventsCount > 0) {
+ lastEvent = eventsList.get(eventsCount - 1);
+ }
+ // sanity check that we have a correct end-of-track
+ if (lastEvent != eotEvent) {
+ // if there is no eot event, add our immutable instance again
+ if (lastEvent != null) {
+ // set eotEvent's tick to the last tick of the track
+ eotEvent.setTick(lastEvent.getTick());
+ } else {
+ // if the events list is empty, just set the tick to 0
+ eotEvent.setTick(0);
+ }
+ // we needn't check for a duplicate of eotEvent in "eventsList",
+ // since then it would appear in the set.
+ eventsList.add(eotEvent);
+ set.add(eotEvent);
+ eventsCount = eventsList.size();
+ }
+
+ // first see if we are trying to add
+ // and endoftrack event.
+ if (MidiUtils.isMetaEndOfTrack(event.getMessage())) {
+ // since end of track event is useful
+ // for delays at the end of a track, we want to keep
+ // the tick value requested here if it is greater
+ // than the one on the eot we are maintaining.
+ // Otherwise, we only want a single eot event, so ignore.
+ if (event.getTick() > eotEvent.getTick()) {
+ eotEvent.setTick(event.getTick());
+ }
+ return true;
+ }
+
+ // prevent duplicates
+ set.add(event);
+
+ // insert event such that events is sorted in increasing
+ // tick order
+ int i = eventsCount;
+ for ( ; i > 0; i--) {
+ if (event.getTick() >= (eventsList.get(i-1)).getTick()) {
+ break;
+ }
+ }
+ if (i == eventsCount) {
+ // we're adding an event after the
+ // tick value of our eot, so push the eot out.
+ // Always add at the end for better performance:
+ // this saves all the checks and arraycopy when inserting
+
+ // overwrite eot with new event
+ eventsList.set(eventsCount - 1, event);
+ // set new time of eot, if necessary
+ if (eotEvent.getTick() < event.getTick()) {
+ eotEvent.setTick(event.getTick());
+ }
+ // add eot again at the end
+ eventsList.add(eotEvent);
+ } else {
+ eventsList.add(i, event);
+ }
+ return true;
+ }
+ }
+
+ 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,
+ * otherwise <code>false</code>
+ */
+ public boolean remove(MidiEvent event) {
+
+ // this implementation allows removing the EOT event.
+ // pretty bad, but would probably be too risky to
+ // change behavior now, in case someone does tricks like:
+ //
+ // while (track.size() > 0) track.remove(track.get(track.size() - 1));
+
+ // also, would it make sense to adjust the EOT's time
+ // to the last event, if the last non-EOT event is removed?
+ // Or: document that the ticks() length will not be reduced
+ // by deleting events (unless the EOT event is removed)
+ synchronized(eventsList) {
+ if (set.remove(event)) {
+ int i = eventsList.indexOf(event);
+ if (i >= 0) {
+ eventsList.remove(i);
+ return true;
+ }
+ }
+ }
+ 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
+ * 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 of a tick in seconds is determined by the timing resolution
+ * of the <code>Sequence</code> containing this track, and also by
+ * 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 long ticks() {
+ long ret = 0;
+ synchronized (eventsList) {
+ if (eventsList.size() > 0) {
+ ret = (eventsList.get(eventsList.size() - 1)).getTick();
+ }
+ }
+ return ret;
+ }
+
+ private static class ImmutableEndOfTrack extends MetaMessage {
+ private ImmutableEndOfTrack() {
+ super(new byte[3]);
+ data[0] = (byte) META;
+ data[1] = MidiUtils.META_END_OF_TRACK_TYPE;
+ data[2] = 0;
+ }
+
+ public void setMessage(int type, byte[] data, int length) throws InvalidMidiDataException {
+ throw new InvalidMidiDataException("cannot modify end of track message");
+ }
+ }
+
+}