2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
17 package javax.servlet.http;
19 import java.io.IOException;
20 import java.io.InputStream;
21 import java.util.Collection;
24 * This class represents a part as uploaded to the server as part of a
25 * <code>multipart/form-data</code> request body. The part may represent either
26 * an uploaded file or form data.
30 public interface Part {
33 * Obtain an <code>InputStream</code> that can be used to retrieve the
34 * contents of the file.
36 public InputStream getInputStream() throws IOException;
39 * Obtain the content type passed by the browser or <code>null</code> if not
42 public String getContentType();
45 * Obtain the name of the field in the multipart form corresponding to this
48 public String getName();
51 * If this part represents an uploaded file, gets the file name submitted
52 * in the upload. Returns {@code null} if no file name is available or if
53 * this part is not a file upload.
55 * @return the submitted file name or {@code null}.
59 public String getSubmittedFileName();
62 * Obtain the size of this part.
64 public long getSize();
67 * A convenience method to write an uploaded part to disk. The client code
68 * is not concerned with whether or not the part is stored in memory, or on
69 * disk in a temporary location. They just want to write the uploaded part
72 * This method is not guaranteed to succeed if called more than once for
73 * the same part. This allows a particular implementation to use, for
74 * example, file renaming, where possible, rather than copying all of the
75 * underlying data, thus gaining a significant performance benefit.
77 * @param fileName The location into which the uploaded part should be
78 * stored. Relative locations are relative to {@link
79 * javax.servlet.MultipartConfigElement#getLocation()}
81 public void write(String fileName) throws IOException;
84 * Deletes the underlying storage for a part, including deleting any
85 * associated temporary disk file. Although the container will delete this
86 * storage automatically this method can be used to ensure that this is done
87 * at an earlier time, thus preserving system resources.
89 * Containers are only required to delete the associated storage when the
90 * Part instance is garbage collected. Apache Tomcat will delete the
91 * associated storage when the associated request has finished processing.
92 * Behaviour of other containers may be different.
94 public void delete() throws IOException;
97 * Obtains the value of the specified part header as a String. If there are
98 * multiple headers with the same name, this method returns the first header
99 * in the part. The header name is case insensitive.
101 * @param name Header name
102 * @return The header value or <code>null</code> if the header is not
105 public String getHeader(String name);
108 * Obtain all the values of the specified part header. If the part did not
109 * include any headers of the specified name, this method returns an empty
110 * Collection. The header name is case insensitive.
112 public Collection<String> getHeaders(String name);
115 * Returns a Collection of all the header names provided for this part.
117 public Collection<String> getHeaderNames();