Line (Java 2 Platform SE v1.4.1_"07")

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.sound.sampled
Interface Line

All Known Subinterfaces:
  Clip, DataLine, Mixer, Port, SourceDataLine, TargetDataLine

public interface Line

The `Line` interface represents a mono or multi-channel audio feed. A line is an element of the digital audio "pipeline," such as a mixer, an input or output port, or a data path into or out of a mixer.

A line can have controls, such as gain, pan, and reverb. The controls themselves are instances of classes that extend the base ``Control`` class. The `Line` interface provides two accessor methods for obtaining the line's controls: ``getControls`` returns the entire set, and ``getControl`` returns a single control of specified type.

Lines exist in various states at different times. When a line opens, it reserves system resources for itself, and when it closes, these resources are freed for other objects or applications. The ``isOpen()`` method lets you discover whether a line is open or closed. An open line need not be processing data, however. Such processing is typically initiated by subinterface methods such as ``SourceDataLine.write`` and ``TargetDataLine.read``.

You can register an object to receive notifications whenever the line's state changes. The object must implement the ``LineListener`` interface, which consists of the single method ``update``. This method will be invoked when a line opens and closes (and, if it's a `DataLine`, when it starts and stops).

An object can be registered to listen to multiple lines. The event it receives in its `update` method will specify which line created the event, what type of event it was (`OPEN`, `CLOSE`, `START`, or `STOP`), and how many sample frames the line had processed at the time the event occurred.

Certain line operations, such as open and close, can generate security exceptions if invoked by unprivileged code when the line is a shared audio resource.

Since:
  1.3
See Also:
  `LineEvent`

Nested Class Summary
`static class` | `Line.Info` A `Line.Info` object contains information about a line.

Method Summary
`void` | `addLineListener(LineListener listener)` Adds a listener to this line.
`void` | `close()` Closes the line, indicating that any system resources in use by the line can be released.
`Control` | `getControl(Control.Type control)` Obtains a control of the specified type, if there is any.
`Control[]` | `getControls()` Obtains the set of controls associated with this line.
`Line.Info` | `getLineInfo()` Obtains the `Line.Info` object describing this line.
`boolean` | `isControlSupported(Control.Type control)` Indicates whether the line supports a control of the specified type.
`boolean` | `isOpen()` Indicates whether the line is open, meaning that it has reserved system resources and is operational, although it might not currently be playing or capturing sound.
`void` | `open()` Opens the line, indicating that it should acquire any required system resources and become operational.
`void` | `removeLineListener(LineListener listener)` Removes the specified listener from this line's list of listeners.

Method Detail

### getLineInfo

    public Line.Info getLineInfo()

  Obtains the `Line.Info` object describing this line.

  Returns:
    description of the line

### open

    public void open()
              throws LineUnavailableException

  Opens the line, indicating that it should acquire any required system resources and become operational. If this operation succeeds, the line is marked as open, and an `OPEN` event is dispatched to the line's listeners.

  Note that some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in an `LineUnavailableException`.

  Some types of lines have configurable properties that may affect resource allocation. For example, a `DataLine` must be opened with a particular format and buffer size. Such lines should provide a mechanism for configuring these properties, such as an additional `open` method or methods which allow an application to specify the desired settings.

  This method takes no arguments, and opens the line with the current settings. For ``SourceDataLine`` and ``TargetDataLine`` objects, this means that the line is opened with default settings. For a ``Clip``, however, the buffer size is determined when data is loaded. Since this method does not allow the application to specify any data to load, it allocates resources for a clip with zero frames of data, and there is no means for subsequently loading data into that clip. Therefore, you should instead use one of the `open` methods provided in the `Clip` interface to load data into the `Clip`.

  Throws:
    `LineUnavailableException` - if the line cannot be opened due to resource restrictions.
    `SecurityException` - if the line cannot be opened due to security restrictions.
  See Also:
    `close()`, `isOpen()`, `LineEvent`, `DataLine`, `Clip.open(AudioFormat, byte[], int, int)`, `Clip.open(AudioInputStream)`

### close

    public void close()

  Closes the line, indicating that any system resources in use by the line can be released. If this operation succeeds, the line is marked closed and a `CLOSE` event is dispatched to the line's listeners.

  Throws:
    `SecurityException` - if the line cannot be closed due to security restrictions.
  See Also:
    `open()`, `isOpen()`, `LineEvent`

### isOpen

    public boolean isOpen()

  Indicates whether the line is open, meaning that it has reserved system resources and is operational, although it might not currently be playing or capturing sound.

  Returns:
    `true` if the line is open, otherwise `false`
  See Also:
    `open()`, `close()`

### getControls

    public Control[] getControls()

  Obtains the set of controls associated with this line. Some controls may only be available when the line is open. If there are no controls, this method returns an array of length 0.

  Returns:
    the array of controls
  See Also:
    `getControl(javax.sound.sampled.Control.Type)`

### isControlSupported

    public boolean isControlSupported(Control.Type control)

  Indicates whether the line supports a control of the specified type. Some controls may only be available when the line is open.

  Parameters:
    `control` - the type of the control for which support is queried
  Returns:
    `true` if at least one control of the specified type is supported, otherwise `false`.

### getControl

    public Control getControl(Control.Type control)

  Obtains a control of the specified type, if there is any. Some controls may only be available when the line is open.

  Parameters:
    `control` - the type of the requested control
  Returns:
    a control of the specified type
  Throws:
    `IllegalArgumentException` - if a control of the specified type is not supported
  See Also:
    `getControls()`, `isControlSupported(Control.Type control)`

### addLineListener

    public void addLineListener(LineListener listener)

  Adds a listener to this line. Whenever the line's status changes, the listener's `update()` method is called with a `LineEvent` object that describes the change.

  Parameters:
    `listener` - the object to add as a listener to this line
  See Also:
    `removeLineListener(javax.sound.sampled.LineListener)`, `LineListener.update(javax.sound.sampled.LineEvent)`, `LineEvent`

### removeLineListener

    public void removeLineListener(LineListener listener)

  Removes the specified listener from this line's list of listeners.

  Parameters:
    `listener` - listener to remove
  See Also:
    `addLineListener(javax.sound.sampled.LineListener)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.