Java wrapper for the Qore::HTTPClient class in Qore. More...

Inheritance diagram for org.qore.lang.HTTPClient:

Public Member Methods
	HTTPClient (QoreObject ds)
	creates the object

	HTTPClient (Map< String, Object > opts) throws Throwable
	Creates the HTTPClient object based on the option parameter passed. More...

void	setHTTPVersion (String ver) throws Throwable
	Sets the HTTP protocol version string for headers in outgoing messages, allowed values are `"1.0"` and "1.1". More...

String	getHTTPVersion () throws Throwable
	Returns the HTTP protocol version string used in outgoing messages. More...

void	setSecure (boolean secure) throws Throwable
	Sets the object to make a secure SSL/TLS connection on the next connect if the passed argument is true, or an unencrypted cleartext connection if it is false. More...

boolean	isSecure () throws Throwable
	Returns true if the current connection is encrypted, false if not. More...

void	connect () throws Throwable
	Connects to the remote socket; SSL/TLS negotiation is performed if required. More...

void	disconnect () throws Throwable
	Disconnects from the remote socket if a connection is established (otherwise does nothing) More...

HashMap< String, Object >	send (String body, String method, String path, Map< String, Object > headers, boolean getbody) throws Throwable
	Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...

HashMap< String, Object >	send (String body, String method, String path, Map< String, Object > headers) throws Throwable
	Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...

HashMap< String, Object >	send (String body, String method, String path) throws Throwable
	Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...

HashMap< String, Object >	send (String body, String method) throws Throwable
	Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...

HashMap< String, Object >	send (byte[] body, String method, String path, Map< String, Object > headers, boolean getbody) throws Throwable
	Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...

HashMap< String, Object >	send (byte[] body, String method, String path, Map< String, Object > headers) throws Throwable
	Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...

HashMap< String, Object >	send (byte[] body, String method, String path) throws Throwable
	Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...

HashMap< String, Object >	send (byte[] body, String method) throws Throwable
	Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...

String	get (String path, Map< String, Object > headers) throws Throwable
	Sends an HTTP `GET` request and returns the message body received as a string or null if no message body is received. More...

String	get (String path) throws Throwable
	Sends an HTTP `GET` request and returns the message body received as a string or null if no message body is received. More...

String	head (String path, Map< String, Object > headers) throws Throwable
	Sends an HTTP `HEAD` request and returns as hash of the headers received. More...

String	head (String path) throws Throwable
	Sends an HTTP `HEAD` request and returns as hash of the headers received. More...

String	post (String path, String body, Map< String, Object > headers) throws Throwable
	Sends an HTTP `POST` request with a message body and returns the message body received as a string or null if no message body is received. More...

String	post (String path, String body) throws Throwable
	Sends an HTTP `POST` request with a message body and returns the message body received as a string or null if no message body is received. More...

String	post (String path) throws Throwable
	Sends an HTTP `POST` request without a message body and returns the response message body received as a string or null if no message body is received. More...

String	post (String path, byte[] body, Map< String, Object > headers) throws Throwable
	Sends an HTTP `POST` request with a message body and returns the message body received as a string or null if no message body is received. More...

String	post (String path, byte[] body) throws Throwable
	Sends an HTTP `POST` request with a message body and returns the message body received as a string or null if no message body is received. More...

void	setTimeout (int timeout_ms) throws Throwable
	Sets the default I/O timeout value in milliseconds. More...

int	getTimeout () throws Throwable
	Returns the default I/O timeout as an integer in milliseconds. More...

void	setEncoding (String encoding) throws Throwable
	Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding. More...

String	getEncoding () throws Throwable
	Returns the character encoding used for the object. More...

void	setURL (String url) throws Throwable
	Sets a new URL value for the next connection. More...

String	getURL () throws Throwable
	Returns the current URL. More...

void	setProxyURL () throws Throwable
	Clears the new proxy URL value for the next connection. More...

void	setProxyURL (String url) throws Throwable
	Sets a new proxy URL value for the next connection. More...

String	getProxyURL () throws Throwable
	Returns the current proxy URL as a string or null if no proxy URL is set. More...

void	clearProxyURL () throws Throwable
	Clears the new proxy URL value for the next connection. More...

void	setProxySecure (boolean b) throws Throwable
	Sets the SSL/TLS flag for the next connection to the proxy. More...

boolean	isProxySecure () throws Throwable
	Returns the SSL/TLS flag for the next proxy connection. More...

void	setMaxRedirects (int mr) throws Throwable
	Updates the setting for the `max_redirects` value for the object (maximum number of HTTP redirects that will be processed before an exception is raised) More...

int	getMaxRedirects () throws Throwable
	Returns the current `max_redirects` value for the object (the maximum number of HTTP redirects that will be processed before an exception is raised) More...

