Source for javax.sound.sampled.DataLine

   1: /* 
   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.sampled;
  40: 
  41: /**
  42:  * The DataLine interface adds data-related functionality to the Line
  43:  * interface.  For example, it adds methods to start and stop the data
  44:  * on the line.
  45:  * @since 1.3 
  46:  */
  47: public interface DataLine extends Line
  48: {
  49:   /**
  50:    * This class extends Line.Info with information specific to DataLine.
  51:    * In particular it adds information about buffer sizes, and about supported
  52:    * audio formats.
  53:    * @since 1.3
  54:    */
  55:   class Info extends Line.Info
  56:   {
  57:     private int minBufferSize;
  58:     private int maxBufferSize;
  59:     private AudioFormat[] formats;
  60: 
  61:     /**
  62:      * Create a new Info given the line's class and a supported
  63:      * audio format.  The buffer sizes default to AudioSystem.NOT_SPECIFIED.
  64:      * @param klass the class of the line
  65:      * @param fmt the supported format
  66:      */
  67:     public Info(Class<?> klass, AudioFormat fmt)
  68:     {
  69:       super(klass);
  70:       this.minBufferSize = AudioSystem.NOT_SPECIFIED;
  71:       this.maxBufferSize = AudioSystem.NOT_SPECIFIED;
  72:       this.formats = new AudioFormat[] { fmt };
  73:     }
  74: 
  75:     /**
  76:      * Create a new Info given the line's class, the supported audio formats,
  77:      * the minimum buffer size, and the maximum buffer size.
  78:      * @param klass the class of the linee
  79:      * @param fmts the supported audio formats
  80:      * @param minSize the minimum buffer size
  81:      * @param maxSize the maximum buffer size
  82:      */
  83:     public Info(Class<?> klass, AudioFormat[] fmts, int minSize, int maxSize)
  84:     {
  85:       super(klass);
  86:       this.minBufferSize = minSize;
  87:       this.maxBufferSize = maxSize;
  88:       this.formats = fmts;
  89:     }
  90: 
  91:     /**
  92:      * Create a new Info given the line's class, a supported
  93:      * audio format, and a buffer size.  Both the minimum and maximum
  94:      * sizes are set from this size.
  95:      * @param klass the class of the line
  96:      * @param fmt the supported format
  97:      * @param size the buffer size
  98:      */
  99:     public Info(Class<?> klass, AudioFormat fmt, int size)
 100:     {
 101:       super(klass);
 102:       this.minBufferSize = size;
 103:       this.maxBufferSize = size;
 104:       this.formats = new AudioFormat[] { fmt };
 105:     }
 106: 
 107:     /**
 108:      * Return the supported audio formats.
 109:      */
 110:     public AudioFormat[] getFormats()
 111:     {
 112:       // FIXME: clone?
 113:       return formats;
 114:     }
 115: 
 116:     /**
 117:      * Return the maximum buffer size.
 118:      */
 119:     public int getMaxBufferSize()
 120:     {
 121:       return maxBufferSize;
 122:     }
 123: 
 124:     /**
 125:      * Return the minimum buffer size.
 126:      */
 127:     public int getMinBufferSize()
 128:     {
 129:       return minBufferSize;
 130:     }
 131: 
 132:     /**
 133:      * Return true if the indicated audio format is supported by this
 134:      * Info, false otherwise.
 135:      * @param fmt the audio format
 136:      * @return true if the format is supported
 137:      */
 138:     public boolean isFormatSupported(AudioFormat fmt)
 139:     {
 140:       for (int i = 0; i < formats.length; ++i)
 141:     {
 142:       if (fmt.matches(formats[i]))
 143:         return true;
 144:     }
 145:       return false;
 146:     }
 147: 
 148:     /**
 149:      * Return true if this Info matches another Info object.
 150:      */
 151:     public boolean matches(Line.Info o)
 152:     {
 153:       if (! super.matches(o) || ! (o instanceof Info))
 154:     return false;
 155:       Info other = (Info) o;
 156:       if (minBufferSize < other.minBufferSize
 157:       || maxBufferSize > other.maxBufferSize)
 158:     return false;
 159:       for (int i = 0; i < formats.length; ++i)
 160:     {
 161:       boolean ok = false;
 162:       for (int j = 0; j < other.formats.length; ++j)
 163:         {
 164:           if (formats[i].matches(other.formats[j]))
 165:         {
 166:           ok = true;
 167:           break;
 168:         }
 169:         }
 170:       if (! ok)
 171:         return false;
 172:     }
 173:       return true;
 174:     }
 175: 
 176:     /**
 177:      * Return a description of this Info object.
 178:      */
 179:     public String toString()
 180:     {
 181:       StringBuffer result = new StringBuffer();
 182:       result.append("formats: [");
 183:       for (int i = 0; i < formats.length; ++i)
 184:     {
 185:       if (i > 0)
 186:         result.append(", ");
 187:       result.append(formats[i].toString());
 188:     }
 189:       result.append("]; minBufferSize: ");
 190:       result.append(minBufferSize);
 191:       result.append("; maxBufferSize: ");
 192:       result.append(maxBufferSize);
 193:       return result.toString();
 194:     }
 195:   }
 196: 
 197:   /**
 198:    * Return the number of bytes currently available on this DataLine.
 199:    */
 200:   int available();
 201: 
 202:   /**
 203:    * This method blocks until whatever data is buffered in the
 204:    * DataLine's internal buffer has been drained.
 205:    */
 206:   void drain();
 207: 
 208:   /**
 209:    * This flushes the DataLine by discarding any buffered data.
 210:    */
 211:   void flush();
 212: 
 213:   /**
 214:    * Returns the size of the DataLine's internal buffer, in bytes.
 215:    */
 216:   int getBufferSize();
 217: 
 218:   /**
 219:    * Return the current format of the data associated with this DataLine.
 220:    */
 221:   AudioFormat getFormat();
 222: 
 223:   /**
 224:    * Return the current frame position.
 225:    */
 226:   int getFramePosition();
 227: 
 228:   /**
 229:    * Return the volume level for this DataLine.
 230:    */
 231:   float getLevel();
 232: 
 233:   /**
 234:    * Return the current frame position. 
 235:    * @since 1.5
 236:    */
 237:   long getLongFramePosition();
 238: 
 239:   /**
 240:    * Return the number of microseconds this DataLine has been playing.
 241:    */
 242:   long getMicrosecondPosition();
 243: 
 244:   /**
 245:    * Return true if this line is active, meaning that it is actively
 246:    * performing audio I/O.
 247:    */
 248:   boolean isActive();
 249: 
 250:   /**
 251:    * Return true if this line is running, meaning that it has been
 252:    * started.  When the line is stopped, this method will return false.
 253:    */
 254:   boolean isRunning();
 255: 
 256:   /**
 257:    * Start processing data.  This will emit a START event.
 258:    */
 259:   void start();
 260: 
 261:   /**
 262:    * Stop processing data.  This will emit a STOP event.
 263:    */
 264:   void stop();
 265: }