Package org.zkoss.sound

## Class AAudio

- java.lang.Object
- - org.zkoss.sound.AAudio

- All Implemented Interfaces:
    `java.io.Serializable`, `Audio`, `Media`

      public class AAudio
      extends java.lang.Object
      implements Audio, java.io.Serializable

  Represents an audio. Unlike javax.sound.AudioClip, this class is used only to hold the raw data as opaque rather than manipulate the sound.

  In other words, it is used to retrieve and store the opaque data as polymorphic thru the `Media` interface.

  AAudio is serializable, but, if you are using InputStream, you have to extend this class, and provide the implementation to serialize and deserialize `_isdata`. (Since 5.0.11)

  Author:
    tomyeh
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.io.InputStream` | `_isdata` | The raw data in stream (or `DYNAMIC_STREAM`).
    `protected static java.io.InputStream` | `DYNAMIC_STREAM` | Used if you want to implement a media whose input stream is created dynamically each time `getStreamData()` is called.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AAudio​(java.io.File file)` | Constructs an audio with a file.
    `AAudio​(java.io.InputStream is)` | Creates an instance of an audio with an input stream.
    `AAudio​(java.lang.String filename)` | Constructs an audio with a file name.
    `AAudio​(java.lang.String name, byte[] data)` |
    `AAudio​(java.lang.String name, java.io.InputStream isdata)` | Creates an instance of an audio with an input stream.
    `AAudio​(java.net.URL url)` | Constructs an audio with an URL.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `byte[]` | `getByteData()` | Returns the raw data in byte array.
    `java.lang.String` | `getContentType()` | Returns the content type, e.g., "image/jpeg", or null if not available.
    `java.lang.String` | `getFormat()` | Returns the format name, e.g., "jpeg", or null if not available.
    `java.lang.String` | `getName()` | Returns the name (usually filename) of this media, or null if not available.
    `java.io.Reader` | `getReaderData()` | Not supported.
    `java.io.InputStream` | `getStreamData()` | Returns the data in the input stream.
    `java.lang.String` | `getStringData()` | Always throws IllegalStateException.
    `boolean` | `inMemory()` | Returns whether the data is cached in memory (in form of byte[] or String).
    `boolean` | `isBinary()` | Returns whether the format of this content is binary or text-based.
    `boolean` | `isContentDisposition()` | Whether to allow Content-Disposition or not when writing the media to response header.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DYNAMIC_STREAM

          protected static final java.io.InputStream DYNAMIC_STREAM

      Used if you want to implement a media whose input stream is created dynamically each time `getStreamData()` is called.

    - #### _isdata

          protected final transient java.io.InputStream _isdata

      The raw data in stream (or `DYNAMIC_STREAM`). Exactly one of `_data` and `_isdata` is not null.

  - ### Constructor Detail

    - #### AAudio

          public AAudio​(java.lang.String name,
                        byte[] data)
                 throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### AAudio

          public AAudio​(java.lang.String name,
                        java.io.InputStream isdata)
                 throws java.io.IOException

      Creates an instance of an audio with an input stream. If the stream shall be created each time `getStreamData()` is called, you can pass `DYNAMIC_STREAM` to the data argument, and then override `getStreamData()`.

      Note: the caller of `getStreamData()` has to close the returned input stream.

      Throws:
        `java.io.IOException`

    - #### AAudio

          public AAudio​(java.net.URL url)

      Constructs an audio with an URL.

    - #### AAudio

          public AAudio​(java.io.File file)

      Constructs an audio with a file.

    - #### AAudio

          public AAudio​(java.lang.String filename)
                 throws java.io.IOException

      Constructs an audio with a file name.
      Throws:
        `java.io.IOException`

    - #### AAudio

          public AAudio​(java.io.InputStream is)
                 throws java.io.IOException

      Creates an instance of an audio with an input stream. If the stream shall be created each time `getStreamData()` is called, you can pass `DYNAMIC_STREAM` to the data argument, and then override `getStreamData()`.

      Note: the caller of `getStreamData()` has to close the returned input stream.

      Throws:
        `java.io.IOException`

  - ### Method Detail

    - #### isBinary

          public final boolean isBinary()

      Description copied from interface: `Media`
      Returns whether the format of this content is binary or text-based. If true, use `Media.getByteData()` or `Media.getStreamData()` to retrieve its content. If false, use `Media.getStringData()` or `Media.getReaderData()` to retrieve its content.
      Specified by:
        `isBinary` in interface `Media`
      See Also:
        `Media.getStringData()`, `Media.getByteData()`, `Media.getReaderData()`, `Media.getStreamData()`

    - #### inMemory

          public final boolean inMemory()

      Description copied from interface: `Media`
      Returns whether the data is cached in memory (in form of byte[] or String).
      Specified by:
        `inMemory` in interface `Media`
      See Also:
        `Media.getStringData()`, `Media.getByteData()`, `Media.getReaderData()`, `Media.getStreamData()`

    - #### getByteData

          public byte[] getByteData()

      Description copied from interface: `Media`
      Returns the raw data in byte array.

      It might not be a copy, so don't modify it directly unless you know what you are doing.

      If the data is not cached in memory (`Media.inMemory()` return false), the data will be read from `Media.getStreamData()`. Furthermore, it also implies you can not invoke this method again.

      Specified by:
        `getByteData` in interface `Media`
      See Also:
        `Media.getStringData()`

    - #### getStringData

          public final java.lang.String getStringData()

      Always throws IllegalStateException.
      Specified by:
        `getStringData` in interface `Media`
      See Also:
        `Media.getByteData()`

    - #### getStreamData

          public java.io.InputStream getStreamData()

      Returns the data in the input stream.

      Note: the caller has to invoke `InputStream.close()` after using the input stream returned by `getStreamData()`.

      Specified by:
        `getStreamData` in interface `Media`
      See Also:
        `Media.getReaderData()`

    - #### getReaderData

          public final java.io.Reader getReaderData()

      Not supported. It always throws IllegalStateException.
      Specified by:
        `getReaderData` in interface `Media`
      See Also:
        `Media.getStreamData()`

    - #### getName

          public final java.lang.String getName()

      Description copied from interface: `Media`
      Returns the name (usually filename) of this media, or null if not available.
      Specified by:
        `getName` in interface `Media`

    - #### getFormat

          public java.lang.String getFormat()

      Description copied from interface: `Media`
      Returns the format name, e.g., "jpeg", or null if not available.
      Specified by:
        `getFormat` in interface `Media`
      See Also:
        `Media.getContentType()`

    - #### getContentType

          public java.lang.String getContentType()

      Description copied from interface: `Media`
      Returns the content type, e.g., "image/jpeg", or null if not available.
      Specified by:
        `getContentType` in interface `Media`
      See Also:
        `Media.getFormat()`

    - #### isContentDisposition

          public boolean isContentDisposition()

      Description copied from interface: `Media`
      Whether to allow Content-Disposition or not when writing the media to response header.

      Default: true

      Specified by:
        `isContentDisposition` in interface `Media`