<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

@Query

<p>
	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.
</p>
<ul class='javatree'>
	<li class='ja'>{@link oaj.http.annotation.Query}
	<ul>
		<li class='jf'>{@link oaj.http.annotation.Query#_default() _default} - Default value if not present.
		<li class='jf'>{@link oaj.http.annotation.Query#_enum() _enum} - Input validation.  Must match one of the values.
		<li class='jf'>{@link oaj.http.annotation.Query#allowEmptyValue() allowEmptyValue} - Input validation.  Allow empty value.
		<li class='jf'>{@link oaj.http.annotation.Query#api() api} - Free-form Swagger JSON.
		<li class='jf'>{@link oaj.http.annotation.Query#collectionFormat() collectionFormat} - How collections of items are formatted.
		<li class='jf'>{@link oaj.http.annotation.Query#description() description} - Description.
		<li class='jf'>{@link oaj.http.annotation.Query#example() example} - Serialized example.
		<li class='jf'>{@link oaj.http.annotation.Query#exclusiveMaximum() exclusiveMaximum} - Input validation.  Whether maximum is exclusive.
		<li class='jf'>{@link oaj.http.annotation.Query#exclusiveMinimum() exclusiveMinimum} - Input validation.  Whether minimum is exclusive.
		<li class='jf'>{@link oaj.http.annotation.Query#format() format} - The schema type format. 
		<li class='jf'>{@link oaj.http.annotation.Query#items() items} - The schema of items in a collection.
		<li class='jf'>{@link oaj.http.annotation.Query#maximum() maximum} - Input validation.  Maximum numeric value. 
		<li class='jf'>{@link oaj.http.annotation.Query#maxItems() maxItems} - Input validation.  Maximum number of items in a collection.
		<li class='jf'>{@link oaj.http.annotation.Query#maxLength() maxLength} - Input validation.  Maximum length of a string.
		<li class='jf'>{@link oaj.http.annotation.Query#minimum() minimum} - Input validation.  Minimum numeric value.
		<li class='jf'>{@link oaj.http.annotation.Query#minItems() minItems} - Input validation.  Minimum number of items in a collection.
		<li class='jf'>{@link oaj.http.annotation.Query#minLength() minLength} - Input validation.  Minimum length of a string.
		<li class='jf'>{@link oaj.http.annotation.Query#multipleOf() multipleOf} - Input validation.  Number must be a multiple of.
		<li class='jf'>{@link oaj.http.annotation.Query#name() name} - Query parameter name.
		<li class='jf'>{@link oaj.http.annotation.Query#parser() parser} - Override the part parser.
		<li class='jf'>{@link oaj.http.annotation.Query#pattern() pattern} - Input validation.  Must match regular expression.
		<li class='jf'>{@link oaj.http.annotation.Query#required() required} - Input validation.  Query parameter must be present.
		<li class='jf'>{@link oaj.http.annotation.Query#type() type} - The schema type.
		<li class='jf'>{@link oaj.http.annotation.Query#uniqueItems() uniqueItems} - Input validation. Collections must contain unique items only.
		<li class='jf'>{@link oaj.http.annotation.Query#value() value} - Free-form Swagger JSON.
	</ul>
</ul>

<p>
	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 <c>application/x-www-form-urlencoded POST</c> calls.
</p>
<p>
	The most typical scenario is to simply use the <c>value</c> field to define query parameter names:
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>)
	<jk>public void</jk> doGet(
		<ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> p1, 
		<ja>@Query</ja>(<js>"p2"</js>) String p2, 
		<ja>@Query</ja>(<js>"p3"</js>) UUID p3) {...}
</p>
<p>
	This is functionally equivalent to the following code:
</p>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>)
	<jk>public void</jk> doGet(RestRequest req) {
		RequestQuery q = req.getQuery();
		<jk>int</jk> p1 = q.get(<js>"p1"</js>, 0, <jk>int</jk>.<jk>class</jk>);
		String p2 = q.get(<js>"p2"</js>, String.<jk>class</jk>);
		UUID p3 = q.get(<js>"p3"</js>, UUID.<jk>class</jk>);
	}
</p>


<p>
	The special name <js>"*"</js> (or blank) can be used to represent all values.
	When used, the data type must be a <c>Map</c> or bean.
</p>
<h5 class='figure'>Examples:</h5>
<p class='bpcode w800'>
	<jc>// Multiple values passed as a map.</jc>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>)
	<jk>public void</jk> doGet(<ja>@Query</ja>(<js>"*"</js>) Map&lt;String,Object&gt; map) {...}
</p>
<p class='bpcode w800'>
	<jc>// Same, but name "*" is inferred.</jc>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>)
	<jk>public void</jk> doGet(<ja>@Query</ja> Map&lt;String,Object&gt; map) {...}
</p>
<p class='bpcode w800'>
	<jc>// Multiple values passed as a bean.</jc>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>)
	<jk>public void</jk> doGet(<ja>@Query</ja> MyBean bean) {...}
</p>

<p>
	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.
</p>
<p>
	For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. <js>"1,2,3|4,5,6|7,8,9"</js>) can be converted to a 2-dimensional array of <c>Longs</c>:
</p>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(method=<js>"GET"</js>, path=<js>"/testQuery"</js>)	
	<jk>public void</jk> testQuery(
		<ja>@Query</ja>(
			name=<js>"queryParamName"</js>,
			collectionFormat=<js>"pipes"</js>,
			items=<ja>@SubItems</ja>(
				collectionFormat=<js>"csv"</js>,
				type=<js>"integer"</js>, 
				format=<js>"int64"</js>,
				minimum=<js>"0"</js>,
				maximum=<js>"100"</js>
				minLength=1,
				maxLength=10
			),
			minLength=1,
			maxLength=10
		)
		Long[][] queryParameter
	) {...}
</p>
<p>
	Input will be converted based on the types and formats defined in the schema definition.
	Input validations such as <c>minLength/maxLength</c> that don't match the input will result in automatic <c>400 Bad Request</c> responses.
</p>
<p>
	For more information about valid parameter types, see {@doc juneau-marshall.OpenApiDetails.Parsers OpenAPI Parsers}
</p>

<p>
	The <ja>@Query</ja> 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.
</p>
<h5 class='figure'>Examples:</h5>
<p class='bpcode w800'>
	<jc>// Normal</jc>
	<ja>@Query</ja>(
		name=<js>"name"</js>,
		description=<js>"Pet name"</js>,
		required=<jk>true</jk>,
		example=<js>"Doggie"</js>
	)
</p>
<p class='bpcode w800'>
	<jc>// Free-form</jc>
	<jc>// Note the extra field</jc>
	<ja>@Query</ja>(
		name=<js>"name"</js>,
		api={
			<js>"description: 'Pet name',"</js>,
			<js>"required: true,"</js>,
			<js>"example: 'Doggie',"</js>
			<js>"x-extra: 'extra field'"</js>
		}
	)
</p>
<p>
	{@doc DefaultRestSvlVariables} (e.g. "$L{my.localized.variable}")
	are supported on annotation fields.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@Query</ja>(
		description=<js>"$L{PetNameDescription}"</js>
	)
</p>


<ul class='seealso'>
	<li class='jc'>{@link oajr.RequestQuery}
	<li class='link'>{@doc juneau-rest-server.OpenApiSchemaPartParsing}
</ul>