1/*
2 * Copyright (c) 1999, 2017, 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
26package javax.sound.midi;
27
28/**
29 * A {@code Transmitter} sends {@link MidiEvent} objects to one or more
30 * {@link Receiver Receivers}. Common MIDI transmitters include sequencers and
31 * MIDI input ports.
32 *
33 * @author Kara Kytle
34 * @see Receiver
35 */
36public interface Transmitter extends AutoCloseable {
37
38    /**
39     * Sets the receiver to which this transmitter will deliver MIDI messages.
40     * If a receiver is currently set, it is replaced with this one.
41     *
42     * @param  receiver the desired receiver
43     */
44    void setReceiver(Receiver receiver);
45
46    /**
47     * Obtains the current receiver to which this transmitter will deliver MIDI
48     * messages.
49     *
50     * @return the current receiver. If no receiver is currently set, returns
51     *         {@code null}.
52     */
53    Receiver getReceiver();
54
55    /**
56     * Indicates that the application has finished using the transmitter, and
57     * that limited resources it requires may be released or made available.
58     * <p>
59     * If the creation of this {@code Transmitter} resulted in implicitly
60     * opening the underlying device, the device is implicitly closed by this
61     * method. This is true unless the device is kept open by other
62     * {@code Receiver} or {@code Transmitter} instances that opened the device
63     * implicitly, and unless the device has been opened explicitly. If the
64     * device this {@code Transmitter} is retrieved from is closed explicitly by
65     * calling {@link MidiDevice#close MidiDevice.close}, the
66     * {@code Transmitter} is closed, too. For a detailed description of
67     * open/close behaviour see the class description of
68     * {@link MidiDevice MidiDevice}.
69     *
70     * @see MidiSystem#getTransmitter
71     */
72    @Override
73    void close();
74}
75