View Javadoc

1   /*
2    * $Id: MultipartRequestHandler.java 421119 2006-07-12 04:49:11Z wsmoak $
3    *
4    * Copyright 1999-2004 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.apache.struts.upload;
19  
20  import org.apache.struts.action.ActionMapping;
21  import org.apache.struts.action.ActionServlet;
22  
23  import javax.servlet.ServletException;
24  import javax.servlet.http.HttpServletRequest;
25  
26  import java.util.Hashtable;
27  
28  /***
29   * <p> MultipartRequestHandler provides an standard interface for struts to
30   * deal with file uploads from forms with enctypes of "multipart/form-data".
31   * Providers must provide a no-argument constructor for initialization. </p>
32   */
33  public interface MultipartRequestHandler {
34      /***
35       * <p> This is the ServletRequest attribute that should be set when a
36       * multipart request is being read and the maximum length is exceeded. The
37       * value is a Boolean. If the maximum length isn't exceeded, this
38       * attribute shouldn't be put in the ServletRequest. It's the job of the
39       * implementation to put this attribute in the request if the maximum
40       * length is exceeded; in the handleRequest(HttpServletRequest) method.
41       * </p>
42       */
43      public static final String ATTRIBUTE_MAX_LENGTH_EXCEEDED =
44          "org.apache.struts.upload.MaxLengthExceeded";
45  
46      /***
47       * <p> Convienience method to set a reference to a working ActionServlet
48       * instance. </p>
49       */
50      public void setServlet(ActionServlet servlet);
51  
52      /***
53       * <p> Convienience method to set a reference to a working ActionMapping
54       * instance. </p>
55       */
56      public void setMapping(ActionMapping mapping);
57  
58      /***
59       * <p> Get the ActionServlet instance </p>
60       */
61      public ActionServlet getServlet();
62  
63      /***
64       * <p> Get the ActionMapping instance for this request </p>
65       */
66      public ActionMapping getMapping();
67  
68      /***
69       * <p> After constructed, this is the first method called on by
70       * ActionServlet. Use this method for all your data-parsing of the
71       * ServletInputStream in the request </p>
72       *
73       * @throws ServletException thrown if something goes wrong
74       */
75      public void handleRequest(HttpServletRequest request)
76          throws ServletException;
77  
78      /***
79       * <p> This method is called on to retrieve all the text input elements of
80       * the request. </p>
81       *
82       * @return A Hashtable where the keys and values are the names and values
83       *         of the request input parameters
84       */
85      public Hashtable getTextElements();
86  
87      /***
88       * <p> This method is called on to retrieve all the FormFile input
89       * elements of the request. </p>
90       *
91       * @return A Hashtable where the keys are the input names of the files and
92       *         the values are FormFile objects
93       * @see FormFile
94       */
95      public Hashtable getFileElements();
96  
97      /***
98       * <p> This method returns all elements of a multipart request. </p>
99       *
100      * @return A Hashtable where the keys are input names and values are
101      *         either String arrays or FormFiles
102      */
103     public Hashtable getAllElements();
104 
105     /***
106      * <p> This method is called on when there's some sort of problem and the
107      * form post needs to be rolled back.  Providers should remove any
108      * FormFiles used to hold information by setting them to null and also
109      * physically delete them if the implementation calls for writing directly
110      * to disk. NOTE: Currently implemented but not automatically supported,
111      * ActionForm implementors must call rollback() manually for rolling back
112      * file uploads. </p>
113      */
114     public void rollback();
115 
116     /***
117      * <p> This method is called on when a successful form post has been made.
118      * Some implementations will use this to destroy temporary files or write
119      * to a database or something of that nature. </p>
120      */
121     public void finish();
122 }