org.jsoup

Interface Connection

All Known Implementing Classes:

HttpConnection

public interface Connection

A Connection provides a convenient interface to fetch content from the web, and parse them into Documents.

To get a new Connection, use Jsoup.connect(String). Connections contain Connection.Request and Connection.Response objects. The request objects are reusable as prototype requests.

Request configuration can be made using either the shortcut methods in Connection (e.g. userAgent(String)), or by methods in the Connection.Request object directly. All request configuration must be made before the request is executed.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Connection.Base<T extends Connection.Base> Common methods for Requests and Responses
static interface	Connection.KeyVal A Key:Value tuple(+), used for form data.
static class	Connection.Method GET and POST http methods.
static interface	Connection.Request Represents a HTTP request.
static interface	Connection.Response Represents a HTTP response.

Method Summary

Modifier and Type	Method and Description
Connection	cookie(java.lang.String name, java.lang.String value) Set a cookie to be sent in the request.
Connection	cookies(java.util.Map<java.lang.String,java.lang.String> cookies) Adds each of the supplied cookies to the request.
Connection	data(java.util.Collection<Connection.KeyVal> data) Adds all of the supplied data to the request data parameters
Connection	data(java.util.Map<java.lang.String,java.lang.String> data) Adds all of the supplied data to the request data parameters
Connection	data(java.lang.String... keyvals) Add a number of request data parameters.
Connection.KeyVal	data(java.lang.String key) Get the data KeyVal for this key, if any
Connection	data(java.lang.String key, java.lang.String value) Add a request data parameter.
Connection	data(java.lang.String key, java.lang.String filename, java.io.InputStream inputStream) Add an input stream as a request data parameter.
Connection	data(java.lang.String key, java.lang.String filename, java.io.InputStream inputStream, java.lang.String contentType) Add an input stream as a request data parameter.
Connection.Response	execute() Execute the request.
Connection	followRedirects(boolean followRedirects) Configures the connection to (not) follow server redirects.
Document	get() Execute the request as a GET, and parse the result.
Connection	header(java.lang.String name, java.lang.String value) Set a request header.
Connection	headers(java.util.Map<java.lang.String,java.lang.String> headers) Adds each of the supplied headers to the request.
Connection	ignoreContentType(boolean ignoreContentType) Ignore the document's Content-Type when parsing the response.
Connection	ignoreHttpErrors(boolean ignoreHttpErrors) Configures the connection to not throw exceptions when a HTTP error occurs.
Connection	maxBodySize(int bytes) Set the maximum bytes to read from the (uncompressed) connection into the body, before the connection is closed, and the input truncated.
Connection	method(Connection.Method method) Set the request method to use, GET or POST.
Connection	parser(Parser parser) Provide an alternate parser to use when parsing the response to a Document.
Document	post() Execute the request as a POST, and parse the result.
Connection	postDataCharset(java.lang.String charset) Sets the default post data character set for x-www-form-urlencoded post data
Connection	proxy(java.net.Proxy proxy) Set the proxy to use for this request.
Connection	proxy(java.lang.String host, int port) Set the HTTP proxy to use for this request.
Connection	referrer(java.lang.String referrer) Set the request referrer (aka "referer") header.
Connection.Request	request() Get the request object associated with this connection
Connection	request(Connection.Request request) Set the connection's request
Connection	requestBody(java.lang.String body) Set a POST (or PUT) request body.
Connection.Response	response() Get the response, once the request has been executed
Connection	response(Connection.Response response) Set the connection's response
Connection	sslSocketFactory(javax.net.ssl.SSLSocketFactory sslSocketFactory) Set custom SSL socket factory
Connection	timeout(int millis) Set the total request timeout duration.
Connection	url(java.lang.String url) Set the request URL to fetch.
Connection	url(java.net.URL url) Set the request URL to fetch.
Connection	userAgent(java.lang.String userAgent) Set the request user-agent header.
Connection	validateTLSCertificates(boolean value) Deprecated. as distributions (specifically Google Play) are starting to show warnings if these checks are disabled.

Method Detail

url

Connection url(java.net.URL url)

Set the request URL to fetch. The protocol must be HTTP or HTTPS.

Parameters:

url - URL to connect to

Returns:

this Connection, for chaining

url

Connection url(java.lang.String url)

Set the request URL to fetch. The protocol must be HTTP or HTTPS.

Parameters:

url - URL to connect to

Returns:

this Connection, for chaining

proxy

Connection proxy(java.net.Proxy proxy)

Set the proxy to use for this request. Set to null to disable.

Parameters:

proxy - proxy to use

Returns:

this Connection, for chaining

proxy

Connection proxy(java.lang.String host,
                 int port)

