Qore jni Module  1.1.0
org.qore.lang.HTTPClient Class Reference

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

Inheritance diagram for org.qore.lang.HTTPClient:
org.qore.jni.QoreObjectWrapper org.qore.lang.soapclient.SoapClient

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
optssets 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-ERRORinvalid or unknown option passed in option hash
HTTP-CLIENT-URL-ERRORinvalid URL string
HTTP-CLIENT-UNKNOWN-PROTOCOLunknown protocol passed in URL
ILLEGAL-FILESYSTEM-ACCESSif 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
paththe path for the message (i.e. "/path/resource?method&param=value")
headersAn 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-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
paththe 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-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
paththe path for the message (i.e. "/path/resource?method&param=value")
headersAn 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-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
paththe 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-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
paththe path for the message (i.e. "/path/resource?method&param=value")
bodythe string to use as the message body
headersAn 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-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
paththe path for the message (i.e. "/path/resource?method&param=value")
bodythe 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-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
paththe 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-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
paththe path for the message (i.e. "/path/resource?method&param=value")
bodythe optional data to use as the message body
headersAn 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-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
paththe path for the message (i.e. "/path/resource?method&param=value")
bodythe 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-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
bodyThe 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
methodThe 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.
pathThe path for the message (i.e. "/path/resource?method&param=value")
headersAn 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
getbodyIf 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
bodyThe 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
methodThe 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.
pathThe path for the message (i.e. "/path/resource?method&param=value")
headersAn 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
bodyThe 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
methodThe 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.
pathThe 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
bodyThe 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
methodThe 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
bodyThe message body to send; pass null (no value) to send no body
methodThe 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.
pathThe path for the message (i.e. "/path/resource?method&param=value")
headersAn 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
getbodyIf 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
bodyThe message body to send; pass null (no value) to send no body
methodThe 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.
pathThe path for the message (i.e. "/path/resource?method&param=value")
headersAn 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
bodyThe message body to send; pass null (no value) to send no body
methodThe 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.
pathThe 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
bodyThe message body to send; pass null (no value) to send no body
methodThe 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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_msthe 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
paththe 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
encodingthe 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-ERRORinvalid 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
mrthe 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
bthe 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
urlthe new proxy URL value for the next connection
Example:
httpclient.setProxyURL("http://user:password@proxy_host:8080/path");
Exceptions
HTTP-CLIENT-URL-ERRORinvalid proxy URL string; invalid authorization credentials in proxy URL (username without password or vice-versa)
HTTP-CLIENT-PROXY-PROTOCOL-ERRORunknown 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
userthe username to use for proxy authentication in the next HTTP connection
passthe 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
secureif 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_ms0 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
urlthe new URL for the object
Exceptions
HTTP-CLIENT-URL-ERRORinvalid URL string; invalid authorization credentials in URL (username without password or vice-versa)
HTTP-CLIENT-UNKNOWN-PROTOCOLunknown 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
userthe username to use for authentication in the next HTTP connection
passthe 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: