org.apache.xmlgraphics.image.loader

## Interface ImageSessionContext

- All Known Implementing Classes:
    AbstractImageSessionContext, DefaultImageSessionContext

      public interface ImageSessionContext

  This interface is used to tell the cache which images are used by a session (in FOP that would be a rendering run). Images access within a session get a hard reference so they cannot be discarded. That could increase memory usage but helps with performance because the images don't get unloaded between layout and rendering which would mean that they have to be reloaded.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `ImageContext` | `getParentContext()` Returns the session-independent context object which provides configuration information.
    `javax.xml.transform.Source` | `getSource(java.lang.String uri)` Returns a Source object for a URI.
    `float` | `getTargetResolution()` Returns the resolution (in dpi) of the target device used when painting images.
    `javax.xml.transform.Source` | `needSource(java.lang.String uri)` Returns a Source object for a URI.
    `javax.xml.transform.Source` | `newSource(java.lang.String uri)` Attempts to create a Source object from the given URI.
    `void` | `returnSource(java.lang.String uri, javax.xml.transform.Source src)` Returns a Source object to a pool.

- - ### Method Detail

    - #### getParentContext

          ImageContext getParentContext()

      Returns the session-independent context object which provides configuration information.
      Returns:
        the associated ImageContext instance

    - #### getTargetResolution

          float getTargetResolution()

      Returns the resolution (in dpi) of the target device used when painting images.
      Returns:
        the target resolution (in dpi)

    - #### newSource

          javax.xml.transform.Source newSource(java.lang.String uri)

      Attempts to create a Source object from the given URI. If possible this method returns an ImageSource instance which provides the best possible method to access the image.
      Parameters:
        `uri` - URI to access
      Returns:
        A `Source` object, or null if the URI cannot be resolved.

    - #### getSource

          javax.xml.transform.Source getSource(java.lang.String uri)

      Returns a Source object for a URI. This method is not guaranteed to return an instance. Implementations normally return already created Sources from a pool (normally populated through the `returnSource(String, Source)` method).
      Parameters:
        `uri` - the URI of the image
      Returns:
        the Source object to load the image from, or null

    - #### needSource

          javax.xml.transform.Source needSource(java.lang.String uri)
                                         throws java.io.FileNotFoundException

      Returns a Source object for a URI. This method is guaranteed to return a Source object. If the image cannot be found, a `FileNotFoundException` is thrown.
      Parameters:
        `uri` - the URI of the image
      Returns:
        the Source object to load the image from
      Throws:
        `java.io.FileNotFoundException` - if the image cannot be found

    - #### returnSource

          void returnSource(java.lang.String uri,
                            javax.xml.transform.Source src)

      Returns a Source object to a pool. This is provided in order to reuse a Source object between the preloading and the final loading of an image. Note that not all Source objects can be reused! Non-reusable Sources are discarded.
      Parameters:
        `uri` - the URI of the image
        `src` - the Source object belonging to the URI

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