Set the HTTP proxy to use for this request.

Parameters:

host - the proxy hostname

port - the proxy port

Returns:

this Connection, for chaining

userAgent

Connection userAgent(java.lang.String userAgent)

Set the request user-agent header.

Parameters:

userAgent - user-agent to use

Returns:

this Connection, for chaining

See Also:

HttpConnection.DEFAULT_UA

timeout

Connection timeout(int millis)

Set the total request timeout duration. If a timeout occurs, an SocketTimeoutException will be thrown.

The default timeout is 30 seconds (30,000 millis). A timeout of zero is treated as an infinite timeout.

Note that this timeout specifies the combined maximum duration of the connection time and the time to read the full response.

Parameters:

millis - number of milliseconds (thousandths of a second) before timing out connects or reads.

Returns:

this Connection, for chaining

See Also:

maxBodySize(int)

maxBodySize

Connection maxBodySize(int bytes)

Set the maximum bytes to read from the (uncompressed) connection into the body, before the connection is closed, and the input truncated. The default maximum is 1MB. A max size of zero is treated as an infinite amount (bounded only by your patience and the memory available on your machine).

Parameters:

bytes - number of bytes to read from the input before truncating

Returns:

this Connection, for chaining

referrer

Connection referrer(java.lang.String referrer)

Set the request referrer (aka "referer") header.

Parameters:

referrer - referrer to use

Returns:

this Connection, for chaining

followRedirects

Connection followRedirects(boolean followRedirects)

Configures the connection to (not) follow server redirects. By default this is true.

Parameters:

followRedirects - true if server redirects should be followed.

Returns:

this Connection, for chaining

method

Connection method(Connection.Method method)

Set the request method to use, GET or POST. Default is GET.

Parameters:

method - HTTP request method

Returns:

this Connection, for chaining

ignoreHttpErrors

Connection ignoreHttpErrors(boolean ignoreHttpErrors)

Configures the connection to not throw exceptions when a HTTP error occurs. (4xx - 5xx, e.g. 404 or 500). By default this is false; an IOException is thrown if an error is encountered. If set to true, the response is populated with the error body, and the status message will reflect the error.

Parameters:

ignoreHttpErrors - - false (default) if HTTP errors should be ignored.

Returns:

this Connection, for chaining

ignoreContentType

Connection ignoreContentType(boolean ignoreContentType)

Ignore the document's Content-Type when parsing the response. By default this is false, an unrecognised content-type will cause an IOException to be thrown. (This is to prevent producing garbage by attempting to parse a JPEG binary image, for example.) Set to true to force a parse attempt regardless of content type.

Parameters:

ignoreContentType - set to true if you would like the content type ignored on parsing the response into a Document.

Returns:

this Connection, for chaining

validateTLSCertificates

Connection validateTLSCertificates(boolean value)

Deprecated. as distributions (specifically Google Play) are starting to show warnings if these checks are disabled.

Disable/enable TLS certificates validation for HTTPS requests.

By default this is true; all connections over HTTPS perform normal validation of certificates, and will abort requests if the provided certificate does not validate.

Some servers use expired, self-generated certificates; or your JDK may not support SNI hosts. In which case, you may want to enable this setting.

Be careful and understand why you need to disable these validations.

Parameters:

value - if should validate TLS (SSL) certificates. true by default.

Returns:

this Connection, for chaining

sslSocketFactory

Connection sslSocketFactory(javax.net.ssl.SSLSocketFactory sslSocketFactory)

Set custom SSL socket factory

Parameters:

sslSocketFactory - custom SSL socket factory

Returns:

this Connection, for chaining

data

Connection data(java.lang.String key,
                java.lang.String value)

Add a request data parameter. Request parameters are sent in the request query string for GETs, and in the request body for POSTs. A request may have multiple values of the same name.

Parameters:

key - data key

value - data value

Returns:

this Connection, for chaining

data

Connection data(java.lang.String key,
                java.lang.String filename,
                java.io.InputStream inputStream)

Add an input stream as a request data parameter. For GETs, has no effect, but for POSTS this will upload the input stream.

Parameters:

key - data key (form item name)

filename - the name of the file to present to the remove server. Typically just the name, not path, component.

inputStream - the input stream to upload, that you probably obtained from a FileInputStream. You must close the InputStream in a finally block.

Returns:

this Connections, for chaining

See Also:

if you want to set the uploaded file's mimetype.

data

Connection data(java.lang.String key,
                java.lang.String filename,
                java.io.InputStream inputStream,
                java.lang.String contentType)

Add an input stream as a request data parameter. For GETs, has no effect, but for POSTS this will upload the input stream.

Parameters:

key - data key (form item name)

filename - the name of the file to present to the remove server. Typically just the name, not path, component.

