juneau-doc/docs/Topics/07.juneau-rest-server/06.RestMethod/01.MethodParameters.html

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

Java Method Parameters

<p>
	Java methods can contain any of the following parameters in any order:
</p>
<ul class='spaced-list'>
	<li>
		<b>Parameters based on class types:</b>
		<ul class='spaced-list'>
			<li><b>Request/response objects:</b>
				<ul>
					<li class='jc'>{@link oajr.RestRequest} - The request object.
					<li class='jc'>{@link javax.servlet.http.HttpServletRequest} - The superclass of <c>RestRequest</c>.
					<li class='jc'>{@link oajr.RestResponse} - The response object.
					<li class='jc'>{@link javax.servlet.http.HttpServletResponse} - The superclass of <c>RestResponse</c>.
				</ul>
			<li><b>Parsed request header values:</b>
				<ul>
					<li class='jc'>{@link oaj.http.Accept}
					<li class='jc'>{@link oaj.http.AcceptCharset}
					<li class='jc'>{@link oaj.http.AcceptEncoding}
					<li class='jc'>{@link oaj.http.AcceptLanguage}
					<li class='jc'>{@link oaj.http.Authorization}
					<li class='jc'>{@link oaj.http.CacheControl}
					<li class='jc'>{@link oaj.http.Connection}
					<li class='jc'>{@link oaj.http.ContentLength}
					<li class='jc'>{@link oaj.http.ContentType}
					<li class='jc'>{@link oaj.http.Date}
					<li class='jc'>{@link oaj.http.Expect}
					<li class='jc'>{@link oaj.http.From}
					<li class='jc'>{@link oaj.http.Host}
					<li class='jc'>{@link oaj.http.IfMatch}
					<li class='jc'>{@link oaj.http.IfModifiedSince}
					<li class='jc'>{@link oaj.http.IfNoneMatch}
					<li class='jc'>{@link oaj.http.IfRange}
					<li class='jc'>{@link oaj.http.IfUnmodifiedSince}
					<li class='jc'>{@link oaj.http.MaxForwards}
					<li class='jc'>{@link oaj.http.Pragma}
					<li class='jc'>{@link oaj.http.ProxyAuthorization}
					<li class='jc'>{@link oaj.http.Range}
					<li class='jc'>{@link oaj.http.Referer}
					<li class='jc'>{@link oaj.http.TE}
					<li class='jc'>{@link oaj.http.UserAgent}
					<li class='jc'>{@link oaj.http.Upgrade}
					<li class='jc'>{@link oaj.http.Via}
					<li class='jc'>{@link oaj.http.Warning}
					<li class='jc'>{@link java.util.TimeZone}
				</ul>
			<li><b>Direct streams on request/response:</b>
				<ul>
					<li class='jc'>{@link java.io.InputStream}
					<li class='jc'>{@link javax.servlet.ServletInputStream}
					<li class='jc'>{@link java.io.Reader}
					<li class='jc'>{@link java.io.OutputStream}
					<li class='jc'>{@link javax.servlet.ServletOutputStream}
					<li class='jc'>{@link java.io.Writer}
				</ul>
			<li><b>Localization:</b>
				<ul>
					<li class='jc'>{@link java.util.ResourceBundle} - Client-localized resource bundle.
					<li class='jc'>{@link oaj.utils.MessageBundle} - A resource bundle with additional features.
					<li class='jc'>{@link java.util.Locale} - Client locale.
				</ul>
			<li><b>Request APIs:</b>
				<ul>
					<li class='jc'>{@link oajr.RequestHeaders} - API for accessing request headers.
					<li class='jc'>{@link oajr.RequestQuery} - API for accessing request query parameters.
					<li class='jc'>{@link oajr.RequestFormData} - API for accessing request form data.
					<li class='jc'>{@link oajr.RequestPath} - API for accessing path variables.
					<li class='jc'>{@link oajr.RequestBody} - API for accessing request body.
				</ul>
			<li><b>Other:</b>
				<ul>
					<li class='jc'>{@link oaj.http.HttpMethod} - The method name matched (when using <c><ja>@RestMethod</ja>(name=<js>"*"</js>)</c>)
					<li class='jc'>{@link oajr.RestLogger} - Logger with additional features.
					<li class='jc'>{@link oajr.RestContext} - The resource read-only context.
					<li class='jc'>{@link oaj.parser.Parser} - The parser matching the request content type.
					<li class='jc'>{@link oaj.parser.ReaderParser} - The reader parser matching the request content type.
					<li class='jc'>{@link oaj.parser.InputStreamParser} - The input stream parser matching the request content type.
					<li class='jc'>{@link oaj.dto.swagger.Swagger} - The auto-generated Swagger doc.
					<li class='jc'>{@link oaj.config.Config} - The external config for the resource.
					<li class='jc'>{@link oajr.RequestProperties} - API for modifying request-time configuration properties.
				</ul>
		</ul>
	<li><b>Annotated parameters:</b>
		<ul>
			<li class='ja'>{@link oaj.http.annotation.Path} - Variables in matched URL path patterns.
			<li class='ja'>{@link oaj.http.annotation.FormData} - Multipart form post parameter values.
			<li class='ja'>{@link oaj.http.annotation.HasFormData} - Denotes whether the form data parameter exists.
			<li class='ja'>{@link oaj.http.annotation.Query} - Query parameters.  Using this prevents the HTTP body from being processed as a URL-Encoded form post.
			<li class='ja'>{@link oaj.http.annotation.HasQuery} - Denotes whether the query parameter exists.
			<li class='ja'>{@link oaj.http.annotation.Header} - A header value.
			<li class='ja'>{@link oaj.http.annotation.Body} - The HTTP content parsed as a POJO.
			<li class='ja'>{@link oajr.annotation.Method} - The HTTP method name. 
			<li class='ja'>{@link oaj.http.annotation.Request} - HTTP request parts available through a proxy bean interface.
			<li class='ja'>{@link oaj.http.annotation.Response} - HTTP response parts available through a POJO.
			<li class='ja'>{@link oaj.http.annotation.ResponseHeader} - HTTP response header.
			<li class='ja'>{@link oaj.http.annotation.ResponseStatus} - HTTP response status code.
		</ul>
</ul>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/example1/{a1}/{a2}/{a3}/*"</js>)
	<jk>public</jk> String doGetExample1(
		RestRequest req,
		RestResponse res,
		<ja>@Method</ja> String method,
		<ja>@Path</ja>(<js>"a1"</js>) String a1,
		<ja>@Path</ja>(<js>"a2"</js>) <jk>int</jk> a2,
		<ja>@Path</ja>(<js>"a3"</js>) UUID a3,
		<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,
		<ja>@HasQuery</ja>(<js>"p3"</js>) boolean hasP3,
		<ja>@Path</ja>(<js>"/*"</js>) String remainder,
		<ja>@Header</ja>(<js>"Accept-Language"</js>) String lang,
		<ja>@Header</ja>(<js>"Accept"</js>) String accept,
		<ja>@Header</ja>(<js>"DNT"</js>) <jk>int</jk> doNotTrack,
		RequestProperties properties,
		ResourceBundle nls
	) {
		<jc>// Do something with all of those</jc>
	}
</p>
<ul class='notes'>
	<li>All annotations have programmatic equivalents on the {@link oajr.RestRequest} class.
</ul>
<ul class='seealso'>
	<li class='jf'>{@link oajr.RestContext#REST_paramResolvers} - For configuring custom parameter types.
</ul>