IFileItem (ph-web 9.1.1 API)

All Superinterfaces:

DataSource, com.helger.commons.io.IHasInputStream, Serializable

All Known Implementing Classes:

DiskFileItem
```
public interface IFileItem
extends Serializable, DataSource, com.helger.commons.io.IHasInputStream
```
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 ServletFileUpload.parseRequest(javax.servlet.http.HttpServletRequest) ), you may either request all contents of the file at once using directGet() 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.

Version:

$Id: FileItem.java 963609 2010-07-13 06:56:47Z jochen $

Author:

Rafal Krzewski, Sean Legassick, Jason van Zyl, Martin Cooper

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`void`	`delete()` Deletes the underlying storage for a file item, including deleting any associated temporary disk file.
`byte[]`	`directGet()`
`String`	`getContentType()`
`String`	`getFieldName()` Returns the name of the field in the multipart form corresponding to this file item.
`InputStream`	`getInputStream()`
`String`	`getName()` Returns the original filename in the client's filesystem, as provided by the browser (or other client software).
`String`	`getNameSecure()` Returns the original filename in the client's filesystem, as provided by the browser (or other client software).
`String`	`getNameUnchecked()` Returns the original filename in the client's filesystem, as provided by the browser (or other client software).
`OutputStream`	`getOutputStream()`
`long`	`getSize()`
`String`	`getString()` Returns the contents of the file item as a String, using the default character encoding (if one provided, it is used).
`default String`	`getString(Charset aEncoding)` Returns the contents of the file item as a String, using the specified encoding.
`boolean`	`isFormField()` Determines whether or not a `FileItem` instance represents a simple form field.
`boolean`	`isInMemory()` Provides a hint as to whether or not the file contents will be read from memory.
`void`	`setFieldName(String sFieldName)` Sets the field name used to reference this file item.
`void`	`setFormField(boolean bIsFormField)` Specifies whether or not a `FileItem` instance represents a simple form field.
`com.helger.commons.state.ISuccessIndicator`	`write(File aDstFile)` A convenience method to write an uploaded item to disk.

Methods inherited from interface com.helger.commons.io.IHasInputStream
getBufferedInputStream, isReadMultiple

- Method Detail
  - getInputStream
```
@Nonnull
InputStream getInputStream()
```
    Specified by:
    
    getInputStream in interface DataSource
    
    Specified by:
    
    getInputStream in interface com.helger.commons.io.IHasInputStream
    
    Returns:
    
    An InputStream that can be used to retrieve the contents of the file.
  - getOutputStream
```
@Nonnull
OutputStream getOutputStream()
```
    Specified by:
    
    getOutputStream in interface DataSource
    
    Returns:
    
    An OutputStream that can be used for storing the contents of the file.
  - getContentType
```
@Nullable
String getContentType()
```
    Specified by:
    
    getContentType in interface DataSource
    
    Returns:
    
    The content type passed by the user agent or null if not defined.
  - getName
```
@Nullable
String getName()
```
    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.
    
    Specified by:
    
    getName in interface DataSource
    
    Returns:
    
    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().
  - getNameSecure
```
@Nullable
String getNameSecure()
```
    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. Compared to getName() this method automatically removes everything and including a NUL byte and therefore does not throw an InvalidFileNameException.
    
    Returns:
    
    The original filename in the client's filesystem without invalid characters.
    
    Since:
    
    6.1.0
  - getNameUnchecked
```
@Nullable
String getNameUnchecked()
```
    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.
    
    Returns:
    
    The original filename in the client's filesystem.
    
    Since:
    
    6.1.0
  - isInMemory
```
boolean isInMemory()
```
    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.
  - getSize
```
@Nonnegative
long getSize()
```
    Returns:
    
    The size of the file item, in bytes.
  - directGet
```
byte[] directGet()
```
    Returns:
    
    The contents of the file item as an array of bytes.
  - getString
```
@Nonnull
default String getString(@Nonnull
                                   Charset aEncoding)
```
    Returns the contents of the file item as a String, using the specified encoding. This method uses directGet() to retrieve the contents of the item.
    
    Parameters:
    
    aEncoding - The character encoding to use.
    
    Returns:
    
    The contents of the item, as a string.
  - getString
```
@Nonnull
String getString()
```
    Returns the contents of the file item as a String, using the default character encoding (if one provided, it is used). This method uses directGet() to retrieve the contents of the item.
    
    Returns:
    
    The contents of the item, as a string.
  - write
```
@Nonnull
com.helger.commons.state.ISuccessIndicator write(@Nonnull
                                                           File aDstFile)
                                                    throws FileUploadException
```
    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.
    
    Parameters:
    
    aDstFile - The File into which the uploaded item should be stored.
    
    Returns:
    
    Never null
    
    Throws:
    
    FileUploadException - if an error occurs.
  - delete
```
void delete()
```
    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.
  - getFieldName
```
String getFieldName()
```
    Returns the name of the field in the multipart form corresponding to this file item.
    
    Returns:
    
    The name of the form field.
  - setFieldName
```
void setFieldName(String sFieldName)
```
    Sets the field name used to reference this file item.
    
    Parameters:
    
    sFieldName - The name of the form field.
  - isFormField
```
boolean isFormField()
```
    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.
  - setFormField
```
void setFormField(boolean bIsFormField)
```
    Specifies whether or not a FileItem instance represents a simple form field.
    
    Parameters:
    
    bIsFormField - true if the instance represents a simple form field; false if it represents an uploaded file.

Interface IFileItem

Method Summary

Methods inherited from interface com.helger.commons.io.IHasInputStream

Method Detail

getInputStream

getOutputStream

getContentType

getName

getNameSecure

getNameUnchecked

isInMemory

getSize

directGet

getString

getString

write

delete

getFieldName

setFieldName

isFormField

setFormField