void	setConnectTimeout (int timeout_ms) throws Throwable
	Sets the connect timeout in milliseconds. More...

int	getConnectTimeout () throws Throwable
	Returns the connect timeout as an integer in milliseconds. More...

int	setNoDelay (boolean b) throws Throwable
	Sets the `TCP_NODELAY` setting for the object. More...

boolean	getNoDelay () throws Throwable
	Returns the `TCP_NODELAY` setting for the HTTPClient object. More...

boolean	isConnected () throws Throwable
	Returns true or false giving the current connection state. More...

void	setUserPassword (String user, String pass) throws Throwable
	Sets the username and password for the connection; call after HTTPClient::setURL() More...

void	setUserPassword () throws Throwable
	Clears the username and password for the connection. More...

void	clearUserPassword () throws Throwable
	Clears the username and password for the connection. More...

void	setProxyUserPassword (String user, String pass) throws Throwable
	Sets the username and password for the connection to the proxy; call after HTTPClient::setProxyURL() More...

void	setProxyUserPassword () throws Throwable
	Clears the username and password for the next proxy connection. More...

void	clearProxyUserPassword () throws Throwable
	Clears the username and password for the next proxy connection. More...

void	setDefaultPath (String path) throws Throwable
	Sets the default path used by the object if no path is set in the URL. More...

String	getDefaultPath () throws Throwable
	Returns the default path used by the object if no path is set in the URL. More...

String	getConnectionPath () throws Throwable
	Returns the current connection path set in the URL. More...

HashMap< String, Object >	getUsageInfo () throws Throwable
	Returns performance statistics for the socket. More...

void	clearStats () throws Throwable
	Clears performance statistics. More...

void	setPersistent () throws Throwable
	temporarily disables implicit reconnections; must be called when the server is already connected More...

Public Member Methods inherited from org.qore.jni.QoreObjectWrapper
	QoreObjectWrapper (QoreObject obj)
	creates the wrapper object with the Qore object

void	release ()
	releases the Qore object; do not call any further methods on the object after this call

QoreObject	getQoreObject ()
	returns the Qore object

String	className ()
	returns the class name for the Qore object

boolean	instanceOf (String class_name)
	returns true if the object is an instance of the given class

Additional Inherited Members
Private Attributes inherited from org.qore.jni.QoreObjectWrapper
QoreObject	obj
	the wrapper Qore object

Detailed Description

Java wrapper for the Qore::HTTPClient class in Qore.

Note: Loads and initializes the Qore library and the jni module in static initialization if necessary

Constructor & Destructor Documentation

◆ HTTPClient()

org.qore.lang.HTTPClient.HTTPClient ( Map< String, Object > opts ) throws Throwable

inline

Creates the HTTPClient object based on the option parameter passed.

To connect, call any method that requires a connection and an implicit connection is established, or call HTTPClient::connect().

Example:: HTTPClient httpclient = new HTTPClient(opts);

Parameters

opts

sets options and changes default behaviour for the object, etc; key names are case-sensitive and therefore must all be in lower-case:

additional_methods: An optional hash defining additional HTTP methods to handle. This allows the HTTPClient class to handle various HTTP extensions like e.g. WebDAV. The hash is defined with new method names as keys; the values are True or False indicating if the method can accept a message body; for example:
# add two new HTTP methods for WebDAV; both require message bodies
HTTPClient httpclient(("url": url, "additional_methods": ("PROPFIND": True, "MKCOL": True )));
connect_timeout: The timeout value in milliseconds for establishing a new socket connection (also can be a relative date-time value for clarity, ex: 30s)
default_path: The default path to use for new connections if a path is not otherwise specified in the connection URL
default_port: The default port number to connect to if none is given in the URL
http_version: Either "1.0" or "1.1" for the claimed HTTP protocol version compliancy in outgoing message headers
max_redirects: The maximum number of redirects before throwing an exception (the default is 5)
protocols: A hash describing new protocols, the key is the protocol name and the value is either an integer giving the default port number or a hash with "port" and "ssl" keys giving the default port number and a boolean value to indicate that an SSL connection should be established
proxy: The proxy URL for connecting through a proxy
ssl_cert_path: a path to an X.509 client certificate file in PEM format; if this option is used, then the calling context must not be restricted with sandbox restriction Qore::PO_NO_FILESYSTEM which is checked at runtime
ssl_key_path: a path to a private key file in PEM format for the X.509 client certificate; if this option is used, then the calling context must not be restricted with sandbox restriction Qore::PO_NO_FILESYSTEM which is checked at runtime
ssl_key_password: the password to the private key given with ssl_key_path
ssl_verify_cert: if True then the server's certificate will only be accepted if it's verified
timeout: The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: 5m)
url: A string giving the URL to connect to

