xmlgraphics-commons 1.4

org.apache.xmlgraphics.image.loader
Class ImageManager

java.lang.Object
  extended by org.apache.xmlgraphics.image.loader.ImageManager

public class ImageManager
extends java.lang.Object

ImageManager is the central starting point for image access.


Field Summary
protected static org.apache.commons.logging.Log log
          logger
 
Constructor Summary
ImageManager(ImageContext context)
          Main constructor.
ImageManager(ImageImplRegistry registry, ImageContext context)
          Constructor for testing purposes.
 
Method Summary
 ImageProviderPipeline choosePipeline(ImageProviderPipeline[] candidates)
          Chooses the best ImageProviderPipeline from a set of candidates.
 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 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

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

xmlgraphics-commons 1.4

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