org.apache.xmlgraphics.image.loader.impl
Class AbstractImageSessionContext

java.lang.Object
  org.apache.xmlgraphics.image.loader.impl.AbstractImageSessionContext

All Implemented Interfaces:

ImageSessionContext

Direct Known Subclasses:

DefaultImageSessionContext

public abstract class AbstractImageSessionContext
extends Object
implements ImageSessionContext

Abstract base class for classes implementing ImageSessionContext. This class provides all the special treatment for Source creation, i.e. it provides optimized Source objects where possible.

Nested Class Summary

static interface	AbstractImageSessionContext.FallbackResolver Implementations of this interface will be used as the mechanism for creating the Source that wraps resources.
static class	AbstractImageSessionContext.RestrictedFallbackResolver This fallback resolver is to be used in environments where controlling file access is of critical importance.
static class	AbstractImageSessionContext.UnrestrictedFallbackResolver An unrestricted resolver that has various contingency mechanisms that access the file-system.

Constructor Summary

AbstractImageSessionContext()

AbstractImageSessionContext(AbstractImageSessionContext.FallbackResolver fallbackResolver)

Method Summary

protected static ImageInputStream	createImageInputStream(InputStream in)
Source	getSource(String uri) Returns a Source object for a URI.
protected boolean	isReusable(Source src) Indicates whether a Source is reusable.
Source	needSource(String uri) Returns a Source object for a URI.
Source	newSource(String uri) Attempts to create a Source object from the given URI.
protected abstract Source	resolveURI(String uri) Attempts to resolve the given URI.
void	returnSource(String uri, Source src) Returns a Source object to a pool.
static File	toFile(URL url) Convert from a URL to a File.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.xmlgraphics.image.loader.ImageSessionContext

getParentContext, getTargetResolution

Constructor Detail

AbstractImageSessionContext

public AbstractImageSessionContext()

AbstractImageSessionContext

public AbstractImageSessionContext(AbstractImageSessionContext.FallbackResolver fallbackResolver)

Parameters:

fallbackResolver - the fallback resolution mechanism to be used when simply getting an InputStream that backs a Source isn't possible.

Method Detail

resolveURI

protected abstract Source resolveURI(String uri)

Attempts to resolve the given URI.

Parameters:

uri - URI to access

Returns:

A Source object, or null if the URI cannot be resolved.

newSource

public Source newSource(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.

Specified by:

newSource in interface ImageSessionContext

Parameters:

uri - URI to access

Returns:

A Source object, or null if the URI cannot be resolved.

createImageInputStream

protected static ImageInputStream createImageInputStream(InputStream in)
                                                  throws IOException

Throws:

IOException

toFile

public static File toFile(URL url)

Convert from a URL to a File.

This method will decode the URL. Syntax such as file:///my%20docs/file.txt will be correctly decoded to /my docs/file.txt.

Note: this method has been copied over from Apache Commons IO and enhanced to support UNC paths.

Parameters:

url - the file URL to convert, null returns null

Returns:

the equivalent File object, or null if the URL's protocol is not file

Throws:

IllegalArgumentException - if the file is incorrectly encoded

getSource

public Source getSource(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 ImageSessionContext.returnSource(String, Source) method).

Specified by:

getSource in interface ImageSessionContext

Parameters:

uri - the URI of the image

Returns:

the Source object to load the image from, or null

needSource

public Source needSource(String uri)
                  throws 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.

Specified by:

needSource in interface ImageSessionContext

Parameters:

uri - the URI of the image

Returns:

the Source object to load the image from

Throws:

FileNotFoundException - if the image cannot be found

returnSource

public void returnSource(String uri,
                         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.

Specified by:

returnSource in interface ImageSessionContext

Parameters:

uri - the URI of the image

src - the Source object belonging to the URI

isReusable

protected boolean isReusable(Source src)

Indicates whether a Source is reusable. A Source object is reusable if it's an ImageSource (containing an ImageInputStream) or a DOMSource.

Parameters:

src - the Source object

Returns:

true if the Source is reusable