Class WebUtils

java.lang.Object
io.fluxzero.sdk.web.WebUtils
public class WebUtils extends Object
Utility methods for working with web request and response data, including cookies, headers, and handler annotations.

This class supports parsing and formatting of HTTP cookie headers, case-insensitive HTTP header maps, and discovery of WebPattern annotations on handler methods annotated with HandleWeb.

  • Constructor Details

    • WebUtils

      public WebUtils()

  • Method Details

    • toResponseHeaderString

      public static String toResponseHeaderString(@NonNull @NonNull HttpCookie cookie)
      Returns a properly formatted Set-Cookie header value for the given cookie.

      The result includes standard attributes such as Domain, Path, Max-Age, HttpOnly, and Secure if they are set on the cookie.

      Parameters:
      cookie - the cookie to format (must not be null)
      Returns:
      a header string suitable for a Set-Cookie response header

    • toRequestHeaderString

      public static String toRequestHeaderString(@NonNull @NonNull HttpCookie cookie)
      Returns a formatted string for the Cookie request header containing the given cookie.
      Parameters:
      cookie - the cookie to encode (must not be null)
      Returns:
      a header string suitable for inclusion in a Cookie request header

    • parseRequestCookieHeader

      public static List<HttpCookie> parseRequestCookieHeader(String cookieHeader)
      Parses a Cookie request header string into a list of HttpCookie instances.

      The input is expected to contain one or more name-value pairs separated by semicolons.

      Parameters:
      cookieHeader - the value of the Cookie header, or null
      Returns:
      a list of parsed HttpCookie instances (empty if input is null)

    • parseResponseCookieHeader

      public static List<HttpCookie> parseResponseCookieHeader(List<String> setCookieHeaders)
      Parses a list of Set-Cookie header values into a list of HttpCookie instances.

      Each value in the input list should be a properly formatted Set-Cookie header line.

      Parameters:
      setCookieHeaders - the list of Set-Cookie header values, or null
      Returns:
      a list of parsed HttpCookie instances (empty if input is null)

    • getWebPatterns

      public static List<WebPattern> getWebPatterns(Class<?> targetClass, @Nullable Object handler, Executable method)
      Returns all WebPattern instances declared on the given method in the given target class.

      This inspects all HandleWeb annotations on the method and resolves any declared WebParameters to extract associated patterns.

      Parameters:
      targetClass - the target class
      handler - the handler instance (may be null)
      method - the method to inspect
      Returns:
      a list of WebPattern instances associated with the method

    • getHandlerPath

      public static String getHandlerPath(Class<?> targetClass, @Nullable Object handler, @Nullable Executable method)
      Computes the complete @Path value for the given handler. targetClass is required; handler and method are not. The path value is determined by inspecting the following elements:
      • sub-packages
      • class package
      • target class
      • handler properties (if the given handler is not null)
      • handler method (if the given method is not null)

      @Path values are joined together in the order listed above, with a slash as delimiter. If any of the @Path values start with a slash or contain an absolute URL, the chain is reset.

    • emptyHeaderMap

      public static Map<String, List<String>> emptyHeaderMap()
      Returns a new case-insensitive header map, with keys compared ignoring case.
      Returns:
      an empty case-insensitive Map for headers

    • asHeaderMap

      public static Map<String, List<String>> asHeaderMap(Map<String, List<String>> input)
      Converts the input map into a case-insensitive header map.

      Keys in the result will be case-insensitive, with the contents copied from the input map.

      Parameters:
      input - the input map
      Returns:
      a case-insensitive map containing the same entries

    • getHeaders

      public static Map<String, List<String>> getHeaders(Metadata metadata)
      Retrieves a case-insensitive map of headers from the provided Metadata object.

    • getHeader

      public static Optional<String> getHeader(Metadata metadata, String name)
      Retrieves the first header value for the given name from the provided Metadata object.

    • convertPayload

      public static <R> R convertPayload(Object payload, Type type, String contentType)
      Converts a web payload to the requested target type.

      This method preserves already-compatible payload instances, supports explicit low-level conversion to String and byte[], and only parses raw JSON when the payload is represented as text or bytes and the content type indicates JSON.

      When the payload is an InputStream, the stream is fully consumed before conversion.

      Type Parameters:
      R - the expected return type
      Parameters:
      payload - the decoded payload value
      type - the requested target type
      contentType - the associated content type, used to determine whether JSON parsing should be applied
      Returns:
      the converted payload, or null if the input payload is null

    • isJsonContentType

      public static boolean isJsonContentType(String contentType)
      Checks whether a content type should be treated as JSON.

      This recognizes the canonical application/json media type, optional parameters such as charset, and structured syntax suffixes such as application/problem+json.

      Parameters:
      contentType - the content type to inspect
      Returns:
      true if the content type denotes JSON; otherwise false

    • hasPathParameter

      public static boolean hasPathParameter(String path)
      Checks if the given path contains a named path parameter.

    • extractPathParameters

      public static List<String> extractPathParameters(String path)
      Extracts all named path parameters from the given path.

      Example usage: 

      E.g. List<String> params = extractPathParameters("/games/{gameId}/refund/{orderId}");
     // → ["gameId", "orderId"]

    • replacePathParameter

      public static String replacePathParameter(String path, String parameterName, String value)
      Replaces named path parameter with provided value.

      Example usage: 

      replacePathParameter("/users/{userId}/games/{gameId}", "userId", "123");
     // → "/users/123/games/{gameId}"

    • concatenateUrlParts

      public static String concatenateUrlParts(String... parts)
      Concatenates multiple segments of a URL, ensuring that:
      • Double slashes in schemes like https:// are preserved
      • Duplicate slashes between path segments are removed
      • Null or empty segments are skipped
      Parameters:
      parts - URL parts, e.g., "https://", "example.org", "/api/", "/v1/"
      Returns:
      A clean, properly concatenated URL, e.g. "https://example.org/api/v1/"