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. 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): 

     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

      • toWebTarget

        public javax.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​(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 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:
        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:
        this instance

      • queryParamFilterNotNull

        public WebTargetHelper queryParamFilterNotNull​(String name,
                                               List<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:
        this instance

      • queryParamFilterNotNull

        public WebTargetHelper queryParamFilterNotNull​(String name,
                                               Stream<Object> 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:
        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:
        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:
        this instance

      • queryParamFilterNotBlank

        public WebTargetHelper queryParamFilterNotBlank​(String name,
                                                List<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:
        this instance

      • queryParamFilterNotBlank

        public WebTargetHelper queryParamFilterNotBlank​(String name,
                                                Stream<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:
        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:
        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​(javax.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 representing the query parameters
        Returns:
        this instance
        Implementation Note:
        See implementation note on queryParamsFromMap(Map) for an explanation why this method is named separately and distinctly.