1 /*
2 * Copyright 2002-2015 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.portlet.multipart;
18
19 import javax.portlet.ActionRequest;
20
21 import org.springframework.web.multipart.MultipartException;
22
23 /**
24 * Portlet version of Spring's multipart resolution strategy for file uploads
25 * as defined in <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>.
26 *
27 * <p>Implementations are typically usable both within any application context
28 * and standalone.
29 *
30 * <p>There is one concrete implementation included in Spring:
31 * <ul>
32 * <li>{@link org.springframework.web.multipart.commons.CommonsMultipartResolver}
33 * for Apache Commons FileUpload
34 * </ul>
35 *
36 * <p>There is no default resolver implementation used for Spring
37 * {@link org.springframework.web.portlet.DispatcherPortlet DispatcherPortlets},
38 * as an application might choose to parse its multipart requests itself. To
39 * define an implementation, create a bean with the id "portletMultipartResolver"
40 * in a {@code DispatcherPortlet's} application context. Such a resolver
41 * gets applied to all requests handled by that {@code DispatcherPortlet}.
42 *
43 * <p>If a {@code DispatcherPortlet} detects a multipart request, it will
44 * resolve it via the configured
45 * {@link org.springframework.web.portlet.multipart.PortletMultipartResolver}
46 * and pass on a wrapped Portlet {@link ActionRequest}. Controllers can then
47 * cast their given request to the {@link MultipartActionRequest} interface,
48 * being able to access {@code MultipartFiles}. Note that this cast is only
49 * supported in case of an actual multipart request.
50 *
51 * <pre class="code"> public void handleActionRequest(ActionRequest request, ActionResponse response) {
52 * MultipartActionRequest multipartRequest = (MultipartActionRequest) request;
53 * MultipartFile multipartFile = multipartRequest.getFile("image");
54 * ...
55 * }</pre>
56 *
57 * Instead of direct access, command or form controllers can register a
58 * {@link org.springframework.web.multipart.support.ByteArrayMultipartFileEditor}
59 * or {@link org.springframework.web.multipart.support.StringMultipartFileEditor}
60 * with their data binder, to automatically apply multipart content to form
61 * bean properties.
62 *
63 * <p>Note: There is hardly ever a need to access the {@code MultipartResolver}
64 * itself from application code. It will simply do its work behind the scenes,
65 * making {@code MultipartActionRequests} available to controllers.
66 *
67 * @author Juergen Hoeller
68 * @since 2.0
69 * @see MultipartActionRequest
70 * @see org.springframework.web.multipart.MultipartFile
71 * @see CommonsPortletMultipartResolver
72 * @see org.springframework.web.multipart.support.ByteArrayMultipartFileEditor
73 * @see org.springframework.web.multipart.support.StringMultipartFileEditor
74 * @see org.springframework.web.portlet.DispatcherPortlet
75 */
76 public interface PortletMultipartResolver {
77
78 /**
79 * Determine if the given request contains multipart content.
80 * <p>Will typically check for content type
81 * "{@code multipart/form-data}", but the actually accepted requests
82 * might depend on the capabilities of the resolver implementation.
83 * @param request the portlet request to be evaluated
84 * @return whether the request contains multipart content
85 */
86 boolean isMultipart(ActionRequest request);
87
88 /**
89 * Parse the given portlet request into multipart files and parameters,
90 * and wrap the request inside a MultipartActionRequest object
91 * that provides access to file descriptors and makes contained
92 * parameters accessible via the standard PortletRequest methods.
93 * @param request the portlet request to wrap (must be of a multipart content type)
94 * @return the wrapped portlet request
95 * @throws org.springframework.web.multipart.MultipartException if the portlet request
96 * is not multipart, or if implementation-specific problems are encountered
97 * (such as exceeding file size limits)
98 * @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFile
99 * @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFileNames
100 * @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFileMap
101 * @see javax.portlet.ActionRequest#getParameter
102 * @see javax.portlet.ActionRequest#getParameterNames
103 * @see javax.portlet.ActionRequest#getParameterMap
104 */
105 MultipartActionRequest resolveMultipart(ActionRequest request) throws MultipartException;
106
107 /**
108 * Cleanup any resources used for the multipart handling,
109 * such as storage for any uploaded file(s).
110 * @param request the request to cleanup resources for
111 */
112 void cleanupMultipart(MultipartActionRequest request);
113
114 }