rev 57600 : 8236980: toString() cleanup in JavaSound
Reviewed-by: XXX

   1 /*
   2  * Copyright (c) 1999, 2020, 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 java.io.IOException;
  29 import java.io.InputStream;
  30 
  31 /**
  32  * A hardware or software device that plays back a MIDI
  33  * {@link Sequence sequence} is known as a <em>sequencer</em>. A MIDI sequence
  34  * contains lists of time-stamped MIDI data, such as might be read from a
  35  * standard MIDI file. Most sequencers also provide functions for creating and
  36  * editing sequences.
  37  * <p>
  38  * The {@code Sequencer} interface includes methods for the following basic MIDI
  39  * sequencer operations:
  40  * <ul>
  41  *   <li>obtaining a sequence from MIDI file data
  42  *   <li>starting and stopping playback
  43  *   <li>moving to an arbitrary position in the sequence
  44  *   <li>changing the tempo (speed) of playback
  45  *   <li>synchronizing playback to an internal clock or to received MIDI
  46  *   messages
  47  *   <li>controlling the timing of another device
  48  * </ul>
  49  * In addition, the following operations are supported, either directly, or
  50  * indirectly through objects that the {@code Sequencer} has access to:
  51  * <ul>
  52  *   <li>editing the data by adding or deleting individual MIDI events or entire
  53  *   tracks
  54  *   <li>muting or soloing individual tracks in the sequence
  55  *   <li>notifying listener objects about any meta-events or control-change
  56  *   events encountered while playing back the sequence
  57  * </ul>
  58  *
  59  * @author Kara Kytle
  60  * @author Florian Bomers
  61  * @see SyncMode
  62  * @see #addMetaEventListener
  63  * @see ControllerEventListener
  64  * @see Receiver
  65  * @see Transmitter
  66  * @see MidiDevice
  67  */
  68 public interface Sequencer extends MidiDevice {
  69 
  70     /**
  71      * A value indicating that looping should continue indefinitely rather than
  72      * complete after a specific number of loops.
  73      *
  74      * @see #setLoopCount
  75      * @since 1.5
  76      */
  77     int LOOP_CONTINUOUSLY = -1;
  78 
  79     /**
  80      * Sets the current sequence on which the sequencer operates.
  81      * <p>
  82      * This method can be called even if the {@code Sequencer} is closed.
  83      *
  84      * @param  sequence the sequence to be loaded
  85      * @throws InvalidMidiDataException if the sequence contains invalid MIDI
  86      *         data, or is not supported
  87      */
  88     void setSequence(Sequence sequence) throws InvalidMidiDataException;
  89 
  90     /**
  91      * Sets the current sequence on which the sequencer operates. The stream
  92      * must point to MIDI file data.
  93      * <p>
  94      * This method can be called even if the {@code Sequencer} is closed.
  95      *
  96      * @param  stream stream containing MIDI file data
  97      * @throws IOException if an I/O exception occurs during reading of the
  98      *         stream
  99      * @throws InvalidMidiDataException if invalid data is encountered in the
 100      *         stream, or the stream is not supported
 101      */
 102     void setSequence(InputStream stream)
 103             throws IOException, InvalidMidiDataException;
 104 
 105     /**
 106      * Obtains the sequence on which the Sequencer is currently operating.
 107      * <p>
 108      * This method can be called even if the {@code Sequencer} is closed.
 109      *
 110      * @return the current sequence, or {@code null} if no sequence is currently
 111      *         set
 112      */
 113     Sequence getSequence();
 114 
 115     /**
 116      * Starts playback of the MIDI data in the currently loaded sequence.
 117      * Playback will begin from the current position. If the playback position
 118      * reaches the loop end point, and the loop count is greater than 0,
 119      * playback will resume at the loop start point for the number of
 120      * repetitions set with {@code setLoopCount}. After that, or if the loop
 121      * count is 0, playback will continue to play to the end of the sequence.
 122      * <p>
 123      * The implementation ensures that the synthesizer is brought to a
 124      * consistent state when jumping to the loop start point by sending
 125      * appropriate controllers, pitch bend, and program change events.
 126      *
 127      * @throws IllegalStateException if the {@code Sequencer} is closed
 128      * @see #setLoopStartPoint
 129      * @see #setLoopEndPoint
 130      * @see #setLoopCount
 131      * @see #stop
 132      */
 133     void start();
 134 
 135     /**
 136      * Stops recording, if active, and playback of the currently loaded
 137      * sequence, if any.
 138      *
 139      * @throws IllegalStateException if the {@code Sequencer} is closed
 140      * @see #start
 141      * @see #isRunning
 142      */
 143     void stop();
 144 
 145     /**
 146      * Indicates whether the Sequencer is currently running. The default is
 147      * {@code false}. The Sequencer starts running when either{@link #start} or
 148      * {@link #startRecording} is called. {@code isRunning} then returns
 149      * {@code true} until playback of the sequence completes or {@link #stop} is
 150      * called.
 151      *
 152      * @return {@code true} if the Sequencer is running, otherwise {@code false}
 153      */
 154     boolean isRunning();
 155 
 156     /**
 157      * Starts recording and playback of MIDI data. Data is recorded to all
 158      * enabled tracks, on the channel(s) for which they were enabled. Recording
 159      * begins at the current position of the sequencer. Any events already in
 160      * the track are overwritten for the duration of the recording session.
 161      * Events from the currently loaded sequence, if any, are delivered to the
 162      * sequencer's transmitter(s) along with messages received during recording.
 163      * <p>
 164      * Note that tracks are not by default enabled for recording. In order to
 165      * record MIDI data, at least one track must be specifically enabled for
 166      * recording.
 167      *
 168      * @throws IllegalStateException if the {@code Sequencer} is closed
 169      * @see #recordEnable
 170      * @see #recordDisable
 171      */
 172     void startRecording();
 173 
 174     /**
 175      * Stops recording, if active. Playback of the current sequence continues.
 176      *
 177      * @throws IllegalStateException if the {@code Sequencer} is closed
 178      * @see #startRecording
 179      * @see #isRecording
 180      */
 181     void stopRecording();
 182 
 183     /**
 184      * Indicates whether the Sequencer is currently recording. The default is
 185      * {@code false}. The Sequencer begins recording when
 186      * {@link #startRecording} is called, and then returns {@code true} until
 187      * {@link #stop} or {@link #stopRecording} is called.
 188      *
 189      * @return {@code true} if the Sequencer is recording, otherwise
 190      *         {@code false}
 191      */
 192     boolean isRecording();
 193 
 194     /**
 195      * Prepares the specified track for recording events received on a
 196      * particular channel. Once enabled, a track will receive events when
 197      * recording is active.
 198      *
 199      * @param  track the track to which events will be recorded
 200      * @param  channel the channel on which events will be received. If -1 is
 201      *         specified for the channel value, the track will receive data from
 202      *         all channels.
 203      * @throws IllegalArgumentException thrown if the track is not part of the
 204      *         current sequence
 205      */
 206     void recordEnable(Track track, int channel);
 207 
 208     /**
 209      * Disables recording to the specified track. Events will no longer be
 210      * recorded into this track.
 211      *
 212      * @param  track the track to disable for recording, or {@code null} to
 213      *         disable recording for all tracks
 214      */
 215     void recordDisable(Track track);
 216 
 217     /**
 218      * Obtains the current tempo, expressed in beats per minute. The actual
 219      * tempo of playback is the product of the returned value and the tempo
 220      * factor.
 221      *
 222      * @return the current tempo in beats per minute
 223      * @see #getTempoFactor
 224      * @see #setTempoInBPM(float)
 225      * @see #getTempoInMPQ
 226      */
 227     float getTempoInBPM();
 228 
 229     /**
 230      * Sets the tempo in beats per minute. The actual tempo of playback is the
 231      * product of the specified value and the tempo factor.
 232      *
 233      * @param  bpm desired new tempo in beats per minute
 234      * @see #getTempoFactor
 235      * @see #setTempoInMPQ(float)
 236      * @see #getTempoInBPM
 237      */
 238     void setTempoInBPM(float bpm);
 239 
 240     /**
 241      * Obtains the current tempo, expressed in microseconds per quarter note.
 242      * The actual tempo of playback is the product of the returned value and the
 243      * tempo factor.
 244      *
 245      * @return the current tempo in microseconds per quarter note
 246      * @see #getTempoFactor
 247      * @see #setTempoInMPQ(float)
 248      * @see #getTempoInBPM
 249      */
 250     float getTempoInMPQ();
 251 
 252     /**
 253      * Sets the tempo in microseconds per quarter note. The actual tempo of
 254      * playback is the product of the specified value and the tempo factor.
 255      *
 256      * @param  mpq desired new tempo in microseconds per quarter note
 257      * @see #getTempoFactor
 258      * @see #setTempoInBPM(float)
 259      * @see #getTempoInMPQ
 260      */
 261     void setTempoInMPQ(float mpq);
 262 
 263     /**
 264      * Scales the sequencer's actual playback tempo by the factor provided. The
 265      * default is 1.0. A value of 1.0 represents the natural rate (the tempo
 266      * specified in the sequence), 2.0 means twice as fast, etc. The tempo
 267      * factor does not affect the values returned by {@link #getTempoInMPQ} and
 268      * {@link #getTempoInBPM}. Those values indicate the tempo prior to scaling.
 269      * <p>
 270      * Note that the tempo factor cannot be adjusted when external
 271      * synchronization is used. In that situation, {@code setTempoFactor} always
 272      * sets the tempo factor to 1.0.
 273      *
 274      * @param  factor the requested tempo scalar
 275      * @see #getTempoFactor
 276      */
 277     void setTempoFactor(float factor);
 278 
 279     /**
 280      * Returns the current tempo factor for the sequencer. The default is 1.0.
 281      *
 282      * @return tempo factor
 283      * @see #setTempoFactor(float)
 284      */
 285     float getTempoFactor();
 286 
 287     /**
 288      * Obtains the length of the current sequence, expressed in MIDI ticks, or 0
 289      * if no sequence is set.
 290      *
 291      * @return length of the sequence in ticks
 292      */
 293     long getTickLength();
 294 
 295     /**
 296      * Obtains the current position in the sequence, expressed in MIDI ticks.
 297      * (The duration of a tick in seconds is determined both by the tempo and by
 298      * the timing resolution stored in the {@link Sequence}.)
 299      *
 300      * @return current tick
 301      * @see #setTickPosition
 302      */
 303     long getTickPosition();
 304 
 305     /**
 306      * Sets the current sequencer position in MIDI ticks.
 307      *
 308      * @param  tick the desired tick position
 309      * @see #getTickPosition
 310      */
 311     void setTickPosition(long tick);
 312 
 313     /**
 314      * Obtains the length of the current sequence, expressed in microseconds, or
 315      * 0 if no sequence is set.
 316      *
 317      * @return length of the sequence in microseconds
 318      */
 319     long getMicrosecondLength();
 320 
 321     /**
 322      * Obtains the current position in the sequence, expressed in microseconds.
 323      *
 324      * @return the current position in microseconds
 325      * @see #setMicrosecondPosition
 326      */
 327     @Override
 328     long getMicrosecondPosition();
 329 
 330     /**
 331      * Sets the current position in the sequence, expressed in microseconds.
 332      *
 333      * @param  microseconds desired position in microseconds
 334      * @see #getMicrosecondPosition
 335      */
 336     void setMicrosecondPosition(long microseconds);
 337 
 338     /**
 339      * Sets the source of timing information used by this sequencer. The
 340      * sequencer synchronizes to the master, which is the internal clock, MIDI
 341      * clock, or MIDI time code, depending on the value of {@code sync}. The
 342      * {@code sync} argument must be one of the supported modes, as returned by
 343      * {@link #getMasterSyncModes}.
 344      *
 345      * @param  sync the desired master synchronization mode
 346      * @see SyncMode#INTERNAL_CLOCK
 347      * @see SyncMode#MIDI_SYNC
 348      * @see SyncMode#MIDI_TIME_CODE
 349      * @see #getMasterSyncMode
 350      */
 351     void setMasterSyncMode(SyncMode sync);
 352 
 353     /**
 354      * Obtains the current master synchronization mode for this sequencer.
 355      *
 356      * @return the current master synchronization mode
 357      * @see #setMasterSyncMode(SyncMode)
 358      * @see #getMasterSyncModes
 359      */
 360     SyncMode getMasterSyncMode();
 361 
 362     /**
 363      * Obtains the set of master synchronization modes supported by this
 364      * sequencer.
 365      *
 366      * @return the available master synchronization modes
 367      * @see SyncMode#INTERNAL_CLOCK
 368      * @see SyncMode#MIDI_SYNC
 369      * @see SyncMode#MIDI_TIME_CODE
 370      * @see #getMasterSyncMode
 371      * @see #setMasterSyncMode(SyncMode)
 372      */
 373     SyncMode[] getMasterSyncModes();
 374 
 375     /**
 376      * Sets the slave synchronization mode for the sequencer. This indicates the
 377      * type of timing information sent by the sequencer to its receiver. The
 378      * {@code sync} argument must be one of the supported modes, as returned by
 379      * {@link #getSlaveSyncModes}.
 380      *
 381      * @param  sync the desired slave synchronization mode
 382      * @see SyncMode#MIDI_SYNC
 383      * @see SyncMode#MIDI_TIME_CODE
 384      * @see SyncMode#NO_SYNC
 385      * @see #getSlaveSyncModes
 386      */
 387     void setSlaveSyncMode(SyncMode sync);
 388 
 389     /**
 390      * Obtains the current slave synchronization mode for this sequencer.
 391      *
 392      * @return the current slave synchronization mode
 393      * @see #setSlaveSyncMode(SyncMode)
 394      * @see #getSlaveSyncModes
 395      */
 396     SyncMode getSlaveSyncMode();
 397 
 398     /**
 399      * Obtains the set of slave synchronization modes supported by the
 400      * sequencer.
 401      *
 402      * @return the available slave synchronization modes
 403      * @see SyncMode#MIDI_SYNC
 404      * @see SyncMode#MIDI_TIME_CODE
 405      * @see SyncMode#NO_SYNC
 406      */
 407     SyncMode[] getSlaveSyncModes();
 408 
 409     /**
 410      * Sets the mute state for a track. This method may fail for a number of
 411      * reasons. For example, the track number specified may not be valid for the
 412      * current sequence, or the sequencer may not support this functionality. An
 413      * application which needs to verify whether this operation succeeded should
 414      * follow this call with a call to {@link #getTrackMute}.
 415      *
 416      * @param  track the track number. Tracks in the current sequence are
 417      *         numbered from 0 to the number of tracks in the sequence minus 1.
 418      * @param  mute the new mute state for the track. {@code true} implies the
 419      *         track should be muted, {@code false} implies the track should be
 420      *         unmuted.
 421      * @see #getSequence
 422      */
 423     void setTrackMute(int track, boolean mute);
 424 
 425     /**
 426      * Obtains the current mute state for a track. The default mute state for
 427      * all tracks which have not been muted is false. In any case where the
 428      * specified track has not been muted, this method should return false. This
 429      * applies if the sequencer does not support muting of tracks, and if the
 430      * specified track index is not valid.
 431      *
 432      * @param  track the track number. Tracks in the current sequence are
 433      *         numbered from 0 to the number of tracks in the sequence minus 1.
 434      * @return {@code true} if muted, {@code false} if not
 435      */
 436     boolean getTrackMute(int track);
 437 
 438     /**
 439      * Sets the solo state for a track. If {@code solo} is {@code true} only
 440      * this track and other solo'd tracks will sound. If {@code solo} is
 441      * {@code false} then only other solo'd tracks will sound, unless no tracks
 442      * are solo'd in which case all un-muted tracks will sound.
 443      * <p>
 444      * This method may fail for a number of reasons. For example, the track
 445      * number specified may not be valid for the current sequence, or the
 446      * sequencer may not support this functionality. An application which needs
 447      * to verify whether this operation succeeded should follow this call with a
 448      * call to {@link #getTrackSolo}.
 449      *
 450      * @param  track the track number. Tracks in the current sequence are
 451      *         numbered from 0 to the number of tracks in the sequence minus 1.
 452      * @param  solo the new solo state for the track. {@code true} implies the
 453      *         track should be solo'd, {@code false} implies the track should
 454      *         not be solo'd.
 455      * @see #getSequence
 456      */
 457     void setTrackSolo(int track, boolean solo);
 458 
 459     /**
 460      * Obtains the current solo state for a track. The default mute state for
 461      * all tracks which have not been solo'd is false. In any case where the
 462      * specified track has not been solo'd, this method should return false.
 463      * This applies if the sequencer does not support soloing of tracks, and if
 464      * the specified track index is not valid.
 465      *
 466      * @param  track the track number. Tracks in the current sequence are
 467      *         numbered from 0 to the number of tracks in the sequence minus 1.
 468      * @return {@code true} if solo'd, {@code false} if not
 469      */
 470     boolean getTrackSolo(int track);
 471 
 472     /**
 473      * Registers a meta-event listener to receive notification whenever a
 474      * meta-event is encountered in the sequence and processed by the sequencer.
 475      * This method can fail if, for instance,this class of sequencer does not
 476      * support meta-event notification.
 477      *
 478      * @param  listener listener to add
 479      * @return {@code true} if the listener was successfully added, otherwise
 480      *         {@code false}
 481      * @see #removeMetaEventListener
 482      * @see MetaEventListener
 483      * @see MetaMessage
 484      */
 485     boolean addMetaEventListener(MetaEventListener listener);
 486 
 487     /**
 488      * Removes the specified meta-event listener from this sequencer's list of
 489      * registered listeners, if in fact the listener is registered.
 490      *
 491      * @param  listener the meta-event listener to remove
 492      * @see #addMetaEventListener
 493      */
 494     void removeMetaEventListener(MetaEventListener listener);
 495 
 496     /**
 497      * Registers a controller event listener to receive notification whenever
 498      * the sequencer processes a control-change event of the requested type or
 499      * types. The types are specified by the {@code controllers} argument, which
 500      * should contain an array of MIDI controller numbers. (Each number should
 501      * be between 0 and 127, inclusive. See the MIDI 1.0 Specification for the
 502      * numbers that correspond to various types of controllers.)
 503      * <p>
 504      * The returned array contains the MIDI controller numbers for which the
 505      * listener will now receive events. Some sequencers might not support
 506      * controller event notification, in which case the array has a length of 0.
 507      * Other sequencers might support notification for some controllers but not
 508      * all. This method may be invoked repeatedly. Each time, the returned array
 509      * indicates all the controllers that the listener will be notified about,
 510      * not only the controllers requested in that particular invocation.
 511      *
 512      * @param  listener the controller event listener to add to the list of
 513      *         registered listeners
 514      * @param  controllers the MIDI controller numbers for which change
 515      *         notification is requested
 516      * @return the numbers of all the MIDI controllers whose changes will now be
 517      *         reported to the specified listener
 518      * @see #removeControllerEventListener
 519      * @see ControllerEventListener
 520      */
 521     int[] addControllerEventListener(ControllerEventListener listener,
 522                                      int[] controllers);
 523 
 524     /**
 525      * Removes a controller event listener's interest in one or more types of
 526      * controller event. The {@code controllers} argument is an array of MIDI
 527      * numbers corresponding to the controllers for which the listener should no
 528      * longer receive change notifications. To completely remove this listener
 529      * from the list of registered listeners, pass in {@code null} for
 530      * {@code controllers}. The returned array contains the MIDI controller
 531      * numbers for which the listener will now receive events. The array has a
 532      * length of 0 if the listener will not receive change notifications for any
 533      * controllers.
 534      *
 535      * @param  listener old listener
 536      * @param  controllers the MIDI controller numbers for which change
 537      *         notification should be cancelled, or {@code null} to cancel for
 538      *         all controllers
 539      * @return the numbers of all the MIDI controllers whose changes will now be
 540      *         reported to the specified listener
 541      * @see #addControllerEventListener
 542      */
 543     int[] removeControllerEventListener(ControllerEventListener listener,
 544                                         int[] controllers);
 545 
 546     /**
 547      * Sets the first MIDI tick that will be played in the loop. If the loop
 548      * count is greater than 0, playback will jump to this point when reaching
 549      * the loop end point.
 550      * <p>
 551      * A value of 0 for the starting point means the beginning of the loaded
 552      * sequence. The starting point must be lower than or equal to the ending
 553      * point, and it must fall within the size of the loaded sequence.
 554      * <p>
 555      * A sequencer's loop start point defaults to start of the sequence.
 556      *
 557      * @param  tick the loop's starting position, in MIDI ticks (zero-based)
 558      * @throws IllegalArgumentException if the requested loop start point cannot
 559      *         be set, usually because it falls outside the sequence's duration
 560      *         or because the start point is after the end point
 561      * @see #setLoopEndPoint
 562      * @see #setLoopCount
 563      * @see #getLoopStartPoint
 564      * @see #start
 565      * @since 1.5
 566      */
 567     void setLoopStartPoint(long tick);
 568 
 569     /**
 570      * Obtains the start position of the loop, in MIDI ticks.
 571      *
 572      * @return the start position of the loop, in MIDI ticks (zero-based)
 573      * @see #setLoopStartPoint
 574      * @since 1.5
 575      */
 576     long getLoopStartPoint();
 577 
 578     /**
 579      * Sets the last MIDI tick that will be played in the loop. If the loop
 580      * count is 0, the loop end point has no effect and playback continues to
 581      * play when reaching the loop end point.
 582      * <p>
 583      * A value of -1 for the ending point indicates the last tick of the
 584      * sequence. Otherwise, the ending point must be greater than or equal to
 585      * the starting point, and it must fall within the size of the loaded
 586      * sequence.
 587      * <p>
 588      * A sequencer's loop end point defaults to -1, meaning the end of the
 589      * sequence.
 590      *
 591      * @param  tick the loop's ending position, in MIDI ticks (zero-based), or
 592      *         -1 to indicate the final tick
 593      * @throws IllegalArgumentException if the requested loop point cannot be
 594      *         set, usually because it falls outside the sequence's duration or
 595      *         because the ending point is before the starting point
 596      * @see #setLoopStartPoint
 597      * @see #setLoopCount
 598      * @see #getLoopEndPoint
 599      * @see #start
 600      * @since 1.5
 601      */
 602     void setLoopEndPoint(long tick);
 603 
 604     /**
 605      * Obtains the end position of the loop, in MIDI ticks.
 606      *
 607      * @return the end position of the loop, in MIDI ticks (zero-based), or -1
 608      *         to indicate the end of the sequence
 609      * @see #setLoopEndPoint
 610      * @since 1.5
 611      */
 612     long getLoopEndPoint();
 613 
 614     /**
 615      * Sets the number of repetitions of the loop for playback. When the
 616      * playback position reaches the loop end point, it will loop back to the
 617      * loop start point {@code count} times, after which playback will continue
 618      * to play to the end of the sequence.
 619      * <p>
 620      * If the current position when this method is invoked is greater than the
 621      * loop end point, playback continues to the end of the sequence without
 622      * looping, unless the loop end point is changed subsequently.
 623      * <p>
 624      * A {@code count} value of 0 disables looping: playback will continue at
 625      * the loop end point, and it will not loop back to the loop start point.
 626      * This is a sequencer's default.
 627      * <p>
 628      * If playback is stopped during looping, the current loop status is
 629      * cleared; subsequent start requests are not affected by an interrupted
 630      * loop operation.
 631      *
 632      * @param  count the number of times playback should loop back from the
 633      *         loop's end position to the loop's start position, or
 634      *         {@link #LOOP_CONTINUOUSLY} to indicate that looping should
 635      *         continue until interrupted
 636      * @throws IllegalArgumentException if {@code count} is negative and not
 637      *         equal to {@link #LOOP_CONTINUOUSLY}
 638      * @see #setLoopStartPoint
 639      * @see #setLoopEndPoint
 640      * @see #getLoopCount
 641      * @see #start
 642      * @since 1.5
 643      */
 644     void setLoopCount(int count);
 645 
 646     /**
 647      * Obtains the number of repetitions for playback.
 648      *
 649      * @return the number of loops after which playback plays to the end of the
 650      *         sequence
 651      * @see #setLoopCount
 652      * @see #start
 653      * @since 1.5
 654      */
 655     int getLoopCount();
 656 
 657     /**
 658      * A {@code SyncMode} object represents one of the ways in which a MIDI
 659      * sequencer's notion of time can be synchronized with a master or slave
 660      * device. If the sequencer is being synchronized to a master, the sequencer
 661      * revises its current time in response to messages from the master. If the
 662      * sequencer has a slave, the sequencer similarly sends messages to control
 663      * the slave's timing.
 664      * <p>
 665      * There are three predefined modes that specify possible masters for a
 666      * sequencer: {@code INTERNAL_CLOCK}, {@code MIDI_SYNC}, and
 667      * {@code MIDI_TIME_CODE}. The latter two work if the sequencer receives
 668      * MIDI messages from another device. In these two modes, the sequencer's
 669      * time gets reset based on system real-time timing clock messages or MIDI
 670      * time code (MTC) messages, respectively. These two modes can also be used
 671      * as slave modes, in which case the sequencer sends the corresponding types
 672      * of MIDI messages to its receiver (whether or not the sequencer is also
 673      * receiving them from a master). A fourth mode, {@code NO_SYNC}, is used to
 674      * indicate that the sequencer should not control its receiver's timing.
 675      *
 676      * @see Sequencer#setMasterSyncMode(SyncMode)
 677      * @see Sequencer#setSlaveSyncMode(SyncMode)
 678      */
 679     class SyncMode {
 680 
 681         /**
 682          * Synchronization mode name.
 683          */
 684         private final String name;
 685 
 686         /**
 687          * Constructs a synchronization mode.
 688          *
 689          * @param  name name of the synchronization mode
 690          */
 691         protected SyncMode(String name) {
 692 
 693             this.name = name;
 694         }
 695 
 696         /**
 697          * Indicates whether the specified object is equal to this
 698          * synchronization mode, returning {@code true} if the objects are the
 699          * same.
 700          *
 701          * @param  obj the reference object with which to compare
 702          * @return {@code true} if the specified object is equal to this
 703          *         synchronization mode; {@code false} otherwise
 704          */
 705         @Override
 706         public final boolean equals(Object obj) {
 707 
 708             return super.equals(obj);
 709         }
 710 
 711         /**
 712          * Returns a hash code value for this synchronization mode.
 713          *
 714          * @return a hash code value for this synchronization mode
 715          */
 716         @Override
 717         public final int hashCode() {
 718 
 719             return super.hashCode();
 720         }
 721 
 722         /**
 723          * Returns mode's name as the string representation of the
 724          * synchronization mode.
 725          *
 726          * @return a string representation of the synchronization mode
 727          */
 728         @Override
 729         public final String toString() {

 730             return name;
 731         }
 732 
 733         /**
 734          * A master synchronization mode that makes the sequencer get its timing
 735          * information from its internal clock. This is not a legal slave sync
 736          * mode.
 737          */
 738         public static final SyncMode INTERNAL_CLOCK = new SyncMode("Internal Clock");
 739 
 740         /**
 741          * A master or slave synchronization mode that specifies the use of MIDI
 742          * clock messages. If this mode is used as the master sync mode, the
 743          * sequencer gets its timing information from system real-time MIDI
 744          * clock messages. This mode only applies as the master sync mode for
 745          * sequencers that are also MIDI receivers. If this is the slave sync
 746          * mode, the sequencer sends system real-time MIDI clock messages to its
 747          * receiver. MIDI clock messages are sent at a rate of 24 per quarter
 748          * note.
 749          */
 750         public static final SyncMode MIDI_SYNC = new SyncMode("MIDI Sync");
 751 
 752         /**
 753          * A master or slave synchronization mode that specifies the use of MIDI
 754          * Time Code. If this mode is used as the master sync mode, the
 755          * sequencer gets its timing information from MIDI Time Code messages.
 756          * This mode only applies as the master sync mode to sequencers that are
 757          * also MIDI receivers. If this mode is used as the slave sync mode, the
 758          * sequencer sends MIDI Time Code messages to its receiver. (See the
 759          * MIDI 1.0 Detailed Specification for a description of MIDI Time Code.)
 760          */
 761         public static final SyncMode MIDI_TIME_CODE = new SyncMode("MIDI Time Code");
 762 
 763         /**
 764          * A slave synchronization mode indicating that no timing information
 765          * should be sent to the receiver. This is not a legal master sync mode.
 766          */
 767         public static final SyncMode NO_SYNC = new SyncMode("No Timing");
 768 
 769     }
 770 }
--- EOF ---