Package org.kiwiproject.jaxrs.client

Class WebTargetHelper

java.lang.Object
org.kiwiproject.jaxrs.client.WebTargetHelper
All Implemented Interfaces:
jakarta.ws.rs.client.WebTarget, jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>
@Beta public class WebTargetHelper extends Object implements jakarta.ws.rs.client.WebTarget
Use with Jakarta REST WebTarget instances to provide convenient functionality when adding query parameters. Most of this functionality is intended for cases when you only want to add parameters when they are not null (or not blank in the case of Strings). If you want a query parameter to be added regardless of whether a value is present or not, use the regular queryParam method in WebTarget.

The methods provided by this helper class allow you to either require query parameters or include them only when they have a value. When you require a query parameter, an IllegalArgumentException is thrown when a caller does not supply a name or value. Other methods allow you to optionally include one or more query parameters, as well as add them from a Map or a MultivaluedMap, such that only non-null/non-blank values are added.

Usage example (assuming withClient is statically imported): 

 var response = withClient(client).target("/search")
         .queryParamRequireNotBlank("q", query)
         .queryParamIfNotBlank("sort", sort)
         .queryParamIfNotBlank("page", page)
         .queryParamIfNotBlank("limit", limit)
         .queryParamFilterNotBlank("lang", languages)
         .request()
         .get();
