HTTPAgent
The HTTPAgent class allows you to handle HTTPAgent objects that can be used to manage the persistence and reuse of connections to servers using the HTTPRequest class.
The HTTPAgent class is available from the 4D class store. You can create a new HTTPAgent object using the 4D.HTTPAgent.new() function.
When no agent is associated to an HTTP request, a global agent with default values is used. The default agent is the simplest form of HTTP agent, suitable for basic use cases. Custom agents are recommended for more control, at the agent level rather than for each HTTP request, over specific aspects of the connection such keep-alive settings, timeouts or TLS/SSL configurations.
History
| Release | Changes |
|---|---|
| 20 R6 | Class added |
HTTPAgent Object
An HTTPAgent object is a shareable object.
HTTPAgent objects provide the following properties and functions:
| options : Object the current used options of the HTTPAgent |
| requestsCount : Integer the number of requests currently handled by the HTTPAgent |
| freeSocketsCount : Integer the number of free sockets from maxSockets associated with the HTTPAgent |
Since HTTPAgent is a shareable object, you can add one to a singleton class so you can use the same agent for all your requests to the same server.
4D.HTTPAgent.new()
4D.HTTPAgent.new( { options : Object } ) : 4D.HTTPAgent
History
| Release | Changes |
|---|---|
| 21 | Support of storeCertificateName property |
| Parameter | Type | Description | |
|---|---|---|---|
| options | Object | -> | default options for the HTTPAgent |
| Result | 4D.HTTPAgent | <- | New HTTPAgent object |
Description
The 4D.HTTPAgent.new() function creates a shareable HTTPAgent object with the defined options, and returns a 4D.HTTPAgent object.
The returned HTTPAgent object is used to customize connections to HTTP servers.
options parameter
In the options parameter, pass an object that can contain the following properties (all the properties are optional):
HTTPAgent options will be merged with HTTPRequest options (HTTPRequest options take precedence); if no specific agent is defined, a global agent is used.
| Property | Type | Default | Description |
|---|---|---|---|
| certificatesFolder | Folder | undefined (see default value in HTTPRequest.new()) | Sets the active client certificates folder for the requests using the agent. Can be overriden by "storeCertificateName" (see below) |
| keepAlive | Boolean | true | Activates keep alive for the agent |
| maxSockets | Integer | 65535 | Maximum number of sockets per server |
| maxTotalSockets | Integer | 65535 | Maximum number of sockets for the agent |
| minTLSVersion | Text | undefined (see default value in HTTPRequest.new()) | Sets the minimum version of TLS for the requests using this agent |
| protocol | Text | undefined (see default value in HTTPRequest.new()) | Protocol used for the requests using the agent |
| storeCertificateName | Text | undefined | (Windows only) Name of the OS certificate store (e.g. "LocalMachine") from where to use certificates instead of those in the certificates folder for the requests using the agent. If the certificate store is not found, an error is returned. For more information, see this blog post. |
| timeout | Real | undefined | If defined, timeout after which an unused socket is closed |
| validateTLSCertificate | Boolean | undefined (see default value in HTTPRequest.new()) | validateTLSCertificate for the requests using the agent |
You can request multiple servers using the same agent. In that case, each server will have its own pool of connections using the same agent options.
Example
Creating the HTTPAgent:
var $options:={}
$options.maxSockets:=5 //5 is the maximum number of sockets per server
$options.maxTotalSockets:=10 //10 is the maximum number of sockets for the agent
$options.validateTLSCertificate:=True //To validate the server's certificate
var $myAgent:=4D.HTTPAgent.new($options)
Sending a request to check the local time of any city:
var $options:={}
$options.method:="GET"
$options.agent:=$myAgent
var $myRequest:=4D.HTTPRequest.new("http://worldtimeapi.org/api/timezone/Europe/Paris"; $options)
When no agent is associated to an HTTPRequest, a global agent with default values is used.
.params
options : Object
Description
The .params property object contains the current used options of the HTTPAgent.
.requestsCount
requestsCount : Integer
Description
The .requestsCount property contains the number of requests currently handled by the HTTPAgent.
.freeSocketsCount
freeSocketsCount : Integer
Description
The .freeSocketsCount property contains the number of free sockets from maxSockets associated with the HTTPAgent.