Module bus.http
Package org.miaixz.bus.http.plugin.httpv

Class CoverHttp<C extends CoverHttp<?>>

java.lang.Object
org.miaixz.bus.http.plugin.httpv.CoverHttp<C>
Type Parameters:
C - The concrete subclass type, for method chaining.
All Implemented Interfaces:
Cancelable
Direct Known Subclasses:
CoverCall.Client, CoverHttp.Async, CoverHttp.Sync
public abstract class CoverHttp<C extends CoverHttp<?>> extends Object implements Cancelable
An abstract base class for building HTTP requests, providing a fluent interface. It supports synchronous, asynchronous, and WebSocket requests.
Since:
Java 17+
Author:
Kimi Liu

  • Field Details

    • httpv

      public Httpv httpv
      The core HTTP client instance.

    • nothrow

      public boolean nothrow
      If true, exceptions will not be thrown but will be available in the result object.

    • nextOnIO

      public boolean nextOnIO
      If true, the next callback will be executed on an I/O thread.

    • skipPreproc

      public boolean skipPreproc
      If true, all preprocessors (both serial and parallel) will be skipped for this request.

    • skipSerialPreproc

      public boolean skipSerialPreproc
      If true, serial preprocessors will be skipped for this request.

  • Constructor Details

    • CoverHttp

      public CoverHttp(Httpv httpv, String url)
      Constructs a new CoverHttp request builder.
      Parameters:
      httpv - The core Httpv client instance.
      url - The base URL or URL path for the request.

  • Method Details

    • getUrl

      public String getUrl()
      Gets the URL of this request task.
      Returns:
      The URL string.

    • getTag

      public String getTag()
      Gets the tag of this request task.
      Returns:
      The tag string.

    • getBodyType

      public String getBodyType()
      Gets the body type of this request task.
      Returns:
      The body type string (e.g., "json", "form").

    • isTagged

      public boolean isTagged(String tag)
      Checks if this request's tag matches (contains) the given tag.
      Parameters:
      tag - The tag to check against.
      Returns:
      True if the request is tagged with the specified tag, false otherwise.

    • getHeaders

      public Map<String,String> getHeaders()
      Gets the headers of this request task.
      Returns:
      A map of headers.

    • getBound

      public Object getBound()
      Gets the object bound to this request.
      Returns:
      The bound object.

    • nothrow

      public C nothrow()
      Configures the request to not throw exceptions on failure. Instead, the exception will be available in the `CoverResult` object.
      Returns:
      This instance for chaining.

    • skipPreproc

      public C skipPreproc()
      Specifies that this request should skip all preprocessors (both serial and parallel).
      Returns:
      This instance for chaining.

    • skipSerialPreproc

      public C skipSerialPreproc()
      Specifies that this request should skip any serial preprocessors.
      Returns:
      This instance for chaining.

    • tag

      public C tag(String tag)
      Adds a tag to the request. Multiple tags can be added and will be concatenated with dots.
      Parameters:
      tag - The tag to add.
      Returns:
      This instance for chaining.

    • charset

      public C charset(Charset charset)
      Sets the character encoding for this request.
      Parameters:
      charset - The character set.
      Returns:
      This instance for chaining.

    • bodyType

      public C bodyType(String type)
      Sets the request body type, such as "form", "json", "xml", "protobuf", etc. This determines which message converter will be used for serialization.
      Parameters:
      type - The body type.
      Returns:
      This instance for chaining.

    • nextOnIO

      public C nextOnIO()
      Specifies that the next callback should be executed on an I/O thread.
      Returns:
      This instance for chaining.

    • bind

      public C bind(Object object)
      Binds an arbitrary object to this request.
      Parameters:
      object - The object to bind.
      Returns:
      This instance for chaining.

    • addHeader

      public C addHeader(String name, String value)
      Adds a request header.
      Parameters:
      name - The header name.
      value - The header value.
      Returns:
      This instance for chaining.

    • addHeader

      public C addHeader(Map<String,String> headers)
      Adds multiple request headers.
      Parameters:
      headers - A map of headers to add.
      Returns:
      This instance for chaining.

    • setRange

      public C setRange(long rangeStart)
      Sets the Range header to resume a download.
      Parameters:
      rangeStart - The byte offset to start receiving data from (inclusive).
      Returns:
      This instance for chaining.

    • setRange

      public C setRange(long rangeStart, long rangeEnd)
      Sets the Range header to download a specific chunk of a file.
      Parameters:
      rangeStart - The starting byte offset (inclusive).
      rangeEnd - The ending byte offset (inclusive).
      Returns:
      This instance for chaining.

    • setOnProcess

      public C setOnProcess(Callback<Progress> onProcess)
      Sets a callback to monitor the progress of the request body upload.
      Parameters:
      onProcess - The progress callback function.
      Returns:
      This instance for chaining.

    • stepBytes

      public C stepBytes(long stepBytes)
      Sets the step size in bytes for progress callbacks. The callback will be triggered approximately every `stepBytes` bytes are transferred. Defaults to 8KB.
      Parameters:
      stepBytes - The step size in bytes.
      Returns:
      This instance for chaining.

    • stepRate

      public C stepRate(double stepRate)
      Sets the step rate for progress callbacks. The callback will be triggered at percentage increments defined by this rate (e.g., 0.01 for every 1%).
      Parameters:
      stepRate - The step rate (between 0.0 and 1.0).
      Returns:
      This instance for chaining.

    • addPathPara

      public C addPathPara(String name, Object value)
      Adds a path parameter to be replaced in the URL (e.g., for /api/user/{id}).
      Parameters:
      name - The parameter name (without braces).
      value - The parameter value.
      Returns:
      This instance for chaining.

    • addPathPara

      public C addPathPara(Map<String,?> params)
      Adds multiple path parameters.
      Parameters:
      params - A map of path parameters.
      Returns:
      This instance for chaining.

    • addUrlPara

      public C addUrlPara(String name, Object value)
      Adds a URL parameter to be appended to the query string.
      Parameters:
      name - The parameter name.
      value - The parameter value.
      Returns:
      This instance for chaining.

    • addUrlPara

      public C addUrlPara(Map<String,?> params)
      Adds multiple URL parameters.
      Parameters:
      params - A map of URL parameters.
      Returns:
      This instance for chaining.

    • addBodyPara

      public C addBodyPara(String name, Object value)
      Adds a parameter to be included in the request body (e.g., for form submissions).
      Parameters:
      name - The parameter name.
      value - The parameter value.
      Returns:
      This instance for chaining.

    • addBodyPara

      public C addBodyPara(Map<String,?> params)
      Adds multiple body parameters.
      Parameters:
      params - A map of body parameters.
      Returns:
      This instance for chaining.

    • setBodyPara

      public C setBodyPara(Object body)
      Sets the request body directly. The body can be a byte array, a string, or a Java object that will be serialized by a configured message converter.
      Parameters:
      body - The request body.
      Returns:
      This instance for chaining.

    • addFilePara

      public C addFilePara(String name, String filePath)
      Adds a file parameter for a multipart request.
      Parameters:
      name - The parameter name.
      filePath - The path to the file.
      Returns:
      This instance for chaining.

    • addFilePara

      public C addFilePara(String name, File file)
      Adds a file parameter for a multipart request.
      Parameters:
      name - The parameter name.
      file - The file object.
      Returns:
      This instance for chaining.

    • addFilePara

      public C addFilePara(String name, String type, byte[] content)
      Adds a file parameter from a byte array for a multipart request.
      Parameters:
      name - The parameter name.
      type - The file type/extension (e.g., "png", "jpg").
      content - The file content as a byte array.
      Returns:
      This instance for chaining.

    • addFilePara

      public C addFilePara(String name, String type, String fileName, byte[] content)
      Adds a file parameter from a byte array for a multipart request.
      Parameters:
      name - The parameter name.
      type - The file type/extension (e.g., "png", "jpg").
      fileName - The name of the file.
      content - The file content as a byte array.
      Returns:
      This instance for chaining.

    • cancel

      public boolean cancel()
      Cancels the request.
      Specified by:
      cancel in interface Cancelable
      Returns:
      True if the request was successfully canceled, false otherwise.

    • registeTagTask

      protected void registeTagTask(Cancelable canceler)
      Registers this task with the tag manager.
      Parameters:
      canceler - The object that can cancel this task.

    • removeTagTask

      protected void removeTagTask()
      Removes this task from the tag manager.

    • prepareCall

      protected NewCall prepareCall(String method)
      Prepares the Httpd Call object for execution.
      Parameters:
      method - The HTTP method (e.g., "GET", "POST").
      Returns:
      A new Call instance.

    • prepareRequest

      protected Request prepareRequest(String method)
      Prepares the Httpd Request object.
      Parameters:
      method - The HTTP method.
      Returns:
      A new Request instance.

    • toState

      public CoverResult.State toState(IOException e)
      Converts an IOException into a CoverResult.State.
      Parameters:
      e - The IOException.
      Returns:
      The corresponding state.

    • assertNotConflict

      protected void assertNotConflict(boolean bodyCantUsed)
      Asserts that there are no conflicting body parameter settings.
      Parameters:
      bodyCantUsed - True if the HTTP method does not permit a request body.

    • timeoutAwait

      protected boolean timeoutAwait(CountDownLatch latch)
      Awaits on a CountDownLatch with a timeout.
      Parameters:
      latch - The CountDownLatch to wait on.
      Returns:
      False if a timeout occurred, true otherwise.

    • timeoutResult

      protected CoverResult timeoutResult()
      Creates a result object for a timeout event.
      Returns:
      A timeout CoverResult.

    • charset

      public Charset charset(Response response)
      Extracts the character set from an HTTP response.
      Parameters:
      response - The HTTP response.
      Returns:
      The character set, or the default if not specified.