Exceptions

HTTP-CLIENT-OPTION-ERROR	invalid or unknown option passed in option hash
HTTP-CLIENT-URL-ERROR	invalid URL string
HTTP-CLIENT-UNKNOWN-PROTOCOL	unknown protocol passed in URL
ILLEGAL-FILESYSTEM-ACCESS	if the calling context is restricted with the Qore::PO_NO_FILESYSTEM sandboxing restriction and one of the following options is used: `ssl_cert_path` or `ssl_key_path`

Note

URLs with UNIX sockets are generally supported in Qore with the following syntax: scheme://socket=url_encoded_path/path, where url_encoded_path is a path with URL-encoding as performed by encode_url(string, True); for example: "http://socket=%2ftmp%socket-dir%2fsocket-file-1/url/path"; this allows a filesystem path to be used in the host portion of the URL and for the URL to include a URL path as well.
other I/O errors can be thrown opening and reading the certificate and/or private key files if the ssl_cert_path or ssl_key_path options are used
the Qore::PO_NO_FILESYSTEM sandbox restriction is checked at runtime if one of the following options is used: ssl_cert_path or ssl_key_path

Since

Qore 0.8.13 added the following options:

ssl_cert_path
ssl_key_path
ssl_key_password
ssl_verify_cert

Member Function Documentation

◆ clearProxyURL()

void org.qore.lang.HTTPClient.clearProxyURL ( ) throws Throwable

inline

Clears the new proxy URL value for the next connection.

Example:: httpclient.setProxyURL();

◆ clearProxyUserPassword()

void org.qore.lang.HTTPClient.clearProxyUserPassword ( ) throws Throwable

inline

Clears the username and password for the next proxy connection.

Call this method after calling HTTPClient::setProxyURL() to clear any proxy authentication information present in the URL used in HTTPClient::setProxyURL()

Example:: httpclient.clearProxyUserPassword();

◆ clearStats()

void org.qore.lang.HTTPClient.clearStats ( ) throws Throwable

inline

Clears performance statistics.

Example:: httpclient.clearStats();

Since: Qore 0.8.9

See also: HTTPClient::getUsageInfo()

◆ clearUserPassword()

void org.qore.lang.HTTPClient.clearUserPassword ( ) throws Throwable

inline

Clears the username and password for the connection.

Call this method after calling HTTPClient::setURL() to clear any authentication information present in the URL used in HTTPClient::setURL()

Example:: httpclient.clearUserPassword();

◆ connect()

void org.qore.lang.HTTPClient.connect ( ) throws Throwable

inline

Connects to the remote socket; SSL/TLS negotiation is performed if required.

If the protocol indicates that a secure connection should be established (or HTTPClient::setSecure() was called previsouly), SSL/TLS negotiation will be attempted.

