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

@Path

<p>
	The {@link oaj.http.annotation.Path @Path} annotation can be applied to arguments of <ja>@RemoteMethod</ja>-annotated methods
	to denote that they are path parameters on the request.
</p>
<ul class='javatree'>
	<li class='ja'>{@link oaj.http.annotation.Path}
	<ul>
		<li class='jf'>{@link oaj.http.annotation.Path#_enum() _enum} - Input validation.  Must match one of the values.
		<li class='jf'>{@link oaj.http.annotation.Path#allowEmptyValue() allowEmptyValue} - Input validation.  Allow empty value.
		<li class='jf'>{@link oaj.http.annotation.Path#collectionFormat() collectionFormat} - How collections of items are formatted.
		<li class='jf'>{@link oaj.http.annotation.Path#exclusiveMaximum() exclusiveMaximum} - Input validation.  Whether maximum is exclusive.
		<li class='jf'>{@link oaj.http.annotation.Path#exclusiveMinimum() exclusiveMinimum} - Input validation.  Whether minimum is exclusive.
		<li class='jf'>{@link oaj.http.annotation.Path#format() format} - The schema type format. 
		<li class='jf'>{@link oaj.http.annotation.Path#items() items} - The schema of items in a collection.
		<li class='jf'>{@link oaj.http.annotation.Path#maximum() maximum} - Input validation.  Maximum numeric value. 
		<li class='jf'>{@link oaj.http.annotation.Path#maxLength() maxLength} - Input validation.  Maximum length of a string.
		<li class='jf'>{@link oaj.http.annotation.Path#minimum() minimum} - Input validation.  Minimum numeric value.
		<li class='jf'>{@link oaj.http.annotation.Path#minLength() minLength} - Input validation.  Minimum length of a string.
		<li class='jf'>{@link oaj.http.annotation.Path#multipleOf() multipleOf} - Input validation.  Number must be a multiple of.
		<li class='jf'>{@link oaj.http.annotation.Path#name() name} - Path variable name.
		<li class='jf'>{@link oaj.http.annotation.Path#pattern() pattern} - Input validation.  Must match regular expression.
		<li class='jf'>{@link oaj.http.annotation.Path#serializer() serializer} - Override the part serializer.
		<li class='jf'>{@link oaj.http.annotation.Path#type() type} - The schema type.
	</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 path parameters.</jc>
		<jc>// pojo will be converted to UON notation (unless plain-text parts enabled).</jc>
		<ja>@RemoteMethod</ja>(path=<js>"/mymethod1/{foo}/{bar}"</js>)
		String myProxyMethod1(<ja>@Path</ja>(<js>"foo"</js>)</ja> String foo, <ja>@Path</ja>(<js>"bar"</js>)</ja> MyPojo pojo);

		<jc>// Multiple values pulled from a NameValuePairs object.</jc>
		<jc>// Same as @Path("*").</jc>
		<ja>@RemoteMethod</ja>(path=<js>"/mymethod2/{foo}/{bar}/{baz}"</js>)
		String myProxyMethod2(<ja>@Path</ja> NameValuePairs nameValuePairs);

		<jc>// Multiple values pulled from a Map.</jc>
		<jc>// Same as @Path("*").</jc>
		<ja>@RemoteMethod</ja>(path=<js>"/mymethod3/{foo}/{bar}/{baz}"</js>)
		String myProxyMethod3(<ja>@Path</ja> Map&lt;String,Object&gt; map);

		<jc>// Multiple values pulled from a bean.</jc>
		<jc>// Same as @Path("*").</jc>
		<ja>@RemoteMethod</ja>(path=<js>"/mymethod4/{foo}/{bar}/{baz}"</js>)
		String myProxyMethod4(<ja>@Path</ja> MyBean myBean);
	}
</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.Path#serializer() @Path(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>
		<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).
</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>