<!--
/***************************************************************************************************************************
 * 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 is used to retrieve request path parameters.
</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#api() api} - Free-form Swagger JSON.
		<li class='jf'>{@link oaj.http.annotation.Path#collectionFormat() collectionFormat} - How collections of items are formatted.
		<li class='jf'>{@link oaj.http.annotation.Path#description() description} - Description.
		<li class='jf'>{@link oaj.http.annotation.Path#example() example} - Serialized example.
		<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#parser() parser} - Override the part parser.
		<li class='jf'>{@link oaj.http.annotation.Path#pattern() pattern} - Input validation.  Must match regular expression.
		<li class='jf'>{@link oaj.http.annotation.Path#type() type} - The schema type.
		<li class='jf'>{@link oaj.http.annotation.Path#value() value} - Free-form Swagger JSON.
	</ul>
</ul>
<p>
	The most typical scenario is to simply use the <c>value</c> field to define path parameter names:
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
	<jk>public void</jk> doGet(
			<ja>@Path</ja>(<js>"foo"</js>) String foo,
			<ja>@Path</ja>(<js>"bar"</js>) <jk>int</jk> bar,
			<ja>@Path</ja>(<js>"baz"</js>) UUID baz,
			<ja>@Path</ja>(<js>"/*"</js>) String remainder 
		) {...}
</p>
<p>
	This is functionally equivalent to the following code:
</p>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
	<jk>public void</jk> doGet(RestRequest req) {
		RequestPath p = req.getPathMatch();
		String foo = p.getString(<js>"foo"</js>);
		<jk>int</jk> bar = p.get(<js>"bar"</js>, <jk>int</jk>.<jk>class</jk>);
		UUID baz = p.get(<js>"baz"</js>, UUID.<jk>class</jk>);
		String remainder = p.getRemainder();
	}
</p>
<p>
	Note that the path variable name <js>"/*"</js> can be used to represent the remainder of the path match.
</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>, path=<js>"/{a}/{b}/{c}/*"</js>)
	<jk>public void</jk> doGet(<ja>@Path</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>, path=<js>"/{a}/{b}/{c}/*"</js>)
	<jk>public void</jk> doGet(<ja>@Path</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>, path=<js>"/{a}/{b}/{c}/*"</js>)
	<jk>public void</jk> doGet(<ja>@Path</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>"POST"</js>, path=<js>"/testPath/{pathParam}"</js>)	
	<jk>public void</jk> testPath(
		<ja>@Path</ja>(
			name=<js>"pathParam"</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[][] pathParameter
	) {...}
</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>@Path</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>@Path</ja>(
		name=<js>"name"</js>,
		description=<js>"Pet name"</js>,
		example=<js>"Doggie"</js>
	)
</p>
<p class='bpcode w800'>
	<jc>// Free-form</jc>
	<jc>// Note the extra field</jc>
	<ja>@Path</ja>(
		name=<js>"name"</js>,
		api={
			<js>"description: 'Pet name',"</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>@Path</ja>(
		description=<js>"$L{PetNameDescription}"</js>
	)
</p>

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