2  * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.

     2  * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.

    30  /**

    30 /**

    31  * <code>MidiDevice</code> is the base interface for all MIDI devices.

    31  * {@code MidiDevice} is the base interface for all MIDI devices. Common devices

    32  * Common devices include synthesizers, sequencers, MIDI input ports, and MIDI

    32  * include synthesizers, sequencers, MIDI input ports, and MIDI output ports.

    33  * output ports.

    33  * <p>

    34  *

    34  * A {@code MidiDevice} can be a transmitter or a receiver of MIDI events, or

    35  * <p>A <code>MidiDevice</code> can be a transmitter or a receiver of

    35  * both. Therefore, it can provide {@link Transmitter} or {@link Receiver}

    36  * MIDI events, or both. Therefore, it can provide {@link Transmitter}

    36  * instances (or both). Typically, MIDI IN ports provide transmitters, MIDI OUT

    37  * or {@link Receiver} instances (or both). Typically, MIDI IN ports

    37  * ports and synthesizers provide receivers. A Sequencer typically provides

    38  * provide transmitters, MIDI OUT ports and synthesizers provide

    38  * transmitters for playback and receivers for recording.

    39  * receivers. A Sequencer typically provides transmitters for playback

    39  * <p>

    40  * and receivers for recording.

    40  * A {@code MidiDevice} can be opened and closed explicitly as well as

    41  *

    41  * implicitly. Explicit opening is accomplished by calling {@link #open},

    42  * <p>A <code>MidiDevice</code> can be opened and closed explicitly as

    42  * explicit closing is done by calling {@link #close} on the {@code MidiDevice}

    43  * well as implicitly. Explicit opening is accomplished by calling

    43  * instance. If an application opens a {@code MidiDevice} explicitly, it has to

    44  * {@link #open}, explicit closing is done by calling {@link

    44  * close it explicitly to free system resources and enable the application to

    45  * #close} on the <code>MidiDevice</code> instance.

    45  * exit cleanly. Implicit opening is done by calling

    46  * If an application opens a <code>MidiDevice</code>

    46  * {@link MidiSystem#getReceiver} and {@link MidiSystem#getTransmitter}. The

    47  * explicitly, it has to close it explicitly to free system resources

    47  * {@code MidiDevice} used by {@code MidiSystem.getReceiver} and

    48  * and enable the application to exit cleanly. Implicit opening is

    48  * {@code MidiSystem.getTransmitter} is implementation-dependant unless the

    49  * done by calling {@link javax.sound.midi.MidiSystem#getReceiver

    49  * properties {@code javax.sound.midi.Receiver} and

    50  * MidiSystem.getReceiver} and {@link

    50  * {@code javax.sound.midi.Transmitter} are used (see the description of

    51  * javax.sound.midi.MidiSystem#getTransmitter

    51  * properties to select default providers in {@link MidiSystem}). A

    52  * MidiSystem.getTransmitter}. The <code>MidiDevice</code> used by

    52  * {@code MidiDevice} that was opened implicitly, is closed implicitly by

    53  * <code>MidiSystem.getReceiver</code> and

    53  * closing the {@code Receiver} or {@code Transmitter} that resulted in opening

    54  * <code>MidiSystem.getTransmitter</code> is implementation-dependant

    54  * it. If more than one implicitly opening {@code Receiver} or

    55  * unless the properties <code>javax.sound.midi.Receiver</code>

    55  * {@code Transmitter} were obtained by the application, the device is closed

    56  * and <code>javax.sound.midi.Transmitter</code> are used (see the

    56  * after the last {@code Receiver} or {@code Transmitter} has been closed. On

    57  * description of properties to select default providers in

    57  * the other hand, calling {@code getReceiver} or {@code getTransmitter} on the

    58  * {@link javax.sound.midi.MidiSystem}). A <code>MidiDevice</code>

    58  * device instance directly does not open the device implicitly. Closing these

    59  * that was opened implicitly, is closed implicitly by closing the

    59  * {@code Transmitter}s and {@code Receiver}s does not close the device

    60  * <code>Receiver</code> or <code>Transmitter</code> that resulted in

    60  * implicitly. To use a device with {@code Receiver}s or {@code Transmitter}s

    61  * opening it. If more than one implicitly opening

    61  * obtained this way, the device has to be opened and closed explicitly.

    62  * <code>Receiver</code> or <code>Transmitter</code> were obtained by

    62  * <p>

    63  * the application, the device is closed after the last

    63  * If implicit and explicit opening and closing are mixed on the same

    64  * <code>Receiver</code> or <code>Transmitter</code> has been

    64  * {@code MidiDevice} instance, the following rules apply:

    65  * closed. On the other hand, calling <code>getReceiver</code> or

    66  * <code>getTransmitter</code> on the device instance directly does

    67  * not open the device implicitly. Closing these

    68  * <code>Transmitter</code>s and <code>Receiver</code>s does not close

    69  * the device implicitly. To use a device with <code>Receiver</code>s

    70  * or <code>Transmitter</code>s obtained this way, the device has to

    71  * be opened and closed explicitly.

    72  *

    73  * <p>If implicit and explicit opening and closing are mixed on the

    74  * same <code>MidiDevice</code> instance, the following rules apply:

    77  * <li>After an explicit open (either before or after implicit

    67  * <li>After an explicit open (either before or after implicit opens), the

    78  * opens), the device will not be closed by implicit closing. The only

    68  * device will not be closed by implicit closing. The only way to close an

    79  * way to close an explicitly opened device is an explicit close.</li>

    69  * explicitly opened device is an explicit close.</li>

    80  *

    70  * <li>An explicit close always closes the device, even if it also has been

    81  * <li>An explicit close always closes the device, even if it also has

    71  * opened implicitly. A subsequent implicit close has no further effect.</li>

    82  * been opened implicitly. A subsequent implicit close has no further

    83  * effect.</li>

    86  * To detect if a MidiDevice represents a hardware MIDI port, the

    74  * To detect if a MidiDevice represents a hardware MIDI port, the following

    87  * following programming technique can be used:

    75  * programming technique can be used:

    98  * A <code>MidiDevice</code> includes a <code>{@link MidiDevice.Info}</code> object

    86  * A {@code MidiDevice} includes a {@link Info} object to provide manufacturer

    99  * to provide manufacturer information and so on.

    87  * information and so on.

   100  *

    88  *

    89  * @author Kara Kytle

    90  * @author Florian Bomers

   115      * <code>Strings</code> containing its name, vendor, and description.

   100      * {@code Strings} containing its name, vendor, and description.

   119     public Info getDeviceInfo();

   104     Info getDeviceInfo();

   120 

   105 

   121 

   106     /**

   122     /**

   107      * Opens the device, indicating that it should now acquire any system

   123      * Opens the device, indicating that it should now acquire any

   108      * resources it requires and become operational.

   124      * system resources it requires and become operational.

   109      * <p>

   125      *

   110      * An application opening a device explicitly with this call has to close

   126      * <p>An application opening a device explicitly with this call

   111      * the device by calling {@link #close}. This is necessary to release system

   127      * has to close the device by calling {@link #close}. This is

   112      * resources and allow applications to exit cleanly.

   128      * necessary to release system resources and allow applications to

   113      * <p>

   129      * exit cleanly.

   114      * Note that some devices, once closed, cannot be reopened. Attempts to

   130      *

   115      * reopen such a device will always result in a MidiUnavailableException.

   131      * <p>

   116      *

   132      * Note that some devices, once closed, cannot be reopened.  Attempts

   117      * @throws MidiUnavailableException thrown if the device cannot be opened

   133      * to reopen such a device will always result in a MidiUnavailableException.

   118      *         due to resource restrictions

   134      *

   119      * @throws SecurityException thrown if the device cannot be opened due to

   135      * @throws MidiUnavailableException thrown if the device cannot be

   120      *         security restrictions

   136      * opened due to resource restrictions.

   137      * @throws SecurityException thrown if the device cannot be

   138      * opened due to security restrictions.

   139      *

   143     public void open() throws MidiUnavailableException;

   124     void open() throws MidiUnavailableException;

   144 

   125 

   145 

   126     /**

   146     /**

   127      * Closes the device, indicating that the device should now release any

   147      * Closes the device, indicating that the device should now release

   128      * system resources it is using.

   148      * any system resources it is using.

   129      * <p>

   149      *

   130      * All {@code Receiver} and {@code Transmitter} instances open from this

   150      * <p>All <code>Receiver</code> and <code>Transmitter</code> instances

   131      * device are closed. This includes instances retrieved via

   151      * open from this device are closed. This includes instances retrieved

   132      * {@code MidiSystem}.

   152      * via <code>MidiSystem</code>.

   157     public void close();

   137     void close();

   158 

   163      * @return <code>true</code> if the device is open, otherwise

   142      * @return {@code true} if the device is open, otherwise {@code false}

   164      * <code>false</code>

   168     public boolean isOpen();

   146     boolean isOpen();

   169 

   147 

   170 

   148     /**

   171     /**

   149      * Obtains the current time-stamp of the device, in microseconds. If a

   172      * Obtains the current time-stamp of the device, in microseconds.

   150      * device supports time-stamps, it should start counting at 0 when the

   173      * If a device supports time-stamps, it should start counting at

   151      * device is opened and continue incrementing its time-stamp in microseconds

   174      * 0 when the device is opened and continue incrementing its

   152      * until the device is closed. If it does not support time-stamps, it should

   175      * time-stamp in microseconds until the device is closed.

   153      * always return -1.

   176      * If it does not support time-stamps, it should always return

   154      *

   177      * -1.

   155      * @return the current time-stamp of the device in microseconds, or -1 if

   178      * @return the current time-stamp of the device in microseconds,

   156      *         time-stamping is not supported by the device

   179      * or -1 if time-stamping is not supported by the device.

   157      */

   180      */

   158     long getMicrosecondPosition();

   181     public long getMicrosecondPosition();

   159 

   182 

   160     /**

   183 

   161      * Obtains the maximum number of MIDI IN connections available on this MIDI

   184     /**

   162      * device for receiving MIDI data.

   185      * Obtains the maximum number of MIDI IN connections available on this

   163      *

   186      * MIDI device for receiving MIDI data.

   164      * @return maximum number of MIDI IN connections, or -1 if an unlimited

   187      * @return maximum number of MIDI IN connections,

   165      *         number of connections is available

   188      * or -1 if an unlimited number of connections is available.

   166      */

   189      */

   167     int getMaxReceivers();

   190     public int getMaxReceivers();

   168 

   191 

   169     /**

   192 

   170      * Obtains the maximum number of MIDI OUT connections available on this MIDI

   193     /**

   171      * device for transmitting MIDI data.

   194      * Obtains the maximum number of MIDI OUT connections available on this

   172      *

   195      * MIDI device for transmitting MIDI data.

   173      * @return maximum number of MIDI OUT connections, or -1 if an unlimited

   196      * @return maximum number of MIDI OUT connections,

   174      *         number of connections is available

   197      * or -1 if an unlimited number of connections is available.

   175      */

   198      */

   176     int getMaxTransmitters();

   199     public int getMaxTransmitters();

   177 

   200 

   178     /**

   201 

   179      * Obtains a MIDI IN receiver through which the MIDI device may receive MIDI

   202     /**

   180      * data. The returned receiver must be closed when the application has

   203      * Obtains a MIDI IN receiver through which the MIDI device may receive

   181      * finished using it.

   204      * MIDI data.  The returned receiver must be closed when the application

   182      * <p>

   205      * has finished using it.

   183      * Usually the returned receiver implements the {@code MidiDeviceReceiver}

   206      *

   184      * interface.

   207      * <p>Usually the returned receiver implements

   185      * <p>

   208      * the {@code MidiDeviceReceiver} interface.

   186      * Obtaining a {@code Receiver} with this method does not open the device.

   209      *

   187      * To be able to use the device, it has to be opened explicitly by calling

   210      * <p>Obtaining a <code>Receiver</code> with this method does not

   188      * {@link #open}. Also, closing the {@code Receiver} does not close the

   211      * open the device. To be able to use the device, it has to be

   189      * device. It has to be closed explicitly by calling {@link #close}.

   212      * opened explicitly by calling {@link #open}. Also, closing the

   190      *

   213      * <code>Receiver</code> does not close the device. It has to be

   191      * @return a receiver for the device

   214      * closed explicitly by calling {@link #close}.

   215      *

   216      * @return a receiver for the device.

   218      * due to resource restrictions

   193      *         due to resource restrictions

   221     public Receiver getReceiver() throws MidiUnavailableException;

   196     Receiver getReceiver() throws MidiUnavailableException;

   222 

   197 

   223 

   198     /**

   224     /**

   199      * Returns all currently active, non-closed receivers connected with this

   225      * Returns all currently active, non-closed receivers

   200      * MidiDevice. A receiver can be removed from the device by closing it.

   226      * connected with this MidiDevice.

   201      * <p>

   227      * A receiver can be removed

   202      * Usually the returned receivers implement the {@code MidiDeviceReceiver}

   228      * from the device by closing it.

   203      * interface.

   229      *

   230      * <p>Usually the returned receivers implement

   231      * the {@code MidiDeviceReceiver} interface.

   241      * MIDI data  The returned transmitter must be closed when the application

   212      * MIDI data. The returned transmitter must be closed when the application

   243      *

   214      * <p>

   244      * <p>Usually the returned transmitter implements

   215      * Usually the returned transmitter implements the

   245      * the {@code MidiDeviceTransmitter} interface.

   216      * {@code MidiDeviceTransmitter} interface.

   246      *

   217      * <p>

   247      * <p>Obtaining a <code>Transmitter</code> with this method does not

   218      * Obtaining a {@code Transmitter} with this method does not open the

   248      * open the device. To be able to use the device, it has to be

   219      * device. To be able to use the device, it has to be opened explicitly by

   249      * opened explicitly by calling {@link #open}. Also, closing the

   220      * calling {@link #open}. Also, closing the {@code Transmitter} does not

   250      * <code>Transmitter</code> does not close the device. It has to be

   221      * close the device. It has to be closed explicitly by calling

   251      * closed explicitly by calling {@link #close}.

   222      * {@link #close}.

   252      *

   223      *

   253      * @return a MIDI OUT transmitter for the device.

   224      * @return a MIDI OUT transmitter for the device

   255      * due to resource restrictions

   226      *         due to resource restrictions

   258     public Transmitter getTransmitter() throws MidiUnavailableException;

   229     Transmitter getTransmitter() throws MidiUnavailableException;

   259 

   230 

   260 

   231     /**

   261     /**

   232      * Returns all currently active, non-closed transmitters connected with this

   262      * Returns all currently active, non-closed transmitters

   233      * MidiDevice. A transmitter can be removed from the device by closing it.

   263      * connected with this MidiDevice.

   234      * <p>

   264      * A transmitter can be removed

   235      * Usually the returned transmitters implement the

   265      * from the device by closing it.

   236      * {@code MidiDeviceTransmitter} interface.

   266      *

   267      * <p>Usually the returned transmitters implement

   268      * the {@code MidiDeviceTransmitter} interface.

   275 

   243     /**

   276 

   244      * A {@code MidiDevice.Info} object contains assorted data about a

   277     /**

   245      * {@link MidiDevice}, including its name, the company who created it, and

   278      * A <code>MidiDevice.Info</code> object contains assorted

   246      * descriptive text.

   279      * data about a <code>{@link MidiDevice}</code>, including its

   280      * name, the company who created it, and descriptive text.

   284     public static class Info {

   250     class Info {

   310          * @param name the name of the device

   275          * @param  name the name of the device

   311          * @param vendor the name of the company who provides the device

   276          * @param  vendor the name of the company who provides the device

   312          * @param description a description of the device

   277          * @param  description a description of the device

   313          * @param version version information for the device

   278          * @param  version version information for the device

   314          */

   279          */

   315         protected Info(String name, String vendor, String description, String version) {

   280         protected Info(String name, String vendor, String description,

   281                        String version) {

   323 

   289         /**

   324         /**

   290          * Reports whether two objects are equal. Returns {@code true} if the

   325          * Reports whether two objects are equal.

   291          * objects are identical.

   326          * Returns <code>true</code> if the objects are identical.

   292          *

   327          * @param obj the reference object with which to compare this

   293          * @param  obj the reference object with which to compare this object

   328          * object

   294          * @return {@code true} if this object is the same as the {@code obj}

   329          * @return <code>true</code> if this object is the same as the

   295          *         argument; {@code false} otherwise

   330          * <code>obj</code> argument; <code>false</code> otherwise

   384 

   346          *