If the TCP_NODELAY flag has been set (see HTTPClient::setNoDelay()), then after a successful connection to the remote socket, this option will be set on the socket. If an error occurs setting the TCP_NODELAY option, the internal flag is set to false (use HTTPClient::getNoDelay() to check the flag's state) and the error code can be retrieved with errno().

Example:: httpclient.connect();

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Note: For possible exceptions, see the Socket::connect() method (or Socket::connectSSL() for secure connections).

◆ disconnect()

void org.qore.lang.HTTPClient.disconnect ( ) throws Throwable

inline

Disconnects from the remote socket if a connection is established (otherwise does nothing)

Example:: httpclient.disconnect();

◆ get() [1/2]

String org.qore.lang.HTTPClient.get	(	String	path,
		Map< String, Object >	headers
	)		throws Throwable

inline

Sends an HTTP GET request and returns the message body received as a string or null if no message body is received.

In order to get the headers and the body, use the HTTPClient::send() method instead (although note that sending an HTTP message bosdy with a GET request is not standards compliant; see httpclient_get_with_body for more information).

If no connection has already been established, an internal call to HTTPClient::connect() will be made before sending the request.

If any content encoding is used for the message body in the reply, the content is decoded and returned as a string; if the content encoding uses an unknown method, then an exception is thrown.

Example:: *string html = httpclient.get("/path/file.html");

Parameters

path	the path for the message (i.e. `"/path/resource?method&param=value"`)
headers	An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

Returns: the message body in the reply to this message or null in case of an error or an erroneous reply by the server with no body

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the return value of the send() method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ get() [2/2]

String org.qore.lang.HTTPClient.get ( String path ) throws Throwable

inline

Sends an HTTP GET request and returns the message body received as a string or null if no message body is received.

In order to get the headers and the body, use the HTTPClient::send() method instead (although note that sending an HTTP message bosdy with a GET request is not standards compliant; see httpclient_get_with_body for more information).

If no connection has already been established, an internal call to HTTPClient::connect() will be made before sending the request.

If any content encoding is used for the message body in the reply, the content is decoded and returned as a string; if the content encoding uses an unknown method, then an exception is thrown.

Example:: *string html = httpclient.get("/path/file.html");

Parameters

path	the path for the message (i.e. `"/path/resource?method&param=value"`)

Returns: the message body in the reply to this message or null in case of an error or an erroneous reply by the server with no body

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the return value of the send() method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ getConnectionPath()

String org.qore.lang.HTTPClient.getConnectionPath ( ) throws Throwable

inline

Returns the current connection path set in the URL.

Returns: the current connection path set in the URL

Example:: *string path = httpclient.getConnectionPath();

◆ getConnectTimeout()

int org.qore.lang.HTTPClient.getConnectTimeout ( ) throws Throwable

inline

Returns the connect timeout as an integer in milliseconds.

Returns: Returns the connect timeout as an integer in milliseconds; negative numbers mean the system default timeout is used

Example:: int to = httpclient.getConnectTimeout();

◆ getDefaultPath()

String org.qore.lang.HTTPClient.getDefaultPath ( ) throws Throwable

inline

Returns the default path used by the object if no path is set in the URL.

Returns: the default path used by the object if no path is set in the URL

Example:: String def_path = httpclient.getDefaultPath();

◆ getEncoding()

String org.qore.lang.HTTPClient.getEncoding ( ) throws Throwable

inline

Returns the character encoding used for the object.

Returns: the character encoding used for the object

Example:: string encoding = httpclient.getEncoding();

◆ getHTTPVersion()

String org.qore.lang.HTTPClient.getHTTPVersion ( ) throws Throwable

inline

Returns the HTTP protocol version string used in outgoing messages.

Returns: the HTTP protocol version string used in outgoing messages

Example:: string version = httpclient.getHTTPVersion();

◆ getMaxRedirects()

int org.qore.lang.HTTPClient.getMaxRedirects ( ) throws Throwable

inline

Returns the current max_redirects value for the object (the maximum number of HTTP redirects that will be processed before an exception is raised)

Returns: the current max_redirects value for the object (the maximum number of HTTP redirects that will be processed before an exception is raised)

Example:: int mr = httpclient.getMaxRedirects();

◆ getNoDelay()

boolean org.qore.lang.HTTPClient.getNoDelay ( ) throws Throwable

inline

Returns the TCP_NODELAY setting for the HTTPClient object.

Example:: boolean b = httpclient.getNoDelay();

See also: also HTTPClient::setNoDelay()

◆ getProxyURL()

String org.qore.lang.HTTPClient.getProxyURL ( ) throws Throwable

inline

Returns the current proxy URL as a string or null if no proxy URL is set.

Returns: the current proxy URL as a string or null if no proxy URL is set

Example:: String proxy_url = httpclient.getProxyURL();

◆ getTimeout()

int org.qore.lang.HTTPClient.getTimeout ( ) throws Throwable

inline

Returns the default I/O timeout as an integer in milliseconds.

Returns: the default I/O timeout as an integer in milliseconds; 0 means immediate timeout (when reading only returns data if it is already available), and negative numbers mean never timeout

Example:: int timeout = httpclient.getTimeout();

◆ getURL()

String org.qore.lang.HTTPClient.getURL ( ) throws Throwable

inline

Returns the current URL.

Returns: the current URL

Example:: String url = httpclient.getURL();

◆ getUsageInfo()

HashMap<String, Object> org.qore.lang.HTTPClient.getUsageInfo ( ) throws Throwable

inline

Returns performance statistics for the socket.

Example:: Map<String, Object> h = httpclient.getUsageInfo();

Returns

a hash with the following keys:

"bytes_sent": an integer giving the total amount of bytes sent
"bytes_recv": an integer giving the total amount of bytes received
"us_sent": an integer giving the total number of microseconds spent sending data
"us_recv": an integer giving the total number of microseconds spent receiving data
"arg": (only if warning values have been set with HTTPClient::setWarningQueue()) the optional argument for warning hashes
"timeout": (only if warning values have been set with HTTPClient::setWarningQueue()) the warning timeout in microseconds
"min_throughput": (only if warning values have been set with HTTPClient::setWarningQueue()) the minimum warning throughput in bytes/sec

Since: Qore 0.8.9

See also: HTTPClient::clearStats()

◆ head() [1/2]

String org.qore.lang.HTTPClient.head	(	String	path,
		Map< String, Object >	headers
	)		throws Throwable

inline

Sends an HTTP HEAD request and returns as hash of the headers received.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:: String msg = httpclient.head("/path");

Parameters

path	the path for the message (i.e. `"/path/resource?method&param=value"`)
headers	An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

Returns: the headers received from the HTTP server with all key names converted to lower-case

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_REDIRECT

Exceptions

HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the return value of the send() method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

◆ head() [2/2]

String org.qore.lang.HTTPClient.head ( String path ) throws Throwable

inline

Sends an HTTP HEAD request and returns as hash of the headers received.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:: String msg = httpclient.head("/path");

Parameters

path	the path for the message (i.e. `"/path/resource?method&param=value"`)

Returns: the headers received from the HTTP server with all key names converted to lower-case

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_REDIRECT

Exceptions

HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the return value of the send() method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

◆ isConnected()

boolean org.qore.lang.HTTPClient.isConnected ( ) throws Throwable

inline

Returns true or false giving the current connection state.

Returns: true or false giving the current connection state

Example:: boolean b = httpclient.isConnected();

◆ isProxySecure()

boolean org.qore.lang.HTTPClient.isProxySecure ( ) throws Throwable

inline

Returns the SSL/TLS flag for the next proxy connection.

Returns: the SSL/TLS flag for the next proxy connection

Example:: boolean b = httpclient.isProxySecure();

◆ isSecure()

boolean org.qore.lang.HTTPClient.isSecure ( ) throws Throwable

inline

Returns true if the current connection is encrypted, false if not.

Returns: true if the current connection is encrypted, false if not

Example:: if (httpclient.isSecure())
printf("secure connection: %s %s\n", httpclient.getSSLCipherName(), httpclient.getSSLCipherVersion());

◆ post() [1/5]

String org.qore.lang.HTTPClient.post	(	String	path,
		String	body,
		Map< String, Object >	headers
	)		throws Throwable

inline

Sends an HTTP POST request with a message body and returns the message body received as a string or null if no message body is received.

In order to get the headers and the body in the response, use the HTTPClient::send() method instead.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:: String str = httpclient.post("/path", body);

Parameters

path	the path for the message (i.e. `"/path/resource?method&param=value"`)
body	the string to use as the message body
headers	An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

Returns: the message body in the reply to this message or null in case no body was present in the response

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the return value of the send() method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

◆ post() [2/5]

String org.qore.lang.HTTPClient.post	(	String	path,
		String	body
	)		throws Throwable

inline

Sends an HTTP POST request with a message body and returns the message body received as a string or null if no message body is received.

In order to get the headers and the body in the response, use the HTTPClient::send() method instead.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:: String str = httpclient.post("/path", body);

Parameters

path	the path for the message (i.e. `"/path/resource?method&param=value"`)
body	the string to use as the message body

Returns: the message body in the reply to this message or null in case no body was present in the response

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the return value of the send() method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

◆ post() [3/5]

String org.qore.lang.HTTPClient.post ( String path ) throws Throwable

inline

Sends an HTTP POST request without a message body and returns the response message body received as a string or null if no message body is received.

In order to get the headers and the body in the response, use the HTTPClient::send() method instead.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:: String str = httpclient.post("/path");

Parameters

path	the path for the message (i.e. `"/path/resource?method&param=value"`)

Returns: the message body in the reply to this message or null in case no body was present in the response

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the return value of the send() method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

◆ post() [4/5]

String org.qore.lang.HTTPClient.post	(	String	path,
		byte []	body,
		Map< String, Object >	headers
	)		throws Throwable

inline

Sends an HTTP POST request with a message body and returns the message body received as a string or null if no message body is received.

In order to get the headers and the body in the response, use the HTTPClient::send() method instead.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:: httpclient.post("/path", body);

Parameters

path	the path for the message (i.e. `"/path/resource?method&param=value"`)
body	the optional data to use as the message body
headers	An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

Returns: the message body in the reply to this message or null in case no body was present in the response

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the return value of the send() method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

◆ post() [5/5]

String org.qore.lang.HTTPClient.post	(	String	path,
		byte []	body
	)		throws Throwable

inline

Sends an HTTP POST request with a message body and returns the message body received as a string or null if no message body is received.

In order to get the headers and the body in the response, use the HTTPClient::send() method instead.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:: httpclient.post("/path", body);

Parameters

path	the path for the message (i.e. `"/path/resource?method&param=value"`)
body	the optional data to use as the message body

Returns: the message body in the reply to this message or null in case no body was present in the response

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the return value of the send() method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

◆ send() [1/8]

HashMap<String, Object> org.qore.lang.HTTPClient.send	(	String	body,
		String	method,
		String	path,
		Map< String, Object >	headers,
		boolean	getbody
	)		throws Throwable

inline

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:: hash msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

body	The message body to send; note that sending an HTTP message bosdy with a `GET` request is not standards compliant; see httpclient_get_with_body for more information
method	The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
path	The path for the message (i.e. `"/path/resource?method&param=value"`)
headers	An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
getbody	If this argument is true, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.

Returns: The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the "body" key and the HTTP status will be assigned to the "status_code" key.

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ send() [2/8]

HashMap<String, Object> org.qore.lang.HTTPClient.send	(	String	body,
		String	method,
		String	path,
		Map< String, Object >	headers
	)		throws Throwable

inline

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:: hash msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

body	The message body to send; note that sending an HTTP message bosdy with a `GET` request is not standards compliant; see httpclient_get_with_body for more information
method	The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
path	The path for the message (i.e. `"/path/resource?method&param=value"`)
headers	An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

Returns: The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the "body" key and the HTTP status will be assigned to the "status_code" key.

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ send() [3/8]

HashMap<String, Object> org.qore.lang.HTTPClient.send	(	String	body,
		String	method,
		String	path
	)		throws Throwable

inline

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:: hash msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

body	The message body to send; note that sending an HTTP message bosdy with a `GET` request is not standards compliant; see httpclient_get_with_body for more information
method	The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
path	The path for the message (i.e. `"/path/resource?method&param=value"`)

Returns: The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the "body" key and the HTTP status will be assigned to the "status_code" key.

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ send() [4/8]

HashMap<String, Object> org.qore.lang.HTTPClient.send	(	String	body,
		String	method
	)		throws Throwable

inline

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:: hash msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

body	The message body to send; note that sending an HTTP message bosdy with a `GET` request is not standards compliant; see httpclient_get_with_body for more information
method	The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.

Returns: The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the "body" key and the HTTP status will be assigned to the "status_code" key.

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ send() [5/8]

HashMap<String, Object> org.qore.lang.HTTPClient.send	(	byte []	body,
		String	method,
		String	path,
		Map< String, Object >	headers,
		boolean	getbody
	)		throws Throwable

inline

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:: hash msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

body	The message body to send; pass null (no value) to send no body
method	The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
path	The path for the message (i.e. `"/path/resource?method&param=value"`)
headers	An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
getbody	If this argument is true, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.

Returns: The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the "body" key and the HTTP status will be assigned to the "status_code" key.

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ send() [6/8]

HashMap<String, Object> org.qore.lang.HTTPClient.send	(	byte []	body,
		String	method,
		String	path,
		Map< String, Object >	headers
	)		throws Throwable

inline

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:: hash msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

body	The message body to send; pass null (no value) to send no body
method	The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
path	The path for the message (i.e. `"/path/resource?method&param=value"`)
headers	An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

Returns: The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the "body" key and the HTTP status will be assigned to the "status_code" key.

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ send() [7/8]

HashMap<String, Object> org.qore.lang.HTTPClient.send	(	byte []	body,
		String	method,
		String	path
	)		throws Throwable

inline

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:: hash msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

body	The message body to send; pass null (no value) to send no body
method	The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
path	The path for the message (i.e. `"/path/resource?method&param=value"`)

Returns: The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the "body" key and the HTTP status will be assigned to the "status_code" key.

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ send() [8/8]

HashMap<String, Object> org.qore.lang.HTTPClient.send	(	byte []	body,
		String	method
	)		throws Throwable

inline

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:: hash msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

body	The message body to send; pass null (no value) to send no body
method	The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.

Returns: The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the "body" key and the HTTP status will be assigned to the "status_code" key.

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server)
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note: For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also: httpclient_get_with_body

