Package com.chilkatsoft.chilkat2

Class HttpCurl

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.HttpCurl
All Implemented Interfaces:
AutoCloseable
public class HttpCurl extends ChilkatObject
curl-style HTTP requests with dependency resolution

Run curl commands and automatically resolve values needed by later requests

The Chilkat.HttpCurl class executes HTTP requests expressed as curl commands, with support for variable substitution, reusable curl functions, automatic dependency resolution, response extraction, and structured diagnostics.

Variables such as {{access_token}}, {{site_id}}, or {{drive_id}} can appear in URLs, headers, query parameters, request bodies, the JSON paths that extract values from a response, and the local file path a response is written to. If a variable is not yet known, HttpCurl can build an execution plan from previously defined curl functions, run the prerequisite requests, extract values from JSON responses, and then execute the final target request.

Define dependencies Use AddFunction with AddOutput or AddOutput2.

Manage variables Use SetVar, GetVar, ClearVar, and GetAllVars.

Preview execution Use ExaminePlan or ToRawRequest before sending.

Read responses Get text, binary, JSON, XML, or stream directly to a file.

After DoYourThing completes, check StatusCode and retrieve the response using the appropriate getter. If something fails, FailReason, FailedCurl, and LastErrorText help identify the failed step and the reason.

Note: Chilkat.HttpCurl is not derived from curl/libcurl and does not wrap libcurl. It accepts curl-style command text and executes the request using Chilkat’s own HTTP implementation.

For an extended overview, see HttpCurl Class Overview.

