lib/servlet-api/javax/servlet/http/Part.java

   1 /*
   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
   8 *
   9 *     http://www.apache.org/licenses/LICENSE-2.0
  10 *
  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.
  16 */
  17 package javax.servlet.http;
  18
  19 import java.io.IOException;
  20 import java.io.InputStream;
  21 import java.util.Collection;
  22
  23 /**
  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.
  27  *
  28  * @since Servlet 3.0
  29  */
  30 public interface Part {
  31
  32     /**
  33      * Obtain an <code>InputStream</code> that can be used to retrieve the
  34      * contents of the file.
  35      */
  36     public InputStream getInputStream() throws IOException;
  37
  38     /**
  39      * Obtain the content type passed by the browser or <code>null</code> if not
  40      * defined.
  41      */
  42     public String getContentType();
  43
  44     /**
  45      * Obtain the name of the field in the multipart form corresponding to this
  46      * part.
  47      */
  48     public String getName();
  49
  50     /**
  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.
  54      *
  55      * @return the submitted file name or {@code null}.
  56      *
  57      * @since Servlet 3.1
  58      */
  59     public String getSubmittedFileName();
  60
  61     /**
  62      * Obtain the size of this part.
  63      */
  64     public long getSize();
  65
  66     /**
  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
  70      * to a file.
  71      *
  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.
  76      *
  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()}
  80      */
  81     public void write(String fileName) throws IOException;
  82
  83     /**
  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.
  88      * <p>
  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.
  93      */
  94     public void delete() throws IOException;
  95
  96     /**
  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.
 100      *
 101      * @param name  Header name
 102      * @return      The header value or <code>null</code> if the header is not
 103      *              present
 104      */
 105     public String getHeader(String name);
 106
 107     /**
 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.
 111      */
 112     public Collection<String> getHeaders(String name);
 113
 114     /**
 115      * Returns a Collection of all the header names provided for this part.
 116      */
 117     public Collection<String> getHeaderNames();
 118 }