◆ setConnectTimeout()

void org.qore.lang.HTTPClient.setConnectTimeout ( int timeout_ms ) throws Throwable

inline

Sets the connect timeout in milliseconds.

Parameters

timeout_ms the connect timeout in milliseconds; negative numbers mean use the default system connect timeout. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 30s = 30 seconds, etc.).

Example:: httpclient.setConnectTimeout(120000);

◆ setDefaultPath()

void org.qore.lang.HTTPClient.setDefaultPath ( String path ) throws Throwable

inline

Sets the default path used by the object if no path is set in the URL.

Parameters

path	the default path value to set or if null then clears the path

Example:: httpclient.setDefaultPath(null);

◆ setEncoding()

void org.qore.lang.HTTPClient.setEncoding ( String encoding ) throws Throwable

inline

Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding.

Parameters

encoding the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding

Example:: httpclient.setEncoding("UTF-8");

◆ setHTTPVersion()

void org.qore.lang.HTTPClient.setHTTPVersion ( String ver ) throws Throwable

inline

Sets the HTTP protocol version string for headers in outgoing messages, allowed values are "1.0" and "1.1".

Parameters

ver	`"1.0"` or "1.1" for the HTTP protocol compliance version

Example:: httpclient.setHTTPVersion("1.1");

Exceptions

