public class UserAgent extends Object
<html>
Element, whose child nodes are <head>
and <body>
Elements. Each Element contains zero or more attributes (such as <body id='main'
) and zero or more children. The children can be Text objects, Comment objects, or other Element Objects.Modifier and Type | Field and Description |
---|---|
Cookies |
cookies
A container for Cookies.
|
Document |
doc
The Document created as a result of the most recent request, where response type was HTML or XML.
|
JNode |
json
The JSON object created as a result of the most recent request, where response type was JSON.
|
HttpResponse |
response
The Response object generated by the most recent HTTP request.
|
UserAgentSettings |
settings
The UserAgent's settings.
|
Constructor and Description |
---|
UserAgent()
Creates a UserAgent; throws runtime exception (ExpirationException) if software has expired.
|
Modifier and Type | Method and Description |
---|---|
UserAgent |
addBasicAuthenticator(String realmName,
String userId,
String password)
Adds a BasicAuthenticator to the collection of BasicAuthenticators.
|
UserAgent |
addBasicAuthenticator(String realmName,
String protectedDir,
String userId,
String password)
Adds a BasicAuthenticator to the collection of BasicAuthenticators.
|
boolean |
cachingEnabled()
Indicates whether document caching is enabled.
|
void |
close()
Performs cleanup such as saving cookies to disk.
|
UserAgent |
copy()
returns a new UserAgent who's state information for certain fields is (deep) copied from this UserAgent; those fields are UserAgent.settings, UserAgent.cookies, as well as the location url (referer), the proxy host, and proxy port.
|
HttpResponse |
download(String url,
File downloadFile)
Downloads and saves the content at the specified url as the specified File, overwriting the file if it already exists; this method does not invoke the parser, and therefore UserAgent.doc is set to an empty Document; UserAgent.response is created to represent the HttpResponse.
|
Cache |
getCache()
Returns the current cache or null if no cache is set.
|
Handler |
getHandler(String contentType)
Returns the content handler that was set for the specified (case-insensitive) contentType, or null if no Handler was set.
|
MultiMap<String,String> |
getHeaders(String key)
Returns a MultiMap containing the headers received for the most recent request, where each header name is associated with one or more header values.
|
String |
getLocation()
Retrieves the current location (url).
|
String |
getProxyHost()
Retrieves the ip address of the http proxy or null if no proxy is being used.
|
int |
getProxyPort()
Retrieves the port number of the current http proxy being used or -1 if the proxy host is unset.
|
String |
getReferer()
Retrieves the referer value (ie, the url of the last document visited, which is sent in the header of the next HTTP request).
|
String |
getSource()
Returns the original unparsed source of the last request, or an empty String if there is no source from a previous request.
|
static String |
getVersionInfo()
returns the version number, edition, and expiration date of this Jaunt release.
|
Document |
open(File file)
Parses the HTML/XHTML/XML within the specified File, and creates UserAgent.doc to represent the Document (which is also returned by this method).
|
Document |
open(File file,
String documentUrl)
Parses the HTML/XHTML/XML within the specified File, and creates UserAgent.doc to represent the Document (which is also returned by this method).
|
Document |
openContent(String content)
Parses the source HTML, XHTML, or XML and creates UserAgent.doc to represent the Document (which is also returned by this method).
|
Document |
openContent(String content,
String documentUrl)
Parses the source HTML, XHTML, or XML and creates UserAgent.doc to represent the Document (which is also returned by this method).
|
JNode |
openJSON(File file)
Parses the JSON within the specified File, and creates UserAgent.json to represent the root node of the JSON object (which is also returned by this method).
|
JNode |
openJSON(String json)
Parses the specified JSON and creates UserAgent.json to represent the root node of the JSON object (which is also returned by this method).
|
int |
removeBasicAuthenticators(String realmName)
Removes any basic authenticators associated with the specified realmName.
|
FilterCallback |
removeFilter()
Deprecated.
|
Document |
send(HttpRequest httpRequest)
Sends the specified HttpRequest (GET, POST, HEAD, DELETE, or PUT)
|
Document |
sendDELETE(String url)
Sends an HTTP DELETE request for the specified url; UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
Document |
sendDELETE(String url,
String... additionalHeaders)
Sends an HTTP DELETE request for the specified url; UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
Document |
sendGET(String url)
Sends an HTTP GET request for the specified url; UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
Document |
sendGET(String url,
String... additionalHeaders)
Sends an HTTP GET request for the specified url; UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
HttpResponse |
sendHEAD(String url)
Sends an HTTP HEAD request to the specified url; UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information), and is also the return value.
|
HttpResponse |
sendHEAD(String url,
String... additionalHeaders)
Sends an HTTP HEAD request to the specified url; UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information), and is also the return value.
|
Document |
sendPOST(String url,
String postData)
Sends an HTTP POST request for the specified url and queryString; UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
Document |
sendPOST(String url,
String postData,
String... additionalHeaders)
Sends an HTTP POST request for the specified url and queryString; UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
Document |
sendPUT(String url,
String content)
Sends an HTTP PUT request for the specified url and content; UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
Document |
sendPUT(String url,
String content,
String... additionalHeaders)
Sends an HTTP PUT request for the specified url and content; UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
UserAgent |
setCache(Cache cache)
Sets the specified cache; the cache must be enabled before being used.
|
UserAgent |
setCacheEnabled(boolean enable)
Turns on/off caching, which causes HTML/XHTML source retrieved by HTTP GET request to be stored in the cache and pulled from that cache for any subsequent GET requests to the same url, as long as caching is enabled; by default, caching is handled by the FileSystemCache, which stores files in a directory called "jaunt_cache", which is in the directory specified by UserAgentSettings.outputPath.
|
UserAgent |
setFilter(FilterCallback filter)
Deprecated.
|
UserAgent |
setHandler(String contentType,
Handler handler)
Sets the content handler for the specified contentType; the Handler receives callbacks to process the content rather than having it handled by the parser.
|
UserAgent |
setProxyHost(String proxyHost)
Sets or clears the ip address of the http proxy.
|
UserAgent |
setProxyPort(int proxyPort)
Sets the port number of the http proxy to be used.
|
UserAgent |
setReferer(String referer)
Sets the value of the referer header in the next HTTP request.
|
Document |
visit(String url)
Directs the UserAgent to visit the specified url (ie, sends an HTTP GET request); UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
Document |
visit(String url,
int redirectCount)
Directs the UserAgent to visit the specified url (ie, to send an HTTP GET request); UserAgent.doc is created to represent the retrieved HTML/XML/XHTML Document (which is also returned by this method); UserAgent.response is created to represent the HttpResponse (the response headers and other response-related information).
|
public HttpResponse response
public UserAgentSettings settings
public Document doc
public JNode json
public Cookies cookies
public UserAgent() throws ExpirationException
ExpirationException
public UserAgent copy()
public MultiMap<String,String> getHeaders(String key)
@Deprecated public UserAgent setFilter(FilterCallback filter)
@Deprecated public FilterCallback removeFilter()
public UserAgent setCache(Cache cache)
cache
- the cache to be used for storing XHTML/HTML source, or null to set no cache.setCacheEnabled(boolean)
public Cache getCache()
public UserAgent setCacheEnabled(boolean enable) throws CacheException
CacheException
public boolean cachingEnabled()
public UserAgent setHandler(String contentType, Handler handler)
contentType
- the (case-insensitive) content-type for the specified Handler (eg "text/css", "text/javascript", "image/png", etc), as designated in the HTTP response header.handler
- an object that implements the Handler interface for handling the response content.public Handler getHandler(String contentType)
public UserAgent setProxyHost(String proxyHost)
proxyHost
- proxy ip address to be used, or null to remove proxysetProxyPort(int)
public String getProxyHost()
public UserAgent setProxyPort(int proxyPort)
proxyPort
- proxy port number.setProxyHost(String)
public int getProxyPort()
public UserAgent addBasicAuthenticator(String realmName, String userId, String password)
realmName
- the string that will be shown when the browser pops up the login window, eg - "Please enter your username and password for [realm name]"public UserAgent addBasicAuthenticator(String realmName, String protectedDir, String userId, String password)
protectedDir
- is an absolute url to the protected directory.realmName
- the string that will be shown when the browser pops up the login window, eg - "Please enter your username and password for [realm name]"public int removeBasicAuthenticators(String realmName)
public UserAgent setReferer(String referer)
public String getReferer()
public String getLocation()
public String getSource()
public Document open(File file) throws IOException, ResponseException
ResponseException
- may occur if the document contains a meta tag that redirects to a url that results in the ResponseException.IOException
public Document open(File file, String documentUrl) throws IOException, ResponseException
documentUrl
- the url of the content in the specified file, used to convert relative/implicit urls in the document to absolute urls; if null, relative urls are not converted.ResponseException
- may occur if the document contains a meta tag that redirects to a url that results in the ResponseException.IOException
public Document openContent(String content) throws ResponseException
content
- the HTML, XHTML, or XML content.ResponseException
parse(String)
public JNode openJSON(File file) throws IOException
IOException
public JNode openJSON(String json)
json
- JSON content.public Document openContent(String content, String documentUrl) throws ResponseException
content
- the HTML, XHTML, or XML content.documentUrl
- the url of the specified content, used to convert relative/implicit urls in the document to absolute urls; if null, relative urls are not converted.ResponseException
parse(String)
public Document send(HttpRequest httpRequest) throws ResponseException
ResponseException
public Document visit(String url) throws ResponseException
ResponseException
public Document visit(String url, int redirectCount) throws ResponseException
redirectCount
- the number of consecutive redirections that occurred immediately before this request.ResponseException
public Document sendGET(String url) throws ResponseException
ResponseException
visit(String)
public Document sendGET(String url, String... additionalHeaders) throws ResponseException
additionalHeaders
- each String must contain a header name followed by a colon followed by the header value (these headers are added-to or override the auto-managed headers [eg cookies, referer, etc] as well as the headers specified in UserAgent.settings.defaultRequestHeaders); can be nullResponseException
visit(String)
public HttpResponse download(String url, File downloadFile) throws ResponseException
url
- the url (beginning with http, https, or ftp) of the file to download.ResponseException
public Document sendDELETE(String url) throws ResponseException
ResponseException
public Document sendDELETE(String url, String... additionalHeaders) throws ResponseException
additionalHeaders
- each String must contain a header name followed by a colon followed by the header value (these headers are added-to or override the auto-managed headers [eg cookies, referer, etc] as well as the headers specified in UserAgent.settings.defaultRequestHeaders); can be nullResponseException
public Document sendPUT(String url, String content) throws ResponseException
content
- the body of the PUT content.ResponseException
public Document sendPUT(String url, String content, String... additionalHeaders) throws ResponseException
additionalHeaders
- each String must contain a header name followed by a colon followed by the header value (these headers are added-to or override the auto-managed headers [eg cookies, referer, etc] as well as the headers specified in UserAgent.settings.defaultRequestHeaders); can be nullcontent
- the body of the PUT content.ResponseException
public HttpResponse sendHEAD(String url, String... additionalHeaders) throws ResponseException
additionalHeaders
- each String must contain a header name followed by a colon followed by the header value (these headers are added-to or override the auto-managed headers [eg cookies, referer, etc] as well as the headers specified in UserAgent.settings.defaultRequestHeaders); can be nullResponseException
public HttpResponse sendHEAD(String url) throws ResponseException
ResponseException
public void close() throws IOException
IOException
public Document sendPOST(String url, String postData) throws ResponseException
postData
- the posted data, which may be url-encoded queryString data (eg "foo=bar&msg=hi%20there") or some other data payload (or null for no data).ResponseException
public Document sendPOST(String url, String postData, String... additionalHeaders) throws ResponseException
postData
- the posted data, which may be url-encoded queryString data (eg "foo=bar&msg=hi%20there") or some other data payload (or null for no data).additionalHeaders
- each String must contain a header name followed by a colon followed by the header value (these headers are added-to or override the auto-managed headers [eg cookies, referer, etc] as well as the headers specified in UserAgent.settings.defaultRequestHeaders); can be nullResponseException
public static String getVersionInfo()