Package com.chilkatsoft.chilkat2

Class HttpRequest

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

Build structured HTTP requests for use with Chilkat.Http.

Chilkat.HttpRequest is a helper class for constructing HTTP requests that are sent by Chilkat.Http. It does not perform network communication on its own. Instead, it provides structured control over the request method, HTTP version, path, headers, query parameters, form parameters, content type, request body, multipart uploads, streamed file bodies, and diagnostic request generation.

Request construction

Build an HTTP request object with the method, path, version, headers, parameters, and body settings required by the target endpoint.

Form parameters

Add name/value parameters for form posts and API requests that expect structured form data.

Custom headers

Set request headers such as content type, accept headers, authorization headers, or application-specific metadata.

Request bodies

Provide body content for POST, PUT, PATCH, or other methods that send data to a server.

Multipart and file uploads

Construct multipart/form-data requests, attach file parts, or stream a file as the request body when the API requires upload content.

Diagnostics

Generate a textual representation of the request to inspect headers, paths, parameters, body structure, and upload formatting before sending.

Common pattern: Create a HttpRequest, set the HTTP method and path, add any headers, parameters, body data, or file parts, then pass the request object to the appropriate Chilkat.Http method for sending. Use HttpRequest for structured or multipart requests; use simpler Http methods directly when only a basic GET, POST, upload, or download is needed.

For an extended overview, see HttpRequest Class Overview.

