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

    All Methods Instance Methods Concrete 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<java.lang.String,java.lang.Object> hints, ImageSessionContext context)` Executes the image converter pipeline.
    `Image` | `execute(ImageInfo info, java.util.Map<java.lang.String,java.lang.Object> 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<java.lang.String,java.lang.Object> 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<java.lang.String,java.lang.Object> 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

Copyright 1999-2025 The Apache Software Foundation. All Rights Reserved.