Source for javax.sound.midi.MidiDevice

   1: /* MidiDevice.java -- Interface for MIDI devices
   2:    Copyright (C) 2005 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package javax.sound.midi;
  40: 
  41: /**
  42:  * Interface for all MIDI devices.
  43:  * 
  44:  * @author Anthony Green (green@redhat.com)
  45:  * @since 1.3
  46:  *
  47:  */
  48: public interface MidiDevice
  49: {
  50:   /**
  51:    * Get the Info object describing this device.
  52:    * @return the Info object describing this device
  53:    */
  54:   public Info getDeviceInfo();
  55:   
  56:   /**
  57:    * Open this MIDI device and allocate any system resource we need.
  58:    * 
  59:    * @throws MidiUnavailableException if we're not able to open for some reason
  60:    */
  61:   public void open() throws MidiUnavailableException;
  62:   
  63:   /**
  64:    * Close this MIDI device, and release any system resources we're using.
  65:    */
  66:   public void close();
  67:   
  68:   /**
  69:    * Returns true if this MIDI device is open and false otherwise.
  70:    * 
  71:    * @return true if this is open, false otherwise
  72:    */
  73:   public boolean isOpen();
  74:   
  75:   /**
  76:    * If this device supports time-stamps, then it will return the number
  77:    * of microseconds since this device has been open, and -1 otherwise.
  78:    * 
  79:    * @return -1 or the number of microseconds since this was opened
  80:    */
  81:   public long getMicrosecondPosition();
  82:   
  83:   /**
  84:    * The maximum number of MIDI IN connections we can get as Receivers,
  85:    * or -1 if there is no maximum.
  86:    * 
  87:    * @return -1 or the maximum number of Receivers we can get
  88:    */
  89:   public int getMaxReceivers();
  90:   
  91:   /**
  92:    * The maximum number of MIDI OUT connections we can get as Transmitters,
  93:    * or -1 if there is no maximum.
  94:    * 
  95:    * @return -1 or the maximum number of Transmitters we can get
  96:    */
  97:   public int getMaxTransmitters();
  98:   
  99:   /**
 100:    * Get a MIDI IN Receiver for this device.
 101:    * 
 102:    * @return a MIDI IN Receiver for this device
 103:    * @throws MidiUnavailableException if we can't get a Receiver
 104:    */
 105:   public Receiver getReceiver() throws MidiUnavailableException;
 106:   
 107:   /**
 108:    * Get a MIDI OUT Transmitter for this device.
 109:    * 
 110:    * @return a MIDI OUT Transmitter for this device
 111:    * @throws MidiUnavailableException if we can't get a Transmitter
 112:    */
 113:   public Transmitter getTransmitter() throws MidiUnavailableException;
 114:   
 115:   /**
 116:    * A MIDI device descriptor object.
 117:    * 
 118:    * @author green@redhat.com
 119:    *
 120:    */
 121:   public static class Info
 122:   {
 123:     // Private data describing this device
 124:     private String name;
 125:     private String vendor;
 126:     private String description;
 127:     private String version;
 128:     
 129:     /**
 130:      * Create an Info object for a MIDI device
 131:      * 
 132:      * @param name the device name
 133:      * @param vendor the vendor name
 134:      * @param description the device description
 135:      * @param version the device version string
 136:      */
 137:     protected Info(String name, String vendor, String description, String version)
 138:     {
 139:       this.name = name;
 140:       this.vendor = vendor;
 141:       this.description = description;
 142:       this.version = version;
 143:     }
 144:     
 145:     /**
 146:      * This equals method only returns true if this object
 147:      * is the same as obj.
 148:      * 
 149:      * @param obj the object we're comparing to
 150:      * @return true if this is the same object
 151:      * @see java.lang.Object#equals(java.lang.Object)
 152:      */
 153:     public final boolean equals(Object obj)
 154:     {
 155:       return super.equals(obj);
 156:     }
 157:   
 158:     /**
 159:      * A hash code for this object.
 160:      *     
 161:      * @return the hash code for this object
 162:      * @see java.lang.Object#hashCode()
 163:      */
 164:     public final int hashCode()
 165:     {
 166:       return super.hashCode();
 167:     }
 168:   
 169:     /**
 170:      * Get the device name.
 171:      * 
 172:      * @return the device name
 173:      */
 174:     public final String getName()
 175:     {
 176:       return name;
 177:     }
 178:     
 179:     /**
 180:      * Get the device vendor.
 181:      * 
 182:      * @return the device vendor
 183:      */
 184:     public final String getVendor()
 185:     {
 186:       return vendor;
 187:     }
 188:     
 189:     /**
 190:      * Get the device description
 191:      * 
 192:      * @return the device description
 193:      */
 194:     public final String getDescription()
 195:     {
 196:       return description;
 197:     }
 198:     
 199:     /**
 200:      * get the device version
 201:      * 
 202:      * @return the device version
 203:      */
 204:     public final String getVersion()
 205:     {
 206:       return version;
 207:     }
 208:     
 209:     /**
 210:      * Simple return the name of the device.
 211:      * 
 212:      * @return the device name
 213:      * @see java.lang.Object#toString()
 214:      */
 215:     public final String toString()
 216:     {
 217:       return name;
 218:     }
 219:   }
 220: }