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 containConnection.Request
andConnection.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 Description static interface
Connection.Base<T extends Connection.Base>
Common methods for Requests and Responsesstatic interface
Connection.KeyVal
A Key Value tuple.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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description Connection
cookie(String name, String value)
Set a cookie to be sent in the request.Connection
cookies(Map<String,String> cookies)
Adds each of the supplied cookies to the request.Connection.KeyVal
data(String key)
Get the data KeyVal for this key, if anyConnection
data(String... keyvals)
Add a number of request data parameters.Connection
data(String key, String value)
Add a request data parameter.Connection
data(String key, String filename, InputStream inputStream)
Add an input stream as a request data parameter.Connection
data(Collection<Connection.KeyVal> data)
Adds all of the supplied data to the request data parametersConnection
data(Map<String,String> data)
Adds all of the supplied data to the request data parametersConnection.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(String name, String value)
Set a request header.Connection
headers(Map<String,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(String charset)
Sets the default post data character set for x-www-form-urlencoded post dataConnection
proxy(String host, int port)
Set the HTTP proxy to use for this request.Connection
proxy(Proxy proxy)
Set the proxy to use for this request.Connection
referrer(String referrer)
Set the request referrer (aka "referer") header.Connection.Request
request()
Get the request object associated with this connectionConnection
request(Connection.Request request)
Set the connection's requestConnection
requestBody(String body)
Set a POST (or PUT) request body.Connection.Response
response()
Get the response, once the request has been executedConnection
response(Connection.Response response)
Set the connection's responseConnection
timeout(int millis)
Set the request timeouts (connect and read).Connection
url(String url)
Set the request URL to fetch.Connection
url(URL url)
Set the request URL to fetch.Connection
userAgent(String userAgent)
Set the request user-agent header.Connection
validateTLSCertificates(boolean value)
Disable/enable TLS certificates validation for HTTPS requests.
-
-
-
Method Detail
-
url
Connection url(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(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(Proxy proxy)
Set the proxy to use for this request. Set tonull
to disable.- Parameters:
proxy
- proxy to use- Returns:
- this Connection, for chaining
-
proxy
Connection proxy(String host, int port)
Set the HTTP proxy to use for this request.- Parameters:
host
- the proxy hostnameport
- the proxy port- Returns:
- this Connection, for chaining
-
userAgent
Connection userAgent(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 request timeouts (connect and read). If a timeout occurs, an IOException will be thrown. The default timeout is (30000 millis). A timeout of zero is treated as an infinite timeout.- Parameters:
millis
- number of milliseconds (thousandths of a second) before timing out connects or reads.- Returns:
- this Connection, for chaining
-
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(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)
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
-
data
Connection data(String key, 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 keyvalue
- data value- Returns:
- this Connection, for chaining
-
data
Connection data(String key, String filename, 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 aFileInputStream
. You must close the InputStream in afinally
block.- Returns:
- this Connections, for chaining
-
data
Connection data(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(Map<String,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(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(String key)
Get the data KeyVal for this key, if any- Parameters:
key
- the data key- Returns:
- null if not set
-
requestBody
Connection requestBody(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.:
If any data key/vals are supplied, they will be sent as URL query params.Jsoup.connect(url) .requestBody(json) .header("Content-Type", "application/json") .post();
- Returns:
- this Request, for chaining
-
header
Connection header(String name, String value)
Set a request header.- Parameters:
name
- header namevalue
- header value- Returns:
- this Connection, for chaining
- See Also:
Connection.Base.headers()
-
headers
Connection headers(Map<String,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(String name, String value)
Set a cookie to be sent in the request.- Parameters:
name
- name of cookievalue
- value of cookie- Returns:
- this Connection, for chaining
-
cookies
Connection cookies(Map<String,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(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 IOException
Execute the request as a GET, and parse the result.- Returns:
- parsed Document
- Throws:
MalformedURLException
- if the request URL is not a HTTP or HTTPS URL, or is otherwise malformedHttpStatusException
- if the response is not OK and HTTP response errors are not ignoredUnsupportedMimeTypeException
- if the response mime type is not supported and those errors are not ignoredSocketTimeoutException
- if the connection times outIOException
- on error
-
post
Document post() throws IOException
Execute the request as a POST, and parse the result.- Returns:
- parsed Document
- Throws:
MalformedURLException
- if the request URL is not a HTTP or HTTPS URL, or is otherwise malformedHttpStatusException
- if the response is not OK and HTTP response errors are not ignoredUnsupportedMimeTypeException
- if the response mime type is not supported and those errors are not ignoredSocketTimeoutException
- if the connection times outIOException
- on error
-
execute
Connection.Response execute() throws IOException
Execute the request.- Returns:
- a response object
- Throws:
MalformedURLException
- if the request URL is not a HTTP or HTTPS URL, or is otherwise malformedHttpStatusException
- if the response is not OK and HTTP response errors are not ignoredUnsupportedMimeTypeException
- if the response mime type is not supported and those errors are not ignoredSocketTimeoutException
- if the connection times outIOException
- 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
-
-