netx.jnlp.cache
Class ResourceTracker

java.lang.Object
  |
  +--netx.jnlp.cache.ResourceTracker

public class ResourceTracker

extends java.lang.Object

This class tracks the downloading of various resources of a JNLP file to local files in the cache. It can be used to download icons, jnlp and extension files, jars, and jardiff files using the version based protocol or any file using the basic download protocol (jardiff and version not implemented yet).

The resource tracker can be configured to prefetch resources, which are downloaded in the order added to the media tracker.

Multiple threads are used to download and cache resources that are actively being waited for (blocking a caller) or those that have been started downloading by calling the startDownload method. Resources that are prefetched are downloaded one at a time and only if no other trackers have requested downloads. This allows the tracker to start downloading many items without using many system resources, but still quickly download items as needed.

Version:

$Revision: 1.17 $

Author:

Jon A. Maxwell (JAM) - initial author

Constructor Summary

ResourceTracker()
Creates a resource tracker that does not prefetch resources.

ResourceTracker(boolean prefetch)
Creates a resource tracker.

Method Summary

void	addDownloadListener(DownloadListener listener) Adds the listener to the list of objects interested in receivind DownloadEvents.
void	addResource(java.net.URL location, Version version, UpdatePolicy updatePolicy) Add a resource identified by the specified location and version.
boolean	checkResource(java.net.URL location) Returns whether a resource is available for use (ie, can be accessed with the getLocalFile method).
protected void	fireDownloadEvent(Resource resource) Fires the download event corresponding to the resource's state.
long	getAmountRead(java.net.URL location) Returns the number of bytes downloaded for a resource.
java.io.InputStream	getInputStream(java.net.URL location) Returns an input stream that reads the contents of the resource.
java.io.File	getLocalFile(java.net.URL location) Returns the file containing the downloaded resource, or null if the resource could not be downloaded to a local file (was not a cacheable resource).
long	getTotalSize(java.net.URL location) Returns the number of total size in bytes of a resource, or -1 it the size is not known.
void	removeDownloadListener(DownloadListener listener) Removes a download listener.
void	removeResource(java.net.URL location) Removes a resource from the tracker.
boolean	startResource(java.net.URL location) Starts loading the resource if it is not already being downloaded or already cached.
protected void	startThread() Start a new download thread if there are not too many threads already running.
boolean	waitForResource(java.net.URL location, long timeout) Wait for a particular resource to be downloaded and made available.
boolean	waitForResources(java.net.URL[] urls, long timeout) Wait for a group of resources to be downloaded and made available locally.

Methods inherited from class java.lang.Object

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

Constructor Detail

ResourceTracker

public ResourceTracker()

Creates a resource tracker that does not prefetch resources.

ResourceTracker

public ResourceTracker(boolean prefetch)

Creates a resource tracker.

Parameters:

prefetch - whether to download resources before requested.

Method Detail

addResource

public void addResource(java.net.URL location,
                        Version version,
                        UpdatePolicy updatePolicy)

Add a resource identified by the specified location and version. The tracker only downloads one version of a given resource per instance (ie cannot download both versions 1 and 2 of a resource in the same tracker).

Parameters:

location - the location of the resource

version - the resource version

updatePolicy - whether to check for updates if already in cache

removeResource

public void removeResource(java.net.URL location)

Removes a resource from the tracker. This method is useful to allow memory to be reclaimed, but calling this method is not required as resources are reclaimed when the tracker is collected.

Throws:

java.lang.IllegalArgumentException - if the resource is not being tracked

addDownloadListener

public void addDownloadListener(DownloadListener listener)

Adds the listener to the list of objects interested in receivind DownloadEvents.

Parameters:

location - the resource to add a callback for

runnable - the runnable to call when resource is completed

removeDownloadListener

public void removeDownloadListener(DownloadListener listener)

Removes a download listener.

fireDownloadEvent

protected void fireDownloadEvent(Resource resource)

Fires the download event corresponding to the resource's state. This method is typicall called by the Resource itself on each tracker that is monitoring the resource. Do not call this method with any locks because the listeners may call back to this ResourceTracker.

getLocalFile

public java.io.File getLocalFile(java.net.URL location)

Returns the file containing the downloaded resource, or null if the resource could not be downloaded to a local file (was not a cacheable resource).

If the resource has not downloaded yet, the method will block until it has been transferred to the cache.

Parameters:

location - the source location to get the local file for

Returns:

the resource, or null if it could not be downloaded

Throws:

java.lang.IllegalArgumentException - if the resource is not being tracked

getInputStream

public java.io.InputStream getInputStream(java.net.URL location)
                                   throws java.io.IOException

Returns an input stream that reads the contents of the resource. For non-cacheable resources, an InputStream that reads from the source location is returned. Otherwise the InputStream reads the cached resource.

This method will block while the resource is downloaded to the cache.

Throws:

java.io.IOException - if there was an error opening the stream

java.lang.IllegalArgumentException - if the resource is not being tracked

waitForResources

public boolean waitForResources(java.net.URL[] urls,
                                long timeout)
                         throws java.lang.InterruptedException

Wait for a group of resources to be downloaded and made available locally.

Returns:

whether the resources downloaded before the timeout

Throws:

java.lang.IllegalArgumentException - if the resource is not being tracked

waitForResource

public boolean waitForResource(java.net.URL location,
                               long timeout)
                        throws java.lang.InterruptedException

Wait for a particular resource to be downloaded and made available.

Parameters:

location - the resource to wait for

timeout - the timeout, or 0 to wait until completed

Returns:

whether the resource downloaded before the timeout

Throws:

java.lang.InterruptedException - if another thread interrupted the wait

java.lang.IllegalArgumentException - if the resource is not being tracked

getAmountRead

public long getAmountRead(java.net.URL location)

Returns the number of bytes downloaded for a resource.

Parameters:

location - the resource location

Returns:

the number of bytes transferred

Throws:

java.lang.IllegalArgumentException - if the resource is not being tracked

checkResource

public boolean checkResource(java.net.URL location)

Returns whether a resource is available for use (ie, can be accessed with the getLocalFile method).

Throws:

java.lang.IllegalArgumentException - if the resource is not being tracked

startResource

public boolean startResource(java.net.URL location)

Starts loading the resource if it is not already being downloaded or already cached. Resources started downloading using this method may download faster than those prefetched by the tracker because the tracker will only prefetch one resource at a time to conserve system resources.

Returns:

true if the resource is already downloaded (or an error occurred)

Throws:

java.lang.IllegalArgumentException - if the resource is not being tracked

getTotalSize

public long getTotalSize(java.net.URL location)

Returns the number of total size in bytes of a resource, or -1 it the size is not known.

Parameters:

location - the resource location

Returns:

the number of bytes, or -1

Throws:

java.lang.IllegalArgumentException - if the resource is not being tracked

startThread

protected void startThread()

Start a new download thread if there are not too many threads already running.

Calls to this method should be synchronized on lock.