001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.httppart;
018
019import static org.apache.juneau.commons.httppart.HttpPartType.*;
020import static org.apache.juneau.commons.utils.IoUtils.*;
021import static org.apache.juneau.commons.utils.Shorts.*;
022import static org.apache.juneau.commons.utils.ThrowableUtils.*;
023
024import java.io.*;
025import java.lang.reflect.*;
026import java.util.*;
027import java.util.regex.*;
028
029import org.apache.juneau.commons.utils.*;
030import org.apache.juneau.http.HttpPart;
031import org.apache.juneau.marshall.*;
032import org.apache.juneau.marshall.httppart.*;
033import org.apache.juneau.rest.server.*;
034
035/**
036 * Represents a single form-data parameter on an HTTP request.
037 *
038 * <p>
039 * Typically accessed through the {@link RequestFormParamList} class.
040 *
041 * <p>
042 *    Some important methods on this class are:
043 * </p>
044 * <ul class='javatree'>
045 *    <li class='jc'>{@link RequestFormParam}
046 *    <ul class='spaced-list'>
047 *       <li>Methods for retrieving simple string values:
048 *       <ul class='javatreec'>
049 *          <li class='jm'>{@link RequestFormParam#asString() asString()}
050 *          <li class='jm'>{@link RequestFormParam#get() get()}
051 *          <li class='jm'>{@link RequestFormParam#isPresent() isPresent()}
052 *          <li class='jm'>{@link RequestFormParam#orElse(String) orElse(String)}
053 *       </ul>
054 *       <li>Methods for retrieving as other common types:
055 *       <ul class='javatreec'>
056 *          <li class='jm'>{@link RequestFormParam#asBoolean() asBoolean()}
057 *          <li class='jm'>{@link RequestFormParam#asBooleanPart() asBooleanPart()}
058 *          <li class='jm'>{@link RequestFormParam#asCsvArray() asCsvArray()}
059 *          <li class='jm'>{@link RequestFormParam#asCsvArrayPart() asCsvArrayPart()}
060 *          <li class='jm'>{@link RequestFormParam#asDate() asDate()}
061 *          <li class='jm'>{@link RequestFormParam#asDatePart() asDatePart()}
062 *          <li class='jm'>{@link RequestFormParam#asInteger() asInteger()}
063 *          <li class='jm'>{@link RequestFormParam#asIntegerPart() asIntegerPart()}
064 *          <li class='jm'>{@link RequestFormParam#asLong() asLong()}
065 *          <li class='jm'>{@link RequestFormParam#asLongPart() asLongPart()}
066 *          <li class='jm'>{@link RequestFormParam#asMatcher(Pattern) asMatcher(Pattern)}
067 *          <li class='jm'>{@link RequestFormParam#asMatcher(String) asMatcher(String)}
068 *          <li class='jm'>{@link RequestFormParam#asMatcher(String,int) asMatcher(String,int)}
069 *          <li class='jm'>{@link RequestFormParam#asStringPart() asStringPart()}
070 *          <li class='jm'>{@link RequestFormParam#asUriPart() asUriPart()}
071 *       </ul>
072 *       <li>Methods for retrieving as custom types:
073 *       <ul class='javatreec'>
074 *          <li class='jm'>{@link RequestFormParam#as(Class) as(Class)}
075 *          <li class='jm'>{@link RequestFormParam#as(ClassMeta) as(ClassMeta)}
076 *          <li class='jm'>{@link RequestFormParam#as(Type,Type...) as(Type,Type...)}
077 *          <li class='jm'>{@link RequestFormParam#parser(HttpPartParserSession) parser(HttpPartParserSession)}
078 *          <li class='jm'>{@link RequestFormParam#schema(HttpPartSchema) schema(HttpPartSchema)}
079 *       </ul>
080 *       <li>Methods for performing assertion checks:
081 *       <ul class='javatreec'>
082 *          <li class='jm'>{@link RequestFormParam#assertCsvArray() assertCsvArray()}
083 *          <li class='jm'>{@link RequestFormParam#assertDate() assertDate()}
084 *          <li class='jm'>{@link RequestFormParam#assertInteger() assertInteger()}
085 *          <li class='jm'>{@link RequestFormParam#assertLong() assertLong()}
086 *          <li class='jm'>{@link RequestFormParam#assertString() assertString()}
087 *       </ul>
088 *       <li>Other methods:
089 *       <ul class='javatreec'>
090 *          <li class='jm'>{@link RequestFormParam#getName() getName()}
091 *          <li class='jm'>{@link RequestFormParam#getValue() getValue()}
092 *       </ul>
093 *    </ul>
094 * </ul>
095 *
096 * <h2 class='section'>See Also:</h2><ul>
097 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerHttpParts">HTTP parts in REST servers</a>
098 * </ul>
099 */
100@SuppressWarnings({
101   "java:S2160", // equals() inherited from parent context; form param identity based on name+value from parent
102   "resource" // RequestFormParam manages Closeable resources
103})
104public class RequestFormParam extends RequestHttpPart implements HttpPart {
105
106   private final jakarta.servlet.http.Part part;
107
108   /**
109    * Constructor.
110    *
111    * @param request The request object.
112    * @param part The HTTP part.
113    */
114   public RequestFormParam(RestRequest request, jakarta.servlet.http.Part part) {
115      super(FORMDATA, request, part.getName(), null);
116      this.part = part;
117   }
118
119   /**
120    * Constructor.
121    *
122    * @param request The request object.
123    * @param name The parameter name.
124    * @param value The parameter value.
125    */
126   public RequestFormParam(RestRequest request, String name, String value) {
127      super(FORMDATA, request, name, value);
128      this.part = null;
129   }
130
131   @Override /* Overridden from RequestHttpPart */
132   public RequestFormParam def(String def) {
133      super.def(def);
134      return this;
135   }
136
137   /**
138    * Returns the content type of this part.
139    *
140    * @return The content type of this part, or <jk>null</jk> if not known.
141    */
142   public String getContentType() { return (part == null ? null : part.getContentType()); }
143
144   /**
145    * Returns the value of the specified mime header as a String.
146    *
147    * <p>
148    * If the Part did not include a header of the specified name, this method returns null.
149    * If there are multiple headers with the same name, this method returns the first header in the part.
150    * The header name is case insensitive.
151    * You can use this method with any request header.
152    *
153    * @param name The header name.
154    * @return The value of the specified mime header as a String.
155    */
156   public String getHeader(String name) {
157      return part.getHeader(name);
158   }
159
160   /**
161    * Returns the header names of this param.
162    *
163    * @return The header names of this param.
164    */
165   public Collection<String> getHeaderNames() { return part.getHeaderNames(); }
166
167   /**
168    * Returns the values of the param header with the given name.
169    *
170    * @param name The param name.
171    * @return The values of the param header with the given name.
172    */
173   public Collection<String> getHeaders(String name) {
174      return part.getHeaders(name);
175   }
176
177   /**
178    * Returns the size of this file.
179    *
180    * @return A long specifying the size of this part, in bytes.
181    */
182   public long getSize() { return part.getSize(); }
183
184   /**
185    * Returns this part value as an input stream.
186    *
187    * @return This part value as an input stream.
188    * @throws IOException If an error occurs in retrieving the content.
189    */
190   public InputStream getStream() throws IOException {
191      if (nn(value))
192         return new ByteArrayInputStream(value.getBytes(UTF8));
193      return part.getInputStream();
194   }
195
196   /**
197    * Returns the file name specified by the client.
198    *
199    * @return The file name specified by the client.
200    */
201   public String getSubmittedFileName() { return part.getSubmittedFileName(); }
202
203   @Override /* Overridden from RequestHttpPart */
204   public String getValue() {
205      if (value == null && nn(part))
206         try {
207            value = IoUtils.read(part.getInputStream());
208         } catch (IOException e) {
209            throw toRex(e);
210         }
211      return value;
212   }
213
214   @Override /* Overridden from RequestHttpPart */
215   public RequestFormParam parser(HttpPartParserSession value) {
216      super.parser(value);
217      return this;
218   }
219
220   @Override /* Overridden from RequestHttpPart */
221   public RequestFormParam schema(HttpPartSchema value) {
222      super.schema(value);
223      return this;
224   }
225}