libjava/classpath/javax/sound/sampled/DataLine.java

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