com.phloc.web.fileupload.IFileItem Maven / Gradle / Ivy
/**
* Copyright (C) 2006-2015 phloc systems
* http://www.phloc.com
* office[at]phloc[dot]com
*
* 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.
*/
package com.phloc.web.fileupload;
import java.io.File;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Serializable;
import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;
import jakarta.activation.DataSource;
import javax.annotation.Nonnull;
import com.phloc.commons.state.ISuccessIndicator;
/**
*
* 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
* {@link com.phloc.web.fileupload.FileUpload FileUpload} instance (see
* {@link com.phloc.web.fileupload.servlet.ServletFileUpload#parseRequest(jakarta.servlet.http.HttpServletRequest)}
* ), 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.
*
* 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.
*
* @author Rafal Krzewski
* @author Sean Legassick
* @author Jason van Zyl
* @author Martin Cooper
* @version $Id: FileItem.java 963609 2010-07-13 06:56:47Z jochen $
*/
public interface IFileItem extends Serializable, DataSource
{
// ------------------------------- Methods from javax.activation.DataSource
/**
* 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.
*/
InputStream getInputStream ();
/**
* 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 contensts of the file.
*/
OutputStream getOutputStream ();
/**
* Returns the content type passed by the browser or null if not
* defined.
*
* @return The content type passed by the browser or null if not
* defined.
*/
String getContentType ();
/**
* Returns the original filename in the client's filesystem, 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 filename in the client's filesystem.
* @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.
*
* @return true if the file contents will be read from memory;
* false otherwise.
*/
boolean isInMemory ();
/**
* 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.
*
* @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 {@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.
*/
@Nonnull
String getString (String encoding) throws UnsupportedEncodingException;
/**
* 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 aEncoding
* The character encoding to use.
* @return The contents of the item, as a string.
*/
@Nonnull
String getString (@Nonnull Charset aEncoding);
/**
* 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.
*
* @param file
* The File into which the uploaded item should be stored.
* @return Never null
* @throws FileUploadException
* if an error occurs.
*/
@Nonnull
ISuccessIndicator write (@Nonnull File file) throws FileUploadException;
/**
* 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.
*/
void delete ();
/**
* 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.
*
* @param name
* The name of the form field.
*/
void setFieldName (String name);
/**
* Determines whether or not a FileItem instance represents a
* simple form field.
*
* @return true if the instance represents a simple form field;
* false if it represents an uploaded file.
*/
boolean isFormField ();
/**
* Specifies whether or not a FileItem instance represents a
* simple form field.
*
* @param state
* true if the instance represents a simple form field;
* false if it represents an uploaded file.
*/
void setFormField (boolean state);
}