public interface Connection
To start a new session, use either Jsoup.newSession()
or Jsoup.connect(String)
.
Connections contain Connection.Request
and Connection.Response
objects (once executed). Configuration
settings (URL, timeout, useragent, etc) set on a session will be applied by default to each subsequent request.
To start a new request from the session, use newRequest()
.
Cookies are stored in memory for the duration of the session. For that reason, do not use one single session for all
requests in a long-lived application, or you are likely to run out of memory, unless care is taken to clean up the
cookie store. The cookie store for the session is available via cookieStore()
. You may provide your own
implementation via cookieStore(java.net.CookieStore)
before making 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. When used as an ongoing session, initialize all defaults prior to making multi-threaded newRequest()
s.
Note that the term "Connection" used here does not mean that a long-lived connection is held against a server for
the lifetime of the Connection object. A socket connection is only made at the point of request execution (execute()
, get()
, or post()
), and the server's response consumed.
For multi-threaded implementations, it is important to use a newRequest()
for each request. The session may
be shared across threads but a given request, not.
Modifier and Type | Interface and Description |
---|---|
static interface |
Connection.Base<T extends Connection.Base<T>>
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.
|
Modifier and Type | Method and 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.
|
CookieStore |
cookieStore()
Get the cookie store used by this Connection.
|
Connection |
cookieStore(CookieStore cookieStore)
Provide a custom or pre-filled CookieStore to be used on requests made by this Connection.
|
Connection |
data(Collection<Connection.KeyVal> data)
Adds all of the supplied data to the request data parameters
|
Connection |
data(Map<String,String> data)
Adds all of the supplied data to the request data parameters
|
Connection |
data(String... keyvals)
Add one or more request
key, val data parameter pairs. |
Connection.KeyVal |
data(String key)
Get the data KeyVal for this key, if any
|
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(String key,
String filename,
InputStream inputStream,
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(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 (i.e.
|
Connection |
method(Connection.Method method)
Set the request method to use, GET or POST.
|
Connection |
newRequest()
Creates a new request, using this Connection as the session-state and to initialize the connection settings (which may then be independently on the returned Connection.Request object).
|
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 data
|
Connection |
proxy(Proxy proxy)
Set the proxy to use for this request.
|
Connection |
proxy(String host,
int port)
Set the HTTP 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 connection
|
Connection |
request(Connection.Request request)
Set the connection's request
|
Connection |
requestBody(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(SSLSocketFactory sslSocketFactory)
Set custom SSL socket factory
|
Connection |
timeout(int millis)
Set the total request timeout duration.
|
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 newRequest()
Connection url(URL url)
url
- URL to connect toConnection url(String url)
url
- URL to connect toConnection proxy(@Nullable Proxy proxy)
null
to disable a previously set proxy.proxy
- proxy to useConnection proxy(String host, int port)
host
- the proxy hostnameport
- the proxy portConnection userAgent(String userAgent)
userAgent
- user-agent to useHttpConnection.DEFAULT_UA
Connection timeout(int millis)
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.
millis
- number of milliseconds (thousandths of a second) before timing out connects or reads.maxBodySize(int)
Connection maxBodySize(int bytes)
0
is treated as an infinite amount (bounded only by your patience and the memory available on your
machine).bytes
- number of bytes to read from the input before truncatingConnection referrer(String referrer)
referrer
- referrer to useConnection followRedirects(boolean followRedirects)
followRedirects
- true if server redirects should be followed.Connection method(Connection.Method method)
method
- HTTP request methodConnection ignoreHttpErrors(boolean ignoreHttpErrors)
ignoreHttpErrors
- - false (default) if HTTP errors should be ignored.Connection ignoreContentType(boolean ignoreContentType)
ignoreContentType
- set to true if you would like the content type ignored on parsing the response into a
Document.Connection sslSocketFactory(SSLSocketFactory sslSocketFactory)
sslSocketFactory
- custom SSL socket factoryConnection data(String key, String value)
key
- data keyvalue
- data valueConnection data(String key, String filename, InputStream inputStream)
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.if you want to set the uploaded file's mimetype.
Connection data(String key, String filename, InputStream inputStream, String contentType)
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.Connection data(Collection<Connection.KeyVal> data)
data
- collection of data parametersConnection data(Map<String,String> data)
data
- map of data parametersConnection data(String... keyvals)
key, val
data parameter pairs.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
For GET requests, data parameters will be sent on the request query string. For POST (and other methods that
contain a body), they will be sent as body form parameters, unless the body is explicitly set by requestBody(String)
, in which case they will be query string parameters.
keyvals
- a set of key value pairs.@Nullable Connection.KeyVal data(String key)
key
- the data keyConnection requestBody(String body)
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.Connection header(String name, String value)
name
- header namevalue
- header valueConnection.Base.headers()
Connection headers(Map<String,String> headers)
headers
- map of headers name -> value pairsConnection.Base.headers()
Connection cookie(String name, String value)
name
- name of cookievalue
- value of cookieConnection cookies(Map<String,String> cookies)
cookies
- map of cookie name -> value pairsConnection cookieStore(CookieStore cookieStore)
cookieStore
- a cookie store to use for subsequent requestsCookieStore cookieStore()
Connection parser(Parser parser)
parser
- alternate parserConnection postDataCharset(String charset)
charset
- character set to encode post dataDocument get() throws IOException
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 errorDocument post() throws IOException
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 errorConnection.Response execute() throws IOException
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 errorConnection.Request request()
Connection request(Connection.Request request)
request
- new request objectConnection.Response response()
IllegalArgumentException
- if called before the response has been executed.Connection response(Connection.Response response)
response
- new responseCopyright © 2009–2024 Jonathan Hedley. All rights reserved.