View Javadoc
1   /*
2    * $Id$
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *  http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  package org.apache.struts.upload;
22  
23  import java.io.FileNotFoundException;
24  import java.io.IOException;
25  import java.io.InputStream;
26  import java.io.Serializable;
27  
28  /**
29   * This interface represents a file that has been uploaded by a client. It is
30   * the only interface or class in upload package which is typically referenced
31   * directly by a Struts application.
32   */
33  public interface FormFile extends Serializable {
34  
35      /**
36       * Returns the content type for this file.
37       *
38       * @return A String representing content type.
39       */
40      public String getContentType();
41  
42      /**
43       * Sets the content type for this file.
44       *
45       * @param contentType The content type for the file.
46       */
47      public void setContentType(String contentType);
48  
49      /**
50       * Returns the size of this file.
51       *
52       * @return The size of the file, in bytes.
53       *
54       * @throws IllegalStateException if size is greater than 2GB
55       *
56       * @see #getFileLength()
57       *
58       * @deprecated use {@link #getFileLength()}
59       */
60      @Deprecated
61      public int getFileSize();
62  
63      /**
64       * Sets the file size.
65       *
66       * @param size The size of the file, in bytes.
67       *
68       * @see #setFileLength(long)
69       *
70       * @deprecated use {@link #setFileLength(long)}
71       */
72      @Deprecated
73      public void setFileSize(int size);
74  
75      /**
76       * Returns the length of this file.
77       *
78       * @return The length of the file, in bytes.
79       */
80      public long getFileLength();
81  
82      /**
83       * Sets the file length.
84       *
85       * @param fileLength The length of the file, in bytes.
86       */
87      public void setFileLength(long fileLength);
88  
89      /**
90       * Returns the file name of this file. This is the base name of the file,
91       * as supplied by the user when the file was uploaded.
92       *
93       * @return The base file name.
94       */
95      public String getFileName();
96  
97      /**
98       * Sets the file name of this file.
99       *
100      * @param fileName The base file name.
101      */
102     public void setFileName(String fileName);
103 
104     /**
105      * Returns the data for the entire file as byte array. Care is needed when
106      * using this method, since a large upload could easily exhaust available
107      * memory. The preferred method for accessing the file data is
108      * {@link #getInputStream() getInputStream}.
109      *
110      * @return The file data as a byte array.
111      *
112      * @throws FileNotFoundException if the uploaded file is not found. Some
113      *                               implementations may not deal with files
114      *                               and/or throw this exception.
115      * @throws IOException           if an error occurred while reading the
116      *                               file.
117      */
118     public byte[] getFileData()
119         throws FileNotFoundException, IOException;
120 
121     /**
122      * Returns an input stream for this file. The caller must close the stream
123      * when it is no longer needed.
124      *
125      * @throws FileNotFoundException if the uploaded file is not found. Some
126      *                               implementations may not deal with files
127      *                               and/or throw this exception.
128      * @throws IOException           if an error occurred while reading the
129      *                               file.
130      */
131     public InputStream getInputStream()
132         throws FileNotFoundException, IOException;
133 
134     /**
135      * Destroys all content for the uploaded file, including any underlying
136      * data files.
137      *
138      * @throws IOException           if an error occurred while destroying all
139      *                               content.
140      */
141     public void destroy() throws IOException;
142 }