org.apache.tools.ant.taskdefs

Class Get

java.lang.Object

org.apache.tools.ant.ProjectComponent

org.apache.tools.ant.Task

org.apache.tools.ant.taskdefs.Get

All Implemented Interfaces:

Cloneable

public class Get
extends Task

Gets a particular file from a URL source. Options include verbose reporting, timestamp based fetches and controlling actions on failures. NB: access through a firewall only works if the whole Java runtime is correctly configured.

Since:

Ant 1.1

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	Get.Base64Converter Provide this for Backward Compatibility.
static interface	Get.DownloadProgress Interface implemented for reporting progress of downloading.
static class	Get.NullProgress do nothing with progress info
static class	Get.VerboseProgress verbose progress system prints to some output stream

Constructor Summary

Constructors

Constructor and Description
Get()

Method Summary

Modifier and Type	Method and Description
void	add(FileNameMapper fileNameMapper) Add a nested filenamemapper.
void	add(ResourceCollection rc) Adds URLs to get.
Mapper	createMapper() Define the mapper to map source to destination files.
boolean	doGet(URL source, File dest, int logLevel, Get.DownloadProgress progress) make a get request, with the supplied progress and logging info.
void	execute() Does the work.
void	log(String msg, int msgLevel) Logs a message with the given priority.
void	setDest(File dest) Where to copy the source file.
void	setHttpUseCaches(boolean httpUseCache) HTTP connections only - control caching on the HttpUrlConnection: httpConnection.setUseCaches(); if false, do not allow caching on the HttpUrlConnection.
void	setIgnoreErrors(boolean v) If true, log errors but do not treat as fatal.
void	setMaxTime(long maxTime) The time in seconds the download is allowed to take before being terminated.
void	setPassword(String p) password for the basic authentication.
void	setQuiet(boolean v) If true, set default log level to Project.MSG_ERR.
void	setRetries(int r) The number of attempts to make for opening the URI, defaults to 3.
void	setSkipExisting(boolean s) Skip files that already exist locally.
void	setSrc(URL u) Set an URL to get.
void	setTryGzipEncoding(boolean b) Whether to transparently try to reduce bandwidth by telling the server ant would support gzip encoding.
void	setUserAgent(String userAgent) HTTP connections only - set the user-agent to be used when communicating with remote server.
void	setUsername(String u) Username for basic auth.
void	setUseTimestamp(boolean v) If true, conditionally download a file based on the timestamp of the local copy.
void	setVerbose(boolean v) If true, show verbose progress information.

Methods inherited from class org.apache.tools.ant.Task

bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject

Methods inherited from class java.lang.Object

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

Constructor Detail

Get

public Get()

Method Detail

add

public void add(FileNameMapper fileNameMapper)

Add a nested filenamemapper.

Parameters:

fileNameMapper - the mapper to add.

Since:

Ant 1.8.0

add

public void add(ResourceCollection rc)

Adds URLs to get.

Since:

Ant 1.8.0

createMapper

public Mapper createMapper()
                    throws BuildException

Define the mapper to map source to destination files.

Returns:

a mapper to be configured.

Throws:

BuildException - if more than one mapper is defined.

Since:

Ant 1.8.0

doGet

public boolean doGet(URL source,
                     File dest,
                     int logLevel,
                     Get.DownloadProgress progress)
              throws IOException

make a get request, with the supplied progress and logging info. All the other config parameters like ignoreErrors are set at the task level.

Parameters:

source - the URL to get

dest - the target file

logLevel - level to log at, see Project.log(String, int)

progress - progress callback; null for no-callbacks

Returns:

true for a successful download, false otherwise. The return value is only relevant when ignoreErrors is true, as when false all failures raise BuildExceptions.

Throws:

IOException - for network trouble

BuildException - for argument errors, or other trouble when ignoreErrors is false.

Since:

Ant 1.8.0

execute

public void execute()
             throws BuildException

Does the work.

Overrides:

execute in class Task

Throws:

BuildException - Thrown in unrecoverable error.

log

public void log(String msg,
                int msgLevel)

Description copied from class: Task

Logs a message with the given priority. This delegates the actual logging to the project.

Overrides:

log in class Task

Parameters:

msg - The message to be logged. Should not be null.

msgLevel - The message priority at which this message is to be logged.

setDest

public void setDest(File dest)

Where to copy the source file.

Parameters:

dest - Path to file.

setHttpUseCaches

public void setHttpUseCaches(boolean httpUseCache)

HTTP connections only - control caching on the HttpUrlConnection: httpConnection.setUseCaches(); if false, do not allow caching on the HttpUrlConnection.

Defaults to true (allow caching, which is also the HttpUrlConnection default value.

Since:

Ant 1.8.0

setIgnoreErrors

public void setIgnoreErrors(boolean v)

If true, log errors but do not treat as fatal.

Parameters:

v - if "true" then don't report download errors up to ant

setMaxTime

public void setMaxTime(long maxTime)

The time in seconds the download is allowed to take before being terminated.

Since:

Ant 1.8.0

setPassword

public void setPassword(String p)

password for the basic authentication.

Parameters:

p - password for authentication

setQuiet

public void setQuiet(boolean v)

If true, set default log level to Project.MSG_ERR.

Parameters:

v - if "true" then be quiet

Since:

Ant 1.9.4

setRetries

public void setRetries(int r)

The number of attempts to make for opening the URI, defaults to 3.

The name of the method is misleading as a value of 1 means "don't retry on error" and a value of 0 meant don't even try to reach the URI at all.

Parameters:

r - number of attempts to make

Since:

Ant 1.8.0

setSkipExisting

public void setSkipExisting(boolean s)

Skip files that already exist locally.

Parameters:

s - "true" to skip existing destination files

Since:

Ant 1.8.0

setSrc

public void setSrc(URL u)

Set an URL to get.

Parameters:

u - URL for the file.

setTryGzipEncoding

public void setTryGzipEncoding(boolean b)

Whether to transparently try to reduce bandwidth by telling the server ant would support gzip encoding.

Setting this to true also means Ant will uncompress .tar.gz and similar files automatically.

Since:

Ant 1.9.5

setUserAgent

public void setUserAgent(String userAgent)

HTTP connections only - set the user-agent to be used when communicating with remote server. if null, then the value is considered unset and the behaviour falls back to the default of the http API.

Since:

Ant 1.9.3

setUsername

public void setUsername(String u)

Username for basic auth.

Parameters:

u - username for authentication

setUseTimestamp

public void setUseTimestamp(boolean v)

If true, conditionally download a file based on the timestamp of the local copy.

In this situation, the if-modified-since header is set so that the file is only fetched if it is newer than the local file (or there is no local file) This flag is only valid on HTTP connections, it is ignored in other cases. When the flag is set, the local copy of the downloaded file will also have its timestamp set to the remote file time.

Note that remote files of date 1/1/1970 (GMT) are treated as 'no timestamp', and web servers often serve files with a timestamp in the future by replacing their timestamp with that of the current time. Also, inter-computer clock differences can cause no end of grief.

Parameters:

v - "true" to enable file time fetching

setVerbose

public void setVerbose(boolean v)

If true, show verbose progress information.

Parameters:

v - if "true" then be verbose