<!--
/***************************************************************************************************************************
 * 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 can be applied to arguments of <ja>@RemoteMethod</ja>-annotated methods
	to denote that they are query parameters on the request.
</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#collectionFormat() collectionFormat} - How collections of items are formatted.
		<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#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#serializer() serializer} - Override the part serializer.
		<li class='jf'>{@link oaj.http.annotation.Query#skipIfEmpty() skipIfEmpty}- Don't add if value is null or empty.
		<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.
	</ul>
</ul>

<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@Remote</ja>(path=<js>"/myproxy"</js>)
	<jk>public interface</jk> MyProxy {
 
		<jc>// Explicit names specified for query parameters.</jc>
		<ja>@RemoteMethod</ja>
		String parameters(
			<ja>@Query</ja>(<js>"foo"</js>)</ja> String foo,
			<ja>@Query</ja>(<js>"bar"</js>)</ja> MyPojo pojo);
 
		<jc>// Multiple values pulled from a NameValuePairs object.</jc>
		<jc>// Same as @Query("*").</jc>
		<ja>@RemoteMethod</ja>
		String nameValuePairs(<ja>@Query</ja> NameValuePairs nameValuePairs);
 
		<jc>// Multiple values pulled from a Map.</jc>
		<jc>// Same as @Query("*").</jc>
		<ja>@RemoteMethod</ja>
		String map(<ja>@Query</ja> Map&lt;String,Object&gt; map);

		<jc>// Multiple values pulled from a bean.</jc>
		<jc>// Same as @Query("*").</jc>
		<ja>@RemoteMethod</ja>
		String bean(<ja>@Query</ja> MyBean myBean);

		<jc>// An entire query string as a String.</jc>
		<jc>// Same as @Query("*").</jc>
		<ja>@RemoteMethod</ja>
		String string(<ja>@Query</ja> String string);

		<jc>// An entire query string as a Reader.</jc>
		<jc>// Same as @Query("*").</jc>
		<ja>@RemoteMethod</ja>
		String reader(<ja>@Query</ja> Reader reader);
	}
</p>

<p>
	Single-part arguments (i.e. those with name != <js>"*"</js>) can be any of the following types:
</p>
<ul class='spaced-list'>
	<li>
		Any serializable POJO - Converted to a string using the {@link oaj.httppart.HttpPartSerializer} registered with the
		<c>RestClient</c> ({@link oaj.oapi.OpenApiSerializer} by default) or associated via the {@link oaj.http.annotation.Query#serializer() @Query(serializer)} annotation.
</ul>

<p>
	Multi-part arguments (i.e. those with name == <js>"*"</js> or empty) can be any of the following types:
</p>
<ul class='spaced-list'>
	<li>
		{@link java.io.Reader} - Raw contents of {@code Reader} will be serialized directly a query string.
	<li>
		<c>NameValuePairs</c> - Serialized as individual query parameters.
	<li>
		<c>Map</c> - Converted to key-value pairs.
			<br>Values serialized using the registered {@link oaj.httppart.HttpPartSerializer} ({@link oaj.oapi.OpenApiSerializer} by default).
	<li>
		Bean - Converted to key-value pairs.
			<br>Values serialized using the registered {@link oaj.httppart.HttpPartSerializer} ({@link oaj.oapi.OpenApiSerializer} by default).
	<li>
		<c>CharSequence</c> - Serialized directly a query string.
</ul>

<p>
	See the link below for information about supported data types in OpenAPI serialization.
</p>

<ul class='seealso'>
	<li class='link'>{@doc juneau-marshall.OpenApiDetails.Serializers}
</ul>