ImageProviderPipeline
Date: 2016-04-28

org.apache.xmlgraphics.image.loader.pipeline

## Class ImageProviderPipeline

- java.lang.Object
- - org.apache.xmlgraphics.image.loader.pipeline.ImageProviderPipeline

-     public class ImageProviderPipeline
      extends java.lang.Object

  Represents a pipeline of ImageConverters with an ImageLoader at the beginning of the pipeline.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static org.apache.commons.logging.Log` | `log` logger

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ImageProviderPipeline()` Default constructor without caching and without an ImageLoader (or the ImageLoader may be set later).
    `ImageProviderPipeline(ImageCache cache, ImageLoader loader)` Main constructor.
    `ImageProviderPipeline(ImageLoader loader)` Constructor for operation without caching.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addConverter(ImageConverter converter)` Adds an additional ImageConverter to the end of the pipeline.
    `Image` | `execute(ImageInfo info, Image originalImage, java.util.Map hints, ImageSessionContext context)` Executes the image converter pipeline.
    `Image` | `execute(ImageInfo info, java.util.Map hints, ImageSessionContext context)` Executes the image converter pipeline.
    `protected Image` | `forceCaching(Image img)` In some cases the provided Image is not cacheable, nor is any of the intermediate Image instances (for example, when loading a raw JPEG file).
    `int` | `getConversionPenalty()` Returns the overall conversion penalty for the pipeline.
    `Penalty` | `getConversionPenalty(ImageImplRegistry registry)` Returns the overall conversion penalty for the pipeline.
    `ImageFlavor` | `getTargetFlavor()` Returns the target flavor generated by this pipeline.
    `void` | `setImageLoader(ImageLoader imageLoader)` Sets the ImageLoader that is used at the beginning of the pipeline if the image is not loaded, yet.
    `java.lang.String` | `toString()`

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

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

- - ### Field Detail

    - #### log

          protected static final org.apache.commons.logging.Log log

      logger

  - ### Constructor Detail

    - #### ImageProviderPipeline

          public ImageProviderPipeline(ImageCache cache,
                               ImageLoader loader)

      Main constructor.
      Parameters:
        `cache` - the image cache (may be null if no caching is desired)
        `loader` - the image loader to drive the pipeline with

    - #### ImageProviderPipeline

          public ImageProviderPipeline(ImageLoader loader)

      Constructor for operation without caching.
      Parameters:
        `loader` - the image loader to drive the pipeline with

    - #### ImageProviderPipeline

          public ImageProviderPipeline()

      Default constructor without caching and without an ImageLoader (or the ImageLoader may be set later).

  - ### Method Detail

    - #### execute

          public Image execute(ImageInfo info,
                      java.util.Map hints,
                      ImageSessionContext context)
                        throws ImageException,
                               java.io.IOException

      Executes the image converter pipeline. First, the image indicated by the ImageInfo instance is loaded through an ImageLoader and then optionally converted by a series of ImageConverters. At the end of the pipeline, the fully loaded and converted image is returned.
      Parameters:
        `info` - the image info object indicating the image to load
        `hints` - a Map of image conversion hints
        `context` - the session context
      Returns:
        the requested image
      Throws:
        `ImageException` - if an error occurs while loader or converting the image
        `java.io.IOException` - if an I/O error occurs

    - #### execute

          public Image execute(ImageInfo info,
                      Image originalImage,
                      java.util.Map hints,
                      ImageSessionContext context)
                        throws ImageException,
                               java.io.IOException

      Executes the image converter pipeline. First, the image indicated by the ImageInfo instance is loaded through an ImageLoader and then optionally converted by a series of ImageConverters. At the end of the pipeline, the fully loaded and converted image is returned.
      Parameters:
        `info` - the image info object indicating the image to load
        `originalImage` - the original image to start the pipeline off or null if an ImageLoader is used
        `hints` - a Map of image conversion hints
        `context` - the session context
      Returns:
        the requested image
      Throws:
        `ImageException` - if an error occurs while loader or converting the image
        `java.io.IOException` - if an I/O error occurs

    - #### forceCaching

          protected Image forceCaching(Image img)
                                throws java.io.IOException

      In some cases the provided Image is not cacheable, nor is any of the intermediate Image instances (for example, when loading a raw JPEG file). If the image is loaded over a potentially slow network, it is preferrable to download the whole file and cache it in memory or in a temporary file. It's not always possible to convert an Image into a cacheable variant.
      Parameters:
        `img` - the Image to investigate
      Returns:
        the converted, cacheable Image or null if the Image cannot be converted
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### setImageLoader

          public void setImageLoader(ImageLoader imageLoader)

      Sets the ImageLoader that is used at the beginning of the pipeline if the image is not loaded, yet.
      Parameters:
        `imageLoader` - the image loader implementation

    - #### addConverter

          public void addConverter(ImageConverter converter)

      Adds an additional ImageConverter to the end of the pipeline.
      Parameters:
        `converter` - the ImageConverter instance

    - #### toString

          public java.lang.String toString()

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

    - #### getConversionPenalty

          public int getConversionPenalty()

      Returns the overall conversion penalty for the pipeline. This can be used to choose among different possible pipelines.
      Returns:
        the overall penalty (a non-negative integer)

    - #### getConversionPenalty

          public Penalty getConversionPenalty(ImageImplRegistry registry)

      Returns the overall conversion penalty for the pipeline. This can be used to choose among different possible pipelines.
      Parameters:
        `registry` - the image implementation registry
      Returns:
        the overall penalty (a non-negative integer)

    - #### getTargetFlavor

          public ImageFlavor getTargetFlavor()

      Returns the target flavor generated by this pipeline.
      Returns:
        the target flavor