Source for javax.sound.sampled.DataLine

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