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.httppart;
014
015import static org.apache.juneau.common.internal.ThrowableUtils.*;
016import static org.apache.juneau.httppart.HttpPartType.*;
017
018import java.io.*;
019import java.lang.reflect.*;
020import java.util.*;
021import java.util.regex.*;
022
023import org.apache.http.*;
024import org.apache.juneau.*;
025import org.apache.juneau.common.internal.*;
026import org.apache.juneau.httppart.*;
027import org.apache.juneau.rest.*;
028
029/**
030 * Represents a single form-data parameter on an HTTP request.
031 *
032 * <p>
033 * Typically accessed through the {@link RequestFormParams} class.
034 *
035 * <p>
036 *    Some important methods on this class are:
037 * </p>
038 * <ul class='javatree'>
039 *    <li class='jc'>{@link RequestFormParam}
040 *    <ul class='spaced-list'>
041 *       <li>Methods for retrieving simple string values:
042 *       <ul class='javatreec'>
043 *          <li class='jm'>{@link RequestFormParam#asString() asString()}
044 *          <li class='jm'>{@link RequestFormParam#get() get()}
045 *          <li class='jm'>{@link RequestFormParam#isPresent() isPresent()}
046 *          <li class='jm'>{@link RequestFormParam#orElse(String) orElse(String)}
047 *       </ul>
048 *       <li>Methods for retrieving as other common types:
049 *       <ul class='javatreec'>
050 *          <li class='jm'>{@link RequestFormParam#asBoolean() asBoolean()}
051 *          <li class='jm'>{@link RequestFormParam#asBooleanPart() asBooleanPart()}
052 *          <li class='jm'>{@link RequestFormParam#asCsvArray() asCsvArray()}
053 *          <li class='jm'>{@link RequestFormParam#asCsvArrayPart() asCsvArrayPart()}
054 *          <li class='jm'>{@link RequestFormParam#asDate() asDate()}
055 *          <li class='jm'>{@link RequestFormParam#asDatePart() asDatePart()}
056 *          <li class='jm'>{@link RequestFormParam#asInteger() asInteger()}
057 *          <li class='jm'>{@link RequestFormParam#asIntegerPart() asIntegerPart()}
058 *          <li class='jm'>{@link RequestFormParam#asLong() asLong()}
059 *          <li class='jm'>{@link RequestFormParam#asLongPart() asLongPart()}
060 *          <li class='jm'>{@link RequestFormParam#asMatcher(Pattern) asMatcher(Pattern)}
061 *          <li class='jm'>{@link RequestFormParam#asMatcher(String) asMatcher(String)}
062 *          <li class='jm'>{@link RequestFormParam#asMatcher(String,int) asMatcher(String,int)}
063 *          <li class='jm'>{@link RequestFormParam#asStringPart() asStringPart()}
064 *          <li class='jm'>{@link RequestFormParam#asUriPart() asUriPart()}
065 *       </ul>
066 *       <li>Methods for retrieving as custom types:
067 *       <ul class='javatreec'>
068 *          <li class='jm'>{@link RequestFormParam#as(Class) as(Class)}
069 *          <li class='jm'>{@link RequestFormParam#as(ClassMeta) as(ClassMeta)}
070 *          <li class='jm'>{@link RequestFormParam#as(Type,Type...) as(Type,Type...)}
071 *          <li class='jm'>{@link RequestFormParam#parser(HttpPartParserSession) parser(HttpPartParserSession)}
072 *          <li class='jm'>{@link RequestFormParam#schema(HttpPartSchema) schema(HttpPartSchema)}
073 *       </ul>
074 *       <li>Methods for performing assertion checks:
075 *       <ul class='javatreec'>
076 *          <li class='jm'>{@link RequestFormParam#assertCsvArray() assertCsvArray()}
077 *          <li class='jm'>{@link RequestFormParam#assertDate() assertDate()}
078 *          <li class='jm'>{@link RequestFormParam#assertInteger() assertInteger()}
079 *          <li class='jm'>{@link RequestFormParam#assertLong() assertLong()}
080 *          <li class='jm'>{@link RequestFormParam#assertString() assertString()}
081 *       </ul>
082 *       <li>Other methods:
083 *       <ul class='javatreec'>
084 *          <li class='jm'>{@link RequestFormParam#getName() getName()}
085 *          <li class='jm'>{@link RequestFormParam#getValue() getValue()}
086*     </ul>
087 * </ul>
088 *
089 * <h5 class='section'>See Also:</h5><ul>
090 *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.HttpParts">HTTP Parts</a>
091 * </ul>
092 */
093public class RequestFormParam extends RequestHttpPart implements NameValuePair {
094
095   private final jakarta.servlet.http.Part part;
096
097   /**
098    * Constructor.
099    *
100    * @param request The request object.
101    * @param part The HTTP part.
102    */
103   public RequestFormParam(RestRequest request, jakarta.servlet.http.Part part) {
104      super(FORMDATA, request, part.getName(), null);
105      this.part = part;
106   }
107
108   /**
109    * Constructor.
110    *
111    * @param request The request object.
112    * @param name The parameter name.
113    * @param value The parameter value.
114    */
115   public RequestFormParam(RestRequest request, String name, String value) {
116      super(FORMDATA, request, name, value);
117      this.part = null;
118   }
119
120   //------------------------------------------------------------------------------------------------------------------
121   // Retrievers
122   //------------------------------------------------------------------------------------------------------------------
123
124   @Override /* RequestHttpPart */
125   public String getValue() {
126      if (value == null && part != null)
127         try {
128            value = IOUtils.read(part.getInputStream());
129         } catch (IOException e) {
130            throw asRuntimeException(e);
131         }
132      return value;
133   }
134
135   /**
136    * Returns this part value as an input stream.
137    *
138    * @return This part value as an input stream.
139    * @throws IOException If an error occurs in retrieving the content.
140    */
141   public InputStream getStream() throws IOException {
142      if (value != null)
143         return new ByteArrayInputStream(value.getBytes(IOUtils.UTF8));
144      return part.getInputStream();
145   }
146
147   /**
148    * Returns the content type of this part.
149    *
150    * @return The content type of this part, or <jk>null</jk> if not known.
151    */
152   public String getContentType() {
153      return (part == null ? null : part.getContentType());
154   }
155
156   /**
157    * Returns the value of the specified mime header as a String.
158    *
159    * <p>
160    * If the Part did not include a header of the specified name, this method returns null.
161    * If there are multiple headers with the same name, this method returns the first header in the part.
162    * The header name is case insensitive.
163    * You can use this method with any request header.
164    *
165    * @param name The header name.
166    * @return The value of the specified mime header as a String.
167    */
168   public String getHeader(String name) {
169      return part.getHeader(name);
170   }
171
172   /**
173    * Returns the header names of this param.
174    *
175    * @return The header names of this param.
176    */
177   public Collection<String> getHeaderNames() {
178      return part.getHeaderNames();
179   }
180
181   /**
182    * Returns the values of the param header with the given name.
183    *
184    * @param name The param name.
185    * @return The values of the param header with the given name.
186    */
187   public Collection<String> getHeaders(String name) {
188      return part.getHeaders(name);
189   }
190
191   /**
192    * Returns the size of this file.
193    *
194    * @return A long specifying the size of this part, in bytes.
195    */
196   public long getSize() {
197      return part.getSize();
198   }
199
200   /**
201    * Returns the file name specified by the client.
202    *
203    * @return The file name specified by the client.
204    */
205   public String getSubmittedFileName() {
206      return part.getSubmittedFileName();
207   }
208
209   // <FluentSetters>
210
211   @Override /* GENERATED */
212   public RequestFormParam schema(HttpPartSchema value) {
213      super.schema(value);
214      return this;
215   }
216
217   @Override /* GENERATED */
218   public RequestFormParam parser(HttpPartParserSession value) {
219      super.parser(value);
220      return this;
221   }
222
223   // </FluentSetters>
224}