Package org.zkoss.util.media

## Class AMedia

- java.lang.Object
- - org.zkoss.util.media.AMedia

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

      public class AMedia
      extends java.lang.Object
      implements Media, java.io.Serializable

  A media object holding content such PDF, HTML, DOC or XLS content.

  AMedia is serializable, but, if you are using InputStream or Reader, you have to extend this class, and provide the implementation to serialize and deserialize `_isdata` or `_rddata` (they are both transient).

  Author:
    tomyeh
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.io.InputStream` | `_isdata` | The input stream, `getStreamData()`
    `protected java.io.Reader` | `_rddata` | The input stream, `getReaderData()`
    `protected static java.io.Reader` | `DYNAMIC_READER` | Used if you want to implement a media whose reader is created dynamically each time `getReaderData()` is called.
    `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
    --- | ---
    `AMedia​(java.io.File file, java.lang.String ctype, java.lang.String charset)` | Construct with a file.
    `AMedia​(java.lang.String name, java.lang.String format, java.lang.String ctype, byte[] data)` | Construct with name, format, content type and binary data.
    `AMedia​(java.lang.String name, java.lang.String format, java.lang.String ctype, java.io.File file, boolean binary)` | Construct with name, format, content type and a file.
    `AMedia​(java.lang.String name, java.lang.String format, java.lang.String ctype, java.io.File file, java.lang.String charset)` | Construct with name, format, content type and a file.
    `AMedia​(java.lang.String name, java.lang.String format, java.lang.String ctype, java.io.InputStream data)` | Construct with name, format, content type and stream data (binary).
    `AMedia​(java.lang.String name, java.lang.String format, java.lang.String ctype, java.io.Reader data)` | Construct with name, format, content type and reader data (textual).
    `AMedia​(java.lang.String name, java.lang.String format, java.lang.String ctype, java.lang.String data)` | Construct with name, format, content type and text data.
    `AMedia​(java.lang.String name, java.lang.String format, java.lang.String ctype, java.net.URL url, java.lang.String charset)` | Construct with name, format, content type and URL.
    `AMedia​(java.net.URL url, java.lang.String ctype, java.lang.String charset)` | Construct with a file.

  - ### 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()` | Returns the reader of this media to retrieve the data.
    `java.io.InputStream` | `getStreamData()` | Returns the input stream of this media.
    `java.lang.String` | `getStringData()` | Returns the raw data in string.
    `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.
    `void` | `setContentDisposition​(boolean cntDisposition)` | Set whether to allow Content-Disposition or not when writing the media to response header.
    `java.lang.String` | `toString()` |

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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.
      See Also:
        `AMedia(String,String,String,InputStream)`

    - #### DYNAMIC_READER

          protected static final java.io.Reader DYNAMIC_READER

      Used if you want to implement a media whose reader is created dynamically each time `getReaderData()` is called.
      See Also:
        `AMedia(String,String,String,Reader)`

    - #### _isdata

          protected transient java.io.InputStream _isdata

      The input stream, `getStreamData()`

    - #### _rddata

          protected transient java.io.Reader _rddata

      The input stream, `getReaderData()`

  - ### Constructor Detail

    - #### AMedia

          public AMedia​(java.lang.String name,
                        java.lang.String format,
                        java.lang.String ctype,
                        byte[] data)

      Construct with name, format, content type and binary data.

      It tries to construct format and ctype from each other or name.

      Parameters:
        `name` - the name (usually filename); might be null.
        `format` - the format; might be null. Example: "html" and "xml"
        `ctype` - the content type; might be null. Example: "text/html" and "text/xml;charset=UTF-8".
        `data` - the binary data; never null

    - #### AMedia

          public AMedia​(java.lang.String name,
                        java.lang.String format,
                        java.lang.String ctype,
                        java.lang.String data)

      Construct with name, format, content type and text data.

      It tries to construct format and ctype from each other or name.

      Parameters:
        `name` - the name (usually filename); might be null.
        `format` - the format; might be null.
        `ctype` - the content type; might be null.
        `data` - the text data; never null

    - #### AMedia

          public AMedia​(java.lang.String name,
                        java.lang.String format,
                        java.lang.String ctype,
                        java.io.InputStream data)

      Construct with name, format, content type and stream data (binary).

      It tries to construct format and ctype from each other or name.

      Parameters:
        `name` - the name (usually filename); might be null.
        `format` - the format; might be null.
        `ctype` - the content type; might be null.
        `data` - the binary data; never null. If the input stream is created dynamically each time `getStreamData()` is called, you shall pass `DYNAMIC_STREAM` as the data argument. Then, override `getStreamData()` to return the correct stream. Note: the caller of `getStreamData()` has to close the returned input stream.

    - #### AMedia

          public AMedia​(java.lang.String name,
                        java.lang.String format,
                        java.lang.String ctype,
                        java.io.Reader data)

      Construct with name, format, content type and reader data (textual).

      It tries to construct format and ctype from each other or name.

      Parameters:
        `name` - the name (usually filename); might be null.
        `format` - the format; might be null.
        `ctype` - the content type; might be null.
        `data` - the string data; never null If the reader is created dynamically each time `getReaderData()` is called, you shall pass `DYNAMIC_READER` as the data argument. Then, override `getReaderData()` to return the correct reader.

    - #### AMedia

          public AMedia​(java.lang.String name,
                        java.lang.String format,
                        java.lang.String ctype,
                        java.io.File file,
                        boolean binary)
                 throws java.io.FileNotFoundException

      Construct with name, format, content type and a file.

      Unlike others, it uses the so-called repeatable input stream or reader (depending on binary or not) to represent the file, so the input stream (`getStreamData()`) or the reader (`getReaderData()`) will be re-opened in the next invocation of `InputStream.read()` after `InputStream.close()` is called. See also `RepeatableInputStream` and `RepeatableReader`.

      Parameters:
        `name` - the name (usually filename); might be null. If null, the file name is used.
        `format` - the format; might be null.
        `ctype` - the content type; might be null.
        `file` - the file; never null.
        `binary` - whether it is binary. If not binary, "UTF-8" is assumed.
      Throws:
        `java.io.FileNotFoundException`

    - #### AMedia

          public AMedia​(java.lang.String name,
                        java.lang.String format,
                        java.lang.String ctype,
                        java.io.File file,
                        java.lang.String charset)
                 throws java.io.FileNotFoundException

      Construct with name, format, content type and a file.

      Unlike others, it uses the so-called repeatable input stream or reader (depending on charset is null or not) to represent the file, so the input stream (`getStreamData()`) or the reader (`getReaderData()`) will be re-opened in the next invocation of `InputStream.read()` after `InputStream.close()` is called. See also `RepeatableInputStream` and `RepeatableReader`.

      Parameters:
        `name` - the name (usually filename); might be null. If null, the file name is used.
        `format` - the format; might be null.
        `ctype` - the content type; might be null.
        `file` - the file; never null.
        `charset` - the charset. If null, it is assumed to be binary.
      Throws:
        `java.io.FileNotFoundException`

    - #### AMedia

          public AMedia​(java.io.File file,
                        java.lang.String ctype,
                        java.lang.String charset)
                 throws java.io.FileNotFoundException

      Construct with a file. It is the same as AMedia(null, null, ctype, file, charset).
      Parameters:
        `ctype` - the content type; might be null. If null, it is retrieved from the file name's extension.
      Throws:
        `java.io.FileNotFoundException`
      Since:
        3.0.8

    - #### AMedia

          public AMedia​(java.lang.String name,
                        java.lang.String format,
                        java.lang.String ctype,
                        java.net.URL url,
                        java.lang.String charset)
                 throws java.io.FileNotFoundException

      Construct with name, format, content type and URL.

      Unlike others, it uses the so-called repeatable input stream or reader (depending on charset is null or not) to represent the resource, so the input stream (`getStreamData()`) or the reader (`getReaderData()`) will be re-opened in the next invocation of `InputStream.read()` after `InputStream.close()` is called. See also `RepeatableInputStream` and `RepeatableReader`.

      Parameters:
        `name` - the name; might be null. If null, URL's name is used.
        `format` - the format; might be null.
        `ctype` - the content type; might be null.
        `url` - the resource URL; never null.
      Throws:
        `java.io.FileNotFoundException`
      Since:
        3.0.8

    - #### AMedia

          public AMedia​(java.net.URL url,
                        java.lang.String ctype,
                        java.lang.String charset)
                 throws java.io.FileNotFoundException

      Construct with a file. It is the same as AMedia(null, null, ctype, url, charset).
      Parameters:
        `ctype` - the content type; might be null. If null, it is retrieved from the file name's extension.
      Throws:
        `java.io.FileNotFoundException`
      Since:
        3.0.8

  - ### Method Detail

    - #### setContentDisposition

          public void setContentDisposition​(boolean cntDisposition)

      Set whether to allow Content-Disposition or not when writing the media to response header.
      Since:
        7.0.0

    - #### isBinary

          public 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 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 java.lang.String getStringData()

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

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

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

    - #### getStreamData

          public java.io.InputStream getStreamData()

      Returns the input stream of this media.

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

      It wraps `getByteData()` with `ByteArrayInputStream` if `inMemory()` returns true.

      Specified by:
        `getStreamData` in interface `Media`
      Throws:
        `java.lang.IllegalStateException` - if the media `isBinary()` returns false
      See Also:
        `Media.getReaderData()`

    - #### getReaderData

          public java.io.Reader getReaderData()

      Returns the reader of this media to retrieve the data.

      Note: the caller has to invoke `Reader.close()` after using the input stream returned by this method.

      It wraps `getStringData()` with `StringReader`, if `inMemory()` returns true.

      Specified by:
        `getReaderData` in interface `Media`
      Throws:
        `java.lang.IllegalStateException` - if `isBinary()` returns true
      See Also:
        `Media.getStreamData()`

    - #### getName

          public 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`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`