KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > web > multipart > MultipartResolver


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.web.multipart;
18
19 import javax.servlet.http.HttpServletRequest JavaDoc;
20
21 /**
22  * A strategy interface for multipart file upload resolution in accordance
23  * with <a HREF="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>.
24  * Implementations are typically usable both within an application context
25  * and standalone.
26  *
27  * <p>There are two concrete implementations included in Spring:
28  * <ul>
29  * <li>{@link org.springframework.web.multipart.commons.CommonsMultipartResolver} for Jakarta Commons FileUpload
30  * <li>{@link org.springframework.web.multipart.cos.CosMultipartResolver} for Jason Hunter's COS (com.oreilly.servlet)
31  * </ul>
32  *
33  * <p>There is no default resolver implementation used for Spring
34  * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlets},
35  * as an application might choose to parse its multipart requests itself. To define
36  * an implementation, create a bean with the id "multipartResolver" in a
37  * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet's}
38  * application context. Such a resolver gets applied to all requests handled
39  * by that {@link org.springframework.web.servlet.DispatcherServlet}.
40  *
41  * <p>If a {@link org.springframework.web.servlet.DispatcherServlet} detects
42  * a multipart request, it will resolve it via the configured
43  * {@link org.springframework.web.multipart.MultipartResolver} and pass on a
44  * wrapped {@link javax.servlet.http.HttpServletRequest}.
45  * Controllers can then cast their given request to the
46  * {@link org.springframework.web.multipart.MultipartHttpServletRequest}
47  * interface, which permits access to any
48  * {@link org.springframework.web.multipart.MultipartFile MultipartFiles}.
49  * Note that this cast is only supported in case of an actual multipart request.
50  *
51  * <pre class="code">
52  * public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) {
53  * MultipartHttpServletRequest multipartRequest = (MultipartHttpServletRequest) request;
54  * MultipartFile multipartFile = multipartRequest.getFile("image");
55  * ...
56  * }</pre>
57  *
58  * Instead of direct access, command or form controllers can register a
59  * {@link org.springframework.web.multipart.support.ByteArrayMultipartFileEditor}
60  * or {@link org.springframework.web.multipart.support.StringMultipartFileEditor}
61  * with their data binder, to automatically apply multipart content to command
62  * bean properties.
63  *
64  * <p>As an alternative to using a
65  * {@link org.springframework.web.multipart.MultipartResolver} with a
66  * {@link org.springframework.web.servlet.DispatcherServlet},
67  * a {@link org.springframework.web.multipart.support.MultipartFilter} can be
68  * registered in <code>web.xml</code>. It will delegate to a corresponding
69  * {@link org.springframework.web.multipart.MultipartResolver} bean in the root
70  * application context. This is mainly intended for applications that do not
71  * use Spring's own web MVC framework.
72  *
73  * <p>Note: There is hardly ever a need to access the
74  * {@link org.springframework.web.multipart.MultipartResolver} itself
75  * from application code. It will simply do its work behind the scenes,
76  * making
77  * {@link org.springframework.web.multipart.MultipartHttpServletRequest MultipartHttpServletRequests}
78  * available to controllers.
79  *
80  * @author Juergen Hoeller
81  * @author Trevor D. Cook
82  * @since 29.09.2003
83  * @see MultipartHttpServletRequest
84  * @see MultipartFile
85  * @see org.springframework.web.multipart.commons.CommonsMultipartResolver
86  * @see org.springframework.web.multipart.cos.CosMultipartResolver
87  * @see org.springframework.web.multipart.support.ByteArrayMultipartFileEditor
88  * @see org.springframework.web.multipart.support.StringMultipartFileEditor
89  * @see org.springframework.web.servlet.DispatcherServlet
90  */
91 public interface MultipartResolver {
92
93     /**
94      * Determine if the given request contains multipart content.
95      * <p>Will typically check for content type "multipart/form-data", but the actually
96      * accepted requests might depend on the capabilities of the resolver implementation.
97      * @param request the servlet request to be evaluated
98      * @return whether the request contains multipart content
99      */
100     boolean isMultipart(HttpServletRequest JavaDoc request);
101
102     /**
103      * Parse the given HTTP request into multipart files and parameters,
104      * and wrap the request inside a
105      * {@link org.springframework.web.multipart.MultipartHttpServletRequest} object
106      * that provides access to file descriptors and makes contained
107      * parameters accessible via the standard ServletRequest methods.
108      * @param request the servlet request to wrap (must be of a multipart content type)
109      * @return the wrapped servlet request
110      * @throws MultipartException if the servlet request is not multipart, or if
111      * implementation-specific problems are encountered (such as exceeding file size limits)
112      * @see MultipartHttpServletRequest#getFile
113      * @see MultipartHttpServletRequest#getFileNames
114      * @see MultipartHttpServletRequest#getFileMap
115      * @see javax.servlet.http.HttpServletRequest#getParameter
116      * @see javax.servlet.http.HttpServletRequest#getParameterNames
117      * @see javax.servlet.http.HttpServletRequest#getParameterMap
118      */
119     MultipartHttpServletRequest resolveMultipart(HttpServletRequest JavaDoc request) throws MultipartException;
120
121     /**
122      * Cleanup any resources used for the multipart handling,
123      * like a storage for the uploaded files.
124      * @param request the request to cleanup resources for
125      */
126     void cleanupMultipart(MultipartHttpServletRequest request);
127
128 }
129
Popular Tags