@Query
The {@link oaj.http.annotation.Query @Query} annotation is used to retrieve request URL query parameters.
It's identical to {@link oaj.http.annotation.FormData @FormData}, but only retrieves the parameter from the URL string, not URL-encoded form posts.
- {@link oaj.http.annotation.Query}
- {@link oaj.http.annotation.Query#_default() _default} - Default value if not present.
- {@link oaj.http.annotation.Query#_enum() _enum} - Input validation. Must match one of the values.
- {@link oaj.http.annotation.Query#allowEmptyValue() allowEmptyValue} - Input validation. Allow empty value.
- {@link oaj.http.annotation.Query#api() api} - Free-form Swagger JSON.
- {@link oaj.http.annotation.Query#collectionFormat() collectionFormat} - How collections of items are formatted.
- {@link oaj.http.annotation.Query#description() description} - Description.
- {@link oaj.http.annotation.Query#example() example} - Serialized example.
- {@link oaj.http.annotation.Query#exclusiveMaximum() exclusiveMaximum} - Input validation. Whether maximum is exclusive.
- {@link oaj.http.annotation.Query#exclusiveMinimum() exclusiveMinimum} - Input validation. Whether minimum is exclusive.
- {@link oaj.http.annotation.Query#format() format} - The schema type format.
- {@link oaj.http.annotation.Query#items() items} - The schema of items in a collection.
- {@link oaj.http.annotation.Query#maximum() maximum} - Input validation. Maximum numeric value.
- {@link oaj.http.annotation.Query#maxItems() maxItems} - Input validation. Maximum number of items in a collection.
- {@link oaj.http.annotation.Query#maxLength() maxLength} - Input validation. Maximum length of a string.
- {@link oaj.http.annotation.Query#minimum() minimum} - Input validation. Minimum numeric value.
- {@link oaj.http.annotation.Query#minItems() minItems} - Input validation. Minimum number of items in a collection.
- {@link oaj.http.annotation.Query#minLength() minLength} - Input validation. Minimum length of a string.
- {@link oaj.http.annotation.Query#multipleOf() multipleOf} - Input validation. Number must be a multiple of.
- {@link oaj.http.annotation.Query#name() name} - Query parameter name.
- {@link oaj.http.annotation.Query#parser() parser} - Override the part parser.
- {@link oaj.http.annotation.Query#pattern() pattern} - Input validation. Must match regular expression.
- {@link oaj.http.annotation.Query#required() required} - Input validation. Query parameter must be present.
- {@link oaj.http.annotation.Query#type() type} - The schema type.
- {@link oaj.http.annotation.Query#uniqueItems() uniqueItems} - Input validation. Collections must contain unique items only.
- {@link oaj.http.annotation.Query#value() value} - Free-form Swagger JSON.
Unlike {@link oaj.http.annotation.FormData @FormData}, using this annotation does not result in the servlet reading the contents of
URL-encoded form posts.
Therefore, this annotation can be used in conjunction with the {@link oaj.http.annotation.Body @Body} annotation or
{@link oajr.RestRequest#getBody()} method for application/x-www-form-urlencoded POST calls.
The most typical scenario is to simply use the value field to define query parameter names:
@RestMethod(name=GET)
public void doGet(
@Query("p1") int p1,
@Query("p2") String p2,
@Query("p3") UUID p3) {...}
This is functionally equivalent to the following code:
@RestMethod(name=GET)
public void doGet(RestRequest req) {
RequestQuery q = req.getQuery();
int p1 = q.get("p1", 0, int.class);
String p2 = q.get("p2", String.class);
UUID p3 = q.get("p3", UUID.class);
}
The special name "*" (or blank) can be used to represent all values.
When used, the data type must be a Map or bean.
// Multiple values passed as a map.
@RestMethod(name=GET)
public void doGet(@Query("*") Map<String,Object> map) {...}
// Same, but name "*" is inferred.
@RestMethod(name=GET)
public void doGet(@Query Map<String,Object> map) {...}
// Multiple values passed as a bean.
@RestMethod(name=GET)
public void doGet(@Query MyBean bean) {...}
The registered {@link oajr.RestContext#REST_partParser REST_partParser} is used to convert strings
to POJOs and controls what POJO types are supported.
By default, this is the {@link oaj.oapi.OpenApiParser} which supports the standard Swagger-based rules for parsing.
For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") can be converted to a 2-dimensional array of Longs:
@RestMethod(method="GET", path="/testQuery")
public void testQuery(
@Query(
name="queryParamName",
collectionFormat="pipes",
items=@SubItems(
collectionFormat="csv",
type="integer",
format="int64",
minimum="0",
maximum="100"
minLength=1,
maxLength=10
),
minLength=1,
maxLength=10
)
Long[][] queryParameter
) {...}
Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.
For more information about valid parameter types, see {@doc juneau-marshall.OpenApiDetails.Parsers OpenAPI Parsers}
The @Query annotation is also used for supplying swagger information about the HTTP part.
This information is used to populate the auto-generated Swagger documentation and UI.
// Normal
@Query(
name="name",
description="Pet name",
required=true,
example="Doggie"
)
// Free-form
// Note the extra field
@Query(
name="name",
api={
"description: 'Pet name',",
"required: true,",
"example: 'Doggie',"
"x-extra: 'extra field'"
}
)
{@doc DefaultRestSvlVariables} (e.g. "$L{my.localized.variable}")
are supported on annotation fields.
@Query(
description="$L{PetNameDescription}"
)
- {@link oajr.RequestQuery}
- {@doc juneau-rest-server.OpenApiSchemaPartParsing}