001: /*
002: * Copyright 2002-2006 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.multipart;
018:
019: import javax.servlet.http.HttpServletRequest;
020:
021: /**
022: * A strategy interface for multipart file upload resolution in accordance
023: * with <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>.
024: * Implementations are typically usable both within an application context
025: * and standalone.
026: *
027: * <p>There are two concrete implementations included in Spring:
028: * <ul>
029: * <li>{@link org.springframework.web.multipart.commons.CommonsMultipartResolver} for Jakarta Commons FileUpload
030: * <li>{@link org.springframework.web.multipart.cos.CosMultipartResolver} for Jason Hunter's COS (com.oreilly.servlet)
031: * </ul>
032: *
033: * <p>There is no default resolver implementation used for Spring
034: * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlets},
035: * as an application might choose to parse its multipart requests itself. To define
036: * an implementation, create a bean with the id "multipartResolver" in a
037: * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet's}
038: * application context. Such a resolver gets applied to all requests handled
039: * by that {@link org.springframework.web.servlet.DispatcherServlet}.
040: *
041: * <p>If a {@link org.springframework.web.servlet.DispatcherServlet} detects
042: * a multipart request, it will resolve it via the configured
043: * {@link org.springframework.web.multipart.MultipartResolver} and pass on a
044: * wrapped {@link javax.servlet.http.HttpServletRequest}.
045: * Controllers can then cast their given request to the
046: * {@link org.springframework.web.multipart.MultipartHttpServletRequest}
047: * interface, which permits access to any
048: * {@link org.springframework.web.multipart.MultipartFile MultipartFiles}.
049: * Note that this cast is only supported in case of an actual multipart request.
050: *
051: * <pre class="code">
052: * public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) {
053: * MultipartHttpServletRequest multipartRequest = (MultipartHttpServletRequest) request;
054: * MultipartFile multipartFile = multipartRequest.getFile("image");
055: * ...
056: * }</pre>
057: *
058: * Instead of direct access, command or form controllers can register a
059: * {@link org.springframework.web.multipart.support.ByteArrayMultipartFileEditor}
060: * or {@link org.springframework.web.multipart.support.StringMultipartFileEditor}
061: * with their data binder, to automatically apply multipart content to command
062: * bean properties.
063: *
064: * <p>As an alternative to using a
065: * {@link org.springframework.web.multipart.MultipartResolver} with a
066: * {@link org.springframework.web.servlet.DispatcherServlet},
067: * a {@link org.springframework.web.multipart.support.MultipartFilter} can be
068: * registered in <code>web.xml</code>. It will delegate to a corresponding
069: * {@link org.springframework.web.multipart.MultipartResolver} bean in the root
070: * application context. This is mainly intended for applications that do not
071: * use Spring's own web MVC framework.
072: *
073: * <p>Note: There is hardly ever a need to access the
074: * {@link org.springframework.web.multipart.MultipartResolver} itself
075: * from application code. It will simply do its work behind the scenes,
076: * making
077: * {@link org.springframework.web.multipart.MultipartHttpServletRequest MultipartHttpServletRequests}
078: * available to controllers.
079: *
080: * @author Juergen Hoeller
081: * @author Trevor D. Cook
082: * @since 29.09.2003
083: * @see MultipartHttpServletRequest
084: * @see MultipartFile
085: * @see org.springframework.web.multipart.commons.CommonsMultipartResolver
086: * @see org.springframework.web.multipart.cos.CosMultipartResolver
087: * @see org.springframework.web.multipart.support.ByteArrayMultipartFileEditor
088: * @see org.springframework.web.multipart.support.StringMultipartFileEditor
089: * @see org.springframework.web.servlet.DispatcherServlet
090: */
091: public interface MultipartResolver {
092:
093: /**
094: * Determine if the given request contains multipart content.
095: * <p>Will typically check for content type "multipart/form-data", but the actually
096: * accepted requests might depend on the capabilities of the resolver implementation.
097: * @param request the servlet request to be evaluated
098: * @return whether the request contains multipart content
099: */
100: boolean isMultipart(HttpServletRequest 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(
120: HttpServletRequest request) throws MultipartException;
121:
122: /**
123: * Cleanup any resources used for the multipart handling,
124: * like a storage for the uploaded files.
125: * @param request the request to cleanup resources for
126: */
127: void cleanupMultipart(MultipartHttpServletRequest request);
128:
129: }
|