/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.apache.tomcat.util.http.fileupload;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.UnsupportedEncodingException;

 This class represents a file or form item that was received within a multipart/form-data POST request. 
 After retrieving an instance of this class from a FileUpload instance (see FileUploadBase.parseRequest(RequestContext)), you may either request all contents of the file at once using get() or request an InputStream with getInputStream() and process the file without attempting to load it into memory, which may come handy with large files. 
 While this interface does not extend javax.activation.DataSource per se (to avoid a seldom used dependency), several of the defined methods are specifically defined with the same signatures as methods in that interface. This allows an implementation of this interface to also implement javax.activation.DataSource with minimal additional work. 
Since:
1.3 additionally implements FileItemHeadersSupport/**
 * <p> This class represents a file or form item that was received within a
 * {@code multipart/form-data} POST request.
 *
 * <p> After retrieving an instance of this class from a {@link
 * org.apache.tomcat.util.http.fileupload.FileUpload FileUpload} instance (see
 * {@link org.apache.tomcat.util.http.fileupload.FileUpload
 * #parseRequest(RequestContext)}), you may
 * either request all contents of the file at once using {@link #get()} or
 * request an {@link java.io.InputStream InputStream} with
 * {@link #getInputStream()} and process the file without attempting to load
 * it into memory, which may come handy with large files.
 *
 * <p> While this interface does not extend
 * {@code javax.activation.DataSource} per se (to avoid a seldom used
 * dependency), several of the defined methods are specifically defined with
 * the same signatures as methods in that interface. This allows an
 * implementation of this interface to also implement
 * {@code javax.activation.DataSource} with minimal additional work.
 *
 * @since 1.3 additionally implements FileItemHeadersSupport
 */
public interface FileItem extends FileItemHeadersSupport {

    // ------------------------------- Methods from javax.activation.DataSource

    
Returns an InputStream that can be used to retrieve the contents of the file. 
Throws:
IOException – if an error occurs.
Returns:
An InputStream that can be used to retrieve the contents of the file./**
     * Returns an {@link java.io.InputStream InputStream} that can be
     * used to retrieve the contents of the file.
     *
     * @return An {@link java.io.InputStream InputStream} that can be
     *         used to retrieve the contents of the file.
     *
     * @throws IOException if an error occurs.
     */
    InputStream getInputStream() throws IOException;

    
Returns the content type passed by the browser or null if not defined. 
Returns:
The content type passed by the browser or null if not defined./**
     * Returns the content type passed by the browser or {@code null} if
     * not defined.
     *
     * @return The content type passed by the browser or {@code null} if
     *         not defined.
     */
    String getContentType();

    
Returns the original file name in the client's file system, as provided by
the browser (or other client software). In most cases, this will be the
base file name, without path information. However, some clients, such as
the Opera browser, do include path information.
Throws:
InvalidFileNameException – The file name contains a NUL character,
  which might be an indicator of a security attack. If you intend to
  use the file name anyways, catch the exception and use
  InvalidFileNameException#getName().
Returns:
The original file name in the client's file system./**
     * Returns the original file name in the client's file system, as provided by
     * the browser (or other client software). In most cases, this will be the
     * base file name, without path information. However, some clients, such as
     * the Opera browser, do include path information.
     *
     * @return The original file name in the client's file system.
     * @throws InvalidFileNameException The file name contains a NUL character,
     *   which might be an indicator of a security attack. If you intend to
     *   use the file name anyways, catch the exception and use
     *   InvalidFileNameException#getName().
     */
    String getName();

