001: /*
002: * Copyright 2002-2007 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: * http://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:
017: package org.springframework.web.portlet.multipart;
018:
019: import javax.portlet.ActionRequest;
020:
021: import 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="http://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 Jakarta 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
040: * {@link org.springframework.web.portlet.DispatcherPortlet#MULTIPART_RESOLVER_BEAN_NAME "portletMultipartResolver"}
041: * in a <code>DispatcherPortlet's</code> application context. Such a resolver
042: * gets applied to all requests handled by that <code>DispatcherPortlet</code>.
043: *
044: * <p>If a <code>DispatcherPortlet</code> detects a multipart request, it will
045: * resolve it via the configured
046: * {@link org.springframework.web.multipart.MultipartResolver} and pass on a
047: * wrapped Portlet {@link ActionRequest}.
048: * {@link org.springframework.web.portlet.mvc.Controller Controllers} can then
049: * cast their given request to the {@link MultipartActionRequest} interface,
050: * being able to access <code>MultipartFiles</code>. Note that this cast is
051: * only supported in case of an actual multipart request.
052: *
053: * <pre class="code"> public void handleActionRequest(ActionRequest request, ActionResponse response) {
054: * MultipartActionRequest multipartRequest = (MultipartActionRequest) request;
055: * MultipartFile multipartFile = multipartRequest.getFile("image");
056: * ...
057: * }</pre>
058: *
059: * Instead of direct access, command or form controllers can register a
060: * {@link org.springframework.web.multipart.support.ByteArrayMultipartFileEditor}
061: * or {@link org.springframework.web.multipart.support.StringMultipartFileEditor}
062: * with their data binder, to automatically apply multipart content to command
063: * bean properties.
064: *
065: * <p>Note: There is hardly ever a need to access the
066: * <code>MultipartResolver</code> itself from application code. It will simply
067: * do its work behind the scenes, making <code>MultipartActionRequests</code>
068: * available to controllers.
069: *
070: * @author Juergen Hoeller
071: * @since 2.0
072: * @see MultipartActionRequest
073: * @see org.springframework.web.multipart.MultipartFile
074: * @see CommonsPortletMultipartResolver
075: * @see org.springframework.web.multipart.support.ByteArrayMultipartFileEditor
076: * @see org.springframework.web.multipart.support.StringMultipartFileEditor
077: * @see org.springframework.web.portlet.DispatcherPortlet
078: */
079: public interface PortletMultipartResolver {
080:
081: /**
082: * Determine if the given request contains multipart content.
083: * <p>Will typically check for content type
084: * "<code>multipart/form-data</code>", but the actually accepted requests
085: * might depend on the capabilities of the resolver implementation.
086: * @param request the portlet request to be evaluated
087: * @return whether the request contains multipart content
088: */
089: boolean isMultipart(ActionRequest request);
090:
091: /**
092: * Parse the given portlet request into multipart files and parameters,
093: * and wrap the request inside a MultipartActionRequest object
094: * that provides access to file descriptors and makes contained
095: * parameters accessible via the standard PortletRequest methods.
096: * @param request the portlet request to wrap (must be of a multipart content type)
097: * @return the wrapped portlet request
098: * @throws org.springframework.web.multipart.MultipartException if the portlet request
099: * is not multipart, or if implementation-specific problems are encountered
100: * (such as exceeding file size limits)
101: * @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFile
102: * @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFileNames
103: * @see org.springframework.web.portlet.multipart.MultipartActionRequest#getFileMap
104: * @see javax.portlet.ActionRequest#getParameter
105: * @see javax.portlet.ActionRequest#getParameterNames
106: * @see javax.portlet.ActionRequest#getParameterMap
107: */
108: MultipartActionRequest resolveMultipart(ActionRequest request)
109: throws MultipartException;
110:
111: /**
112: * Cleanup any resources used for the multipart handling,
113: * such as storage for any uploaded file(s).
114: * @param request the request to cleanup resources for
115: */
116: void cleanupMultipart(MultipartActionRequest request);
117:
118: }
|