org.apache.juneau.rest

Class RequestQuery

java.lang.Object

java.util.AbstractMap<K,V>

java.util.HashMap<K,V>

java.util.LinkedHashMap<String,String[]>

org.apache.juneau.rest.RequestQuery

All Implemented Interfaces:

Serializable, Cloneable, Map<String,String[]>

public final class RequestQuery
extends LinkedHashMap<String,String[]>

Represents the query parameters in an HTTP request.

Similar in functionality to the ServletRequest.getParameter(String) except only looks in the URL string, not parameters from URL-Encoded FORM posts.
This can be useful in cases where you're using GET parameters on FORM POSTs, and you don't want the body of the request to be read.

• Overview > juneau-rest-server > @RestMethod > RequestQuery

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Method Summary

Modifier and Type	Method and Description
RequestQuery	addDefault(Map<String,Object> defaultEntries) Adds default entries to these query parameters.
RequestQuery	addDefault(String name, Object value) Adds a default entries to these query parameters.
boolean	containsAnyKeys(String... params) Returns true if the request contains any of the specified query parameters.
<T> T	get(HttpPartParser parser, HttpPartSchema schema, String name, Class<T> type) Same as get(String, Class) but allows you to override the part parser.
<T> T	get(HttpPartParser parser, HttpPartSchema schema, String name, T def, Class<T> type) Same as get(String, Object, Class) but allows you to override the part parser.
<T> T	get(HttpPartParser parser, HttpPartSchema schema, String name, T def, Type type, Type... args) Same as get(String, Object, Type, Type...) but allows you to override the part parser.
<T> T	get(HttpPartParser parser, HttpPartSchema schema, String name, Type type, Type... args) Same as get(String, Type, Type...) but allows you to override the part parser.
String[]	get(String name, boolean caseInsensitive) Same as LinkedHashMap.get(Object) but allows you to find the query parameter using a case-insensitive match.
<T> T	get(String name, Class<T> type) Returns the specified query parameter value converted to a POJO using the HttpPartParser registered with the resource.
<T> T	get(String name, T def, Class<T> type) Same as get(String, Class) except returns a default value if not found.
<T> T	get(String name, T def, Type type, Type... args) Same as get(String, Class) except returns a default value if not found.
<T> T	get(String name, Type type, Type... args) Returns the specified query parameter value converted to a POJO using the HttpPartParser registered with the resource.
<T> T	getAll(HttpPartParser parser, HttpPartSchema schema, String name, Type type, Type... args) Same as getAll(String, Type, Type...) but allows you to override the part parser.
<T> T	getAll(String name, Class<T> c) Same as get(String, Class) except for use on multi-part parameters (e.g.
<T> T	getAll(String name, Type type, Type... args) Same as get(String, Type, Type...) except for use on multi-part parameters (e.g.
boolean	getBoolean(String name) Same as getString(String) but converts the value to a boolean.
boolean	getBoolean(String name, boolean def) Same as getString(String,String) but converts the value to a boolean.
int	getInt(String name) Same as getString(String) but converts the value to an integer.
int	getInt(String name, int def) Same as getString(String,String) but converts the value to an integer.
SearchArgs	getSearchArgs() Locates the special search query arguments in the query and returns them as a SearchArgs object.
String	getString(String name) Returns a query parameter value as a string.
String	getString(String name, boolean caseInsensitive) Same as getString(String) but allows you to search for the query parameter using case-insensitive matching.
String	getString(String name, String def) Same as getString(String) but returns the specified default value if the query parameter was not specified.
boolean	hasAny(String... paramNames) Returns true if the query parameters contains any of the specified names.
void	put(String name, Object value) Sets a request query parameter value.
String	toQueryString() Converts this object to a query string.
String	toString()
String	toString(boolean sorted) Converts the query parameters to a readable string.

Methods inherited from class java.util.LinkedHashMap

clear, containsValue, entrySet, forEach, get, getOrDefault, keySet, removeEldestEntry, replaceAll, values

Methods inherited from class java.util.HashMap

clone, compute, computeIfAbsent, computeIfPresent, containsKey, isEmpty, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, size

Methods inherited from class java.util.AbstractMap

equals, hashCode

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, containsKey, equals, hashCode, isEmpty, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, size

Method Detail

addDefault

public RequestQuery addDefault(Map<String,Object> defaultEntries)

Adds default entries to these query parameters.

This includes the default queries defined at the resource and method levels.

Parameters:

defaultEntries - The default entries.
Can be null.

Returns:

This object (for method chaining).

addDefault

public RequestQuery addDefault(String name,
                               Object value)

Adds a default entries to these query parameters.

Similar to put(String, Object) but doesn't override existing values.

Parameters:

name - The query parameter name.

value - The query parameter value.
Converted to a String using toString().
Ignored if value is null or blank.

Returns:

This object (for method chaining).

get

public String[] get(String name,
                    boolean caseInsensitive)

Same as LinkedHashMap.get(Object) but allows you to find the query parameter using a case-insensitive match.

Parameters:

name - The query parameter name.

caseInsensitive - If true use case-insensitive matching on the query parameter name.

Returns:

The resolved entry, or null if not found.

put

public void put(String name,
                Object value)

Sets a request query parameter value.

This overwrites any existing value.

Parameters:

name - The parameter name.

value - The parameter value.
Can be null.

getString

public String getString(String name)

Returns a query parameter value as a string.

If multiple query parameters have the same name, this returns only the first instance.

Parameters:

name - The URL parameter name.

Returns:

The parameter value, or null if parameter not specified or has no value (e.g. "&foo").

getString

public String getString(String name,
                        boolean caseInsensitive)

Same as getString(String) but allows you to search for the query parameter using case-insensitive matching.

If multiple query parameters have the same name, this returns only the first instance.

Parameters:

name - The URL parameter name.

caseInsensitive - If true use case insensitive matching on the query parameter name.

Returns:

The parameter value, or null if parameter not specified or has no value (e.g. "&foo").

getString

public String getString(String name,
                        String def)

Same as getString(String) but returns the specified default value if the query parameter was not specified.

Parameters:

name - The URL parameter name.

def - The default value.

Returns:

The parameter value, or the default value if parameter not specified or has no value (e.g. "&foo").

getInt

public int getInt(String name)

Same as getString(String) but converts the value to an integer.

Parameters:

name - The URL parameter name.

Returns:

The parameter value, or 0 if parameter not specified or has no value (e.g. "&foo").

getInt

public int getInt(String name,
                  int def)

Same as getString(String,String) but converts the value to an integer.

Parameters:

name - The URL parameter name.

def - The default value.

Returns:

The parameter value, or the default value if parameter not specified or has no value (e.g. "&foo").

getBoolean

public boolean getBoolean(String name)

Same as getString(String) but converts the value to a boolean.

Parameters:

name - The URL parameter name.

Returns:

The parameter value, or false if parameter not specified or has no value (e.g. "&foo").

getBoolean

public boolean getBoolean(String name,
                          boolean def)

Same as getString(String,String) but converts the value to a boolean.

Parameters:

name - The URL parameter name.

def - The default value.

Returns:

The parameter value, or the default value if parameter not specified or has no value (e.g. "&foo").

get

public <T> T get(String name,
                 Class<T> type)
          throws BadRequest,
                 InternalServerError

Returns the specified query parameter value converted to a POJO using the HttpPartParser registered with the resource.

Examples:

// Parse into an integer. int myparam = query.get("myparam", int.class); // Parse into an int array. int[] myparam = query.get("myparam", int[].class); // Parse into a bean. MyBean myparam = query.get("myparam", MyBean.class); // Parse into a linked-list of objects. List myparam = query.get("myparam", LinkedList.class); // Parse into a map of object keys/values. Map myparam = query.get("myparam", TreeMap.class);

• RestContext.REST_partParser

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

name - The parameter name.

type - The class type to convert the parameter value to.

Returns:

The parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed.

InternalServerError - Thrown if any other exception occurs.

get

public <T> T get(HttpPartParser parser,
                 HttpPartSchema schema,
                 String name,
                 Class<T> type)
          throws BadRequest,
                 InternalServerError

Same as get(String, Class) but allows you to override the part parser.

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

parser - The parser to use for parsing the string value.
If null, uses the part parser defined on the resource/method.

schema - The schema object that defines the format of the input.
If null, defaults to the schema defined on the parser.
If that's also null, defaults to HttpPartSchema.DEFAULT.
Only used if parser is schema-aware (e.g. OpenApiParser).

name - The parameter name.

type - The class type to convert the parameter value to.

Returns:

The parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed or fails schema validation.

InternalServerError - Thrown if any other exception occurs.

get

public <T> T get(String name,
                 T def,
                 Class<T> type)
          throws BadRequest,
                 InternalServerError

Same as get(String, Class) except returns a default value if not found.

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

name - The parameter name.

def - The default value if the parameter was not specified or is null.

type - The class type to convert the parameter value to.

Returns:

The parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed.

InternalServerError - Thrown if any other exception occurs.

get

public <T> T get(HttpPartParser parser,
                 HttpPartSchema schema,
                 String name,
                 T def,
                 Class<T> type)
          throws BadRequest,
                 InternalServerError

Same as get(String, Object, Class) but allows you to override the part parser.

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

parser - The parser to use for parsing the string value.
If null, uses the part parser defined on the resource/method.

schema - The schema object that defines the format of the input.
If null, defaults to the schema defined on the parser.
If that's also null, defaults to HttpPartSchema.DEFAULT.
Only used if parser is schema-aware (e.g. OpenApiParser).

name - The parameter name.

def - The default value if the parameter was not specified or is null.

type - The class type to convert the parameter value to.

Returns:

The parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed or fails schema validation.

InternalServerError - Thrown if any other exception occurs.

get

public <T> T get(String name,
                 Type type,
                 Type... args)
          throws BadRequest,
                 InternalServerError

Returns the specified query parameter value converted to a POJO using the HttpPartParser registered with the resource.

Similar to get(String,Class) but allows for complex collections of POJOs to be created.

Examples:

// Parse into a linked-list of strings. List<String> myparam = query.get("myparam", LinkedList.class, String.class); // Parse into a linked-list of linked-lists of strings. List<List<String>> myparam = query.get("myparam", LinkedList.class, LinkedList.class, String.class); // Parse into a map of string keys/values. Map<String,String> myparam = query.get("myparam", TreeMap.class, String.class, String.class); // Parse into a map containing string keys and values of lists containing beans. Map<String,List<MyBean>> myparam = query.get("myparam", TreeMap.class, String.class, List.class, MyBean.class);

• Collections must be followed by zero or one parameter representing the value type.
• Maps must be followed by zero or two parameters representing the key and value types.

• RestContext.REST_partParser

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

name - The parameter name.

type - The type of object to create.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType

args - The type arguments of the class if it's a collection or map.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
Ignored if the main type is not a map or collection.

Returns:

The parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed.

InternalServerError - Thrown if any other exception occurs.

get

public <T> T get(HttpPartParser parser,
                 HttpPartSchema schema,
                 String name,
                 Type type,
                 Type... args)
          throws BadRequest,
                 InternalServerError

Same as get(String, Type, Type...) but allows you to override the part parser.

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

parser - The parser to use for parsing the string value.
If null, uses the part parser defined on the resource/method.

schema - The schema object that defines the format of the input.
If null, defaults to the schema defined on the parser.
If that's also null, defaults to HttpPartSchema.DEFAULT.
Only used if parser is schema-aware (e.g. OpenApiParser).

name - The parameter name.

type - The type of object to create.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType

args - The type arguments of the class if it's a collection or map.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
Ignored if the main type is not a map or collection.

Returns:

The parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed or fails schema validation.

InternalServerError - Thrown if any other exception occurs.

get

public <T> T get(String name,
                 T def,
                 Type type,
                 Type... args)
          throws BadRequest,
                 InternalServerError

Same as get(String, Class) except returns a default value if not found.

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

name - The parameter name.

type - The type of object to create.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType

args - The type arguments of the class if it's a collection or map.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
Ignored if the main type is not a map or collection.

def - The default value if the parameter was not specified or is null.

Returns:

The parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed.

InternalServerError - Thrown if any other exception occurs.

get

public <T> T get(HttpPartParser parser,
                 HttpPartSchema schema,
                 String name,
                 T def,
                 Type type,
                 Type... args)
          throws BadRequest,
                 InternalServerError

Same as get(String, Object, Type, Type...) but allows you to override the part parser.

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

parser - The parser to use for parsing the string value.
If null, uses the part parser defined on the resource/method.

schema - The schema object that defines the format of the input.
If null, defaults to the schema defined on the parser.
If that's also null, defaults to HttpPartSchema.DEFAULT.
Only used if parser is schema-aware (e.g. OpenApiParser).

name - The parameter name.

type - The type of object to create.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType

args - The type arguments of the class if it's a collection or map.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
Ignored if the main type is not a map or collection.

def - The default value if the parameter was not specified or is null.

Returns:

The parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed or fails schema validation.

InternalServerError - Thrown if any other exception occurs.

getAll

public <T> T getAll(String name,
                    Class<T> c)
             throws BadRequest,
                    InternalServerError

Same as get(String, Class) except for use on multi-part parameters (e.g. "&key=1&key=2&key=3" instead of "&key=@(1,2,3)").

This method must only be called when parsing into classes of type Collection or array.

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

name - The query parameter name.

c - The class type to convert the parameter value to.

Returns:

The query parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed.

InternalServerError - Thrown if any other exception occurs.

getAll

public <T> T getAll(String name,
                    Type type,
                    Type... args)
             throws BadRequest,
                    InternalServerError

Same as get(String, Type, Type...) except for use on multi-part parameters (e.g. "&key=1&key=2&key=3" instead of "&key=@(1,2,3)").

This method must only be called when parsing into classes of type Collection or array.

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

name - The query parameter name.

type - The type of object to create.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType

args - The type arguments of the class if it's a collection or map.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
Ignored if the main type is not a map or collection.

Returns:

The query parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed.

InternalServerError - Thrown if any other exception occurs.

getAll

public <T> T getAll(HttpPartParser parser,
                    HttpPartSchema schema,
                    String name,
                    Type type,
                    Type... args)
             throws BadRequest,
                    InternalServerError

Same as getAll(String, Type, Type...) but allows you to override the part parser.

Type Parameters:

T - The class type to convert the parameter value to.

Parameters:

parser - The parser to use for parsing the string value.
If null, uses the part parser defined on the resource/method.

schema - The schema object that defines the format of the input.
If null, defaults to the schema defined on the parser.
If that's also null, defaults to HttpPartSchema.DEFAULT.
Only used if parser is schema-aware (e.g. OpenApiParser).

name - The query parameter name.

type - The type of object to create.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType

args - The type arguments of the class if it's a collection or map.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
Ignored if the main type is not a map or collection.

Returns:

The query parameter value converted to the specified class type.

Throws:

BadRequest - Thrown if input could not be parsed or fails schema validation.

InternalServerError - Thrown if any other exception occurs.

containsAnyKeys

public boolean containsAnyKeys(String... params)

Returns true if the request contains any of the specified query parameters.

Parameters:

params - The list of parameters to check for.

Returns:

true if the request contains any of the specified query parameters.

getSearchArgs

public SearchArgs getSearchArgs()

Locates the special search query arguments in the query and returns them as a SearchArgs object.

The query arguments are as follows:

• "&s=" - A comma-delimited list of column-name/search-token pairs.
  Example: "&s=column1=foo*,column2=*bar"
• "&v=" - A comma-delimited list column names to view.
  Example: "&v=column1,column2"
• "&o=" - A comma-delimited list column names to sort by.
  Column names can be suffixed with '-' to indicate descending order.
  Example: "&o=column1,column2-"
• "&p=" - The zero-index row number of the first row to display.
  Example: "&p=100"
• "&l=" - The number of rows to return.
  0 implies return all rows.
  Example: "&l=100"
• "&i=" - The case-insensitive search flag.
  Example: "&i=true"

• Whitespace is trimmed in the parameters.

Returns:

A new SearchArgs object initialized with the special search query arguments.
Returns null if no search arguments were found.

hasAny

public boolean hasAny(String... paramNames)

Returns true if the query parameters contains any of the specified names.

Parameters:

paramNames - The parameter names to check for.

Returns:

true if the query parameters contains any of the specified names.

toString

public String toString(boolean sorted)

Converts the query parameters to a readable string.

Parameters:

sorted - Sort the query parameters by name.

Returns:

A JSON string containing the contents of the query parameters.

toQueryString

public String toQueryString()

Converts this object to a query string.

Returned query string does not start with '?'.

Returns:

A new query string, or an empty string if this object is empty.

toString

public String toString()

Overrides:

toString in class AbstractMap<String,String[]>