Package io.grpc

Class QueryParams

  • @Internal
public final class QueryParams
extends Object
    A parser and mutable container class for application/x-www-form-urlencoded-style URL parameters as conceived by RFC 1866 Section 8.2.1.

    For example, a URI like "http://who?name=John+Doe&role=admin&role=user&active" has:

    • A key name with value John Doe
    • A key role with value admin
    • A second key named role with value user
    • "Lone" key active without a value.

    This class is meant to be used with Uri. For example: 

    
 Uri uri = Uri.parse("http://who?name=John+Doe&role=admin&role=user&active");
 QueryParams params = QueryParams.fromRawQuery(uri.getRawQuery());
 params.asList().removeIf(e -> "role".equals(e.getKey()) && "admin".equals(e.getValue()));

 Uri modifiedUri = uri.toBuilder().setRawQuery(params.toRawQuery()).build();

    Note that the empty collection is encoded as a null raw query string, which means "absent" to Uri.Builder.setRawQuery(java.lang.String). An empty string query component (""), on the other hand, is modeled as an instance of QueryParams containing a single lone (empty) key. It must be this way if we are to simultaneously 1) support lone keys, 2) have parse/toRawQuery round-trip transparency, and 3) never fail to parse a valid RFC 3986 query component.

    This container and its QueryParams.Entry take the same position as Uri on equality: raw keys and values must match exactly to be equal. Most callers won't care about how keys and values are encoded on the wire and will work with the getters for cooked keys and values instead.

    Instances are not safe for concurrent access by multiple threads, including by way of the asList() view method.

    • Constructor Detail

      • QueryParams

        public QueryParams()
        Creates a new, empty QueryParams instance.

    • Method Detail

      • fromRawQuery

        public static QueryParams fromRawQuery​(@Nullable
                                       String rawQuery)
        Parses a raw query string into a QueryParams instance.

        The input is split on '&' and each parameter is parsed as either a key/value pair (if it contains an equals sign) or a "lone" key (if it does not).

        No valid RFC 3986 query component will fail to parse. For example, === is parsed as a single parameter with "" as the key and "==" as the value. &&& is parsed as three lone keys named "". And so on. If rawQuery is not a valid RFC 3986 query component, the behavior is undefined. But if you are starting with a Uri, passing the value returned by Uri.getRawQuery() is always well-defined and will never fail.

        Calling toRawQuery() on the returned object is guaranteed to return exactly rawQuery.

        Parameters:
        rawQuery - the raw query component to parse, or null to return an empty container
        Returns:
        a new instance of QueryParams representing the input

      • asList

        public List<QueryParams.Entry> asList()
        Returns a mutable list view of the query parameters.
        Returns:
        the mutable list of entries

      • toRawQuery

        @Nullable
public String toRawQuery()
        Returns the "raw" query string representation of these parameters, suitable for passing to the Uri.Builder.setRawQuery(java.lang.String) method.
        Returns:
        the raw query string

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object