ImageManager
Date: 2016-04-28

org.apache.xmlgraphics.image.loader

## Class ImageManager

- java.lang.Object
- - org.apache.xmlgraphics.image.loader.ImageManager

-     public class ImageManager
      extends java.lang.Object

  ImageManager is the central starting point for image access.

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ImageManager(ImageContext context)` Main constructor.
    `ImageManager(ImageImplRegistry registry, ImageContext context)` Constructor for testing purposes.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ImageProviderPipeline` | `choosePipeline(ImageProviderPipeline[] candidates)` Chooses the best `ImageProviderPipeline` from a set of candidates.
    `void` | `closeImage(java.lang.String uri, ImageSessionContext session)` Closes the resources associated to the given image.
    `Image` | `convertImage(Image image, ImageFlavor[] flavors)` Converts an image with no hints.
    `Image` | `convertImage(Image image, ImageFlavor[] flavors, java.util.Map hints)` Converts an image.
    `ImageCache` | `getCache()` Returns the ImageCache in use by the ImageManager.
    `Image` | `getImage(ImageInfo info, ImageFlavor[] flavors, ImageSessionContext session)` Loads an image with no hints.
    `Image` | `getImage(ImageInfo info, ImageFlavor[] flavors, java.util.Map hints, ImageSessionContext session)` Loads an image.
    `Image` | `getImage(ImageInfo info, ImageFlavor flavor, ImageSessionContext session)` Loads an image with no hints.
    `Image` | `getImage(ImageInfo info, ImageFlavor flavor, java.util.Map hints, ImageSessionContext session)` Loads an image.
    `ImageContext` | `getImageContext()` Returns the ImageContext in use by the ImageManager.
    `ImageInfo` | `getImageInfo(java.lang.String uri, ImageSessionContext session)` Returns an ImageInfo object containing its intrinsic size for a given URI.
    `PipelineFactory` | `getPipelineFactory()` Returns the PipelineFactory in use by the ImageManager.
    `ImageImplRegistry` | `getRegistry()` Returns the ImageImplRegistry in use by the ImageManager.
    `ImageInfo` | `preloadImage(java.lang.String uri, ImageSessionContext session)` Preloads an image, i.e.
    `ImageInfo` | `preloadImage(java.lang.String uri, javax.xml.transform.Source src)` Preloads an image, i.e.

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

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