See also:

  • HttpCurl Overview — concepts, variable substitution, dependency resolution, and workflow examples.
  • Dependency Engine — how execution plans are derived, unknown variables are resolved, and cached variables are managed.

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

    • HttpCurl

      public HttpCurl()
      Creates a new HttpCurl object.

  • Method Details

    • getEnableBodyVars

      public boolean getEnableBodyVars()
      Enables variable substitution in the body of the request. The default value is true.
      Returns:
      the value of the EnableBodyVars property

    • setEnableBodyVars

      public void setEnableBodyVars​(boolean value)
      Sets the EnableBodyVars property; see getEnableBodyVars().
      Parameters:
      value - the new value

    • getFailReason

      public int getFailReason()
      Set to an integer value indicating the reason for failure for the methods doYourThing(String) and examinePlan(String, JsonObject)

      Possible values are:

      1. No error - the method succeeded or hasn't yet been called.
      2. curl command syntax error.
      3. HTTP response status code indidcates an authentication (401) or authorization (403) error.
      4. HTTP response status code indicates an error, but not an authentication or authorization error.
      5. HTTP communications failure.
      6. Impossible to derive an execution plan from defined outputs and inputs.
      7. A step in the execution plan did not resolve any dependency variables.
      8. Failed to get curl data from a local file source (see the note below).
      9. If we are within a Chilkat.Js context and don't have permission to read the local filesystem.
      10. Chilkat has not been successfully unlocked by previously and successfully calling UnlockBundle.
      11. Failed to open or create the local output file (if a curl option directed output to a file).
      12. The response body is compressed with a Content-Encoding Chilkat cannot decode, such as Brotli (br) or zstd, so it is unusable. gzip and deflate are decoded automatically. (Introduced in v11.7.0.)

      Note: curl can read data from a local file and send it in a request (usually POST/PUT) using special syntax:

      • -d @file.txt → reads the file and sends it as request body (form-style encoding).
      • --data-binary @file.bin → sends raw file contents exactly as-is.
      • -F "file=@file.txt" → uploads the file as multipart/form-data.

      The @ tells curl to load the data from a local file instead of using a literal string.

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

    • getFailedCurl

      public String getFailedCurl()
      Set to the specific curl command in the execution plan that failed.
      Returns:
      the value of the FailedCurl property (read-only)

    • getHeartbeatMs

      public int getHeartbeatMs()
      Specifies the interval, in milliseconds, between AbortCheck event callbacks.

      This allows an application to periodically decide whether a long-running operation should be aborted.

      The default value is 0, which means no AbortCheck callbacks are generated.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

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

    • getResponseBodyStr

      public String getResponseBodyStr()
      Returns the HTTP response body from the last call to doYourThing(String) .
      Returns:
      the value of the ResponseBodyStr property (read-only)

    • getResponseFilePath

      public String getResponseFilePath()
      Set this property to the path of a file to stream the response body to a file. If the response is streamed to a file, it will not be available in getResponseBodyStr() , getResponseSb(StringBuilder) , or getResponseBd(BinData) .
      Returns:
      the value of the ResponseFilePath property

    • setResponseFilePath

      public void setResponseFilePath​(String value)
      Sets the ResponseFilePath property; see getResponseFilePath().
      Parameters:
      value - the new value (not null)

    • getResponseHeader

      public String getResponseHeader()
      Returns the HTTP response header from the last call to doYourThing(String): the status line (such as HTTP/1.1 200 OK) followed by the header fields, with CRLF line endings. Empty if no response was received. When redirects were followed (-L), this is the header of the final response. To get a single field, use getResponseHeaderField(String). The curl -D/--dump-header option writes the header of every response (including redirects) to a file, and -i/--include writes the header before the body in the -o/-O output file; neither changes this property or the response body returned in memory.
      Returns:
      the value of the ResponseHeader property (read-only)

    • getStatusCode

      public int getStatusCode()
      Returns the HTTP status code from the last call to doYourThing(String). A value of 0 indicates no response header was received.
      Returns:
      the value of the StatusCode property (read-only)

    • getUncommonOptions

      public String getUncommonOptions()
      Provides a comma-separated list of uncommon option keywords.

      This property defaults to an empty string and should normally remain empty.

      Can be set to a list of the following comma separated keywords:

      • IgnoreUnknownCurlOptions - Introduced in v11.7.0. Starting in v11.7.0, a curl option that HttpCurl does not recognize causes doYourThing(String) to fail with a syntax error (getFailReason() = 1) naming the option in LastErrorText, rather than being silently dropped as in earlier versions. (Options that are meaningless to HttpCurl but harmless, such as --progress-bar or --retry, are accepted and ignored.) This keyword restores the earlier behavior: an unknown option is skipped with a note in LastErrorText. Note that the value of an unknown option that takes one is then seen as a stray token.

      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)

    • addFunction

      public void addFunction​(String funcName, String curl)
      Adds a named curl function that can be used in dependency resolution. Inputs required by the curl function are indicated by the variable names enclosed in {{ and }}. Outputs are defined in one or more calls to addOutput(String, String, String) .
      Parameters:
      funcName - the funcName argument (not null)
      curl - the curl argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addOutput

      public void addOutput​(String funcName, String jsonPath, String varName)
      Adds or updates a defined output for a dependency resolution curl function previously defined by calling addFunction(String, String). The jsonPath is the JSON path in the JSON response body where the varName's value is located. If either the funcName or jsonPath already exist for the funcName, then the output is updated.
      Parameters:
      funcName - the funcName argument (not null)
      jsonPath - the jsonPath argument (not null)
      varName - the varName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addOutput2

      public void addOutput2​(String funcName, String arrayPath, String wherePath, String whereValue, boolean caseSensitive, String subPath, String varName)
      Adds or updates an output variable definition for a dependency-resolution curl function previously created by calling AddFunction. Use this method when the curl response is JSON containing an array of objects, and a value needs to be extracted from one specific array element.

      The method searches the array located at arrayPath, finds the array element where the value at wherePath matches whereValue, and then extracts the value at subPath. The extracted value is assigned to the variable named by varName.

      The wherePath and subPath values are paths relative to each individual array element. The comparison between whereValue and the JSON value found at wherePath is either case-sensitive or case-insensitive depending on the value of caseSensitive.

      Parameters

      • funcName — The name of the curl function previously added by calling AddFunction. The output definition is associated with this function.
      • arrayPath — The JSON path identifying the array of records within the JSON response. May contain variable references (see below).
      • wherePath — A relative JSON path within each array element used to locate the matching record. May contain variable references (see below).
      • whereValue — The value to match against the JSON value found at wherePath. May contain variable references (see below).
      • caseSensitive — If true, the comparison between whereValue and the JSON value is case-sensitive. If false, the comparison is case-insensitive.
      • subPath — A relative JSON path within the matched array element identifying the value to extract. May contain variable references (see below).
      • varName — The name of the variable that will receive the extracted value.

      Variable references

      Starting in v11.7.0, the arrayPath, wherePath, whereValue and subPath may each contain variable names enclosed in {{ and }}, such as {{site_name}}, either on their own or within a longer string such as result.{{list_name}}.items. Each is stored exactly as passed here, and the references in it are resolved every time this output is evaluated — not when AddOutput2 is called. A variable whose value is set later by SetVar, or that is produced as the output of another curl function, is therefore used with its current value.

      A variable referenced here is treated as an input of the curl function, exactly like one appearing in the curl command itself, so the execution plan runs whatever produces it first. If a referenced variable has no value and nothing can produce it, the reference is left in place, no array element matches, and the LastErrorText reports the failure with both the resolved and the unresolved form of the record spec.

      Example

      Given the following JSON response: 

      {
   "drives": [
     {
       "name": "Documents",
       "id": "A123"
     },
     {
       "name": "Shared",
       "id": "B456"
     }
   ]
 }

      The following call: 

      AddOutput2("GetDrive","drives","name","shared",false,"id","drive_id")

      searches the drives array for the element whose name matches "shared" using case-insensitive comparison. The matching element is: 

      {
   "name": "Shared",
   "id": "B456"
 }

      The value of id is extracted and assigned to the variable drive_id, resulting in: 

      drive_id = "B456"
      Parameters:
      funcName - the funcName argument (not null)
      arrayPath - the arrayPath argument (not null)
      wherePath - the wherePath argument (not null)
      whereValue - the whereValue argument (not null)
      caseSensitive - the caseSensitive argument
      subPath - the subPath argument (not null)
      varName - the varName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addTargetOutput

      public void addTargetOutput​(String jsonPath, String varName)
      Adds an automatically mapped variable for the target curl command. When a JSON response is received from a curl request, the value at the JSON path specified by jsonPath is extracted (if present) and assigned to the variable named by varName.

      This is useful in common workflows where one request returns an identifier (such as an `id`) that must be reused in a subsequent curl request.

      Parameters:
      jsonPath - the jsonPath argument (not null)
      varName - the varName argument (not null)

    • clearTargetOutput

      public void clearTargetOutput​(String varName)
      Clears (undefines) the target output for the specified varName. If varName equals "*", then all target outputs are cleared.
      Parameters:
      varName - the varName argument (not null)

    • clearVar

      public void clearVar​(String varName)
      Undefines the variable with the specified name. If varName equals "*", then all variables are cleared.
      Parameters:
      varName - the varName argument (not null)

    • doYourThing

      public void doYourThing​(String targetCurl)
      Runs a the targetCurl command specified in targetCurl. If the targetCurl contains variable names enclosed in {{ and }}, then an execution plan is constructed from defined functions and outputs to resolve unknown variables, and the execution plan is run. The final step in the execution plan is always the targetCurl command.

      Returns success (true) if a response was received, in which case the response status code will be available in getStatusCode() and the content of the response body will be available in one of two places:

      Assuming the HTTP response is JSON, the target outputs (variables) specified by prior calls to addTargetOutput(String, String) will be populated by applying each variable's JSON path to the response JSON.

      Writing the response to a local file

      A curl command may write the response body to a local file with -o / --output (an explicit filename), or with -O / --remote-name (the filename is the final path segment of the URL). Either may be combined with --output-dir, which, as in curl, is applied only when the filename itself contains no directory separator.

      Starting in v11.7.0, the output file path may contain variable names enclosed in {{ and }}, resolved from the current variable values at the time the request is sent. This applies to the path given with -o, the directory given with --output-dir, and the URL that -O derives a filename from. In previous versions the path was used exactly as written, so -o "{{report_name}}.pdf" created a file literally named {{report_name}}.pdf and reported success. 

      httpCurl.SetVar("customer","acme");
 httpCurl.SetVar("report_name","q3-summary");
 httpCurl.DoYourThing("curl https://api.example.com/reports/{{report_name}} "
     "--output-dir \"reports/{{customer}}\" -o \"{{report_name}}.pdf\"");
 // writes reports/acme/q3-summary.pdf

      Two conditions cause the request to fail rather than write a file:

      • The resolved path still contains a {{varName}} reference, or a variable in it resolved to an empty string. (Elsewhere -- in a URL or a request body -- an unresolved reference is left in place. In a file path that would silently create a misnamed file.)
      • A variable substituted into the path has a value containing a .. directory segment. Because a variable's value can come from a server's response (see addOutput(String, String, String) and addOutput2(String, String, String, String, boolean, String, String)), a response must not be able to move the output file out of the directory the curl command named. A .. written literally in the curl command itself is the application's own choice and is allowed.

      The path as it will actually be used is written to LastErrorText as resolvedOutputPath.

      This is independent of the getResponseFilePath() property, which streams the response body to a file for requests whose curl command names no output file.

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

    • examinePlan

      public void examinePlan​(String curl, JsonObject json)
      Used for debugging. Returns in json the plan of execution that would occur for the curl based on the variables that are either unknown or already known. The plan of execution is what would occur if doYourThing(String) was called with the current state of knowledge.

      If no execution plan is possible with the current known inputs and outputs, then json provides information about what is missing and the method returns false.

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

    • getAllVars

      public void getAllVars​(JsonObject json)
      Returns all defined variables in json.
      Parameters:
      json - the json argument (not null)

    • getResponseBd

      public void getResponseBd​(BinData bd)
      Appends to bd the HTTP response body from the last call to doYourThing(String).
      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getResponseHeaderField

      public String getResponseHeaderField​(String name)
      Returns the value of the response header field named name (case-insensitive) from the last call to doYourThing(String), such as "Content-Type" or "ETag". Returns an empty string if the response has no such field. When redirects were followed (-L), the field is from the final response. The full response header is available in getResponseHeader().
      Parameters:
      name - the name argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getResponseJarr

      public void getResponseJarr​(JsonArray jarr)
      Writes to jarr the HTTP response body from the last call to doYourThing(String).
      Parameters:
      jarr - the jarr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getResponseJson

      public void getResponseJson​(JsonObject json)
      Writes to json the HTTP response body from the last call to doYourThing(String).
      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getResponseSb

      public void getResponseSb​(StringBuilder sb)
      Appends to sb the HTTP response body from the last call to doYourThing(String).
      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getResponseXml

      public void getResponseXml​(Xml xml)
      Writes to xml the HTTP response body from the last call to doYourThing(String).
      Parameters:
      xml - the xml argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getVar

      public String getVar​(String varName)
      Retrieves the current value of the variable specified by varName.
      Parameters:
      varName - the varName argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuth

      public void setAuth​(JsonObject json)
      Sets authorization information that is applied to all calls to doYourThing(String) . See the examples below for details.
      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setVar

      public void setVar​(String varName, String varValue)
      Sets the value of a variable to be replaced in curl commands. Variable names are enclosed in {{ and }} and can occur in the path, query params, or the body of the request. Starting in v11.7.0, they can also occur in the arrayPath, wherePath, whereValue and subPath passed to addOutput2(String, String, String, String, boolean, String, String), and in the local output file path of a curl command -- the path given with -o or --output, the directory given with --output-dir, and the URL that -O derives a filename from. See doYourThing(String) .
      Parameters:
      varName - the varName argument (not null)
      varValue - the varValue argument (not null)

    • toRawRequest

      public void toRawRequest​(String curlCommand, StringBuilder sb)
      Used for debugging purposes. This method behaves the same as doYourThing(String) , but only converts the curlCommand to an HTTP request message in sb containing the full structure:
      • start line
      • headers
      • optional body or multipart body

      It does not actually send the HTTP request.

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

    • varDefined

      public boolean varDefined​(String varName)
      Returns true if the varName is defined, otherwise returns false. Setting varName to "!" checks whether all target output variables have been defined. It returns true if every target output is set, and false if any are missing.
      Parameters:
      varName - the varName argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • 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