    // ------------------------------------------------------- FileItem methods

    
Provides a hint as to whether or not the file contents will be read
from memory.
Returns:
true if the file contents will be read from memory; false otherwise./**
     * Provides a hint as to whether or not the file contents will be read
     * from memory.
     *
     * @return {@code true} if the file contents will be read from memory;
     *         {@code false} otherwise.
     */
    boolean isInMemory();

    
Returns the size of the file item.
Returns:
The size of the file item, in bytes./**
     * Returns the size of the file item.
     *
     * @return The size of the file item, in bytes.
     */
    long getSize();

    
Returns the contents of the file item as an array of bytes.
Returns:
The contents of the file item as an array of bytes./**
     * Returns the contents of the file item as an array of bytes.
     *
     * @return The contents of the file item as an array of bytes.
     */
    byte[] get();

    
Returns the contents of the file item as a String, using the specified encoding. This method uses get() to retrieve the contents of the item. 
Params:
encoding – The character encoding to use.
Throws:
UnsupportedEncodingException – if the requested character
                                     encoding is not available.
Returns:
The contents of the item, as a string./**
     * Returns the contents of the file item as a String, using the specified
     * encoding.  This method uses {@link #get()} to retrieve the
     * contents of the item.
     *
     * @param encoding The character encoding to use.
     *
     * @return The contents of the item, as a string.
     *
     * @throws UnsupportedEncodingException if the requested character
     *                                      encoding is not available.
     */
    String getString(String encoding) throws UnsupportedEncodingException;

    
Returns the contents of the file item as a String, using the default character encoding. This method uses get() to retrieve the contents of the item. 
Returns:
The contents of the item, as a string./**
     * Returns the contents of the file item as a String, using the default
     * character encoding.  This method uses {@link #get()} to retrieve the
     * contents of the item.
     *
     * @return The contents of the item, as a string.
     */
    String getString();

    
A convenience method to write an uploaded item to disk. The client code
is not concerned with whether or not the item is stored in memory, or on
disk in a temporary location. They just want to write the uploaded item
to a file.

This method is not guaranteed to succeed if called more than once for
the same item. This allows a particular implementation to use, for
example, file renaming, where possible, rather than copying all of the
underlying data, thus gaining a significant performance benefit.
Params:
file – The File into which the uploaded item should be stored.
Throws:
Exception – if an error occurs./**
     * A convenience method to write an uploaded item to disk. The client code
     * is not concerned with whether or not the item is stored in memory, or on
     * disk in a temporary location. They just want to write the uploaded item
     * to a file.
     * <p>
     * This method is not guaranteed to succeed if called more than once for
     * the same item. This allows a particular implementation to use, for
     * example, file renaming, where possible, rather than copying all of the
     * underlying data, thus gaining a significant performance benefit.
     *
     * @param file The {@code File} into which the uploaded item should
     *             be stored.
     *
     * @throws Exception if an error occurs.
     */
    void write(File file) throws Exception;

    
Deletes the underlying storage for a file item, including deleting any associated temporary disk file. Although this storage will be deleted automatically when the FileItem instance is garbage collected, this method can be used to ensure that this is done at an earlier time, thus preserving system resources. /**
     * Deletes the underlying storage for a file item, including deleting any
     * associated temporary disk file. Although this storage will be deleted
     * automatically when the {@code FileItem} instance is garbage
     * collected, this method can be used to ensure that this is done at an
     * earlier time, thus preserving system resources.
     */
    void delete();

    
Returns the name of the field in the multipart form corresponding to
this file item.
Returns:
The name of the form field./**
     * Returns the name of the field in the multipart form corresponding to
     * this file item.
     *
     * @return The name of the form field.
     */
    String getFieldName();

    
Sets the field name used to reference this file item.
Params:
name – The name of the form field./**
     * Sets the field name used to reference this file item.
     *
     * @param name The name of the form field.
     */
    void setFieldName(String name);

    
Determines whether or not a FileItem instance represents a simple form field. 
Returns:
true if the instance represents a simple form field; false if it represents an uploaded file./**
     * Determines whether or not a {@code FileItem} instance represents
     * a simple form field.
     *
     * @return {@code true} if the instance represents a simple form
     *         field; {@code false} if it represents an uploaded file.
     */
    boolean isFormField();

    
Specifies whether or not a FileItem instance represents a simple form field. 
Params:
state – true if the instance represents a simple form field; false if it represents an uploaded file./**
     * Specifies whether or not a {@code FileItem} instance represents
     * a simple form field.
     *
     * @param state {@code true} if the instance represents a simple form
     *              field; {@code false} if it represents an uploaded file.
     */
    void setFormField(boolean state);

    
Returns an OutputStream that can be used for storing the contents of the file. 
Throws:
IOException – if an error occurs.
Returns:
An OutputStream that can be used for storing the contents of the file./**
     * Returns an {@link java.io.OutputStream OutputStream} that can
     * be used for storing the contents of the file.
     *
     * @return An {@link java.io.OutputStream OutputStream} that can be used
     *         for storing the contents of the file.
     *
     * @throws IOException if an error occurs.
     */
    OutputStream getOutputStream() throws IOException;

}