<!--
/***************************************************************************************************************************
 * 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.
 ***************************************************************************************************************************/
 -->

@Request

<p>
	The {@link oaj.http.annotation.Request @Request} annotation can be applied to a parameter interface type of a <ja>@RestMethod</ja>-annotated method 
	to identify it as an interface for retrieving HTTP parts through a bean-like interface.
</p>
<ul class='javatree'>
	<li class='ja'>{@link oaj.http.annotation.Request}
	<ul>
		<li class='jf'>{@link oaj.http.annotation.Request#partParser() partParser} - Override the part parser.
	</ul>
</ul>

<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(path=<js>"/pets/{petId}"</js>)
	<jk>public void</jk> putPet(UpdatePet updatePet) {...}

	<ja>@Request</ja>
	<jk>public interface</jk> UpdatePet {

		<ja>@Path</ja> 
		<jk>int</jk> getPetId();

		<ja>@Query</ja>(name=<js>"verbose"</js>)
		<jk>boolean</jk> isDebug();

		<ja>@Header</ja>(<js>"*"</js>)
		Map&lt;String,Object&gt; getAllHeaders();

		<ja>@Body</ja>
		Pet getPet();
	}
</p>
<p>
	The example above is identical in behavior to specifying individual annotated parameters on the <ja>@RestMethod</ja>-annotated method:
</p>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(path=<js>"/pets/{petId}"</js>)
	<jk>public void</jk> putPet(
		<ja>@Path</ja>(<js>"petId"</js>) <jk>int</jk> petId,
		<ja>@Query</ja>(<js>"verbose"</js>) <jk>boolean</jk> debug,
		<ja>@Header</ja>(<js>"*"</js>) Map&lt;String,Object&gt; allHeaders,
		<ja>@Body</ja> Pet pet
	) 
	{...}
</p>
<p>
	The return types of the getters must be the supported parameter types for the HTTP-part annotation used.
	Schema-based serialization and parsing is used just as if used as individual parameter types.
	Annotations used are the exact same used on REST parameters and have all the
	same feature support including automatic Swagger validation and documentation.  
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@Request</ja>
	<jk>public interface</jk> Request {

		<jc>// Schema-based query parameter:  Pipe-delimited lists of comma-delimited lists of integers.</jc>
		<ja>@Query</ja>(
			collectionFormat=<js>"pipes"</js>
			items=<ja>@Items</ja>(
				items=<ja>@SubItems</ja>(
					collectionFormat=<js>"csv"</js>
					type=<js>"integer"</js>,
					minimum=1,
					maximum=100
				),
				maximumLength=10
			)
		)
		<jk>int</jk>[][] getPipedCdlInts();
	}
</p>
<p>
	For clarity, the <ja>@Request</ja> annotation can be defined on the parameter, class, or both.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(path=<js>"/pets/{petId}"</js>)
	<jk>public void</jk> putPet(<ja>@Request</ja> UpdatePet updatePet) {...}

	<ja>@Request</ja>
	<jk>public interface</jk> UpdatePet {...}
</p>