001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.rest;
014
015import java.io.*;
016import java.lang.reflect.*;
017import java.util.*;
018
019import javax.servlet.*;
020import javax.servlet.http.*;
021
022import org.apache.juneau.*;
023import org.apache.juneau.config.*;
024import org.apache.juneau.dto.swagger.*;
025import org.apache.juneau.http.*;
026import org.apache.juneau.http.Date;
027import org.apache.juneau.parser.*;
028import org.apache.juneau.utils.*;
029
030/**
031 * REST java method parameter resolver.
032 * 
033 * <p>
034 * Used to resolve instances of classes being passed to Java REST methods.
035 * 
036 * <p>
037 * By default, the following parameter types can be passed into Java methods in any order:
038 * 
039 * <h5 class='topic'>Standard top-level objects</h5>
040 * <ul>
041 *    <li><b>Standard top-level objects</b>
042 *    <ul>
043 *       <li class='jc'>{@link HttpServletRequest}
044 *       <li class='jc'>{@link RestRequest}
045 *       <li class='jc'>{@link HttpServletResponse}
046 *       <li class='jc'>{@link RestResponse}
047 *    </ul>
048 *    <li><b>Headers</b>
049 *    <ul>
050 *       <li class='jc'>{@link Accept}
051 *       <li class='jc'>{@link AcceptCharset}
052 *       <li class='jc'>{@link AcceptEncoding}
053 *       <li class='jc'>{@link AcceptLanguage}
054 *       <li class='jc'>{@link Authorization}
055 *       <li class='jc'>{@link CacheControl}
056 *       <li class='jc'>{@link Connection}
057 *       <li class='jc'>{@link ContentLength}
058 *       <li class='jc'>{@link ContentType}
059 *       <li class='jc'>{@link Date}
060 *       <li class='jc'>{@link Expect}
061 *       <li class='jc'>{@link From}
062 *       <li class='jc'>{@link Host}
063 *       <li class='jc'>{@link IfMatch}
064 *       <li class='jc'>{@link IfModifiedSince}
065 *       <li class='jc'>{@link IfNoneMatch}
066 *       <li class='jc'>{@link IfRange}
067 *       <li class='jc'>{@link IfUnmodifiedSince}
068 *       <li class='jc'>{@link MaxForwards}
069 *       <li class='jc'>{@link Pragma}
070 *       <li class='jc'>{@link ProxyAuthorization}
071 *       <li class='jc'>{@link Range}
072 *       <li class='jc'>{@link Referer}
073 *       <li class='jc'>{@link TE}
074 *       <li class='jc'>{@link TimeZone}
075 *       <li class='jc'>{@link UserAgent}
076 *       <li class='jc'>{@link Upgrade}
077 *       <li class='jc'>{@link Via}
078 *       <li class='jc'>{@link Warning}
079 *    </ul>
080 *    <li><b>Other objects</b>
081 *    <ul>
082 *       <li class='jc'>{@link Config}
083 *       <li class='jc'>{@link HttpMethod}
084 *       <li class='jc'>{@link InputStream}
085 *       <li class='jc'>{@link Locale}
086 *       <li class='jc'>{@link MessageBundle}
087 *       <li class='jc'>{@link OutputStream}
088 *       <li class='jc'>{@link Parser}
089 *       <li class='jc'>{@link Reader}
090 *       <li class='jc'>{@link RequestBody}
091 *       <li class='jc'>{@link RequestFormData}
092 *       <li class='jc'>{@link RequestHeaders}
093 *       <li class='jc'>{@link RequestPathMatch}
094 *       <li class='jc'>{@link RequestQuery}
095 *       <li class='jc'>{@link ResourceBundle}
096 *       <li class='jc'>{@link RestContext}
097 *       <li class='jc'>{@link RestLogger}
098 *       <li class='jc'>{@link RequestProperties}
099 *       <li class='jc'>{@link ServletInputStream}
100 *       <li class='jc'>{@link ServletOutputStream}
101 *       <li class='jc'>{@link Swagger}
102 *       <li class='jc'>{@link UriContext}
103 *       <li class='jc'>{@link UriResolver}
104 *       <li class='jc'>{@link Writer}
105 *    </ul>
106 * </ul>
107 * 
108 * <h5 class='section'>See Also:</h5>
109 * <ul>
110 *    <li class='jf'>{@link RestContext#REST_paramResolvers}
111 *    <li class='link'><a class="doclink" href="../../../../overview-summary.html#juneau-rest-server.MethodParameters">Overview &gt; juneau-rest-server &gt; Java Method Parameters</a>
112 * </ul>
113 */
114public abstract class RestParam {
115
116   final RestParamType paramType;
117   final String name;
118   final Type type;
119
120   /**
121    * Constructor.
122    * 
123    * @param paramType The Swagger parameter type.
124    * @param name
125    *    The parameter name.
126    *    Can be <jk>null</jk> if parameter doesn't have a name (e.g. the request body).
127    * @param type The object type to convert the parameter to.
128    */
129   protected RestParam(RestParamType paramType, String name, Type type) {
130      this.paramType = paramType;
131      this.name = name;
132      this.type = type;
133   }
134
135   /**
136    * Resolves the parameter object.
137    * 
138    * @param req The rest request.
139    * @param res The rest response.
140    * @return The resolved object.
141    * @throws Exception
142    */
143   public abstract Object resolve(RestRequest req, RestResponse res) throws Exception;
144
145   /**
146    * Returns the parameter class type that this parameter resolver is meant for.
147    * 
148    * @return The parameter class type, or <jk>null</jk> if the type passed in isn't an instance of {@link Class}.
149    */
150   protected Class<?> forClass() {
151      if (type instanceof Class)
152         return (Class<?>)type;
153      return null;
154   }
155
156   /**
157    * Returns the swagger parameter type for this parameter as shown in the Swagger doc.
158    * 
159    * @return the swagger parameter type for this parameter.
160    */
161   protected RestParamType getParamType() {
162      return paramType;
163   }
164
165   /**
166    * Returns the parameter name for this parameter as shown in the Swagger doc.
167    * 
168    * @return the parameter name for this parameter.
169    */
170   protected String getName() {
171      return name;
172   }
173
174   /**
175    * Returns the parameter class type.
176    * 
177    * @return the parameter class type.
178    */
179   public Type getType() {
180      return type;
181   }
182}