Task

<urlConnection>

Connects to a resource, writes data to it and/or reads data from it.

To configure HTTP authentication, use the <setAuthenticator> task.

The following attributes are mutually exclusive:

httpChunkLength="..."

httpContentLength="..."

Also the following attributes and subelements are mutually exclusive:

url="..."

<url>

Also the following attributes are mutually exclusive:

direct="..."

httpProxy="..."

socksProxy="..."

To debug HTTP communication, you may want to execute the following before the <urlConnection> task:

 <!-- Configure super-verbose logging on the HTTP connection. -->
 <logging>
     <logger name="sun.net.www.protocol.http.HttpURLConnection" level="FINEST">
         <handler className="java.util.logging.ConsoleHandler">
             <attribute name="level" value="FINEST" />
         </handler>
     </logger>
 </logging>

Attribute Summary

Attributes

Name	Description
allowUserInteraction="..."	Whether the underlying URL should be examined in a context in which it makes sense to allow user interactions, such as popping up an authentication dialog.
connectTimeout="..."	The timeout, in milliseconds, to be used when opening a communications link to the resource referenced by the underlying URLConnection.
direct="..."	Configures a direct HTTP connection, and ignores any proxy configured with the http[s].proxy(Host|Port) system properties.
httpChunkLength="..."	Enables the "chunked streaming mode".
httpContentLength="..."	Enables the "fixed length streaming mode".
httpFollowRedirects="..."	Whether HTTP redirects (requests with response code 3xx) should be automatically followed.
httpFollowRedirects2="..."	Similar to httpFollowRedirects="...", but additionally allows for redirects across protocols, e.g. from "http://host/index.html" to "https://host/index.html".
httpProxy="..."	Configures an HTTP proxy, and overrides any proxy configured with the http[s].proxy(Host|Port) system properties.
ifModifiedSince="..."	Set the value of the ifModifiedSince field of the underlying URLConnection.
readTimeout="..."	The read timeout, in milliseconds.
socksProxy="..."	Configures a SOCKS proxy, and overrides any proxy configured with the http[s].proxy(Host|Port) system properties.
url="..."	Designates the resource to access.
useCaches="..."	Set the value of the useCaches field of the underlying URLConnection.
httpRequestMethod="..."

Subelement Summary

Subelements

Name	Description
<input>	Configures that the content of the resource should be retrieved.
<output>	Configures that data should be copied to the resource.
<requestProperty>	Configures a "request property".
<url>	Designates the resource to access.

Attribute Detail

Default values are underlined.

httpRequestMethod="method"

See also:

HttpURLConnection.setRequestMethod(String)

allowUserInteraction="true|false"

Whether the underlying URL should be examined in a context in which it makes sense to allow user interactions, such as popping up an authentication dialog.

See also:

URLConnection.setAllowUserInteraction(boolean)

connectTimeout="milliseconds"

The timeout, in milliseconds, to be used when opening a communications link to the resource referenced by the underlying URLConnection. If the timeout expires before the connection can be established, a SocketTimeoutException is raised. A timeout of zero is interpreted as an infinite timeout.

See also:

URLConnection.setConnectTimeout(int)

readTimeout="milliseconds"

The read timeout, in milliseconds. If the timeout expires before there is data available for read, a SocketTimeoutException is raised. A timeout of zero is interpreted as an infinite timeout.

See also:

URLConnection.setReadTimeout(int)

ifModifiedSince="point-of-time"

Set the value of the ifModifiedSince field of the underlying URLConnection.

See also:

URLConnection.setIfModifiedSince(long)

useCaches="true|false"

Set the value of the useCaches field of the underlying URLConnection.

See also:

URLConnection.setUseCaches(boolean)

httpChunkLength="chunk-length"

Enables the "chunked streaming mode". A negative value or zero configures a "default chunk size" (typically 4096 bytes), otherwise the given chunk length.

See also:

HttpURLConnection.setChunkedStreamingMode(int)

httpContentLength="..."

httpContentLength="content-length"

Enables the "fixed length streaming mode". The given value must equal the number of bytes that pose the request body, or an error will occur.

See also:

HttpURLConnection.setFixedLengthStreamingMode(int)

httpChunkLength="..."

httpFollowRedirects="true|false"

Whether HTTP redirects (requests with response code 3xx) should be automatically followed.

See also:

httpFollowRedirects2="..."

HttpURLConnection.setFollowRedirects(boolean)

httpFollowRedirects2="true|false"

Similar to httpFollowRedirects="...", but additionally allows for redirects across protocols, e.g. from "http://host/index.html" to "https://host/index.html".

url="u-r-l"

Designates the resource to access.

direct="true|false"

Configures a direct HTTP connection, and ignores any proxy configured with the http[s].proxy(Host|Port) system properties.

See also:

URL.openConnection(Proxy)

Proxy.NO_PROXY

NetworkingProperties

httpProxy="hostname:port"

Configures an HTTP proxy, and overrides any proxy configured with the http[s].proxy(Host|Port) system properties.

See also:

URL.openConnection(Proxy)

Proxy.Type.HTTP

Networking Properties

socksProxy="hostname:port"

