MultiPartFile

back

/*
 * Copyright 2002-2018 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.
 */

/*
 *版权所有2002-2018的原始作者。
 *
 *根据Apache许可2.0版（“许可”）获得许可；
 *未经许可，您不得使用此文件。
 *您可以在以下位置获得许可的副本：
 *
 *http://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，否则软件
 *根据许可协议分发的内容是按“原样”分发的，
 *不作任何明示或暗示的保证或条件。
 *有关特定语言的管理权限，请参阅许可证
 *许可中的限制。
 */
package org.springframework.web.multipart;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;

import org.springframework.core.io.InputStreamSource;
import org.springframework.core.io.Resource;
import org.springframework.lang.Nullable;
import org.springframework.util.FileCopyUtils;

/**
 * A representation of an uploaded file received in a multipart request.
 *
 * <p>The file contents are either stored in memory or temporarily on disk.
 * In either case, the user is responsible for copying file contents to a
 * session-level or persistent store as and if desired. The temporary storage
 * will be cleared at the end of request processing.
 *
 * @author Juergen Hoeller
 * @author Trevor D. Cook
 * @since 29.09.2003
 * @see org.springframework.web.multipart.MultipartHttpServletRequest
 * @see org.springframework.web.multipart.MultipartResolver
 */
 /**
 *多部分请求中收到的上载文件的表示形式。
 *
 *<p>文件内容存储在内存中或临时存储在磁盘上。
 *在任何一种情况下，用户都有责任将文件内容复制到
 *根据需要在会话级别或持久性存储。临时存储
 *将在请求处理结束时清除。
 *
 *@作者Juergen Hoeller
 *@作者Trevor D.Cook
 *@ 2003年9月29日起
 *@see org.springframework.web.multipart.MultipartHttpServletRequest
 *@see org.springframework.web.multipart.MultipartResolver
 */