HTTP-VERSION-ERROR invalid HTTP version passed (allowed values: "1.0" and "1.1")

◆ setMaxRedirects()

void org.qore.lang.HTTPClient.setMaxRedirects ( int mr ) throws Throwable

inline

Updates the setting for the max_redirects value for the object (maximum number of HTTP redirects that will be processed before an exception is raised)

Parameters

mr	the setting for the maximum number of HTTP redirects that will be processed before an exception is raised

Example:: httpclient.setMaxRedirects(5);

See also: HTTPClient::getMaxRedirects() to retrieve this value

◆ setNoDelay()

int org.qore.lang.HTTPClient.setNoDelay ( boolean b ) throws Throwable

inline

Sets the TCP_NODELAY setting for the object.

When this setting is True, then data will be immediately sent out over the HTTPClient object's socket, when it is false, then data transmission may be delayed to be packaged with other data for the same target.

Delayed data transmissions may cause problems when the sender immediately closes the socket after sending data; in this case the receiver may not get the data even though the send succeeded.

Note that if no value is given to the method, the argument will be assumed to be true, and output buffering will be turned off for the HTTPClient object.

If the socket is not connected when this call is made, then an internal flag is set and the TCP_NODELAY option is enabled when the next connection is established. If the socket is connected, then if an error occurs setting the TCP_NODELAY option on the socket, this method will return a non-zero error code; the actual error can be checked with the errno() function.

