Clarify default connections in default sequencer

The old sequencer automatically connected itself to the default synthesizer's receiver. That was handy, since it wasn't necessary to explicitely get a Synthesizer object, and connect it to the Sequencer. It was also sufficient, because there was only one sequencer, and only one synthesizer available. It was also the only the only way to have a connected sequencer, since the old sequencer did not allow to connect it to arbitrary Receivers.

The new sequencer is implemented correctly, i.e. there is no automatic connection. That'll break almost all programs that use the sequencer (or want to play MIDI files), because people relied on the default connection (to a Receiver instance). Also it's now possible to choose a Receiver from all available ones on the system, not only the Synthesizer. Unfortunately, initializing the sequencer with a default connection is not useful, because there is no way to remove a connection (see below). Transmitters in a sequencer are always added. So you may add explicitely Transmitter which connects to your Receiver of choice, but the default connection will still be there and you'll hear the music on both devices.

Note that the old sequencer is violating in several instances against the specification, and against the intentions of the specification.

As to the missing API for removal of Transmitters from a Sequencer: this is requested in RFE 4931387.


This is the proposed solution:

1) Specify explicitely that the method MidiSystem.getSequencer() will return a Sequencer instance which is automatically connected to the default synthesizer, or with the first MidiDevice which offers a Receiver, if there is no default Synthesizer available. That way we maintain 100% compatibility.

  /**
! * Obtains the default sequencer, connected to a default Receiver.
+ * The returned Sequencer instance is
+ * connected to the default Synthesizer. If there is no Synthesizer
+ * available, or the default Synthesizer cannot be opened,
+ * the Sequencer is connected to the default Receiver.
+ * The connection is made by retrieving a Transmitter instance
+ * from the Sequencer and setting its Receiver.
+ *
+ * Closing and re-opening the sequencer will restore the
+ * connection to the default MIDI device.
+ *
+ * <p>This method is equivalent to calling
+ * <code>getSequencer(true)</code>.
   *
   * <p>If the system property
   * <code>javax.sound.midi.Sequencer</code>
   * is defined or it is defined in the file "sound.properties",
   * it is used to identify the default sequencer.
   * For details, refer to the {@link MidiSystem class description}.
   *
! * @return the default sequencer, connected to a default Receiver
   * @throws MidiUnavailableException if the sequencer is not
   * available due to resource restrictions
+ * @see #getSequencer(boolean)
+ * @see #getSynthesizer
+ * @see #getReceiver
   */
  public static Sequencer getSequencer() throws MidiUnavailableException

2) Since now the new Sequencer would be useless, because trying to connect it to another Receiver would create a lot of confusion, add a method that explicitely returns a non-connected Sequencer:

  /**
   * Obtains the default sequencer, optionally connected to a
   * default device.
   * If <code>connected</code> is true, the returned sequencer is
   * connected to the default Synthesizer. If there is no Synthesizer
   * available, or the default Synthesizer cannot be opened,
   * the Sequencer is connected to the default Receiver.
   * The connection is made by retrieving a Transmitter instance
   * from the Sequencer and setting its Receiver.
   * Closing and re-opening the sequencer will restore the
   * connection to the default MIDI device.
   *
   * <p>If <code>connected</code> is false, the returned sequencer is
   * not connected, it has no open Transmitters. In order to
   * play the sequencer on a MIDI device, or a Synthesizer,
   * it is necessary to get a transmitter and set its receiver.
   *
   * <p>If the system property
   * <code>javax.sound.midi.Sequencer</code>
   * is defined or it is defined in the file "sound.properties",
   * it is used to identify the default sequencer.
   * For details, refer to the {@link MidiSystem class description}.
   *
   * @return the default sequencer
   * @throws MidiUnavailableException if the sequencer is not
   * available due to resource restrictions
   * @see #getSynthesizer
   * @see #getReceiver
   * @since 1.5
   */
  public static Sequencer getSequencer(boolean connected)
      throws MidiUnavailableException

======================================================================

###@###.### 2003-10-22