</section>

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

    • HttpRequest

      public HttpRequest()
      Creates a new HttpRequest object.

  • Method Details

    • getBoundary

      public String getBoundary()
      Sets an explicit boundary string to be used in multipart/form-data requests. If no Boundary is set, then a boundary string is automaticaly generated as needed during the sending of a request.
      Returns:
      the value of the Boundary property

    • setBoundary

      public void setBoundary​(String value)
      Sets the Boundary property; see getBoundary().
      Parameters:
      value - the new value (not null)

    • getCharset

      public String getCharset()
      Controls the character encoding used in the URL encoding of query params. The default value of this propoerty is utf-8.
      Returns:
      the value of the Charset property

    • setCharset

      public void setCharset​(String value)
      Sets the Charset property; see getCharset().
      Parameters:
      value - the new value (not null)

    • getContentType

      public String getContentType()
      The ContentType property sets the Content-Type header field, and identifies the content-type of the HTTP request body. Common values are: 
      application/x-www-form-urlencoded
 multipart/form-data
 application/json
 application/xml

      If ContentType is set equal to the empty string, then no Content-Type header is included in the HTTP request.
      Returns:
      the value of the ContentType property

    • setContentType

      public void setContentType​(String value)
      Sets the ContentType property; see getContentType().
      Parameters:
      value - the new value (not null)

    • getEntireHeader

      public String getEntireHeader()
      Composes and returns the entire MIME header of the HTTP request.
      Returns:
      the value of the EntireHeader property

    • setEntireHeader

      public void setEntireHeader​(String value)
      Sets the EntireHeader property; see getEntireHeader().
      Parameters:
      value - the new value (not null)

    • getHttpVerb

      public String getHttpVerb()
      The HttpVerb property should be set to the name of the HTTP method that appears on the start line of an HTTP request, such as GET, POST, PUT, DELETE, etc. It is also possible to use the various WebDav verbs such as PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK, etc. In general, the HttpVerb may be set to anything, even custom verbs recognized by a custom server-side app.
      Returns:
      the value of the HttpVerb property

    • setHttpVerb

      public void setHttpVerb​(String value)
      Sets the HttpVerb property; see getHttpVerb().
      Parameters:
      value - the new value (not null)

    • getHttpVersion

      public String getHttpVersion()
      The HTTP version in the request header. Defaults to 1.1. Can only be set to 1.0 or 1.1.
      Returns:
      the value of the HttpVersion property

    • setHttpVersion

      public void setHttpVersion​(String value)
      Sets the HttpVersion property; see getHttpVersion().
      Parameters:
      value - the new value (not null)

    • getNumHeaderFields

      public int getNumHeaderFields()
      Returns the number of request header fields.
      Returns:
      the value of the NumHeaderFields property (read-only)

    • getNumParams

      public int getNumParams()
      Returns the number of query parameters.
      Returns:
      the value of the NumParams property (read-only)

    • getPath

      public String getPath()
      The path of the resource requested. A path of / indicates the default document of a domain.

      Explaining the Parts of a URL 

      http://example.com:8042/over/there?name=ferret#nose
 \__/   \______________/\_________/ \________/ \__/
  |           |            |            |        |
 scheme   domain+port     path        query   fragment

      This property should be set to the path part of the URL. You may also include the query part in this property value. If the Content-Type of the request is NOT application/x-www-form-urlencoded, then you would definitely want to include query parameters in the path. If the Content-Type of the request IS application/x-www-form-urlencoded, the query parameters are passed in the body of the request. It is also possible to pass some query parameters via the path, and some in the body of a application/x-www-form-urlencoded request, but you shouldn't include the same parameter in both places. You would never need to include the fragment part. The fragment is nothing more than an instruction for a browser to automatically navigate to a particular location in the HTML page (assuming the request returns HTML, otherwise a fragment makes no sense).

      Returns:
      the value of the Path property

    • setPath

      public void setPath​(String value)
      Sets the Path property; see getPath().
      Parameters:
      value - the new value (not null)

    • getSendCharset

      public boolean getSendCharset()
      Controls whether the charset is explicitly included in the content-type header field of the HTTP POST request. The default value of this property is false.
      Returns:
      the value of the SendCharset property

    • setSendCharset

      public void setSendCharset​(boolean value)
      Sets the SendCharset property; see getSendCharset().
      Parameters:
      value - the new value

    • addBdForUpload

      public void addBdForUpload​(String name, String remoteFilename, BinData byteData, String contentType)
      Adds a file to an upload request where the contents of the file come from byteData.

      name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
      remoteFilename is the name of the file to be created on the HTTP server.
      byteData contains the bytes to be uploaded.
      contentType contains is the value of the Content-Type header. An empty string may be passed to allow Chilkat to automatically determine the Content-Type based on the filename extension.

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

    • addFileForUpload

      public void addFileForUpload​(String name, String filePath)
      Adds a file to an upload request. To create a file upload request, set the ContentType property = multipart/form-data and then call AddFileForUpload, AddBytesForUpload, or AddStringForUpload for each file to be uploaded. This method does not read the file into memory. When the upload occurs, the data is streamed directly from the file, thus allowing for very large files to be uploaded without consuming large amounts of memory.

      name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
      filePath is the path to an existing file in the local filesystem.

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

    • addFileForUpload2

      public void addFileForUpload2​(String name, String filePath, String contentType)
      Same as AddFileForUpload, but allows the Content-Type header field to be directly specified. (Otherwise, the Content-Type header is automatically determined based on the file extension.)

      name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
      filePath is the path to an existing file in the local filesystem.

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

    • addHeader

      public void addHeader​(String name, String value)
      Adds a request header to the HTTP request. If a header having the same field name is already present, this method replaces it.

      Note: Never explicitly set the Content-Length header field. Chilkat will automatically compute the correct length and add the Content-Length header to all POST, PUT, or any other request where the Content-Length needs to be specified. (GET requests always have a 0 length body, and therefore never need a Content-Length header field.)

      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)

    • addMwsSignature

      public void addMwsSignature​(String domain, String mwsSecretKey)
      Computes the Amazon MWS signature using the mwsSecretKey and adds the Signature parameter to the request. This method should be called for all Amazon Marketplace Web Service (Amazon MWS) HTTP requests. It should be called after all request parameters have been added.

      Important: The Chilkat v9.5.0.75 release accidentally breaks Amazon MWS (not AWS) authentication. If you need MWS with 9.5.0.75, send email to support@chilkatsoft.com for a hotfix, or revert back to v9.5.0.73, or update to a version after 9.5.0.75.

      The domain should be the domain of the request, such as one of the following:

      • mws.amazonservices.com
      • mws-eu.amazonservices.com
      • mws.amazonservices.in
      • mws.amazonservices.com.cn
      • mws.amazonservices.jp

      Note: This method automatically adds or replaces the existing Timestamp parameter to the current system date/time.

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

    • addParam

      public void addParam​(String name, String value)
      Adds a request query parameter (name/value pair) to the HTTP request. The name and value strings passed to this method should not be URL encoded.
      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)

    • addStringForUpload

      public void addStringForUpload​(String name, String filename, String strData, String charset)
      Same as AddFileForUpload, but the upload data comes from an in-memory string instead of a file.
      Parameters:
      name - the name argument (not null)
      filename - the filename argument (not null)
      strData - the strData argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addStringForUpload2

      public void addStringForUpload2​(String name, String filename, String strData, String charset, String contentType)
      Same as AddStringForUpload, but allows the Content-Type header field to be directly specified. (Otherwise, the Content-Type header is automatically determined based on the filename's file extension.)
      Parameters:
      name - the name argument (not null)
      filename - the filename argument (not null)
      strData - the strData argument (not null)
      charset - the charset argument (not null)
      contentType - the contentType argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addSubHeader

      public void addSubHeader​(int index, String name, String value)
      Adds a request header to the Nth sub-header of the HTTP request. If a header having the same field name is already present, this method replaces it.
      Parameters:
      index - the index argument
      name - the name argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • generateRequestFile

      public void generateRequestFile​(String path)
      The same as GenerateRequestText, except the generated request is written to the file specified by path.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • generateRequestText

      public String generateRequestText()
      Returns the request text that would be sent if Http.SynchronousRequest was called.
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getHeaderField

      public String getHeaderField​(String name)
      Returns the value of a request header field.
      Parameters:
      name - the name argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • getHeaderName

      public String getHeaderName​(int index)
      Returns the Nth request header field name. Indexing begins at 0, and the number of request header fields is specified by the NumHeaderFields property.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getHeaderValue

      public String getHeaderValue​(int index)
      Returns the Nth request header field value. Indexing begins at 0, and the number of request header fields is specified by the NumHeaderFields property.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getParam

      public String getParam​(String name)
      Returns a request query parameter value by name.
      Parameters:
      name - the name argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getParamName

      public String getParamName​(int index)
      Returns the Nth request query parameter field name. Indexing begins at 0, and the number of request query parameter fields is specified by the NumParams property.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getParamValue

      public String getParamValue​(int index)
      Returns the Nth request query parameter field value. Indexing begins at 0, and the number of request query parameter fields is specified by the NumParams property.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getUrlEncodedParams

      public String getUrlEncodedParams()
      Returns the request parameters in URL encoded form (i.e. in the exact form that would be sent if the ContentType property was application/x-www-form-urlencoded). For example, if a request has two params: param1=abc 123 and param2=abc-123, then GetUrlEncodedParams would return abc+123&param2=abc%2D123
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadBodyFromBd

      public void loadBodyFromBd​(BinData requestBody)
      Uses the contents of the requestBody as the HTTP request body.
      Parameters:
      requestBody - the requestBody argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadBodyFromFile

      public void loadBodyFromFile​(String filePath)
      The HTTP protocol is such that all HTTP requests are MIME. For non-multipart requests, this method may be called to set the MIME body of the HTTP request to the exact contents of filePath.
      Note: A non-multipart HTTP request consists of (1) the HTTP start line, (2) MIME header fields, and (3) the MIME body. This method sets the MIME body.
      Parameters:
      filePath - the filePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadBodyFromSb

      public void loadBodyFromSb​(StringBuilder requestBody, String charset)
      Uses the contents of the requestBody as the HTTP request body. The charset indicates the binary representation of the string, such as utf-8, utf-16, iso-8859-*, windows-125*, etc. Any of the character encodings supported at the link below are valid.
      Parameters:
      requestBody - the requestBody argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadBodyFromString

      public void loadBodyFromString​(String bodyStr, String charset)
      The HTTP protocol is such that all HTTP requests are MIME. For non-multipart requests, this method may be called to set the MIME body of the HTTP request to the exact contents of bodyStr.
      Note: A non-multipart HTTP request consists of (1) the HTTP start line, (2) MIME header fields, and (3) the MIME body. This method sets the MIME body.

      charset indicates the charset, such as utf-8 or iso-8859-1, to be used. The HTTP body will contain the bodyStr converted to this character encoding.

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

    • removeAllParams

      public void removeAllParams()
      Removes all request parameters.

    • removeHeader

      public void removeHeader​(String name)
      Removes all occurrences of a HTTP request header field. Always returns true.
      Parameters:
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeParam

      public void removeParam​(String name)
      Removes a single HTTP request parameter by name.
      Parameters:
      name - the name argument (not null)

    • setFromUrl

      public void setFromUrl​(String url)
      Parses a URL and sets the Path and query parameters (NumParams, GetParam, GetParamName, GetParamValue).
      Parameters:
      url - the url argument (not null)

    • streamBodyFromFile

      public void streamBodyFromFile​(String filePath)
      Useful for sending HTTP requests where the body is a very large file. For example, to send an XML HttpRequest containing a very large XML document, one would set the HttpVerb = POST, the ContentType = text/xml, and then call StreamBodyFromFile to indicate that the XML body of the request is to be streamed directly from a file. When the HTTP request is actually sent, the body is streamed directly from the file, and thus the file never needs to be loaded in its entirety in memory.
      Parameters:
      filePath - the filePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • streamChunkFromFile

      public void streamChunkFromFile​(String path, String offset, String numBytes)
      This method is the same as StreamBodyFromFile, but allows for an offset and number of bytes to be specified. The offset and numBytes are integers passed as strings.
      Parameters:
      path - the path argument (not null)
      offset - the offset argument (not null)
      numBytes - the numBytes argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why