- - ### Field Detail

    - #### log

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

      logger

  - ### Constructor Detail

    - #### ImageManager

          public ImageManager(ImageContext context)

      Main constructor.
      Parameters:
        `context` - the session-independent context information

    - #### ImageManager

          public ImageManager(ImageImplRegistry registry,
                      ImageContext context)

      Constructor for testing purposes.
      Parameters:
        `registry` - the implementation registry with all plug-ins
        `context` - the session-independent context information

  - ### Method Detail

    - #### getRegistry

          public ImageImplRegistry getRegistry()

      Returns the ImageImplRegistry in use by the ImageManager.
      Returns:
        the ImageImplRegistry

    - #### getImageContext

          public ImageContext getImageContext()

      Returns the ImageContext in use by the ImageManager.
      Returns:
        the ImageContext

    - #### getCache

          public ImageCache getCache()

      Returns the ImageCache in use by the ImageManager.
      Returns:
        the ImageCache

    - #### getPipelineFactory

          public PipelineFactory getPipelineFactory()

      Returns the PipelineFactory in use by the ImageManager.
      Returns:
        the PipelineFactory

    - #### getImageInfo

          public ImageInfo getImageInfo(java.lang.String uri,
                               ImageSessionContext session)
                                 throws ImageException,
                                        java.io.IOException

      Returns an ImageInfo object containing its intrinsic size for a given URI. The ImageInfo is retrieved from an image cache if it has been requested before.
      Parameters:
        `uri` - the URI of the image
        `session` - the session context through which to resolve the URI if the image is not in the cache
      Returns:
        the ImageInfo object created from the image
      Throws:
        `ImageException` - If no suitable ImagePreloader can be found to load the image or if an error occurred while preloading the image.
        `java.io.IOException` - If an I/O error occurs while preloading the image

    - #### preloadImage

          public ImageInfo preloadImage(java.lang.String uri,
                               ImageSessionContext session)
                                 throws ImageException,
                                        java.io.IOException

      Preloads an image, i.e. the format of the image is identified and some basic information (MIME type, intrinsic size and possibly other values) are loaded and returned as an ImageInfo object. Note that the image is not fully loaded normally. Only with certain formats the image is already fully loaded and references added to the ImageInfo's custom objects (see `ImageInfo.getOriginalImage()`).

      The reason for the preloading: Apache FOP, for example, only needs the image's intrinsic size during layout. Only when the document is rendered to the final format does FOP need to load the full image. Like this a lot of memory can be saved.

      Parameters:
        `uri` - the original URI of the image
        `session` - the session context through which to resolve the URI
      Returns:
        the ImageInfo object created from the image
      Throws:
        `ImageException` - If no suitable ImagePreloader can be found to load the image or if an error occurred while preloading the image.
        `java.io.IOException` - If an I/O error occurs while preloading the image

    - #### preloadImage

          public ImageInfo preloadImage(java.lang.String uri,
                               javax.xml.transform.Source src)
                                 throws ImageException,
                                        java.io.IOException

      Preloads an image, i.e. the format of the image is identified and some basic information (MIME type, intrinsic size and possibly other values) are loaded and returned as an ImageInfo object. Note that the image is not fully loaded normally. Only with certain formats the image is already fully loaded and references added to the ImageInfo's custom objects (see `ImageInfo.getOriginalImage()`).

      The reason for the preloading: Apache FOP, for example, only needs the image's intrinsic size during layout. Only when the document is rendered to the final format does FOP need to load the full image. Like this a lot of memory can be saved.

      Parameters:
        `uri` - the original URI of the image
        `src` - the Source object to load the image from
      Returns:
        the ImageInfo object created from the image
      Throws:
        `ImageException` - If no suitable ImagePreloader can be found to load the image or if an error occurred while preloading the image.
        `java.io.IOException` - If an I/O error occurs while preloading the image

    - #### getImage

          public Image getImage(ImageInfo info,
                       ImageFlavor flavor,
                       java.util.Map hints,
                       ImageSessionContext session)
                         throws ImageException,
                                java.io.IOException

      Loads an image. The caller can indicate what kind of image flavor is requested. When this method is called the code looks for a suitable ImageLoader and, if necessary, builds a conversion pipeline so it can return the image in exactly the form the caller needs.

      Optionally, it is possible to pass in Map of hints. These hints may be used by ImageLoaders and ImageConverters to act on the image. See `ImageProcessingHints` for common hints used by the bundled implementations. You can, of course, define your own hints.

      Parameters:
        `info` - the ImageInfo instance for the image (obtained by `getImageInfo(String, ImageSessionContext)`)
        `flavor` - the requested image flavor.
        `hints` - a Map of hints to any of the background components or null
        `session` - the session context
      Returns:
        the fully loaded image
      Throws:
        `ImageException` - If no suitable loader/converter combination is available to fulfill the request or if an error occurred while loading the image.
        `java.io.IOException` - If an I/O error occurs

    - #### getImage

          public Image getImage(ImageInfo info,
                       ImageFlavor[] flavors,
                       java.util.Map hints,
                       ImageSessionContext session)
                         throws ImageException,
                                java.io.IOException

      Loads an image. The caller can indicate what kind of image flavors are requested. When this method is called the code looks for a suitable ImageLoader and, if necessary, builds a conversion pipeline so it can return the image in exactly the form the caller needs. The array of image flavors is ordered, so the first image flavor is given highest priority.

      Optionally, it is possible to pass in Map of hints. These hints may be used by ImageLoaders and ImageConverters to act on the image. See `ImageProcessingHints` for common hints used by the bundled implementations. You can, of course, define your own hints.

      Parameters:
        `info` - the ImageInfo instance for the image (obtained by `getImageInfo(String, ImageSessionContext)`)
        `flavors` - the requested image flavors (in preferred order).
        `hints` - a Map of hints to any of the background components or null
        `session` - the session context
      Returns:
        the fully loaded image
      Throws:
        `ImageException` - If no suitable loader/converter combination is available to fulfill the request or if an error occurred while loading the image.
        `java.io.IOException` - If an I/O error occurs

    - #### getImage

          public Image getImage(ImageInfo info,
                       ImageFlavor flavor,
                       ImageSessionContext session)
                         throws ImageException,
                                java.io.IOException

      Loads an image with no hints. See `getImage(ImageInfo, ImageFlavor, Map, ImageSessionContext)` for more information.
      Parameters:
        `info` - the ImageInfo instance for the image (obtained by `getImageInfo(String, ImageSessionContext)`)
        `flavor` - the requested image flavor.
        `session` - the session context
      Returns:
        the fully loaded image
      Throws:
        `ImageException` - If no suitable loader/converter combination is available to fulfill the request or if an error occurred while loading the image.
        `java.io.IOException` - If an I/O error occurs

    - #### getImage

          public Image getImage(ImageInfo info,
                       ImageFlavor[] flavors,
                       ImageSessionContext session)
                         throws ImageException,
                                java.io.IOException

      Loads an image with no hints. See `getImage(ImageInfo, ImageFlavor[], Map, ImageSessionContext)` for more information.
      Parameters:
        `info` - the ImageInfo instance for the image (obtained by `getImageInfo(String, ImageSessionContext)`)
        `flavors` - the requested image flavors (in preferred order).
        `session` - the session context
      Returns:
        the fully loaded image
      Throws:
        `ImageException` - If no suitable loader/converter combination is available to fulfill the request or if an error occurred while loading the image.
        `java.io.IOException` - If an I/O error occurs

    - #### closeImage

          public void closeImage(java.lang.String uri,
                        ImageSessionContext session)

      Closes the resources associated to the given image. This method should be used only when none of the `getImage` methods is called by the client application.
      Parameters:
        `uri` - the URI of the image
        `session` - the session context that was used to resolve the URI

    - #### convertImage

          public Image convertImage(Image image,
                           ImageFlavor[] flavors,
                           java.util.Map hints)
                             throws ImageException,
                                    java.io.IOException

      Converts an image. The caller can indicate what kind of image flavors are requested. When this method is called the code looks for a suitable combination of ImageConverters so it can return the image in exactly the form the caller needs. The array of image flavors is ordered, so the first image flavor is given highest priority.

      Optionally, it is possible to pass in Map of hints. These hints may be used by ImageConverters to act on the image. See `ImageProcessingHints` for common hints used by the bundled implementations. You can, of course, define your own hints.

      Parameters:
        `image` - the image to convert
        `flavors` - the requested image flavors (in preferred order).
        `hints` - a Map of hints to any of the background components or null
      Returns:
        the fully loaded image
      Throws:
        `ImageException` - If no suitable loader/converter combination is available to fulfill the request or if an error occurred while loading the image.
        `java.io.IOException` - If an I/O error occurs

    - #### convertImage

          public Image convertImage(Image image,
                           ImageFlavor[] flavors)
                             throws ImageException,
                                    java.io.IOException

      Converts an image with no hints. See `convertImage(Image, ImageFlavor[], Map)` for more information.
      Parameters:
        `image` - the image to convert
        `flavors` - the requested image flavors (in preferred order).
      Returns:
        the fully loaded image
      Throws:
        `ImageException` - If no suitable loader/converter combination is available to fulfill the request or if an error occurred while loading the image.
        `java.io.IOException` - If an I/O error occurs

    - #### choosePipeline

          public ImageProviderPipeline choosePipeline(ImageProviderPipeline[] candidates)

      Chooses the best `ImageProviderPipeline` from a set of candidates.
      Parameters:
        `candidates` - the candidates
      Returns:
        the best pipeline