Package com.chilkatsoft.chilkat2

Class Rest

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Rest
All Implemented Interfaces:
AutoCloseable
public class Rest extends ChilkatObject
<section class="rest-summary">

Build, send, authenticate, stream, and inspect REST API requests with precise control.

Chilkat.Rest is a flexible REST client class for applications that need detailed control over request construction, connection reuse, authentication, headers, query parameters, multipart bodies, streaming uploads and downloads, response parsing, and low-level diagnostics. It is especially useful for APIs where the application must carefully manage provider-specific signing, request paths, body formats, and server responses.

Precise request construction

Build REST requests with explicit paths, headers, query parameters, request bodies, content types, and HTTP methods.

Connection reuse

Connect once and send multiple requests over the same underlying connection when appropriate.

Authentication support

Work with bearer tokens, OAuth2, AWS-style signing, Azure and Google auth helpers, and other service-specific authentication patterns.

Request bodies and multipart

Send JSON, XML, text, binary data, form parameters, multipart requests, streams, and file-based request bodies.

Response handling

Read response bodies as strings, bytes, streams, JSON, XML, or StringBuilder content, and inspect status codes and headers.

Diagnostics and debugging

Use detailed error text, raw request generation, response headers, connection state, and verbose diagnostics to troubleshoot API behavior.

Choosing the right class: Use Chilkat.Rest when you want fine-grained control over the connection and request construction. For higher-level HTTP convenience methods that accept full URLs directly, use Chilkat.Http. For advanced socket routing, create the connection with Chilkat.Socket and pass it to UseConnection.

Stateful request configuration: Request headers, ordinary query parameters, path substitutions, multipart parts, and authentication settings remain associated with the Rest object until they are replaced or cleared. When reusing an object for unrelated requests, call the applicable Clear* methods rather than assuming request state is automatically reset.

Low-level response workflow: After a SendReq* call, call ReadResponseHeader and then read the response body exactly once when a body is present. Fully consume the body before sending another request on the same connection. A HEAD response has no body; a 204 No Content response is represented by an empty body.

Redirects and cookies: The Rest class exposes redirect and response-header information but does not automatically follow redirects or maintain a cookie jar. Applications should process Location and Set-Cookie values explicitly when needed.

