dw.net
Class HTTPClient
Object
dw.net.HTTPClient
The HTTPClient class supports the HTTP methods GET, POST, HEAD, PUT, PATCH, OPTIONS, and DELETE. If a secure connection via HTTPS is established the used server certificate or the signing CAs certificate needs to be imported into the customer key store via Business Manager. Note: when this class is used with sensitive data, be careful in persisting sensitive information.
 
 var httpClient : HTTPClient = new HTTPClient();
 var message : String;
 httpClient.open('GET', 'http://www.myinstance.com/feed.xml');
 httpClient.setTimeout(3000);
 httpClient.send();
 if (httpClient.statusCode == 200)
 {
      message = httpClient.text;
 }
 else
 {
     // error handling
     message="An error occurred with status code "+httpClient.statusCode;
 }
 
 
Constants
DEFAULT_GET_FILE_SIZE  :  Number = 5242880
The default size for sendAndReceiveToFile() returning a File is 5MB deprecated in favor of MAX_GET_FILE_SIZE
Deprecated:
Use MAX_GET_FILE_SIZE instead.
MAX_GET_FILE_SIZE  :  Number = 209715200
The maximum permitted size (in bytes) of an HTTP response when calling operations which write the response to file. (200MB)
MAX_GET_MEM_SIZE  :  Number = 10485760
The maximum permitted size (in bytes) of an HTTP response when calling operations which store the response in memory. (10MB)
Properties
allResponseHeaders  :  HashMap  (Read Only)
All response headers as a map containing the name and value of the response header.
Deprecated:
Use getResponseHeaders() instead.
errorText  :  String  (Read Only)
The returned message body as text for HTTP status code greater or equal to 400. Error messages are not written to the response file.
responseHeaders  :  Map  (Read Only)
All response headers as a map in which each entry represents an individual header. The key of the entry holds the header name and the entry value holds a list of all header values.
statusCode  :  Number  (Read Only)
The status code of the last HTTP operation.
statusMessage  :  String  (Read Only)
The message text of the last HTTP operation.
text  :  String  (Read Only)
The returned message body as text for HTTP status codes between 200 and 299.
timeout  :  Number
The timeout for this client, in milliseconds.
Constructor Summary
Method Summary
enableCaching(ttl : Number) : void
Calling this method enables caching for GET requests.
getAllResponseHeaders() : HashMap
Returns all response headers as a map containing the name and value of the response header.
getErrorText() : String
Returns the returned message body as text for HTTP status code greater or equal to 400.
getResponseHeader(header : String) : String
Returns a specific response header from the last HTTP operation.
getResponseHeaders(name : String) : List
Returns all the values of a response header from the last HTTP operation as a list of strings.
getResponseHeaders() : Map
Returns all response headers as a map in which each entry represents an individual header.
getStatusCode() : Number
Returns the status code of the last HTTP operation.
getStatusMessage() : String
Returns the message text of the last HTTP operation.
getText() : String
Returns the returned message body as text for HTTP status codes between 200 and 299.
getText(encoding : String) : String
Returns the returned message body as text for HTTP status codes between 200 and 299.
getTimeout() : Number
Returns the timeout for this client, in milliseconds.
open(method : String, url : String) : void
Opens the specified URL using the specified method.
open(method : String, url : String, async : boolean, user : String, password : String) : void
Deprecated method.
open(method : String, url : String, user : String, password : String) : void
Opens the specified URL with the in parameter method specified Http method with given credentials [user, password] using HTTP basic authentication.
send() : void
Sends an HTTP request.
send(text : String) : void
This method performs the actual HTTP communication.
send(text : String, encoding : String) : void
This method performs the actual HTTP communication.
send(file : File) : void
This method performs the actual HTTP communication.
sendAndReceiveToFile(file : File) : boolean
This method performs the actual HTTP communication.
sendAndReceiveToFile(text : String, outFile : File) : boolean
This method performs the actual HTTP communication.
sendAndReceiveToFile(text : String, encoding : String, outFile : File) : boolean
This method performs the actual HTTP communication.
sendMultiPart(parts : HTTPRequestPart...) : boolean
Sends a multipart HTTP request.
setRequestHeader(key : String, value : String) : void
Sets a request header for the next HTTP operation.
setTimeout(timeoutMillis : Number) : void
Sets the timeout for connections made with this client to the given number of milliseconds.
Methods inherited from class Object
Constructor Detail
HTTPClient
public HTTPClient()

Method Detail
enableCaching
enableCaching(ttl : Number) : void
Calling this method enables caching for GET requests.

It basically means that a response is cached, and before making a request the HTTP client looks into the cache to determine whether the response is already available. Only responses with a status code of 2xx, with a content length, with a size less then 50k, and which are not intended to be immediately written to a file are cached.

The provided parameter defines the TTL (time to live) for the cached content. A value of 0 disables caching. The URL and the user name are used as cache keys. The total size of the cacheable content and the number of cached items is limited and automatically managed by the system. Cache control information send by the remote server is ignored. Caching HTTP responses should be done very carefully. It is important to ensure that the response really depends only on the URL and doesn't contain any remote state information or time information which is independent of the URL. It is also important to verify that the application sends exactly the same URL multiple times.

Parameters:
ttl - the TTL for the cached content in secs

getAllResponseHeaders
getAllResponseHeaders() : HashMap
Returns all response headers as a map containing the name and value of the response header.
Deprecated:
Use getResponseHeaders() instead.
Returns:
a map containing the names and corresponding values of the response headers.

getErrorText
getErrorText() : String
Returns the returned message body as text for HTTP status code greater or equal to 400. Error messages are not written to the response file.
Returns:
the returned message body as text.

