Package org.zkoss.image

## Class AImage

- java.lang.Object
- - org.zkoss.image.AImage

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

      public class AImage
      extends java.lang.Object
      implements Image, java.io.Serializable

  Represents an image. Unlike java.awt.Image and javax.swing.ImageIcon, this class holds the raw image data, i.e., the original format, as opaque.

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

  To encode AWT image to an instance of `Image`, use `Images.encode(java.lang.String, java.awt.image.RenderedImage, float, boolean)`.

  Author:
    tomyeh
  See Also:
    `Images.encode(java.lang.String, java.awt.image.RenderedImage, float, boolean)`, Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AImage​(java.io.File file)` | Constructs an image with a file.
    `AImage​(java.lang.String filename)` | Constructs an image with a file name.
    `AImage​(java.lang.String name, byte[] data)` | Constructs an image with a byte array.
    `AImage​(java.lang.String name, java.io.InputStream is)` | Constructs an image with an input stream.
    `AImage​(java.net.URL url)` | Constructs an image 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.
    `int` | `getHeight()` | Returns the height.
    `java.lang.String` | `getName()` | Returns the name (usually filename) of this media, or null if not available.
    `java.io.Reader` | `getReaderData()` | Always throws `IllegalStateException`.
    `java.io.InputStream` | `getStreamData()` | Return a `ByteArrayInputStream` that contains data of `getByteData()`.
    `java.lang.String` | `getStringData()` | Always throws `IllegalStateException`.
    `int` | `getWidth()` | Returns the width.
    `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.
    `javax.swing.ImageIcon` | `toImageIcon()` | Converts to an image icon.

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

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

- - ### Constructor Detail

    - #### AImage

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

      Constructs an image with a byte array.
      Throws:
        `java.io.IOException`

    - #### AImage

          public AImage​(java.lang.String name,
                        java.io.InputStream is)
                 throws java.io.IOException

      Constructs an image with an input stream.

      Note that this method automatically closes the input stream (since ZK 3.0.0).

      Throws:
        `java.io.IOException`

    - #### AImage

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

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

    - #### AImage

          public AImage​(java.io.File file)
                 throws java.io.IOException

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

    - #### AImage

          public AImage​(java.net.URL url)
                 throws java.io.IOException

      Constructs an image with an URL.
      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 final java.io.InputStream getStreamData()

      Return a `ByteArrayInputStream` that contains data of `getByteData()`.

      Though harmless, the caller doesn't need to close the returned stream.

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

    - #### getReaderData

          public final java.io.Reader getReaderData()

      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 final 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 final 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()`

    - #### getWidth

          public final int getWidth()

      Returns the width.
      Specified by:
        `getWidth` in interface `Image`

    - #### getHeight

          public final int getHeight()

      Returns the height.
      Specified by:
        `getHeight` in interface `Image`

    - #### toImageIcon

          public final javax.swing.ImageIcon toImageIcon()

      Converts to an image icon.
      Specified by:
        `toImageIcon` in interface `Image`

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