@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.

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:

Example:

@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.

Examples:

// 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 OpenApiParsers 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.

Examples:

// 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 RestSvlVariables} (e.g. "$L{my.localized.variable}") are supported on annotation fields.

Example:

@Query( description="$L{PetNameDescription}" )