001/* An input or output line
002   Copyright (C) 2005, 2012 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.sound.sampled;
040
041/**
042 * A Line represents a single input or output audio line.
043 * @since 1.3
044 */
045public interface Line
046  extends AutoCloseable
047{
048  /**
049   * An object of this type holds information about a Line.
050   * @since 1.3
051   */
052  class Info
053  {
054    private Class<?> klass;
055
056    /**
057     * Create a new Info object.  The argument is the class of the line,
058     * for instance TargetDataLine.class.
059     * @param klass the class of the line
060     */
061    public Info(Class<?> klass)
062    {
063      this.klass = klass;
064    }
065
066    /**
067     * Return the line's class.
068     */
069    public Class<?> getLineClass()
070    {
071      return klass;
072    }
073
074    /**
075     * Return true if this Info object matches the given object.
076     * @param other the object to match
077     * @return true if they match, false otherwise
078     */
079    public boolean matches(Info other)
080    {
081      return klass.equals(other.klass);
082    }
083
084    /**
085     * Return a description of this Info object.
086     */
087    public String toString()
088    {
089      return klass.toString();
090    }
091  }
092
093  /**
094   * Add a listener which will be notified whenever this Line changes state.
095   * @param listener the listener to notify
096   */
097  void addLineListener(LineListener listener);
098
099  /**
100   * Close this line.
101   */
102  void close();
103
104  /**
105   * Return the control associated with this Line that matches the
106   * argument.
107   * @param what the type of the control to match
108   * @return the associated control
109   * @throws IllegalArgumentException if a control of this type is not
110   * available for this line
111   */
112  Control getControl(Control.Type what);
113
114  /**
115   * Return an array of controls associated with this Line.  Note that
116   * this method will not return null -- if there are no controls, it
117   * will return a zero-length array.
118   */
119  Control[] getControls();
120
121  /**
122   * Return the Info object associated with this Line.
123   */
124  Info getLineInfo();
125
126  /**
127   * Return true if a Control matching the argument is available for this
128   * Line, false otherwise.
129   * @param what the type of the control to match
130   */
131  boolean isControlSupported(Control.Type what);
132
133  /**
134   * Return true if this line is open, false otherwise.
135   */
136  boolean isOpen();
137
138  /**
139   * Open this line.
140   * @throws LineUnavailableException if the line is unavailable for some
141   * reason
142   */
143  void open() throws LineUnavailableException;
144
145  /**
146   * Remove the listener from this Line; after this call the listener will
147   * no longer be notified when this Line changes state.
148   * @param listener the listener to remove
149   */
150  void removeLineListener(LineListener listener);
151}