Example:: httpclient.setNoDelay(true);

Parameters

b	the `TCP_NODELAY` setting for the object

See also: HTTPClient::getNoDelay()

◆ setPersistent()

void org.qore.lang.HTTPClient.setPersistent ( ) throws Throwable

inline

temporarily disables implicit reconnections; must be called when the server is already connected

Example:: httpclient.connect();
httpclient.setPersistent();

The persistent flag is automatically reset to False whenever the connection is closed; it must be called manually for every connection to turn off implicit reconnections.

To turn off the persistent flag manually, call HTTPClient.disconnect()

Since: Qore 0.8.10

◆ setProxySecure()

void org.qore.lang.HTTPClient.setProxySecure ( boolean b ) throws Throwable

inline

Sets the SSL/TLS flag for the next connection to the proxy.

Example:: httpclient.setProxySecure(true);

See also: HTTPClient::isProxySecure() to check the flag

◆ setProxyURL() [1/2]

void org.qore.lang.HTTPClient.setProxyURL ( ) throws Throwable

inline

Clears the new proxy URL value for the next connection.

This variant of the method is equivalent to HTTPClient::clearProxyURL()

Example:: httpclient.setProxyURL();

◆ setProxyURL() [2/2]

void org.qore.lang.HTTPClient.setProxyURL ( String url ) throws Throwable

inline

Sets a new proxy URL value for the next connection.

Parameters

url	the new proxy URL value for the next connection

Example:: httpclient.setProxyURL("http://user:password@proxy_host:8080/path");

Exceptions

HTTP-CLIENT-URL-ERROR	invalid proxy URL string; invalid authorization credentials in proxy URL (username without password or vice-versa)
HTTP-CLIENT-PROXY-PROTOCOL-ERROR	unknown protocol passed in URL

Note: URLs with UNIX sockets are generally supported in Qore with the following syntax: scheme://socket=url_encoded_path/path, where url_encoded_path is a path with URL-encoding as performed by encode_url(string, True); for example: "http://socket=%2ftmp%socket-dir%2fsocket-file-1/url/path"; this allows a filesystem path to be used in the host portion of the URL and for the URL to include a URL path as well.

◆ setProxyUserPassword() [1/2]

void org.qore.lang.HTTPClient.setProxyUserPassword	(	String	user,
		String	pass
	)		throws Throwable

inline

Sets the username and password for the connection to the proxy; call after HTTPClient::setProxyURL()

Call this method after calling HTTPClient::setProxyURL() to set proxy authentication information when not present in the URL used in HTTPClient::setProxyURL()

Example:: httpclient.setProxyUserPassword(user, pass);

Parameters

user	the username to use for proxy authentication in the next HTTP connection
pass	the password to use for proxy authentication in the next HTTP connection

◆ setProxyUserPassword() [2/2]

void org.qore.lang.HTTPClient.setProxyUserPassword ( ) throws Throwable

inline

Clears the username and password for the next proxy connection.

Call this method after calling HTTPClient::setProxyURL() to clear any proxy authentication information present in the URL used in HTTPClient::setProxyURL()

This variant of the method is equivalent to HTTPClient::clearProxyUserPassword()

Example:: httpclient.setProxyUserPassword();

See also: HTTPClient::clearProxyUserPassword()

◆ setSecure()