public interface MultipartFile extends InputStreamSource {

/**
* Return the name of the parameter in the multipart form.
* @return the name of the parameter (never {@code null} or empty)
*/
/**
*以多部分形式返回参数名称。
*@返回参数的名称（不要{@code null}或为空）
*/
String getName();

/**
    * Return the original filename in the client's filesystem.
    * <p>This may contain path information depending on the browser used,
    * but it typically will not with any other than Opera.
    * @return the original filename, or the empty String if no file has been chosen
    * in the multipart form, or {@code null} if not defined or not available
    * @see org.apache.commons.fileupload.FileItem#getName()
    * @see org.springframework.web.multipart.commons.CommonsMultipartFile#setPreserveFilename
    */
/**
    *返回客户端文件系统中的原始文件名。
    *<p>其中可能包含路径信息，具体取决于所使用的浏览器，
    *，但Opera除外。
    *@返回原始文件名，如果未选择文件，则返回空字符串
    *为多部分形式；如果未定义或不可用，则为{@code null}
    *@see org.apache.commons.fileupload.FileItem＃getName（）
    *@see org.springframework.web.multipart.commons.CommonsMultipartFile＃setPreserveFilename
    */
@Nullable
String getOriginalFilename();

/**
    * Return the content type of the file.
    * @return the content type, or {@code null} if not defined
    * (or no file has been chosen in the multipart form)
    */
/**
    *返回文件的内容类型。
    *@返回内容类型，如果未定义，则返回{@code null}
    *（或没有以多部分形式选择文件）
    */
@Nullable
String getContentType();

/**
    * Return whether the uploaded file is empty, that is, either no file has
    * been chosen in the multipart form or the chosen file has no content.
    */
boolean isEmpty();

/**
    * Return the size of the file in bytes.
    * @return the size of the file, or 0 if empty
    */
/**
    *返回文件的大小（以字节为单位）。
    *@返回文件的大小；如果为空，则返回0
    */
long getSize();

/**
    * Return the contents of the file as an array of bytes.
    * @return the contents of the file as bytes, or an empty byte array if empty
    * @throws IOException in case of access errors (if the temporary store fails)
    */
/**
    *以字节数组形式返回文件的内容。
    *@返回文件内容为字节，如果为空则返回一个空字节数组
    *@如果发生访问错误（如果临时存储失败），则抛出IOException
    */
byte[] getBytes() throws IOException;

/**
    * Return an InputStream to read the contents of the file from.
    * <p>The user is responsible for closing the returned stream.
    * @return the contents of the file as stream, or an empty stream if empty
    * @throws IOException in case of access errors (if the temporary store fails)
    */
/**
    *返回一个InputStream来从中读取文件的内容。
    *<p>用户负责关闭返回的流。
    *@将文件内容作为流返回，如果为空则返回空流
    *@如果发生访问错误（如果临时存储失败），则抛出IOException
    */
@Override
InputStream getInputStream() throws IOException;

/**
    * Return a Resource representation of this MultipartFile. This can be used
    * as input to the {@code RestTemplate} or the {@code WebClient} to expose
    * content length and the filename along with the InputStream.
    * @return this MultipartFile adapted to the Resource contract
    * @since 5.1
    */
/**
    *返回此MultipartFile的资源表示形式。可以用
    *作为{@code RestTemplate}或{@code WebClient}的输入以公开
    *内容长度和文件名以及InputStream。
    *@返回此MultipartFile以适应资源合同
    *@从5.1开始
    */
default Resource getResource() {
    return new MultipartFileResource(this);
}

/**
    * Transfer the received file to the given destination file.
    * <p>This may either move the file in the filesystem, copy the file in the
    * filesystem, or save memory-held contents to the destination file. If the
    * destination file already exists, it will be deleted first.
    * <p>If the target file has been moved in the filesystem, this operation
    * cannot be invoked again afterwards. Therefore, call this method just once
    * in order to work with any storage mechanism.
    * <p><b>NOTE:</b> Depending on the underlying provider, temporary storage
    * may be container-dependent, including the base directory for relative
    * destinations specified here (e.g. with Servlet 3.0 multipart handling).
    * For absolute destinations, the target file may get renamed/moved from its
    * temporary location or newly copied, even if a temporary copy already exists.
    * @param dest the destination file (typically absolute)
    * @throws IOException in case of reading or writing errors
    * @throws IllegalStateException if the file has already been moved
    * in the filesystem and is not available anymore for another transfer
    * @see org.apache.commons.fileupload.FileItem#write(File)
    * @see javax.servlet.http.Part#write(String)
    */
/**
    *将接收到的文件传输到给定的目标文件。
    *<p>这可以将文件移动到文件系统中，也可以将文件复制到
    *文件系统，或将内存保存的内容保存到目标文件。如果
    *目标文件已存在，将首先删除。
    *<p>如果目标文件已在文件系统中移动，则此操作
    *之后无法再次调用。因此，只需调用一次此方法
    *为了与任何存储机制一起使用。
    *<p> <b>注意：</b>取决于基础提供程序，临时存储
    *可能与容器有关，包括相对的基本目录
    *在此指定的目的地（例如，使用Servlet 3.0多部分处理）。
    *对于绝对目的地，目标文件可能会从其重命名/移动
    *临时位置或新复制的，即使已经存在一个临时副本。
    *@param目标文件（通常是绝对文件）
    *@读取或写入错误时抛出IOException
    *@throws IllegalStateException如果文件已经被移动
    *在文件系统中，不再可用于其他传输
    *@see org.apache.commons.fileupload.FileItem＃write（文件）
    *@see javax.servlet.http.Part＃write（String）
    */
void transferTo(File dest) throws IOException, IllegalStateException;

/**
    * Transfer the received file to the given destination file.
    * <p>The default implementation simply copies the file input stream.
    * @since 5.1
    * @see #getInputStream()
    * @see #transferTo(File)
    */
/**
    *将接收到的文件传输到给定的目标文件。
    *<p>默认实现只是复制文件输入流。
    *@从5.1开始
    *@see #getInputStream（）
    *@请参阅#transferTo（文件）
    */
default void transferTo(Path dest) throws IOException, IllegalStateException {
    FileCopyUtils.copy(getInputStream(), Files.newOutputStream(dest));
}

}