View Javadoc

1   /*
2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3    *
4    * Copyright 1997-2008 Sun Microsystems, Inc. All rights reserved.
5    *
6    * The contents of this file are subject to the terms of either the GNU
7    * General Public License Version 2 only ("GPL") or the Common Development
8    * and Distribution License("CDDL") (collectively, the "License").  You
9    * may not use this file except in compliance with the License. You can obtain
10   * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11   * or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific
12   * language governing permissions and limitations under the License.
13   *
14   * When distributing the software, include this License Header Notice in each
15   * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
16   * Sun designates this particular file as subject to the "Classpath" exception
17   * as provided by Sun in the GPL Version 2 section of the License file that
18   * accompanied this code.  If applicable, add the following below the License
19   * Header, with the fields enclosed by brackets [] replaced by your own
20   * identifying information: "Portions Copyrighted [year]
21   * [name of copyright owner]"
22   *
23   * Contributor(s):
24   *
25   * If you wish your version of this file to be governed by only the CDDL or
26   * only the GPL Version 2, indicate your decision by adding "[Contributor]
27   * elects to include this software in this distribution under the [CDDL or GPL
28   * Version 2] license."  If you don't indicate a single choice of license, a
29   * recipient has the option to distribute your version of this file under
30   * either the CDDL, the GPL Version 2 or to extend the choice of license to
31   * its licensees as provided above.  However, if you add GPL Version 2 code
32   * and therefore, elected the GPL Version 2 license, then the option applies
33   * only if the new code is made subject to such option by the copyright
34   * holder.
35   */
36  
37  package org.mule.transport.http.multipart;
38  
39  import java.io.IOException;
40  import java.io.InputStream;
41  import java.util.Collection;
42  
43  /**
44   * <p> This class represents a part or form item that was received within a
45   * <code>multipart/form-data</code> POST request.
46   *
47   * This is an adaptation of the javax.servlet.Part interface introduced into the Servlet 3.0 specification. 
48   * The API has been kept that same but the package has changed not to conflict with the Servlet spec.
49   *
50   * @since 3.0
51   */
52  public interface Part {
53  
54      /**
55       * Gets the content of this part as an <tt>InputStream</tt>
56       *
57       * @return The content of this part as an <tt>InputStream</tt>
58       * @throws IOException If an error occurs in retrieving the content
59       * as an <tt>InputStream</tt>
60       */
61      public InputStream getInputStream() throws IOException;
62  
63      /**
64       * Gets the content type of this part.
65       *
66       * @return The content type of this part.
67       */
68      public String getContentType();
69  
70      /**
71       * Gets the name of this part
72       *
73       * @return The name of this part as a <tt>String</tt>
74       */
75      public String getName();
76  
77      /**
78       * Returns the size of this file.
79       *
80       * @return a <code>long</code> specifying the size of this part, in bytes.
81       */
82      public long getSize();
83  
84      /**
85       * A convenience method to write this uploaded item to disk.
86       *
87       * <p>This method is not guaranteed to succeed if called more than once for
88       * the same part. This allows a particular implementation to use, for
89       * example, file renaming, where possible, rather than copying all of the
90       * underlying data, thus gaining a significant performance benefit.
91       *
92       * @param fileName the name of the file to which the stream will be
93       * written. The file is created relative to the location as
94       * specified in the MultipartConfig
95       *
96       * @throws IOException if an error occurs.
97       */
98      public void write(String fileName) throws IOException;
99  
100     /**
101      * Deletes the underlying storage for a file item, including deleting any
102      * associated temporary disk file.
103      *
104      * @throws IOException if an error occurs.
105      */
106     public void delete() throws IOException;
107 
108     /**
109      *
110      * Returns the value of the specified mime header
111      * as a <code>String</code>. If the Part did not include a header
112      * of the specified name, this method returns <code>null</code>.
113      * If there are multiple headers with the same name, this method
114      * returns the first header in the part.
115      * The header name is case insensitive. You can use
116      * this method with any request header.
117      *
118      * @param name        a <code>String</code> specifying the
119      *                header name
120      *
121      * @return            a <code>String</code> containing the
122      *                value of the requested
123      *                header, or <code>null</code>
124      *                if the part does not
125      *                have a header of that name
126      */
127     public String getHeader(String name);
128 
129     /**
130      * Gets the values of the Part header with the given name.
131      *
132      * <p>Any changes to the returned <code>Collection</code> must not
133      * affect this <code>Part</code>.
134      *
135      * <p>Part header names are case insensitive.
136      *
137      * @param name the header name whose values to return
138      *
139      * @return a (possibly empty) <code>Collection</code> of the values of
140      * the header with the given name
141      */
142     public Collection<String> getHeaders(String name);
143 
144     /**
145      * Gets the header names of this Part.
146      *
147      * <p>Some servlet containers do not allow
148      * servlets to access headers using this method, in
149      * which case this method returns <code>null</code>
150      *
151      * <p>Any changes to the returned <code>Collection</code> must not
152      * affect this <code>Part</code>.
153      *
154      * @return a (possibly empty) <code>Collection</code> of the header
155      * names of this Part
156      */
157     public Collection<String> getHeaderNames();
158 
159 }