001/*
002 * Copyright 2002-2015 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.portlet.multipart;
018
019import javax.portlet.ActionRequest;
020
021import org.springframework.web.multipart.MultipartException;
022
023/**
024 * Portlet version of Spring's multipart resolution strategy for file uploads
025 * as defined in <a href="https://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>.
026 *
027 * <p>Implementations are typically usable both within any application context
028 * and standalone.
029 *
030 * <p>There is one concrete implementation included in Spring:
031 * <ul>
032 * <li>{@link org.springframework.web.multipart.commons.CommonsMultipartResolver}
033 * for Apache Commons FileUpload
034 * </ul>
035 *
036 * <p>There is no default resolver implementation used for Spring
037 * {@link org.springframework.web.portlet.DispatcherPortlet DispatcherPortlets},
038 * as an application might choose to parse its multipart requests itself. To
039 * define an implementation, create a bean with the id "portletMultipartResolver"
040 * in a {@code DispatcherPortlet's} application context. Such a resolver
041 * gets applied to all requests handled by that {@code DispatcherPortlet}.
042 *
043 * <p>If a {@code DispatcherPortlet} detects a multipart request, it will
044 * resolve it via the configured
045 * {@link org.springframework.web.portlet.multipart.PortletMultipartResolver}
046 * and pass on a wrapped Portlet {@link ActionRequest}. Controllers can then
047 * cast their given request to the {@link MultipartActionRequest} interface,
048 * being able to access {@code MultipartFiles}. Note that this cast is only
049 * supported in case of an actual multipart request.
050 *
051 * <pre class="code"> public void handleActionRequest(ActionRequest request, ActionResponse response) {
052 *   MultipartActionRequest multipartRequest = (MultipartActionRequest) request;
053 *   MultipartFile multipartFile = multipartRequest.getFile("image");
054 *   ...
055 * }</pre>
056 *
057 * Instead of direct access, command or form controllers can register a
058 * {@link org.springframework.web.multipart.support.ByteArrayMultipartFileEditor}
059 * or {@link org.springframework.web.multipart.support.StringMultipartFileEditor}
060 * with their data binder, to automatically apply multipart content to form
061 * bean properties.
062 *
063 * <p>Note: There is hardly ever a need to access the {@code MultipartResolver}
064 * itself from application code. It will simply do its work behind the scenes,
065 * making {@code MultipartActionRequests} available to controllers.
066 *
067 * @author Juergen Hoeller
068 * @since 2.0
069 * @see MultipartActionRequest
070 * @see org.springframework.web.multipart.MultipartFile
071 * @see CommonsPortletMultipartResolver
072 * @see org.springframework.web.multipart.support.ByteArrayMultipartFileEditor
073 * @see org.springframework.web.multipart.support.StringMultipartFileEditor
074 * @see org.springframework.web.portlet.DispatcherPortlet
075 */
076public interface PortletMultipartResolver {
077
078        /**
079         * Determine if the given request contains multipart content.
080         * <p>Will typically check for content type
081         * "{@code multipart/form-data}", but the actually accepted requests
082         * might depend on the capabilities of the resolver implementation.
083         * @param request the portlet request to be evaluated
084         * @return whether the request contains multipart content
085         */
086        boolean isMultipart(ActionRequest request);
087
088        /**
089         * Parse the given portlet request into multipart files and parameters,
090         * and wrap the request inside a MultipartActionRequest object
091         * that provides access to file descriptors and makes contained
092         * parameters accessible via the standard PortletRequest methods.
093         * @param request the portlet request to wrap (must be of a multipart content type)
094         * @return the wrapped portlet request
095         * @throws org.springframework.web.multipart.MultipartException if the portlet request
096         * is not multipart, or if implementation-specific problems are encountered
097         * (such as exceeding file size limits)
098         * @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFile
099         * @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}