getResponseHeader
getResponseHeader(header : String) : String
Returns a specific response header from the last HTTP operation. The method returns null if the specific header was not returned.
Parameters:
header - the name of the response header to locate.
Returns:
the value of the specified header or null if the header cannot be found.

getResponseHeaders
getResponseHeaders(name : String) : List
Returns all the values of a response header from the last HTTP operation as a list of strings. This reflects the fact that a specific header, e.g. "Set-Cookie", may be set multiple times. In case there is no such header, the method returns an empty list.
Parameters:
name - The name of the response header to locate.
Returns:
The values of the specified header as a list of strings or an empty list if the header cannot be found.

getResponseHeaders
getResponseHeaders() : Map
Returns all response headers as a map in which each entry represents an individual header. The key of the entry holds the header name and the entry value holds a list of all header values.
Returns:
A map containing the names and corresponding values of the response headers.

getStatusCode
getStatusCode() : Number
Returns the status code of the last HTTP operation.
Returns:
the status code of the last HTTP operation.

getStatusMessage
getStatusMessage() : String
Returns the message text of the last HTTP operation.
Returns:
the message text of the last HTTP operation.

getText
getText() : String
Returns the returned message body as text for HTTP status codes between 200 and 299.
Returns:
the returned message body as text.

getText
getText(encoding : String) : String
Returns the returned message body as text for HTTP status codes between 200 and 299.
Parameters:
encoding - the character encoding to use.
Returns:
String the encoded String.

getTimeout
getTimeout() : Number
Returns the timeout for this client, in milliseconds.
Returns:
the timeout in milliseconds

open
open(method : String, url : String) : void
Opens the specified URL using the specified method. The following methods are supported: GET, POST, HEAD, PUT, PATCH, OPTIONS, and DELETE
Parameters:
method - the method to use for opening the URL.
url - the url to open.

open
open(method : String, url : String, async : boolean, user : String, password : String) : void
Deprecated method.
Deprecated:
Parameters:
method - the method to use for opening the URL.
url - the url to open.
async - true if asynchronous.
user - name of the user.
password - password.

open
open(method : String, url : String, user : String, password : String) : void
Opens the specified URL with the in parameter method specified Http method with given credentials [user, password] using HTTP basic authentication. The following methods are supported: GET, POST, HEAD, PUT, PATCH, OPTIONS, and DELETE
Parameters:
method - HTTP method
url - the url
user - name of the user
password - password

send
send() : void
Sends an HTTP request.

send
send(text : String) : void
This method performs the actual HTTP communication. The text is sent as a request body. If the text is null no data will be send to the HTTP server.
Parameters:
text - text String to be sent as request body.

send
send(text : String, encoding : String) : void
This method performs the actual HTTP communication. The text is sent as a request body. If the text is null no data will be send to the HTTP server.
Parameters:
text - text String to be sent as request body.
encoding - character encoding name.

send
send(file : File) : void
This method performs the actual HTTP communication. Sends the file to the HTTP server. The file content is sent as a request body and is sent "as-is" (text or binary).
Parameters:
file - File to be sent.

sendAndReceiveToFile
sendAndReceiveToFile(file : File) : boolean
This method performs the actual HTTP communication. If the file is null no data will be send to the HTTP server. If this method is used with a GET then the file parameter will contain the contents retrieved. When using this method with a PUT/POST then the contents of the file parameter will be sent to the server.
Parameters:
file - local file used to read from or write to, depending on the method used.
Returns:
true if the returned code was a positive status code

sendAndReceiveToFile
sendAndReceiveToFile(text : String, outFile : File) : boolean
This method performs the actual HTTP communication. If the text is null no data will be send to the HTTP server.
Parameters:
text - text String to be sent.
outFile - local file to write to.
Returns:
true if the returned code was a positive status code

sendAndReceiveToFile
sendAndReceiveToFile(text : String, encoding : String, outFile : File) : boolean
This method performs the actual HTTP communication. If the text is null no data will be send to the HTTP server.
Parameters:
text - text String to be sent.
encoding - character encoding name.
outFile - local file to write to.
Returns:
true if the returned code was a positive status code

sendMultiPart
sendMultiPart(parts : HTTPRequestPart...) : boolean
Sends a multipart HTTP request. This method should only be called if the connection to the remote URL was opened with a POST or PATCH method. All other methods will result in an exception being thrown. The request is constructed from the passed array of parts.
Parameters:
parts - List of part objects representing either string or file parts.
Returns:
true if the returned code was a positive status code.

setRequestHeader
setRequestHeader(key : String, value : String) : void
Sets a request header for the next HTTP operation.
Parameters:
key - the request header.
value - the request headers' value.

setTimeout
setTimeout(timeoutMillis : Number) : void
Sets the timeout for connections made with this client to the given number of milliseconds. If the given timeout is less than or equal to zero, the timeout is set to a maximum value of 2 or 15 minutes, depending on the context.

This timeout value controls both the "connection timeout" (how long it takes to connect to the remote host) and the "socket timeout" (how long, after connecting, it will wait without any data being read). Therefore, in the worst case scenario, the total time of inactivity could be twice as long as the specified value.

The maximum timeout is 15 minutes when the client is used in a job, and 2 minutes otherwise. The default timeout for a new client is the maximum timeout value.

This method can be called at any time, and will affect the next connection made with this client. It is not possible to set the timeout for an open connection.

You should always set a reasonable timeout (e.g., a few seconds). Allowing connections to run long can result in thread exhaustion.

Parameters:
timeoutMillis - timeout, in milliseconds, up to a maximum of 2 or 15 minutes, depending on the context.