This class implements WebTarget, and overridden methods return WebTargetHelper, so you can chain methods as you normally would. For example, using withWebTarget: 
 var response = withWebTarget(originalTarget)
         .path("/resolve/{id}")
         .resolveTemplate("id", 42)
         .queryParamIfNotBlank("format", format)
         .queryParamIfNotNull("force", force)
         .request()
         .get();

  • Method Details

    • toWebTarget

      public jakarta.ws.rs.client.WebTarget toWebTarget()
      Convert the current state contained in this helper to a new WebTarget instance.
      Returns:
      a new WebTarget instance

    • withWebTarget

      public static WebTargetHelper withWebTarget(jakarta.ws.rs.client.WebTarget webTarget)
      Create a new instance with the given WebTarget.
      Parameters:
      webTarget - the WebTarget to use
      Returns:
      a new instance

    • queryParamRequireNotNull

      public WebTargetHelper queryParamRequireNotNull(String name, Object value)
      Add the required query parameter.
      Parameters:
      name - the parameter name
      value - the parameter value
      Returns:
      a new instance
      Throws:
      IllegalArgumentException - if name is blank or value is null

    • queryParamIfNotNull

      public WebTargetHelper queryParamIfNotNull(String name, Object value)
      Add the given query parameter only if name is not blank and value is not null.
      Parameters:
      name - the parameter name
      value - the parameter value
      Returns:
      a new instance if name and value are not blank, otherwise this instance

    • queryParamFilterNotNull

      public WebTargetHelper queryParamFilterNotNull(String name, Object... values)
      Adds any non-null values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      values - one or more parameter values
      Returns:
      a new instance if name is not blank and values is not null or empty, otherwise this instance
      See Also:

    • queryParamFilterNotNull

      @Deprecated(since="4.10.0", forRemoval=true) @KiwiDeprecated(replacedBy="#queryParamFilterListNotNull(String name, List<?> values)", removeAt="5.0.0") public WebTargetHelper queryParamFilterNotNull(String name, List<Object> values)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use queryParamFilterListNotNull(String, List)
      Adds any non-null values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      values - one or more parameter values
      Returns:
      a new instance if name is not blank and values is not null or empty, otherwise this instance

    • queryParamFilterListNotNull

      public WebTargetHelper queryParamFilterListNotNull(String name, List<?> values)
      Adds any non-null values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      values - one or more parameter values
      Returns:
      a new instance if name is not blank and values is not null or empty, otherwise this instance

    • queryParamFilterNotNull

      @Deprecated(since="4.10.0", forRemoval=true) @KiwiDeprecated(replacedBy="#queryParamFilterStreamNotNull(String name, Stream<?> stream)", removeAt="5.0.0") public WebTargetHelper queryParamFilterNotNull(String name, Stream<Object> stream)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use queryParamFilterStreamNotNull(String, Stream)
      Adds any non-null values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      stream - containing one or more parameter values
      Returns:
      a new instance if name is not blank and stream is not null, otherwise this instance

    • queryParamFilterStreamNotNull

      public WebTargetHelper queryParamFilterStreamNotNull(String name, Stream<?> stream)
      Adds any non-null values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      stream - containing one or more parameter values
      Returns:
      a new instance if name is not blank and stream is not null, otherwise this instance

    • queryParamRequireNotBlank

      public WebTargetHelper queryParamRequireNotBlank(String name, String value)
      Add the required query parameter.
      Parameters:
      name - the parameter name
      value - the parameter value
      Returns:
      this instance
      Throws:
      IllegalArgumentException - if name or value is blank

    • queryParamIfNotBlank

      public WebTargetHelper queryParamIfNotBlank(String name, String value)
      Add the given query parameter only if both name and value are not blank.
      Parameters:
      name - the parameter name
      value - the parameter value
      Returns:
      a new instance if name is and value are not blank, otherwise this instance

    • queryParamFilterNotBlank

      public WebTargetHelper queryParamFilterNotBlank(String name, String... values)
      Adds any non-blank values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      values - one or more parameter values
      Returns:
      a new instance if name is not blank and values is not null or empty, otherwise this instance
      See Also:

    • queryParamFilterObjectsNotBlank

      public WebTargetHelper queryParamFilterObjectsNotBlank(String name, Object... values)
      Adds non-blank query parameters, converting each object to a string if necessary.

      Any null or blank string values are ignored. Non-CharSequence objects are converted using Object.toString().

      Parameters:
      name - the query parameter name
      values - the values to filter and add
      Returns:
      a new instance with updated query parameters, or this instance if input is empty or invalid
      See Also:

    • queryParamFilterNotBlank

      @Deprecated(since="4.10.0", forRemoval=true) @KiwiDeprecated(replacedBy="#queryParamFilterListNotBlank(String name, List<String> values)", removeAt="5.0.0") public WebTargetHelper queryParamFilterNotBlank(String name, List<String> values)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use queryParamFilterListNotBlank(String, List)
      Adds any non-blank values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      values - one or more parameter values
      Returns:
      a new instance if name is not blank and values is not null or empty, otherwise this instance

    • queryParamFilterListNotBlank

      public WebTargetHelper queryParamFilterListNotBlank(String name, List<?> values)
      Adds any non-blank values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      values - one or more parameter values
      Returns:
      a new instance if name is not blank and values is not null or empty, otherwise this instance

    • queryParamFilterNotBlank

      @Deprecated(since="4.10.0", forRemoval=true) @KiwiDeprecated(replacedBy="queryParamFilterStreamNotBlank(String name, Stream<String> stream)", removeAt="5.0.0") public WebTargetHelper queryParamFilterNotBlank(String name, Stream<String> stream)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use queryParamFilterStreamNotBlank(String, Stream)
      Adds any non-blank values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      stream - containing one or more parameter values
      Returns:
      a new instance if name is not blank and stream is not null, otherwise this instance

    • queryParamFilterStreamNotBlank

      public WebTargetHelper queryParamFilterStreamNotBlank(String name, Stream<?> stream)
      Adds any non-blank values to the given query parameter. If name is blank, this is a no-op.
      Parameters:
      name - the parameter name
      stream - containing one or more parameter values
      Returns:
      a new instance if name is not blank and stream is not null, otherwise this instance

    • queryParamsFromMap

      public <V> WebTargetHelper queryParamsFromMap(Map<String,V> parameters)
      Adds non-null query parameters from the given map. All map keys must be non-null.
      Type Parameters:
      V - the type of keys in the map
      Parameters:
      parameters - a map representing the query parameters
      Returns:
      a new instance if parameters is not null or empty, otherwise this instance
      Implementation Note:
      This method is distinct from queryParamsFromMultivaluedMap(MultivaluedMap) because the MultivaluedMap interface extends the regular Java Map and under certain circumstances this method will be called even when the argument is actually a MultivaluedMap. By having separate and distinctly named methods, it unambiguously avoids this potential problem, at the expense of callers needing to make a concrete decision on which method to call. However, in most situations that we have seen (in our own code) this is not an issue. For example, UriInfo.getQueryParameters() returns a MultivaluedMap, which makes it easy to select the appropriate method to call.

    • queryParamsFromMultivaluedMap

      public <V> WebTargetHelper queryParamsFromMultivaluedMap(jakarta.ws.rs.core.MultivaluedMap<String,V> parameters)
      Adds non-null query parameters from the given multivalued map. All map keys must be non-null.
      Type Parameters:
      V - the type of keys in the map
      Parameters:
      parameters - a multivalued map representing the query parameters
      Returns:
      a new instance if parameters is not null or empty, otherwise this instance
      Implementation Note:
      See implementation note on queryParamsFromMap(Map) for an explanation why this method is named separately and distinctly.

    • getUri

      public URI getUri()
      Specified by:
      getUri in interface jakarta.ws.rs.client.WebTarget

    • getUriBuilder

      public jakarta.ws.rs.core.UriBuilder getUriBuilder()
      Specified by:
      getUriBuilder in interface jakarta.ws.rs.client.WebTarget

    • path

      public WebTargetHelper path(String path)
      Specified by:
      path in interface jakarta.ws.rs.client.WebTarget

    • resolveTemplate

      public WebTargetHelper resolveTemplate(String name, Object value)
      Specified by:
      resolveTemplate in interface jakarta.ws.rs.client.WebTarget

    • resolveTemplate

      public WebTargetHelper resolveTemplate(String name, Object value, boolean encodeSlashInPath)
      Specified by:
      resolveTemplate in interface jakarta.ws.rs.client.WebTarget

    • resolveTemplateFromEncoded

      public WebTargetHelper resolveTemplateFromEncoded(String name, Object value)
      Specified by:
      resolveTemplateFromEncoded in interface jakarta.ws.rs.client.WebTarget

    • resolveTemplates

      public WebTargetHelper resolveTemplates(Map<String,Object> templateValues)
      Specified by:
      resolveTemplates in interface jakarta.ws.rs.client.WebTarget

    • resolveTemplates

      public WebTargetHelper resolveTemplates(Map<String,Object> templateValues, boolean encodeSlashInPath)
      Specified by:
      resolveTemplates in interface jakarta.ws.rs.client.WebTarget

    • resolveTemplatesFromEncoded

      public WebTargetHelper resolveTemplatesFromEncoded(Map<String,Object> templateValues)
      Specified by:
      resolveTemplatesFromEncoded in interface jakarta.ws.rs.client.WebTarget

    • matrixParam

      public WebTargetHelper matrixParam(String name, Object... values)
      Specified by:
      matrixParam in interface jakarta.ws.rs.client.WebTarget

    • queryParam

      public WebTargetHelper queryParam(String name, Object... values)
      Specified by:
      queryParam in interface jakarta.ws.rs.client.WebTarget

    • request

      public jakarta.ws.rs.client.Invocation.Builder request()
      Specified by:
      request in interface jakarta.ws.rs.client.WebTarget

    • request

      public jakarta.ws.rs.client.Invocation.Builder request(String... acceptedResponseTypes)
      Specified by:
      request in interface jakarta.ws.rs.client.WebTarget

    • request

      public jakarta.ws.rs.client.Invocation.Builder request(jakarta.ws.rs.core.MediaType... acceptedResponseTypes)
      Specified by:
      request in interface jakarta.ws.rs.client.WebTarget

    • getConfiguration

      public jakarta.ws.rs.core.Configuration getConfiguration()
      Specified by:
      getConfiguration in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>

    • property

      public WebTargetHelper property(String name, Object value)
      Specified by:
      property in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>

    • register

      public WebTargetHelper register(Class<?> componentClass)
      Specified by:
      register in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>

    • register

      public WebTargetHelper register(Class<?> componentClass, int priority)
      Specified by:
      register in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>

    • register

      public WebTargetHelper register(Class<?> componentClass, Class<?>... contracts)
      Specified by:
      register in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>

    • register

      public WebTargetHelper register(Class<?> componentClass, Map<Class<?>,Integer> contracts)
      Specified by:
      register in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>

    • register

      public WebTargetHelper register(Object component)
      Specified by:
      register in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>

    • register

      public WebTargetHelper register(Object component, int priority)
      Specified by:
      register in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>

    • register

      public WebTargetHelper register(Object component, Class<?>... contracts)
      Specified by:
      register in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>

    • register

      public WebTargetHelper register(Object component, Map<Class<?>,Integer> contracts)
      Specified by:
      register in interface jakarta.ws.rs.core.Configurable<jakarta.ws.rs.client.WebTarget>