http://xmlgraphics.apache.org/commons/: Apache XML Graphics Commons is a library that consists of several reusable components used by Apache Batik and Apache FOP. Many of these components can easily be used separately outside the domains of SVG and XSL-FO. (Apache Software Foundation) 
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/* $Id: ImageSessionContext.java 750418 2009-03-05 11:03:54Z vhennebert $ */

package org.apache.xmlgraphics.image.loader;

import java.io.FileNotFoundException;

import javax.xml.transform.Source;



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.

/**
 * 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.
 */
public interface ImageSessionContext {

    
Returns the session-independent context object which provides configuration information.

Returns:the associated ImageContext instance
/**
     * Returns the session-independent context object which provides configuration information.
     * @return the associated ImageContext instance
     */
    ImageContext getParentContext();

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

Returns:the target resolution (in dpi)
/**
     * Returns the resolution (in dpi) of the target device used when painting images.
     * @return the target resolution (in dpi)
     */
    float getTargetResolution();

    
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.

Params:
  • uri – URI to access
Returns:A Source object, or null if the URI cannot be resolved.
/**
     * 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.
     * @param uri URI to access
     * @return A {@link javax.xml.transform.Source} object, or null if the URI
     * cannot be resolved.
     */
    Source newSource(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). 
Params:
  • uri – the URI of the image
Returns:the Source object to load the image from, or null
/**
     * 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 {@link #returnSource(String, Source)} method).
     * @param uri the URI of the image
     * @return the Source object to load the image from, or null
     */
    Source getSource(String uri);

    
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. 
Params:
  • uri – the URI of the image
Throws:
Returns:the Source object to load the image from
/**
     * Returns a Source object for a URI. This method is guaranteed to return a Source object. If
     * the image cannot be found, a {@link FileNotFoundException} is thrown.
     * @param uri the URI of the image
     * @return the Source object to load the image from
     * @throws FileNotFoundException if the image cannot be found
     */
    Source needSource(String uri) throws FileNotFoundException;

    
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.

Params:
  • uri – the URI of the image
  • src – the Source object belonging to the URI
/**
     * 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.
     * @param uri the URI of the image
     * @param src the Source object belonging to the URI
     */
    void returnSource(String uri, Source src);

}