Configures a SOCKS proxy, and overrides any proxy configured with the http[s].proxy(Host|Port) system properties.

See also:

URL.openConnection(Proxy)

Proxy.Type.SOCKS

Networking Properties

Subelement Detail

<output>

Configures that data should be copied to the resource.

See also:

URLConnection.getOutputStream()

URLConnection.setDoOutput(boolean)

The following attributes and subelements are mutually exclusive:

file="..."

value="..."

<applicationXWwwFormUrlencoded>

<multipartFormData>

(element text)

Text between start and end tag:

A textual definition of the output; equivalent with the value="..." attribute.

Attributes:

value="text"

The text is written to the resource.

encoding="charset-name"

The encoding to use when the value="..." is written to the resource.

file="file"

The contents of the configured file is written to the resource.

Subelements:

<multipartFormData>

Changes the request property "Content-Type" to "multipart/formdata" and adds the given field to the output.

See also RFC 2388.

Representation of a field in a 'multipart/form-data'-encoded document.

The following attributes are mutually exclusive:

value="..."

file="..."

Attributes:

name="name"

The name of the data field (mandatory).

fileName="file-name"

The "file name" of the data field (optional, defaults to none).

value="text"

The value of the data field.

file="file"

The value of the data field is read from the designated file.

Subelements:

<header>

Adds a header to the data field. An XML element that specifies a name-value pair.

Text between start and end tag:

The "value" text - may alternatively be configured by the "value="..."" attribute.

Attributes:

name="name"

The "name" of the name-value pair.

value="value"

The "value" text - may alternatively be configured by text nested between start and end tags.

<applicationXWwwFormUrlencoded>

Adds another form field. Also verifies that the "Content-Type" header is either not defined or has the value "application/x-www-form-urlencoded". An XML element that specifies a name-value pair.

Text between start and end tag:

The "value" text - may alternatively be configured by the "value="..."" attribute.

Attributes:

name="name"

The "name" of the name-value pair.

value="value"

The "value" text - may alternatively be configured by text nested between start and end tags.

<input>

Configures that the content of the resource should be retrieved. The following attributes and subelements are mutually exclusive:

discard="true"

file="..."

stderr="true"

stdout="true"

property="..."

<jsonAsproperties>

Attributes:

discard="true|false"

Whether the contents of the resource should be discarded.

stdout="true|false"

The content of the resource is written to STDOUT.

stderr="true|false"

The content of the resource is written to STDERR.

file="file"

The content of the resource is written to the designated file.

append="true|false"

Relevant iff file="..." is configured.

property="property-name"

The content of the resource is stored in the named property.

encoding="encoding"

Relevant iff file="..." is configured.

Subelements:

<jsonAsProperties>

Assume the retrieved document is in JSON format, and parse it into properties.

See also:

<jsonProperty>

An ANT element that parses a character string as a JSON document and sets a set of properties accordingly.

Attributes:

name="property-name-prefix"

The name prefix of the properties to be set.

Any FilterChain

Configures a filter chain for the resource content retrieval.

<url>

Designates the resource to access.

See also:

URL.openConnection()

The URL can be specified as a string and/or by syntactic components, as described in RFC 2396, section 3. The individual syntactic components take precendence or those in the string. If a component is neither configured individually, nor in the string, then default values take effect as documented below.

The following attributes and subelements are mutually exclusive:

context="..."

<context>

Text between start and end tag:

A textual definition of the URL. Individual components can be overridden with other attributes.

Attributes:

context="context-url"

The "base URL" for a relative URL (a simplified alternative for the <context> subelement described below) (defaults to none).

protocol="schema|http"

The "protocol" component of the URL.

host="host|localhost"

The "host" component of the URL.

port="port-number"

The "port" component of the URL. The default value Depends on the "protocol" component of the URL

userInfo="user-info"

The "userinfo" component of the URL, like "user [ ':'password]". Defaults to none.

path="path|/"

The "path" component of the URL. (An absolute path begins with a slash ("/"), a relative path doesn't.)

query="query-string"

The "query" component of the URL; is appended to the URL with a question mark ("?"). Can alternatively be configured through <formField> subelements.

ref="anchor"

The "ref" component (also known as "anchor" or "fragment identifier"). Defaults to none.

Subelements:

<formField>

These subelements are encoded and added to the query part of the URL as described in RFC 1866, section 8.2.2. An XML element that specifies a name-value pair.

Text between start and end tag:

The "value" text - may alternatively be configured by the "value="..."" attribute.

Attributes:

name="name"

The "name" of the name-value pair.

value="value"

The "value" text - may alternatively be configured by text nested between start and end tags.

<context>

Configures the "base URL" for a relative URL.

An alternative to context=...; must appear at most once.
(The configuration options for this element are the same as described above.)

<requestProperty>

Configures a "request property". (Request properties have different meanings for different protocols.)

See also:

URLConnection.addRequestProperty(String, String)

An XML element that specifies a name-value pair.

Text between start and end tag:

The "value" text - may alternatively be configured by the "value="..."" attribute.

Attributes:

name="name"

The "name" of the name-value pair.

value="value"

The "value" text - may alternatively be configured by text nested between start and end tags.