inputStream - the input stream to upload, that you probably obtained from a FileInputStream.

contentType - the Content Type (aka mimetype) to specify for this file. You must close the InputStream in a finally block.

Returns:

this Connections, for chaining

data

Connection data(java.util.Collection<Connection.KeyVal> data)

Adds all of the supplied data to the request data parameters

Parameters:

data - collection of data parameters

Returns:

this Connection, for chaining

data

Connection data(java.util.Map<java.lang.String,java.lang.String> data)

Adds all of the supplied data to the request data parameters

Parameters:

data - map of data parameters

Returns:

this Connection, for chaining

data

Connection data(java.lang.String... keyvals)

Add a number of request data parameters. Multiple parameters may be set at once, e.g.: .data("name", "jsoup", "language", "Java", "language", "English"); creates a query string like: ?name=jsoup&language=Java&language=English

Parameters:

keyvals - a set of key value pairs.

Returns:

this Connection, for chaining

data

Connection.KeyVal data(java.lang.String key)

Get the data KeyVal for this key, if any

Parameters:

key - the data key

Returns:

null if not set

requestBody

Connection requestBody(java.lang.String body)

Set a POST (or PUT) request body. Useful when a server expects a plain request body, not a set for URL encoded form key/value pairs. E.g.:

Jsoup.connect(url)
 .requestBody(json)
 .header("Content-Type", "application/json")
 .post();

If any data key/vals are supplied, they will be sent as URL query params.

Returns:

this Request, for chaining

header

Connection header(java.lang.String name,
                  java.lang.String value)

Set a request header.

Parameters:

name - header name

value - header value

Returns:

this Connection, for chaining

See Also:

Connection.Base.headers()

headers

Connection headers(java.util.Map<java.lang.String,java.lang.String> headers)

Adds each of the supplied headers to the request.

Parameters:

headers - map of headers name -> value pairs

Returns:

this Connection, for chaining

See Also:

Connection.Base.headers()

cookie

Connection cookie(java.lang.String name,
                  java.lang.String value)

Set a cookie to be sent in the request.

Parameters:

name - name of cookie

value - value of cookie

Returns:

this Connection, for chaining

cookies

Connection cookies(java.util.Map<java.lang.String,java.lang.String> cookies)

Adds each of the supplied cookies to the request.

Parameters:

cookies - map of cookie name -> value pairs

Returns:

this Connection, for chaining

parser

Connection parser(Parser parser)

Provide an alternate parser to use when parsing the response to a Document. If not set, defaults to the HTML parser, unless the response content-type is XML, in which case the XML parser is used.

Parameters:

parser - alternate parser

Returns:

this Connection, for chaining

postDataCharset

Connection postDataCharset(java.lang.String charset)

Sets the default post data character set for x-www-form-urlencoded post data

Parameters:

charset - character set to encode post data

Returns:

this Connection, for chaining

get

Document get()
      throws java.io.IOException

Execute the request as a GET, and parse the result.

Returns:

parsed Document

Throws:

java.net.MalformedURLException - if the request URL is not a HTTP or HTTPS URL, or is otherwise malformed

HttpStatusException - if the response is not OK and HTTP response errors are not ignored

UnsupportedMimeTypeException - if the response mime type is not supported and those errors are not ignored

java.net.SocketTimeoutException - if the connection times out

java.io.IOException - on error

post

Document post()
       throws java.io.IOException

Execute the request as a POST, and parse the result.

Returns:

parsed Document

Throws:

java.net.MalformedURLException - if the request URL is not a HTTP or HTTPS URL, or is otherwise malformed

HttpStatusException - if the response is not OK and HTTP response errors are not ignored

UnsupportedMimeTypeException - if the response mime type is not supported and those errors are not ignored

java.net.SocketTimeoutException - if the connection times out

java.io.IOException - on error

execute

Connection.Response execute()
                     throws java.io.IOException

Execute the request.

Returns:

a response object

Throws:

java.net.MalformedURLException - if the request URL is not a HTTP or HTTPS URL, or is otherwise malformed

HttpStatusException - if the response is not OK and HTTP response errors are not ignored

UnsupportedMimeTypeException - if the response mime type is not supported and those errors are not ignored

java.net.SocketTimeoutException - if the connection times out

java.io.IOException - on error

request

Connection.Request request()

Get the request object associated with this connection

Returns:

request

request

Connection request(Connection.Request request)

Set the connection's request

Parameters:

request - new request object

Returns:

this Connection, for chaining

response

Connection.Response response()

Get the response, once the request has been executed

Returns:

response

response

Connection response(Connection.Response response)

Set the connection's response

Parameters:

response - new response

Returns:

this Connection, for chaining