void org.qore.lang.HTTPClient.setSecure ( boolean secure ) throws Throwable

inline

Sets the object to make a secure SSL/TLS connection on the next connect if the passed argument is true, or an unencrypted cleartext connection if it is false.

This method overrides the default behaviour for the protocol set for the object

Note that the behavior of this method when called with no argument changed in version 0.8.0; prior to version 0.8.0 calling this method with no argument would turn off secure mode; the behavior was changed to the current functionality in order to make the usage of this method consistent with other methods of the same name and to make it more logical.

Example:: httpclient.setSecure(True);

Parameters

secure if true, a SSL/TLS connection will be attempted on the next connection. If false, an unencrypted cleartext connection will be established

◆ setTimeout()

void org.qore.lang.HTTPClient.setTimeout ( int timeout_ms ) throws Throwable

inline

Sets the default I/O timeout value in milliseconds.

Parameters

timeout_ms 0 means immediate timeout (when reading will return data only if it is already available), and negative numbers mean never timeout

Example:: httpclient.setTimeout(120000);

◆ setURL()

void org.qore.lang.HTTPClient.setURL ( String url ) throws Throwable

inline

Sets a new URL value for the next connection.

To retrieve the current URL value, use the HTTPClient::getURL() method

Example:: httpclient.setURL("https://user:password@hostname:8080/path");

Parameters

url	the new URL for the object

Exceptions

HTTP-CLIENT-URL-ERROR	invalid URL string; invalid authorization credentials in URL (username without password or vice-versa)
HTTP-CLIENT-UNKNOWN-PROTOCOL	unknown protocol (scheme) passed in URL

See also: HTTPClient::getURL()

Note: URLs with UNIX sockets are generally supported in Qore with the following syntax: scheme://socket=url_encoded_path/path, where url_encoded_path is a path with URL-encoding as performed by encode_url(string, True); for example: "http://socket=%2ftmp%socket-dir%2fsocket-file-1/url/path"; this allows a filesystem path to be used in the host portion of the URL and for the URL to include a URL path as well.

◆ setUserPassword() [1/2]

void org.qore.lang.HTTPClient.setUserPassword	(	String	user,
		String	pass
	)		throws Throwable

inline

Sets the username and password for the connection; call after HTTPClient::setURL()

Call this method after calling HTTPClient::setURL() to set authentication information when not present in the URL used in HTTPClient::setURL()

Parameters

user	the username to use for authentication in the next HTTP connection
pass	the password to use for authentication in the next HTTP connection

Example:: httpclient.setUserPassword(user, pass);

◆ setUserPassword() [2/2]

void org.qore.lang.HTTPClient.setUserPassword ( ) throws Throwable

inline

Clears the username and password for the connection.

Call this method after calling HTTPClient::setURL() to clear any authentication information present in the URL used in HTTPClient::setURL()

This variant of the method is equivalent to HTTPClient::clearUserPassword()

Example:: httpclient.setUserPassword();

See also: HTTPClient::clearUserPassword()

The documentation for this class was generated from the following file:

/tmp/module-jni/src/java/org/qore/lang/HTTPClient.java

Public Member Methods

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ HTTPClient()

Member Function Documentation

◆ clearProxyURL()

◆ clearProxyUserPassword()

◆ clearStats()

◆ clearUserPassword()

◆ connect()

◆ disconnect()

◆ get() [1/2]

◆ get() [2/2]

◆ getConnectionPath()

◆ getConnectTimeout()

◆ getDefaultPath()

◆ getEncoding()

◆ getHTTPVersion()

◆ getMaxRedirects()

◆ getNoDelay()

◆ getProxyURL()

◆ getTimeout()

◆ getURL()

◆ getUsageInfo()

◆ head() [1/2]

◆ head() [2/2]

◆ isConnected()

◆ isProxySecure()

◆ isSecure()

◆ post() [1/5]

◆ post() [2/5]

◆ post() [3/5]

◆ post() [4/5]

◆ post() [5/5]

◆ send() [1/8]

◆ send() [2/8]

◆ send() [3/8]

◆ send() [4/8]

◆ send() [5/8]

◆ send() [6/8]

◆ send() [7/8]

◆ send() [8/8]

◆ setConnectTimeout()

◆ setDefaultPath()

◆ setEncoding()

◆ setHTTPVersion()

◆ setMaxRedirects()

◆ setNoDelay()

◆ setPersistent()

◆ setProxySecure()

◆ setProxyURL() [1/2]

◆ setProxyURL() [2/2]

◆ setProxyUserPassword() [1/2]

◆ setProxyUserPassword() [2/2]

◆ setSecure()

◆ setTimeout()

◆ setURL()

◆ setUserPassword() [1/2]

◆ setUserPassword() [2/2]