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 java.io.File;
020: import java.io.IOException;
021: import java.io.InputStream;
022:
023: /**
024: * A representation of an uploaded file received in a multipart request.
025: *
026: * <p>The file contents are either stored in memory or temporarily on disk.
027: * In either case, the user is responsible for copying file contents to a
028: * session-level or persistent store as and if desired. The temporary storages
029: * will be cleared at the end of request processing.
030: *
031: * @author Juergen Hoeller
032: * @author Trevor D. Cook
033: * @since 29.09.2003
034: * @see org.springframework.web.multipart.MultipartHttpServletRequest
035: * @see org.springframework.web.multipart.MultipartResolver
036: */
037: public interface MultipartFile {
038:
039: /**
040: * Return the name of the parameter in the multipart form.
041: * @return the name of the parameter (never <code>null</code> or empty)
042: */
043: String getName();
044:
045: /**
046: * Return the original filename in the client's filesystem.
047: * <p>This may contain path information depending on the browser used,
048: * but it typically will not with any other than Opera.
049: * @return the original filename, or the empty String if no file
050: * has been chosen in the multipart form
051: */
052: String getOriginalFilename();
053:
054: /**
055: * Return the content type of the file.
056: * @return the content type, or <code>null</code> if not defined
057: * (or no file has been chosen in the multipart form)
058: */
059: String getContentType();
060:
061: /**
062: * Return whether the uploaded file is empty, that is, either no file has
063: * been chosen in the multipart form or the chosen file has no content.
064: */
065: boolean isEmpty();
066:
067: /**
068: * Return the size of the file in bytes.
069: * @return the size of the file, or 0 if empty
070: */
071: long getSize();
072:
073: /**
074: * Return the contents of the file as an array of bytes.
075: * @return the contents of the file as bytes, or an empty byte array if empty
076: * @throws IOException in case of access errors (if the temporary store fails)
077: */
078: byte[] getBytes() throws IOException;
079:
080: /**
081: * Return an InputStream to read the contents of the file from.
082: * The user is responsible for closing the stream.
083: * @return the contents of the file as stream, or an empty stream if empty
084: * @throws IOException in case of access errors (if the temporary store fails)
085: */
086: InputStream getInputStream() throws IOException;
087:
088: /**
089: * Transfer the received file to the given destination file.
090: * <p>This may either move the file in the filesystem, copy the file in the
091: * filesystem, or save memory-held contents to the destination file.
092: * If the destination file already exists, it will be deleted first.
093: * <p>If the file has been moved in the filesystem, this operation cannot
094: * be invoked again. Therefore, call this method just once to be able to
095: * work with any storage mechanism.
096: * @param dest the destination file
097: * @throws IOException in case of reading or writing errors
098: * @throws IllegalStateException if the file has already been moved
099: * in the filesystem and is not available anymore for another transfer
100: */
101: void transferTo(File dest) throws IOException,
102: IllegalStateException;
103:
104: }
|