Package org.kiwiproject.jaxrs.client

Class WebTargetHelper

  • @Beta
public class WebTargetHelper
extends Object
    Use with JAX-RS WebTarget instances to provide convenient functionality when adding query parameters.

    Usage example (assuming withClient is statically imported): 

     withClient(client).target("/search")
         .queryParamRequireNotBlank("q", query)
         .queryParamIfNotBlank("sort", sort)
         .queryParamIfNotBlank("page", page)
         .queryParamIfNotBlank("limit", limit)
         .queryParamFilterNotBlank("langs", langs);

    Limitations

    This is a limited wrapper around WebTarget that provides enhanced functionality only for adding query parameters. Only the methods defined in this class are chainable, i.e. once you call a method defined in the regular Client interface, you leave the WebTargetHelper context.

    For example you can NOT do this: 

     withClient(client).target("/search")
         .queryParamRequireNotBlank("q", query)
         .queryParam("sort", sort)  // after this, only Client methods are accessible!!! WON'T COMPILE
         .queryParamIfNotBlank("page", page)
         .queryParamIfNotBlank("limit", limit)
         .queryParamFilterNotBlank("langs", langs);
    With the current basic implementation, this means certain usages will be awkward. For example, when using both parameter templates and query parameters, the query parameters need to be added first, for the reason given above about leaving the WebTargetHelper context. For example: 
     var response = withClient(client).target("/users/{userId}/trades/{tradeId}")
         .queryParamIfNotBlank("displayCurrency", currency)
         .queryParamIfNotNull("showLimitPrice", showLimitPrice)
         .resolveTemplate("userId", userId)  // after this, only Client methods are accessible!!!
         .resolveTemplate("tradeId", tradeId)
         .request()
         .get();
    One way to get around this restriction is to use methods from WebTarget as normal, and then wrap it with a WebTargetHelper to add query parameters. The above example would then look like: 
     var pathResolvedTarget = client.target("/users/{userId}/trades/{tradeId}")
         .resolveTemplate("userId", userId)
         .resolveTemplate("tradeId", tradeId);

 var response = withWebTarget(pathResolvedTarget)
         .queryParamIfNotBlank("displayCurrency", currency)
         .queryParamIfNotNull("showLimitPrice", showLimitPrice)
         .request()
         .get();
    This usage allows for full functionality of WebTarget while still getting the enhanced query parameter features of this class. It isn't perfect but it works and, in our opinion anyway, doesn't intrude too much on building JAX-RS requests. In other words, we think it is a decent trade off.
    Implementation Note:
    Internally this uses Lombok's Delegate, which is why this class doesn't implement WebTarget directly. While this lets us easily delegate method calls to a WebTarget, it also restricts what we can do here, and is the primary reason why there are usage restrictions. However, in our general usage this implementation has been enough for our needs. Nevertheless this is currently marked with the Guava Beta annotation in case we change our minds on the implementation.

    • Method Detail

      • withWebTarget

        public static WebTargetHelper withWebTarget​(javax.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:
        this instance
        Throws:
        IllegalArgumentException - if value is null

      • queryParamIfNotNull

        public WebTargetHelper queryParamIfNotNull​(String name,
                                           Object value)
        Add the given query parameter only if it is not null.
        Parameters:
        name - the parameter name
        value - the parameter value
        Returns:
        this instance

      • queryParamFilterNotNull

        public WebTargetHelper queryParamFilterNotNull​(String name,
                                               Object... values)
        Adds any non-null values to the the given query parameter.
        Parameters:
        name - the parameter name
        values - one or more parameter values
        Returns:
        this instance

      • queryParamFilterNotNull

        public WebTargetHelper queryParamFilterNotNull​(String name,
                                               List<Object> values)
        Adds any non-null values to the the given query parameter.
        Parameters:
        name - the parameter name
        values - one or more parameter values
        Returns:
        this instance

      • queryParamFilterNotNull

        public WebTargetHelper queryParamFilterNotNull​(String name,
                                               Stream<Object> stream)
        Adds any non-null values to the the given query parameter.
        Parameters:
        name - the parameter name
        stream - containing one or more parameter values
        Returns:
        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 value is blank

      • queryParamIfNotBlank

        public WebTargetHelper queryParamIfNotBlank​(String name,
                                            String value)
        Add the given query parameter only if it is not blank.
        Parameters:
        name - the parameter name
        value - the parameter value
        Returns:
        this instance

      • queryParamFilterNotBlank

        public WebTargetHelper queryParamFilterNotBlank​(String name,
                                                String... values)
        Adds any non-blank values to the the given query parameter.
        Parameters:
        name - the parameter name
        values - one or more parameter values
        Returns:
        this instance

      • queryParamFilterNotBlank

        public WebTargetHelper queryParamFilterNotBlank​(String name,
                                                List<String> values)
        Adds any non-blank values to the the given query parameter.
        Parameters:
        name - the parameter name
        values - one or more parameter values
        Returns:
        this instance

      • queryParamFilterNotBlank

        public WebTargetHelper queryParamFilterNotBlank​(String name,
                                                Stream<String> stream)
        Adds any non-blank values to the the given query parameter.
        Parameters:
        name - the parameter name
        stream - containing one or more parameter values
        Returns:
        this instance

      • queryParams

        public WebTargetHelper queryParams​(Map<String,​Object> parameters)
        Adds non-null query parameters from the given map. All map keys must be non-null.
        Parameters:
        parameters - a map representing the query parameters
        Returns:
        this instance

      • queryParams

        public WebTargetHelper queryParams​(javax.ws.rs.core.MultivaluedMap<String,​Object> parameters)
        Adds non-null query parameters from the given multivalued map. All map keys must be non-null.
        Parameters:
        parameters - a multivalued representing the query parameters
        Returns:
        this instance