com.google.appengine.api.images

## Interface ImagesService

-     public interface ImagesService

  The images service provides methods to apply transformations to images.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `ImagesService.OutputEncoding` Valid output encoding formats usable for image transforms.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `MAX_COMPOSITES_PER_REQUEST`
    `static int` | `MAX_RESIZE_DIMENSIONS`
    `static int` | `MAX_TRANSFORMS_PER_REQUEST`
    `static java.util.Set<java.lang.Integer>` | `SERVING_CROP_SIZES` Deprecated.
    `static java.util.Set<java.lang.Integer>` | `SERVING_SIZES` Deprecated.
    `static int` | `SERVING_SIZES_LIMIT`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Image` | `applyTransform(Transform transform, Image image)` Applies the provided `transform` to the provided `image` encoding the transformed image stored using PNG file format.
    `Image` | `applyTransform(Transform transform, Image image, ImagesService.OutputEncoding encoding)` Applies the provided `transform` to the provided `image` encoding the transformed image stored using `encoding` file format.
    `Image` | `applyTransform(Transform transform, Image image, InputSettings inputSettings, OutputSettings outputSettings)` Applies the provided `transform` to the provided `image` encoding the transformed image stored using `outputSettings` interpreting `image` according to `inputSettings`.
    `Image` | `applyTransform(Transform transform, Image image, OutputSettings settings)` Applies the provided `transform` to the provided `image` encoding the transformed image stored using `settings`.
    `java.util.concurrent.Future<Image>` | `applyTransformAsync(Transform transform, Image image)` Asynchronously applies the provided `transform` to the provided `image` encoding the transformed image stored using PNG file format.
    `java.util.concurrent.Future<Image>` | `applyTransformAsync(Transform transform, Image image, ImagesService.OutputEncoding encoding)` Asynchronously applies the provided `transform` to the provided `image` encoding the transformed image stored using `encoding` file format.
    `java.util.concurrent.Future<Image>` | `applyTransformAsync(Transform transform, Image image, InputSettings inputSettings, OutputSettings outputSettings)` Asynchronously applies the provided `transform` to the provided `image` encoding the transformed image stored using `settings` interpreting `image` according to `inputSettings`.
    `java.util.concurrent.Future<Image>` | `applyTransformAsync(Transform transform, Image image, OutputSettings settings)` Asynchronously applies the provided `transform` to the provided `image` encoding the transformed image stored using `settings`.
    `Image` | `composite(java.util.Collection<Composite> composites, int width, int height, long color)` Applies the provided `Collection` of `Composite`s using a canvas with dimensions determined by `width` and `height` and background color `color`.
    `Image` | `composite(java.util.Collection<Composite> composites, int width, int height, long color, ImagesService.OutputEncoding encoding)` Applies the provided `Collection` of `Composite`s using a canvas with dimensions determined by `width` and `height` and background color `color`.
    `Image` | `composite(java.util.Collection<Composite> composites, int width, int height, long color, OutputSettings settings)` Applies the provided `Collection` of `Composite`s using a canvas with dimensions determined by `width` and `height` and background color `color`.
    `void` | `deleteServingUrl(BlobKey blobKey)` Deletes a URL that was previously generated by `getServingUrl(BlobKey)`.
    `java.lang.String` | `getServingUrl(BlobKey blobKey)` Deprecated. Replaced by `getServingUrl(ServingUrlOptions)`.
    `java.lang.String` | `getServingUrl(BlobKey blobKey, boolean secureUrl)` Deprecated. Replaced by `getServingUrl(ServingUrlOptions)`.
    `java.lang.String` | `getServingUrl(BlobKey blobKey, int imageSize, boolean crop)` Deprecated. Replaced by `getServingUrl(ServingUrlOptions)`.
    `java.lang.String` | `getServingUrl(BlobKey blobKey, int imageSize, boolean crop, boolean secureUrl)` Deprecated. Replaced by `getServingUrl(ServingUrlOptions)`.
    `java.lang.String` | `getServingUrl(ServingUrlOptions options)` Obtains a URL that can dynamically serve the image stored as a blob.
    `int[][]` | `histogram(Image image)` Calculates the histogram of the image.

- - ### Field Detail

    - #### MAX_TRANSFORMS_PER_REQUEST

          static final int MAX_TRANSFORMS_PER_REQUEST

      See Also:
        Constant Field Values

    - #### MAX_RESIZE_DIMENSIONS

          static final int MAX_RESIZE_DIMENSIONS

      See Also:
        Constant Field Values

    - #### MAX_COMPOSITES_PER_REQUEST

          static final int MAX_COMPOSITES_PER_REQUEST

      See Also:
        Constant Field Values

    - #### SERVING_SIZES_LIMIT

          static final int SERVING_SIZES_LIMIT

      See Also:
        Constant Field Values

    - #### SERVING_SIZES

          @Deprecated
          static final java.util.Set<java.lang.Integer> SERVING_SIZES

      Deprecated.

    - #### SERVING_CROP_SIZES

          @Deprecated
          static final java.util.Set<java.lang.Integer> SERVING_CROP_SIZES

      Deprecated.

  - ### Method Detail

    - #### applyTransform

          Image applyTransform(Transform transform,
                               Image image)

      Applies the provided `transform` to the provided `image` encoding the transformed image stored using PNG file format. The transform is applied in place to the provided image.
      Parameters:
        `transform` - transform to be applied
        `image` - image to be transformed
      Returns:
        transformed image
      Throws:
        `java.lang.IllegalArgumentException` - If `transform` or `image` are invalid.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### applyTransformAsync

          java.util.concurrent.Future<Image> applyTransformAsync(Transform transform,
                                                                 Image image)

      Asynchronously applies the provided `transform` to the provided `image` encoding the transformed image stored using PNG file format. The transform is applied in place to the provided image.
      Parameters:
        `transform` - transform to be applied
        `image` - image to be transformed
      Returns:
        A future containing the transformed image or one of the exceptions documented for `applyTransform(Transform, Image)`.

    - #### applyTransform

          Image applyTransform(Transform transform,
                               Image image,
                               ImagesService.OutputEncoding encoding)

      Applies the provided `transform` to the provided `image` encoding the transformed image stored using `encoding` file format. The transform is applied in place to the provided image.
      Parameters:
        `transform` - transform to be applied
        `image` - image to be transformed
        `encoding` - output encoding to be used
      Returns:
        transformed image
      Throws:
        `java.lang.IllegalArgumentException` - If `transform`, `image` or `encoding` are invalid.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### applyTransformAsync

          java.util.concurrent.Future<Image> applyTransformAsync(Transform transform,
                                                                 Image image,
                                                                 ImagesService.OutputEncoding encoding)

      Asynchronously applies the provided `transform` to the provided `image` encoding the transformed image stored using `encoding` file format. The transform is applied in place to the provided image.
      Parameters:
        `transform` - transform to be applied
        `image` - image to be transformed
        `encoding` - output encoding to be used
      Returns:
        A future containing the transformed image or one of the exceptions documented for `applyTransform(Transform, Image, OutputEncoding)`.

    - #### applyTransform

          Image applyTransform(Transform transform,
                               Image image,
                               OutputSettings settings)

      Applies the provided `transform` to the provided `image` encoding the transformed image stored using `settings`. The transform is applied in place to the provided image.
      Parameters:
        `transform` - transform to be applied
        `image` - image to be transformed
        `settings` - output settings to be used
      Returns:
        transformed image
      Throws:
        `java.lang.IllegalArgumentException` - If `transform`, `image` or `settings` are invalid.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### applyTransformAsync

          java.util.concurrent.Future<Image> applyTransformAsync(Transform transform,
                                                                 Image image,
                                                                 OutputSettings settings)

      Asynchronously applies the provided `transform` to the provided `image` encoding the transformed image stored using `settings`. The transform is applied in place to the provided image.
      Parameters:
        `transform` - transform to be applied
        `image` - image to be transformed
        `settings` - output settings to be used
      Returns:
        A future containing the transformed image or one of the exceptions documented for `applyTransform(Transform, Image, OutputSettings)`.

    - #### applyTransform

          Image applyTransform(Transform transform,
                               Image image,
                               InputSettings inputSettings,
                               OutputSettings outputSettings)

      Applies the provided `transform` to the provided `image` encoding the transformed image stored using `outputSettings` interpreting `image` according to `inputSettings`. The transform is applied in place to the provided image.
      Parameters:
        `transform` - transform to be applied
        `image` - image to be transformed
        `inputSettings` - input settings to be used
        `outputSettings` - output settings to be used
      Returns:
        transformed image
      Throws:
        `java.lang.IllegalArgumentException` - If `transform`, `image`, `inputSettings` or `outputSettings` are invalid.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### applyTransformAsync

          java.util.concurrent.Future<Image> applyTransformAsync(Transform transform,
                                                                 Image image,
                                                                 InputSettings inputSettings,
                                                                 OutputSettings outputSettings)

      Asynchronously applies the provided `transform` to the provided `image` encoding the transformed image stored using `settings` interpreting `image` according to `inputSettings`. The transform is applied in place to the provided image.
      Parameters:
        `transform` - transform to be applied
        `image` - image to be transformed
        `inputSettings` - input settings to be used
        `outputSettings` - output settings to be used
      Returns:
        A future containing the transformed image or one of the exceptions documented for `applyTransform(Transform, Image, InputSettings, OutputSettings)`.

    - #### composite

          Image composite(java.util.Collection<Composite> composites,
                          int width,
                          int height,
                          long color)

      Applies the provided `Collection` of `Composite`s using a canvas with dimensions determined by `width` and `height` and background color `color`. Uses PNG as its output encoding.
      Parameters:
        `composites` - Compositing operations to be applied.
        `width` - Width of the canvas in pixels.
        `height` - Height of the canvas in pixels.
        `color` - Background color of the canvas in ARGB format.
      Returns:
        A new image containing the result of composition.
      Throws:
        `java.lang.IllegalArgumentException` - If `width` or `height` is greater than 4000, color is outside the range [0, 0xffffffff], `composites` contains more than 16 elements or something is wrong with the contents of `composites`.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### composite

          Image composite(java.util.Collection<Composite> composites,
                          int width,
                          int height,
                          long color,
                          ImagesService.OutputEncoding encoding)

      Applies the provided `Collection` of `Composite`s using a canvas with dimensions determined by `width` and `height` and background color `color`.
      Parameters:
        `composites` - Compositing operations to be applied.
        `width` - Width of the canvas in pixels.
        `height` - Height of the canvas in pixels.
        `color` - Background color of the canvas in ARGB format.
        `encoding` - Encoding to be used for the resulting image.
      Returns:
        A new image containing the result of composition.
      Throws:
        `java.lang.IllegalArgumentException` - If `width` or `height` is greater than 4000, color is outside the range [0, 0xffffffff], `composites` contains more than 16 elements or something is wrong with the contents of `composites`.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### composite

          Image composite(java.util.Collection<Composite> composites,
                          int width,
                          int height,
                          long color,
                          OutputSettings settings)

      Applies the provided `Collection` of `Composite`s using a canvas with dimensions determined by `width` and `height` and background color `color`.
      Parameters:
        `composites` - Compositing operations to be applied.
        `width` - Width of the canvas in pixels.
        `height` - Height of the canvas in pixels.
        `color` - Background color of the canvas in ARGB format.
        `settings` - OutputSettings to be used for the resulting image.
      Returns:
        A new image containing the result of composition.
      Throws:
        `java.lang.IllegalArgumentException` - If `width` or `height` is greater than 4000, color is outside the range [0, 0xffffffff], `composites` contains more than 16 elements or something is wrong with the contents of `composites`.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### histogram

          int[][] histogram(Image image)

      Calculates the histogram of the image.
      Parameters:
        `image` - image for which to calculate a histogram
      Returns:
        An array of 3 arrays of length 256, each containing the image histogram for one color channel. The channels are ordered RGB from entry 0 to 3. Each channel ranges from 0 where the color is not present to 255 where the color is fully bright.

    - #### getServingUrl

          @Deprecated
          java.lang.String getServingUrl(BlobKey blobKey)

      Deprecated. Replaced by `getServingUrl(ServingUrlOptions)`.
      Obtains a URL that can serve the image stored as a blob dynamically.

      This URL is served by a high-performance dynamic image serving infrastructure that is available globally. The URL returned by this method is always public, but not guessable; private URLs are not currently supported. If you wish to stop serving the URL, delete the underlying blob key. This takes up to 24 hours to take effect. The URL format also allows dynamic resizing and crop with certain restrictions. To get dynamic resizing and cropping simply append options to the end of the url obtained via this call. Here is an example: `getServingUrl -> "http://lh3.ggpht.com/SomeCharactersGoesHere"`

      To get a 32 pixel sized version (aspect-ratio preserved) simply append "=s32" to the url: `"http://lh3.ggpht.com/SomeCharactersGoesHere=s32"`

      To get a 32 pixel cropped version simply append "=s32-c": `"http://lh3.ggpht.com/SomeCharactersGoesHere=s32-c"`

      Valid sizes are any integer in the range [0, 1600] and is available as SERVING_SIZES_LIMIT.

      Parameters:
        `blobKey` - blob key of the image to serve by the returned URL.
      Returns:
        a URL that can serve the image dynamically.
      Throws:
        `java.lang.IllegalArgumentException` - If blob key is not valid or doesn't contain an image.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### getServingUrl

          @Deprecated
          java.lang.String getServingUrl(BlobKey blobKey,
                                                     boolean secureUrl)

      Deprecated. Replaced by `getServingUrl(ServingUrlOptions)`.
      Obtains a URL that can serve the image stored as a blob dynamically.

      This URL is served by a high-performance dynamic image serving infrastructure that is available globally. The URL returned by this method is always public, but not guessable; private URLs are not currently supported. If you wish to stop serving the URL, delete the underlying blob key. This takes up to 24 hours to take effect. The URL format also allows dynamic resizing and crop with certain restrictions. To get dynamic resizing and cropping simply append options to the end of the url obtained via this call. Here is an example: `getServingUrl -> "http://lh3.ggpht.com/SomeCharactersGoesHere"`

      To get a 32 pixel sized version (aspect-ratio preserved) simply append "=s32" to the url: `"http://lh3.ggpht.com/SomeCharactersGoesHere=s32"`

      To get a 32 pixel cropped version simply append "=s32-c": `"http://lh3.ggpht.com/SomeCharactersGoesHere=s32-c"`

      Valid sizes are any integer in the range [0, 1600] and is available as SERVING_SIZES_LIMIT.

      Parameters:
        `blobKey` - blob key of the image to serve by the returned URL.
        `secureUrl` - controls if the url scheme should be https or http.
      Returns:
        a URL that can serve the image dynamically.
      Throws:
        `java.lang.IllegalArgumentException` - If blob key is not valid or doesn't contain an image.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### getServingUrl

          @Deprecated
          java.lang.String getServingUrl(BlobKey blobKey,
                                                     int imageSize,
                                                     boolean crop)

      Deprecated. Replaced by `getServingUrl(ServingUrlOptions)`.
      Calculates the serving URL for specific size and crop parameters from generic URL returned by `getServingUrl(BlobKey)`.
      Parameters:
        `blobKey` - blob key of the image to serve by the returned URL with specified size and crop.
        `imageSize` - size of the served image in pixels.
        `crop` - controls whether the image should be resized or cropped.
      Returns:
        a URL that can serve the image dynamically.
      Throws:
        `java.lang.IllegalArgumentException` - If blob key is not valid or doesn't contain an image or specified size is not supported by the service.
        `ImagesServiceFailureException` - If there is a problem with the Images Service
      See Also:
        `getServingUrl(BlobKey)`

    - #### getServingUrl

          @Deprecated
          java.lang.String getServingUrl(BlobKey blobKey,
                                                     int imageSize,
                                                     boolean crop,
                                                     boolean secureUrl)

      Deprecated. Replaced by `getServingUrl(ServingUrlOptions)`.
      Calculates the serving URL for specific size and crop parameters from generic URL returned by `getServingUrl(BlobKey)`.
      Parameters:
        `blobKey` - blob key of the image to serve by the returned URL with specified size and crop.
        `imageSize` - size of the served image in pixels.
        `crop` - controls whether the image should be resized or cropped.
        `secureUrl` - controls if the url scheme should be https or http.
      Returns:
        a URL that can serve the image dynamically.
      Throws:
        `java.lang.IllegalArgumentException` - If blob key is not valid or doesn't contain an image or specified size is not supported by the service.
        `ImagesServiceFailureException` - If there is a problem with the Images Service
      See Also:
        `getServingUrl(BlobKey)`

    - #### getServingUrl

          java.lang.String getServingUrl(ServingUrlOptions options)

      Obtains a URL that can dynamically serve the image stored as a blob.

      This URL is served by a high-performance dynamic image serving infrastructure that is available globally. The URL returned by this method is always public, but not guessable; private URLs are not currently supported. If you wish to stop serving the URL, delete the underlying blob key. This takes up to 24 hours to take effect. The URL format also allows dynamic resizing and crop with certain restrictions. To get dynamic resizing and cropping simply append options to the end of the url obtained via this call. Here is an example: `getServingUrl -> "http://lh3.ggpht.com/SomeCharactersGoesHere"`

      To get a 32 pixel sized version (aspect-ratio preserved) simply append "=s32" to the url: `"http://lh3.ggpht.com/SomeCharactersGoesHere=s32"`

      To get a 32 pixel cropped version simply append "=s32-c": `"http://lh3.ggpht.com/SomeCharactersGoesHere=s32-c"`

      Valid sizes are any integer in the range [0, 1600] (maximum is available as `SERVING_SIZES_LIMIT`).

      Parameters:
        `options` - Specific options for generating the serving URL.
      Returns:
        a URL that can serve the image dynamically.
      Throws:
        `java.lang.IllegalArgumentException` - If options does not contain a valid blobKey or googleStorageFileName.
        `ImagesServiceFailureException` - If there is a problem with the Images Service

    - #### deleteServingUrl

          void deleteServingUrl(BlobKey blobKey)

      Deletes a URL that was previously generated by `getServingUrl(BlobKey)`.
      Parameters:
        `blobKey` - blob key that was previously used in the call to create the serving URL.
      Throws:
        `java.lang.IllegalArgumentException` - If blob key is not valid.