For an extended overview, see Rest Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Rest

      public Rest()
      Creates a new Rest object.

  • Method Details

    • getAllowHeaderFolding

      public boolean getAllowHeaderFolding()
      Controls whether long request-header fields may be folded onto continuation lines. The default is false. When set to false, each request header is emitted on a single physical line.

      Modern HTTP compatibility: Obsolete HTTP line folding is rejected by some servers and signing systems. Set this property to false when the service requires unfolded header lines, as is common for canonicalized request signatures.

      Returns:
      the value of the AllowHeaderFolding property

    • setAllowHeaderFolding

      public void setAllowHeaderFolding​(boolean value)
      Sets the AllowHeaderFolding property; see getAllowHeaderFolding().
      Parameters:
      value - the new value

    • getAllowHeaderQB

      public boolean getAllowHeaderQB()
      Controls whether non-ASCII request-header values may be converted to RFC 2047 encoded-word form using Q or Base64 encoding. The default is true.

      Encoded words have forms such as =?utf-8?Q?...?= and =?utf-8?B?...?=. When this property is false, Chilkat does not apply this conversion.

      Compatibility feature: RFC 2047 encoded words originated in Internet message headers. Use this behavior only when the target HTTP service expects it; many APIs instead require ASCII header values or a service-specific encoding.

      Returns:
      the value of the AllowHeaderQB property

    • setAllowHeaderQB

      public void setAllowHeaderQB​(boolean value)
      Sets the AllowHeaderQB property; see getAllowHeaderQB().
      Parameters:
      value - the new value

    • getAuthorization

      public String getAuthorization()
      Gets or sets the value sent in the HTTP Authorization request header. Supply only the field value, such as Bearer eyJ..., not the text Authorization:.

      Authentication helpers: For generated authentication, prefer the appropriate SetAuth* method. A configured authentication provider may generate or replace the Authorization header when the request is sent.Provider precedence: When a SetAuth* provider is active, its generated Authorization header takes precedence over this property and over a manually added Authorization header. clearAuth() clears both the provider and this value; clearing top-level headers also clears this property.

      Returns:
      the value of the Authorization property

    • setAuthorization

      public void setAuthorization​(String value)
      Sets the Authorization property; see getAuthorization().
      Parameters:
      value - the new value (not null)

    • getConnectFailReason

      public int getConnectFailReason()
      After connect(String, int, boolean, boolean) fails, returns a code identifying the connection stage or TLS handshake stage that failed.

      Code Meaning

      0 Success

      1 Empty hostname

      2 DNS lookup failed

      3 DNS timeout

      4 Aborted by the application

      5 Internal failure

      6 Connection timed out

      7 Connection rejected or otherwise failed

      99 Chilkat is not unlocked or the trial expired

      TLS-related codes:

      Code Meaning

      100 TLS internal error

      101 Failed to send ClientHello

      102 Unexpected handshake message

      103 Failed to read ServerHello

      104 No server certificate

      105 Unexpected TLS protocol version

      106 Server certificate verification failed

      107 Unacceptable TLS protocol version

      109 Failed to read handshake messages

      110 Failed to send the client-certificate handshake message

      111 Failed to send ClientKeyExchange

      112 Client certificate private key is inaccessible

      113 Failed to send CertificateVerify

      114 Failed to send ChangeCipherSpec

      115 Failed to send Finished

      116 The server Finished message is invalid

      Detailed diagnostics: Use the code as a category and inspect LastErrorText for the full failure context.Reset after success: A successful connect(String, int, boolean, boolean) resets this property to 0. HTTP response properties are separate and are not cleared by a later failed connection attempt.

      Returns:
      the value of the ConnectFailReason property (read-only)

    • getConnectTimeoutMs

      public int getConnectTimeoutMs()
      Gets or sets the maximum number of milliseconds to wait for the remote server to accept the TCP connection. This timeout covers connection establishment, not the later sending or receiving of HTTP data.

      Related timeout: Use getIdleTimeoutMs() to control how long an established operation may remain without send or receive progress.

      The default is 30000 milliseconds.

      Returns:
      the value of the ConnectTimeoutMs property

    • setConnectTimeoutMs

      public void setConnectTimeoutMs​(int value)
      Sets the ConnectTimeoutMs property; see getConnectTimeoutMs().
      Parameters:
      value - the new value

    • getDebugMode

      public boolean getDebugMode()
      When true, calls to the Send* and FullRequest* methods compose the complete request but do not transmit it. Retrieve the generated request with getLastDebugRequest(BinData). The default is false.

      Safe request inspection: This is useful for validating signing, headers, query strings, multipart formatting, and body encoding without contacting the server. The captured request may contain secrets.

      In debug mode, a composed full-request call reports a synthetic successful result with ResponseStatusCode equal to 201, ResponseStatusText equal to OK, and no actual response header or response body.

      Returns:
      the value of the DebugMode property

    • setDebugMode

      public void setDebugMode​(boolean value)
      Sets the DebugMode property; see getDebugMode().
      Parameters:
      value - the new value

    • getEnableSecrets

      public boolean getEnableSecrets()
      Controls automatic resolution of credentials from operating-system secure storage. The default is false.

      When set to true, supported credential inputs may contain a secret specification beginning with !! instead of a literal secret. Chilkat resolves the specification from Windows Credential Manager on Windows or Apple Keychain on macOS.

      The specification format is: 

      !![appName|]service[|domain]|username

      For this class, secret specifications apply to the username and password supplied to setAuthBasic(String, String).

      Why use secret resolution: It avoids embedding long-lived credentials directly in source code, configuration files, command lines, or logs. The requested secret must already exist in the platform credential store.

      Returns:
      the value of the EnableSecrets property

    • setEnableSecrets

      public void setEnableSecrets​(boolean value)
      Sets the EnableSecrets property; see getEnableSecrets().
      Parameters:
      value - the new value

    • getHeartbeatMs

      public int getHeartbeatMs()
      Controls the interval, in milliseconds, between AbortCheck event callbacks during supported long-running operations. The default is 0, which disables periodic AbortCheck callbacks.

      Choosing an interval: A smaller value makes cancellation more responsive but causes callbacks more frequently.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

      public void setHeartbeatMs​(int value)
      Sets the HeartbeatMs property; see getHeartbeatMs().
      Parameters:
      value - the new value

    • getHost

      public String getHost()
      Gets or sets the value of the HTTP Host request header.

      Usually automatic: For a normal connection, Chilkat derives the Host header from the server established by connect(String, int, boolean, boolean) or useConnection(Socket, boolean). Set this property explicitly only when the request must present a different virtual-host value.

      An explicitly assigned value overrides the generated HTTP Host field, but it does not change the TCP/TLS destination established by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).

      Returns:
      the value of the Host property

    • setHost

      public void setHost​(String value)
      Sets the Host property; see getHost().
      Parameters:
      value - the new value (not null)

    • getIdleTimeoutMs

      public int getIdleTimeoutMs()
      Gets or sets the maximum number of milliseconds to wait when a send or receive operation has stopped making progress. The default is 30000 milliseconds.

      Not an overall deadline: This is an inactivity timeout. An operation can run longer than this value as long as data continues to be sent or received.

      A value of 0 disables the inactivity timeout.

      Returns:
      the value of the IdleTimeoutMs property

    • setIdleTimeoutMs

      public void setIdleTimeoutMs​(int value)
      Sets the IdleTimeoutMs property; see getIdleTimeoutMs().
      Parameters:
      value - the new value

    • getLastRedirectUrl

      public String getLastRedirectUrl()
      Returns the redirect target from the most recently received response. The value comes from the response Location header. If the most recent response was not a redirect or did not contain a Location header, this property is empty.

      Relative redirects: A Location value may be an absolute URL or a relative reference, depending on the server response.Redirect handling: The value is the response Location field as received. Rest does not automatically follow the redirect; send a new request explicitly, reconnecting first if the target host changes.

      Returns:
      the value of the LastRedirectUrl property (read-only)

    • getLastRequestHeader

      public String getLastRequestHeader()
      Returns the HTTP header fields from the most recently composed request, excluding the request line. The request line is available separately in getLastRequestStartLine().

      Sensitive data: The header block may contain credentials, bearer tokens, cookies, or signatures. Avoid writing it to logs unless sensitive values are redacted.

      A failed connect(String, int, boolean, boolean) does not clear this value. It continues to describe the last request that was composed and sent.

      Returns:
      the value of the LastRequestHeader property (read-only)

    • getLastRequestStartLine

      public String getLastRequestStartLine()
      Returns the request line from the most recently composed request. It contains the HTTP method, request target, and HTTP version, for example: 
      GET /v1/items?limit=10 HTTP/1.1

      A failed connect(String, int, boolean, boolean) does not clear this value. It continues to describe the last request that was composed and sent.

      Returns:
      the value of the LastRequestStartLine property (read-only)

    • getNumResponseHeaders

      public int getNumResponseHeaders()
      Returns the number of response header field occurrences. Enumerate them with zero-based indexes using responseHdrName(int) and responseHdrValue(int).

      A failed connect(String, int, boolean, boolean) does not reset this count; it remains the count for the last received HTTP response.

      Returns:
      the value of the NumResponseHeaders property (read-only)

    • getPartSelector

      public String getPartSelector()
      Selects the multipart entity or part targeted by multipart-building operations such as AddHeader, RemoveHeader, and the SetMultipartBody* methods.

      Value Selected target

      (empty) The top-level request entity

      0 The top-level request entity

      1 The first multipart subpart

      2 The second multipart subpart

      1.2 The second child within the first subpart

      Multipart indexes: PartSelector uses one-based part numbers, unlike most Chilkat indexed accessors. Reset it to the empty string before modifying top-level request headers.

      The value 0, like the empty string, selects the top-level request entity. A nonnumeric selector is invalid. A body assignment can create a higher-numbered part even when lower-numbered parts do not yet exist.

      Returns:
      the value of the PartSelector property

    • setPartSelector

      public void setPartSelector​(String value)
      Sets the PartSelector property; see getPartSelector().
      Parameters:
      value - the new value (not null)

    • getPercentDoneOnSend

      public boolean getPercentDoneOnSend()
      Applies to the full-request methods that both upload a request and download a response. It selects which direction is represented by percent-complete events.
      • false (default): progress refers to receiving the response body.
      • true: progress refers to sending the request body.

      A known total is required: Percentage can be calculated only when the total byte count is known. For example, a chunked response may not provide a total response length.

      Returns:
      the value of the PercentDoneOnSend property

    • setPercentDoneOnSend

      public void setPercentDoneOnSend​(boolean value)
      Sets the PercentDoneOnSend property; see getPercentDoneOnSend().
      Parameters:
      value - the new value

    • getResponseHeader

      public String getResponseHeader()
      Returns the HTTP response header fields from the most recently received response, excluding the status line.

      Status line: The numeric status and reason text are available through getResponseStatusCode() and getResponseStatusText().

      Repeated fields remain separate and in received order. The field-name casing is preserved. A failed connect(String, int, boolean, boolean) does not clear this value; it continues to describe the last received HTTP response.

      Returns:
      the value of the ResponseHeader property (read-only)

    • getResponseStatusCode

      public int getResponseStatusCode()
      Returns the numeric HTTP status code from the most recently received response, such as 200, 404, or 503.

      HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Last completed exchange: A failed connect(String, int, boolean, boolean) does not clear this property. It continues to report the status of the last HTTP response that was actually received.

      Returns:
      the value of the ResponseStatusCode property (read-only)

    • getResponseStatusText

      public String getResponseStatusText()
      Returns the reason phrase associated with the most recently received HTTP status code, such as OK or Not Found.

      Reason phrases are informational: Applications should make decisions from the numeric status code. A reason phrase may be empty or may vary by server.Last completed exchange: A failed connect(String, int, boolean, boolean) does not clear this property; it remains associated with the last received HTTP response.

      Returns:
      the value of the ResponseStatusText property (read-only)

    • getStreamNonChunked

      public boolean getStreamNonChunked()
      Controls whether streaming uploads use a Content-Length header instead of HTTP/1.1 chunked transfer encoding when the total body size is known. The default is true.

      When true and the stream length can be determined—for example, a file stream—Chilkat sends a non-chunked request. When false, Chilkat uses Transfer-Encoding: chunked. If the stream length is unknown, chunked transfer may still be required.

      Server compatibility: Some HTTP servers and signing schemes require Content-Length and do not accept chunked request bodies; others support either form.

      Returns:
      the value of the StreamNonChunked property

    • setStreamNonChunked

      public void setStreamNonChunked​(boolean value)
      Sets the StreamNonChunked property; see getStreamNonChunked().
      Parameters:
      value - the new value

    • getUncommonOptions

      public String getUncommonOptions()
      Provides opt-in compatibility settings for uncommon requirements. The default is the empty string. Supply one or more comma-separated keywords:

      Keyword Effect

      AllowDuplicateQueryParams Allows AddQueryParam to append another parameter having the same name instead of replacing the existing one.

      AllowInsecureBasicAuth Allows Basic authentication over a non-TLS remote connection. By default, Basic authentication is allowed only over TLS, an SSH tunnel, or localhost.

      DisableTls13 Disables TLS 1.3 so negotiation is limited to TLS 1.2 or earlier supported versions.

      ProtectFromVpn On Android, attempts to bypass an installed or active VPN for this connection.

      Use sparingly: Leave this property empty unless a documented interoperability requirement calls for one of these options. In particular, AllowInsecureBasicAuth can expose credentials to network observers.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • addHeader

      public void addHeader​(String name, String value)
      Adds an HTTP request header using name as the field name and value as the field value. If a request header with the same name is already present for the selected part, its value is replaced.

      HTTP header names: Field names are case-insensitive. Pass only the field name in name—for example, Content-Type—and not the trailing colon. For multipart requests, getPartSelector() determines whether the header is added to the top-level request or to a MIME part.

      Request headers persist across requests until removed or cleared. Adding the same header again replaces its current value.

      Multipart selection: Header operations apply to the entity selected by getPartSelector(). Use an empty selector or 0 for top-level request headers; select a part before adding that part's headers.

      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addMwsSignature

      public void addMwsSignature​(String httpVerb, String uriPath, String domain, String mwsSecretKey)
      Computes the Amazon Marketplace Web Service (MWS) request signature using the secret key in mwsSecretKey and adds or replaces the Signature query parameter. Call this after all other MWS request parameters have been added.

      httpVerb is the HTTP method, uriPath is the MWS resource path, and domain is the request domain. httpVerb and uriPath should match the values used by the request-sending method. The method also adds or replaces the Timestamp parameter using the current system time.

      Legacy MWS signing: This method implements Amazon MWS signing and is not a general AWS request signer. For AWS services that use AWS authorization providers, use setAuthAws(AuthAws).

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      domain - the domain argument (not null)
      mwsSecretKey - the mwsSecretKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addPathParam

      public void addPathParam​(String name, String value)
      Adds or replaces a path-substitution parameter. Before a request is sent, occurrences of name in the supplied request path are replaced by value.

      For example, setting name to fileId and value to abc123 transforms /drive/v3/files/fileId into /drive/v3/files/abc123.

      Placeholders are application-defined: The placeholder syntax is simply the text stored in name; braces are not required unless they are part of the placeholder text you choose.

      Matching is case-sensitive and literal. Every occurrence of name is replaced, substitutions are applied in the order they were added, and replacement applies to the entire uriPath string, including any query portion.

      Reserved characters: The replacement is not a general path-segment encoder. Spaces are percent-encoded, but reserved URI characters such as /, ?, and # remain delimiters, and existing percent escapes are preserved. Percent-encode reserved characters before calling this method when they are intended to be data.

      Path substitutions persist across requests until replaced or removed with clearAllPathParams().

      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addQueryParam

      public void addQueryParam​(String name, String value)
      Adds or replaces a query-string parameter using name as the parameter name and value as its value. The stored query parameters are incorporated into the request target when a request is sent.

      Duplicate parameter names: By default, adding the same name again replaces the existing value. To retain repeated names such as tag=red&tag=blue, include AllowDuplicateQueryParams in getUncommonOptions().Encoding and lifetime: name and value are unencoded text. Chilkat percent-encodes the parameter name and value when composing the request target. For example, a space becomes %20, a literal plus sign becomes %2B, and a literal percent sign becomes %25. Existing percent escapes supplied to this method are therefore encoded again. Parameters persist across ordinary requests until removed or cleared.

      Parameter names are case-sensitive. Adding the same exact name again replaces the existing value unless AllowDuplicateQueryParams is enabled in getUncommonOptions().

      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addQueryParamSb

      public void addQueryParamSb​(String name, StringBuilder value)
      Adds or replaces a query-string parameter named by name. The parameter value is read from the StringBuilder in value.

      Duplicate parameter names: By default, the same name is replaced. Include AllowDuplicateQueryParams in getUncommonOptions() to retain repeated names.Encoding and lifetime: name and the text in value are unencoded text. Chilkat percent-encodes the parameter name and value when composing the request target. For example, a space becomes %20, a literal plus sign becomes %2B, and a literal percent sign becomes %25. Existing percent escapes supplied to this method are therefore encoded again. Parameters persist across ordinary requests until removed or cleared.

      Parameter names are case-sensitive. Adding the same exact name again replaces the existing value unless AllowDuplicateQueryParams is enabled in getUncommonOptions().

      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addQueryParams

      public void addQueryParams​(String queryString)
      Adds multiple query parameters from the query-string text in queryString. Use the form field1=value1&field2=value2&field3=value3.

      Encoding responsibility: The values in queryString must already be percent-encoded as required for a URL query string. Do not include a leading ?. For individual name/value pairs, addQueryParam(String, String) is usually clearer.

      The input is parsed as an already URL-encoded query string and then normalized when the request is composed. A plus sign is interpreted as a space and is emitted as %20; encoded delimiters such as %26 remain data; an item without an equals sign is treated as a parameter with an empty value.

      Parameters added by this method persist across ordinary requests. When ARG2 of a request method already contains a query string, those inline parameters appear first, followed by the parameters stored in the Rest object.

      Parameters:
      queryString - the queryString argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clearAllHeaders

      public void clearAllHeaders()
      Removes all HTTP request headers previously added to this object.

      The method clears headers only from the entity selected by getPartSelector(). Clearing top-level headers also clears the getAuthorization() property. Automatically generated fields such as Host and Content-Length may be added again when the next request is composed.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clearAllParts

      public void clearAllParts()
      Removes all multipart subparts from the request under construction. This is useful when reusing the same REST object after sending a multipart request.

      Scope: This clears multipart parts; it does not by itself clear query parameters, path parameters, authentication settings, or ordinary top-level request headers.

      This also resets getPartSelector() to the empty string and releases the configured multipart bodies and part streams.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clearAllPathParams

      public void clearAllPathParams()
      Removes all path-substitution parameters previously added with addPathParam(String, String).

      After clearing, placeholder text in later request paths is sent unchanged.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clearAllQueryParams

      public void clearAllQueryParams()
      Removes all query parameters previously added to this object.

      This clears the stored query/form parameter collection. It does not remove a query string written directly in the uriPath argument of a request method.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clearAuth

      public void clearAuth()
      Clears authentication providers and credentials previously configured through this class's SetAuth* methods.

      This removes the active authentication provider and clears the manually configured getAuthorization() value.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clearResponseBodyStream

      public void clearResponseBodyStream()
      Clears the response-stream destination previously configured by setResponseBodyStream(int, boolean, Stream). Subsequent full-request methods return or store the response body normally instead of streaming it to that destination.

      Clearing the destination does not alter the Stream object itself.

    • connect

      public void connect​(String hostname, int port, boolean tls, boolean autoReconnect)
      Establishes the initial TCP connection to the REST server. hostname is a DNS hostname or an IPv4/IPv6 address, port is the server port, and tls specifies whether the connection uses TLS. Common combinations are port 80 with tls set to false, and port 443 with tls set to true.

      If autoReconnect is true, subsequent requests may automatically reconnect when the existing connection is no longer usable. If autoReconnect is false, a lost connection causes the request to fail until the application explicitly reconnects.

      Hostname only: hostname is not a URL. For https://api.example.com/v1/items, pass api.example.com. The request path is supplied separately to the request method.Advanced connections: Connect is intended for a direct connection. For HTTP or SOCKS proxies, SSH tunneling, client certificates, custom socket routing, or other advanced connection setup, establish a connected Socket and pass it to useConnection(Socket, boolean).Reconnect behavior: When autoReconnect is true, Chilkat can establish a new connection before a later request after the previous connection has closed. This option should not be interpreted as a promise to replay a request that failed after transmission began.Result-state behavior: A successful connection resets getConnectFailReason() to 0. A failed Connect does not clear the HTTP response and last-request properties from an earlier completed exchange; those properties continue to describe the last HTTP request/response, not the failed connection attempt.

      Parameters:
      hostname - the hostname argument (not null)
      port - the port argument
      tls - the tls argument
      autoReconnect - the autoReconnect argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • disconnect

      public void disconnect​(int maxWaitMs)
      Closes the current HTTP connection, if one is open. maxWaitMs is the maximum number of milliseconds to wait while attempting a clean shutdown.

      Tunneled connections: When the REST connection uses an SSH tunnel, this closes the logical channel used by REST. It does not close the underlying SSH session itself.Socket supplied by UseConnection: When the transport was supplied through useConnection(Socket, boolean), calling Disconnect also disconnects that Socket. If automatic reconnection was enabled, a later request may reconnect it.

      Parameters:
      maxWaitMs - the maxWaitMs argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fullRequestBd

      public void fullRequestBd​(String httpVerb, String uriPath, BinData binData, StringBuilder responseBody)
      Sends a complete request whose binary body is read from the BinData in binData. The text response body replaces the existing contents of the StringBuilder in responseBody.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect getResponseStatusCode() and the response body to determine the API-level result.

      responseBody is cleared and replaced with the textual response body.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      binData - the binData argument (not null)
      responseBody - the responseBody argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fullRequestFormUrlEncoded

      public String fullRequestFormUrlEncoded​(String httpVerb, String uriPath)
      Sends a complete application/x-www-form-urlencoded request. The form body is built from the parameters previously added with addQueryParam(String, String) or addQueryParams(String). The request Content-Type is set to application/x-www-form-urlencoded. The response body is read as text and returned.

      This convenience method performs the equivalent of sendReqFormUrlEncoded(String, String), readResponseHeader(), and readRespBodyString() in sequence.

      For full-request methods, getPercentDoneOnSend() selects whether percent-complete events refer to sending the request body or receiving the response body.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect getResponseStatusCode() and the response body to determine the API-level result.

      Parameters written directly in uriPath remain in the URL query string. Parameters stored through addQueryParam(String, String), addQueryParamSb(String, StringBuilder), or addQueryParams(String) are encoded into the form body. After the form request is sent, this stored parameter collection is cleared.

      Persistent Content-Type: The method sets the top-level Content-Type to application/x-www-form-urlencoded. That request-header value remains configured for later requests until it is replaced or cleared.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fullRequestMultipart

      public String fullRequestMultipart​(String httpVerb, String uriPath)
      Sends a complete multipart request using the parts and part headers configured through getPartSelector(), addHeader(String, String), and the multipart-body methods. The response body is read as text and returned.

      This convenience method performs the equivalent of sendReqMultipart(String, String), readResponseHeader(), and readRespBodyString() in sequence.

      For full-request methods, getPercentDoneOnSend() selects whether percent-complete events refer to sending the request body or receiving the response body.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect getResponseStatusCode() and the response body to determine the API-level result.Multipart state: Assigning a body to a selected part creates that part. Parts may be created out of numeric order, persist across multipart requests, and retain the generated boundary while the multipart structure remains configured. The default top-level media type is multipart/form-data.

      The request fails if no multipart subparts are configured.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fullRequestNoBody

      public String fullRequestNoBody​(String httpVerb, String uriPath)
      Sends a complete request with no request body. The response body is read as text and returned.

      This convenience method performs the equivalent of sendReqNoBody(String, String), readResponseHeader(), and readRespBodyString() in sequence.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect getResponseStatusCode() and the response body to determine the API-level result.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fullRequestNoBodyBd

      public void fullRequestNoBodyBd​(String httpVerb, String uriPath, BinData binData)
      Sends a complete request without a request body and stores the binary response body in the BinData in binData, replacing its previous contents.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect getResponseStatusCode() and the response body to determine the API-level result.

      binData is cleared and replaced with the binary response body.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fullRequestNoBodySb

      public void fullRequestNoBodySb​(String httpVerb, String uriPath, StringBuilder sb)
      Sends a complete request without a request body and stores the text response body in the StringBuilder in sb, replacing its previous contents.

      This is the StringBuilder form of fullRequestNoBody(String, String).

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect getResponseStatusCode() and the response body to determine the API-level result.

      sb is cleared and replaced with the textual response body.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fullRequestSb

      public void fullRequestSb​(String httpVerb, String uriPath, StringBuilder requestBody, StringBuilder responseBody)
      Sends a complete request whose text body is read from the StringBuilder in requestBody. The text response body replaces the existing contents of the StringBuilder in responseBody.

      This is the StringBuilder form of fullRequestString(String, String, String).

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect getResponseStatusCode() and the response body to determine the API-level result.Text encoding and Content-Type: Unicode text is encoded as UTF-8. Generic string-body methods do not automatically add a Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.

      responseBody is cleared and replaced with the response body.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      requestBody - the requestBody argument (not null)
      responseBody - the responseBody argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fullRequestStream

      public String fullRequestStream​(String httpVerb, String uriPath, Stream stream)
      Sends a complete request whose body is read from the Stream in stream. Streaming is appropriate for large uploads because the entire request body need not be held in memory. The response body is read as text and returned.

      This convenience method performs the equivalent of sendReqStreamBody(String, String, Stream), readResponseHeader(), and readRespBodyString() in sequence.

      For full-request methods, getPercentDoneOnSend() selects whether percent-complete events refer to sending the request body or receiving the response body.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect getResponseStatusCode() and the response body to determine the API-level result.Stream position: The stream is read from its current position and is left consumed. Reusing the same stream without resetting its source or position sends only the unread remainder, which may be zero bytes.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      stream - the stream argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fullRequestString

      public String fullRequestString​(String httpVerb, String uriPath, String bodyText)
      Sends a complete request whose text body is supplied in bodyText, such as JSON, XML, or plain text. The response body is read as text and returned.

      This convenience method performs the equivalent of sendReqStringBody(String, String, String), readResponseHeader(), and readRespBodyString() in sequence.

      For full-request methods, getPercentDoneOnSend() selects whether percent-complete events refer to sending the request body or receiving the response body.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).HTTP status versus method success: Receiving an HTTP error status such as 400 or 404 is still a completed HTTP exchange. Inspect getResponseStatusCode() and the response body to determine the API-level result.Text encoding and Content-Type: Unicode text is encoded as UTF-8. Generic string-body methods do not automatically add a Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      bodyText - the bodyText argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getLastDebugRequest

      public void getLastDebugRequest​(BinData bd)
      Copies the fully composed HTTP request generated while getDebugMode() was true into the BinData in bd. The captured data includes the request line, headers, and body that would have been sent.

      Diagnostic use: Debug mode does not transmit the request. Treat captured requests as sensitive because they may contain authorization headers, cookies, tokens, or request-body credentials.

      bd is cleared and replaced. The captured bytes are the complete composed HTTP/1.1 request, including chunk framing when a streaming request uses Transfer-Encoding: chunked.

      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getLastJsonData

      public void getLastJsonData​(JsonObject json)
      Copies operation-specific diagnostic or result information from the most recently completed method into the JsonObject in json. Many methods do not produce additional JSON details, in which case the object is empty.

      Read immediately: Call this immediately after the operation of interest because a later method call may replace the stored JSON data.

      Parameters:
      json - the json argument (not null)

    • readRespBd

      public void readRespBd​(BinData responseBody)
      Reads the response body as raw bytes into the BinData in responseBody, replacing its previous contents. Call this after readResponseHeader().

      Use for binary content: Typical examples include images, archives, PDFs, encrypted data, and arbitrary file downloads.Read once: A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.Responses without a body: Do not call a body-reading method for a HEAD response. A 204 No Content response is handled as a successful empty body.

      Parameters:
      responseBody - the responseBody argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readRespBodyStream

      public void readRespBodyStream​(Stream stream, boolean autoSetStreamCharset)
      Reads the response body into the Stream supplied in stream. Call this after readResponseHeader().

      If autoSetStreamCharset is true and the response is textual, the stream's StringCharset is set from the charset parameter in the response Content-Type header when one is present. autoSetStreamCharset has no effect for binary responses.

      Large downloads: A stream can write directly to a file or another destination, avoiding the need to buffer the entire response body in memory.Read once: A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.Responses without a body: Do not call a body-reading method for a HEAD response. A 204 No Content response is handled as a successful empty body.

      Parameters:
      stream - the stream argument (not null)
      autoSetStreamCharset - the autoSetStreamCharset argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readRespBodyString

      public String readRespBodyString()
      Reads the response body as text and returns it. Call this only after readResponseHeader() has returned the response status code.

      Text versus binary: Use this method for JSON, XML, HTML, and other textual responses. Use readRespBd(BinData) or readRespBodyStream(Stream, boolean) for binary or very large content.Read once: A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.Responses without a body: Do not call a body-reading method for a HEAD response. A 204 No Content response is handled as a successful empty body.

      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readRespChunkBd

      public int readRespChunkBd​(int minSize, BinData bd)
      After readResponseHeader() has been called, reads the next chunk of the response body and appends the received bytes to the BinData in bd. The call waits until at least minSize bytes are available, unless the response ends first. The final chunk may contain fewer than minSize bytes, including zero bytes.

      Return value Meaning

      -1 The read failed; inspect LastErrorText.

      0 The remaining response bytes were returned and the response body is complete.

      1 A chunk was returned and more response bytes remain.

      Incremental processing: This method is useful when the application wants to process a long response progressively rather than buffer it all at once.

      Parameters:
      minSize - the minSize argument
      bd - the bd argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • readRespSb

      public void readRespSb​(StringBuilder responseBody)
      Reads the response body as text into the StringBuilder in responseBody, replacing its previous contents. Call this after readResponseHeader().

      Read once: A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.Responses without a body: Do not call a body-reading method for a HEAD response. A 204 No Content response is handled as a successful empty body.

      Parameters:
      responseBody - the responseBody argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readResponseHeader

      public int readResponseHeader()
      Reads the HTTP response status line and header fields. The returned integer is the HTTP status code, such as 200, 404, or 500. A return value of -1 means that no HTTP response was received because a transport or protocol error occurred.

      After this method returns a status code, inspect getResponseHeader(), getResponseStatusCode(), getResponseStatusText(), and the response-header access methods. If the response has a body, read it with readRespBodyString(), readRespBd(BinData), readRespBodyStream(Stream, boolean), or another appropriate body-reading method.

      Do not infer body presence from the request method alone: Whether a response body is present depends on the response status, request method, and response headers. For example, a GET commonly has a response body, while HEAD does not.Read once: A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.Responses without a body: Do not call a body-reading method for a HEAD response. A 204 No Content response is handled as a successful empty body.

      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • removeHeader

      public void removeHeader​(String name)
      Removes all request headers named by name from the request level selected by getPartSelector().

      Header-name matching is case-insensitive, and all matching occurrences are removed.

      Parameters:
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeQueryParam

      public void removeQueryParam​(String name)
      Removes all query parameters whose name matches name.

      Parameter-name matching is case-sensitive. All parameters having the exact name are removed. A true return value indicates that the operation completed successfully; it does not guarantee that a matching parameter existed.

      Parameters:
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • responseHdrByName

      public String responseHdrByName​(String name)
      Returns the value of the response header field named by name. HTTP header field names are case-insensitive.

      Repeated response headers: When the response can contain repeated fields, use getNumResponseHeaders(), responseHdrName(int), and responseHdrValue(int) to enumerate every field occurrence.

      If the response contains the same field more than once, this method returns the first matching value. Enumerate the header collection to obtain all occurrences, especially for fields such as Set-Cookie.

      Parameters:
      name - the name argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • responseHdrName

      public String responseHdrName​(int index)
      Returns the field name of the response header at zero-based index index. Valid indexes range from 0 through getNumResponseHeaders() minus one.

      Enumeration preserves the response-field order and the field-name casing received from the server. Repeated fields occupy separate indexes.

      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • responseHdrValue

      public String responseHdrValue​(int index)
      Returns the field value of the response header at zero-based index index. Use the same index with responseHdrName(int) to obtain the corresponding field name.

      Repeated response fields occupy separate indexes and are returned in received order.

      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendReqBd

      public void sendReqBd​(String httpVerb, String uriPath, BinData body)
      Sends a request whose binary body is read from the BinData in body.

      httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call readResponseHeader() and then read the response body with the appropriate response method.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      body - the body argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendReqFormUrlEncoded

      public void sendReqFormUrlEncoded​(String httpVerb, String uriPath)
      Sends an application/x-www-form-urlencoded request. The request body is built from the parameters added with addQueryParam(String, String) or addQueryParams(String). Any manually supplied Content-Type value is replaced with application/x-www-form-urlencoded.

      httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call readResponseHeader() and then read the response body with the appropriate response method.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).

      Parameters written directly in uriPath remain in the URL query string. Parameters stored through addQueryParam(String, String), addQueryParamSb(String, StringBuilder), or addQueryParams(String) are encoded into the form body. After the form request is sent, this stored parameter collection is cleared.

      Persistent Content-Type: The method sets the top-level Content-Type to application/x-www-form-urlencoded. That request-header value remains configured for later requests until it is replaced or cleared.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendReqMultipart

      public void sendReqMultipart​(String httpVerb, String uriPath)
      Sends a multipart request using the parts configured with getPartSelector(), addHeader(String, String), and the multipart-body methods.

      httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call readResponseHeader() and then read the response body with the appropriate response method.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).Multipart state: Assigning a body to a selected part creates that part. Parts may be created out of numeric order, persist across multipart requests, and retain the generated boundary while the multipart structure remains configured. The default top-level media type is multipart/form-data.

      The request fails if no multipart subparts are configured.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendReqNoBody

      public void sendReqNoBody​(String httpVerb, String uriPath)
      Sends a request without a request body.

      httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call readResponseHeader() and then read the response body with the appropriate response method.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendReqSb

      public void sendReqSb​(String httpVerb, String uriPath, StringBuilder bodySb)
      Sends a request whose text body is read from the StringBuilder in bodySb. Set the request Content-Type header to identify the body format.

      httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call readResponseHeader() and then read the response body with the appropriate response method.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).Text encoding and Content-Type: Unicode text is encoded as UTF-8. Generic string-body methods do not automatically add a Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      bodySb - the bodySb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendReqStreamBody

      public void sendReqStreamBody​(String httpVerb, String uriPath, Stream stream)
      Sends a request whose body is read from the Stream in stream. The stream may supply text or binary data; set the request Content-Type header as required by the API.

      httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call readResponseHeader() and then read the response body with the appropriate response method.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).Streaming: The stream is consumed while the request is sent, which is useful when the body is too large to hold in memory.Stream position: The stream is read from its current position and is left consumed. Reusing the same stream without resetting its source or position sends only the unread remainder, which may be zero bytes.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      stream - the stream argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendReqStringBody

      public void sendReqStringBody​(String httpVerb, String uriPath, String bodyText)
      Sends a request whose text body is supplied in bodyText, such as JSON, XML, form-independent text, or another textual representation. Set the request Content-Type header to identify the body format expected by the server.

      httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call readResponseHeader() and then read the response body with the appropriate response method.

      Request path: uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by connect(String, int, boolean, boolean) or useConnection(Socket, boolean).Text encoding and Content-Type: Unicode text is encoded as UTF-8. Generic string-body methods do not automatically add a Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.

      Parameters:
      httpVerb - the httpVerb argument (not null)
      uriPath - the uriPath argument (not null)
      bodyText - the bodyText argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthAws

      public void setAuthAws​(AuthAws authProvider)
      Associates the AuthAws provider in authProvider with this REST object. Chilkat uses the provider to sign each AWS request after the request method, path, query parameters, headers, and body are known. The application does not need to construct the Authorization header manually.

      Request signing: AWS signatures cover selected request components. Add all required headers and query parameters before sending the request so the generated signature matches the final request.

      Parameters:
      authProvider - the authProvider argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthAzureSas

      public void setAuthAzureSas​(AuthAzureSAS authProvider)
      Associates the AuthAzureSAS provider in authProvider with this REST object. Chilkat automatically adds an Authorization: SharedAccessSignature ... header to subsequent requests.

      SAS terminology: This method is for Azure services that use a Shared Access Signature in the Authorization header. It is distinct from a storage SAS token embedded in a URL query string.

      Parameters:
      authProvider - the authProvider argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthAzureStorage

      public void setAuthAzureStorage​(AuthAzureStorage authProvider)
      Associates the AuthAzureStorage provider in authProvider with this REST object. Chilkat automatically applies the Azure Storage authorization information required for each request.

      Azure Storage authentication: The provider contains the storage account credentials and signing settings. Request-specific headers and the resource path are incorporated when the request is sent.

      Parameters:
      authProvider - the authProvider argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthBasic

      public void setAuthBasic​(String username, String password)
      Configures HTTP Basic authentication using username as the username and password as the password. Chilkat automatically generates an Authorization: Basic ... header for subsequent requests.

      Security requirement: Basic authentication is an encoding scheme, not encryption. Use it only over TLS. By default, Chilkat blocks Basic authentication on an insecure remote connection; AllowInsecureBasicAuth in getUncommonOptions() exists only for exceptional compatibility needs.

      Some APIs use an account ID, client ID, API key, token, or secret in place of a traditional username or password; follow the service documentation.

      Authorization precedence: The Basic authentication provider generates the Authorization header when each request is composed and takes precedence over a value set through the getAuthorization() property or addHeader(String, String).

      Parameters:
      username - the username argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthBasicSecure

      public void setAuthBasicSecure​(SecureString username, SecureString password)
      Configures HTTP Basic authentication using the SecureString objects in username and password for the username and password. The resulting request behavior is the same as setAuthBasic(String, String).

      Credential handling: SecureString reduces unnecessary exposure of the credential text in ordinary application strings. Basic authentication must still be protected by TLS.Authorization precedence: The Basic authentication provider generates the Authorization header when each request is composed and takes precedence over a manually configured Authorization value.

      Parameters:
      username - the username argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthGoogle

      public void setAuthGoogle​(AuthGoogle authProvider)
      Associates the AuthGoogle provider in authProvider with this REST object. Chilkat uses the provider to add the Google authentication information needed by subsequent API requests.
      Parameters:
      authProvider - the authProvider argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthOAuth1

      public void setAuthOAuth1​(OAuth1 authProvider, boolean useQueryParams)
      Associates the OAuth1 provider in authProvider with this REST object for OAuth 1.0 or OAuth 1.0a request signing.

      If useQueryParams is true, the OAuth parameters and signature are placed in the query string. If useQueryParams is false, they are placed in the Authorization header.

      Final request matters: OAuth 1 signatures depend on the HTTP method, request URL, and parameters. Configure the request completely before sending it.

      Parameters:
      authProvider - the authProvider argument (not null)
      useQueryParams - the useQueryParams argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthOAuth2

      public void setAuthOAuth2​(OAuth2 authProvider)
      Associates the OAuth2 provider in authProvider with this REST object. The provider must contain a valid access token. Chilkat then adds an Authorization: Bearer <access-token> header to each request.

      The access token may be obtained through an OAuth flow or loaded from previously saved token data. Token acquisition, refresh, expiration, and scope requirements are determined by the authorization server.

      Manual bearer headers: A bearer token can also be supplied with addHeader(String, String). Do not configure both approaches for the same request because they compete for the same Authorization header.Provider lifetime: The OAuth2 object is consulted when each request is composed rather than copied at setup time. Keep it alive while the Rest object uses it. Changing its AccessToken changes the bearer token used by subsequent requests.Authorization precedence: The provider-generated bearer header takes precedence over a manually configured Authorization value.

      Parameters:
      authProvider - the authProvider argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setMultipartBodyBd

      public void setMultipartBodyBd​(BinData bodyData)
      Sets the binary body of the multipart part identified by getPartSelector() from the BinData in bodyData.

      Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.

      Parameters:
      bodyData - the bodyData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setMultipartBodySb

      public void setMultipartBodySb​(StringBuilder bodySb)
      Sets the text body of the multipart part identified by getPartSelector() from the StringBuilder in bodySb.

      Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.

      Parameters:
      bodySb - the bodySb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setMultipartBodyStream

      public void setMultipartBodyStream​(Stream stream)
      Uses the Stream in stream as the body source for the multipart part identified by getPartSelector().

      Large multipart parts: The stream is read while the request is sent, allowing a large file or generated body to be uploaded without first loading the entire part into memory.Object lifetime and position: The selected part retains the stream as its body source until the multipart request is sent or the parts are cleared. Keep the Stream object alive. It is read from its current position and must be reset before reusing it for another upload.

      Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.

      Parameters:
      stream - the stream argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setMultipartBodyString

      public void setMultipartBodyString​(String bodyText)
      Sets the text body of the multipart part identified by getPartSelector() to bodyText.

      Part metadata: Use addHeader(String, String) while the part is selected to set its Content-Type, Content-Disposition, and other part headers.

      Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.

      Parameters:
      bodyText - the bodyText argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setResponseBodyStream

      public void setResponseBodyStream​(int expectedStatus, boolean autoSetStreamCharset, Stream responseStream)
      Configures a Stream destination for response bodies received by the full-request convenience methods. The body is written to responseStream only when the response status code matches expectedStatus.

      If streaming occurs successfully, a string-returning full-request method returns OK. If streaming was selected but writing the body fails, it returns FAIL. If the status code does not match expectedStatus, the body is not streamed and remains available as the method's normal response text.

      If autoSetStreamCharset is true and the response is textual, the destination stream's StringCharset is set from the response Content-Type charset when available. autoSetStreamCharset is ignored for binary responses.

      expectedStatus value Status codes that are streamed

      200 Only 200

      -200 200 through 299

      -210 210 through 219

      Resetting this behavior: Call clearResponseBodyStream() to restore normal response-body handling.

      For Boolean-returning full-request methods, successful streaming returns true. A StringBuilder response output receives OK; a BinData response output is cleared. If the status does not match expectedStatus, the stream is not written and the method returns the response through its normal output.

      The configuration remains active for later full-request calls until clearResponseBodyStream() is called.

      Parameters:
      expectedStatus - the expectedStatus argument
      autoSetStreamCharset - the autoSetStreamCharset argument
      responseStream - the responseStream argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • useConnection

      public void useConnection​(Socket connection, boolean autoReconnect)
      Uses the already-connected Socket in connection as the transport for REST requests. The socket may represent a direct TCP or TLS connection, an HTTP or SOCKS proxy connection, an SSH-tunneled channel, or another connection configured through the Socket API.

      autoReconnect controls automatic reconnection for later requests when the connection is no longer usable.

      When to use this method: Use connect(String, int, boolean, boolean) for ordinary direct connections. Use UseConnection when the connection requires advanced Socket configuration.Socket lifetime: The Rest object retains and operates on the supplied Socket. Keep the Socket object alive while it is attached. Calling disconnect(int) disconnects it; with autoReconnect set to true, a later request can reconnect the same Socket object.

      Parameters:
      connection - the connection argument (not null)
      autoReconnect - the autoReconnect argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener