/*
* Copyright 2002-2007 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.web.portlet.multipart;
import javax.portlet.ActionRequest;
import org.springframework.web.multipart.MultipartException;
/**
* Portlet version of Spring's multipart resolution strategy for file uploads
* as defined in <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>.
*
* <p>Implementations are typically usable both within any application context
* and standalone.
*
* <p>There is one concrete implementation included in Spring:
* <ul>
* <li>{@link org.springframework.web.multipart.commons.CommonsMultipartResolver}
* for Jakarta Commons FileUpload
* </ul>
*
* <p>There is no default resolver implementation used for Spring
* {@link org.springframework.web.portlet.DispatcherPortlet DispatcherPortlets},
* as an application might choose to parse its multipart requests itself. To
* define an implementation, create a bean with the id
* {@link org.springframework.web.portlet.DispatcherPortlet#MULTIPART_RESOLVER_BEAN_NAME "portletMultipartResolver"}
* in a <code>DispatcherPortlet's</code> application context. Such a resolver
* gets applied to all requests handled by that <code>DispatcherPortlet</code>.
*
* <p>If a <code>DispatcherPortlet</code> detects a multipart request, it will
* resolve it via the configured
* {@link org.springframework.web.multipart.MultipartResolver} and pass on a
* wrapped Portlet {@link ActionRequest}.
* {@link org.springframework.web.portlet.mvc.Controller Controllers} can then
* cast their given request to the {@link MultipartActionRequest} interface,
* being able to access <code>MultipartFiles</code>. Note that this cast is
* only supported in case of an actual multipart request.
*
* <pre class="code"> public void handleActionRequest(ActionRequest request, ActionResponse response) {
* MultipartActionRequest multipartRequest = (MultipartActionRequest) request;
* MultipartFile multipartFile = multipartRequest.getFile("image");
* ...
* }</pre>
*
* Instead of direct access, command or form controllers can register a
* {@link org.springframework.web.multipart.support.ByteArrayMultipartFileEditor}
* or {@link org.springframework.web.multipart.support.StringMultipartFileEditor}
* with their data binder, to automatically apply multipart content to command
* bean properties.
*
* <p>Note: There is hardly ever a need to access the
* <code>MultipartResolver</code> itself from application code. It will simply
* do its work behind the scenes, making <code>MultipartActionRequests</code>
* available to controllers.
*
* @author Juergen Hoeller
* @since 2.0
* @see MultipartActionRequest
* @see org.springframework.web.multipart.MultipartFile
* @see CommonsPortletMultipartResolver
* @see org.springframework.web.multipart.support.ByteArrayMultipartFileEditor
* @see org.springframework.web.multipart.support.StringMultipartFileEditor
* @see org.springframework.web.portlet.DispatcherPortlet
*/
public interface PortletMultipartResolver {
/**
* Determine if the given request contains multipart content.
* <p>Will typically check for content type
* "<code>multipart/form-data</code>", but the actually accepted requests
* might depend on the capabilities of the resolver implementation.
* @param request the portlet request to be evaluated
* @return whether the request contains multipart content
*/
boolean isMultipart(ActionRequest request);
/**
* Parse the given portlet request into multipart files and parameters,
* and wrap the request inside a MultipartActionRequest object
* that provides access to file descriptors and makes contained
* parameters accessible via the standard PortletRequest methods.
* @param request the portlet request to wrap (must be of a multipart content type)
* @return the wrapped portlet request
* @throws org.springframework.web.multipart.MultipartException if the portlet request
* is not multipart, or if implementation-specific problems are encountered
* (such as exceeding file size limits)
* @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFile
* @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFileNames
* @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFileMap
* @see javax.portlet.ActionRequest#getParameter
* @see javax.portlet.ActionRequest#getParameterNames
* @see javax.portlet.ActionRequest#getParameterMap
*/
MultipartActionRequest resolveMultipart(ActionRequest request) throws MultipartException;
/**
* Cleanup any resources used for the multipart handling,
* such as storage for any uploaded file(s).
* @param request the request to cleanup resources for
*/
void cleanupMultipart(MultipartActionRequest request);
}