Tomcat 10.1.19 · org.apache.tomcat.util.http.fileupload.FileItem

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 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.

Method Summary

Modifier and Type	Method and Description
public void	delete() Deletes the underlying storage for a file item, including deleting any associated temporary disk file.
public byte[]	Returns: The contents of the file item as an array of bytes. get() Returns the contents of the file item as an array of bytes.
public String	Returns: The content type passed by the browser or `null` if not defined. getContentType() Returns the content type passed by the browser or `null` if not defined.
public String	Returns: The name of the form field. getFieldName() Returns the name of the field in the multipart form corresponding to this file item.
public InputStream	Returns: An `InputStream` that can be used to retrieve the contents of the file. getInputStream() Returns an `InputStream` that can be used to retrieve the contents of the file.
public String	Returns: The original file name in the client's file system. getName() Returns the original file name in the client's file system, as provided by the browser (or other client software).
public OutputStream	Returns: An `OutputStream` that can be used for storing the contents of the file. getOutputStream() Returns an `OutputStream` that can be used for storing the contents of the file.
public long	Returns: The size of the file item, in bytes. getSize() Returns the size of the file item.
public String	Returns: The contents of the item, as a string. getString(String The character encoding to use. encoding) Returns the contents of the file item as a String, using the specified encoding.
public String	Returns: The contents of the item, as a string. getString() Returns the contents of the file item as a String, using the default character encoding.
public boolean	Returns: `true` if the instance represents a simple form field; `false` if it represents an uploaded file. isFormField() Determines whether or not a `FileItem` instance represents a simple form field.
public boolean	Returns: `true` if the file contents will be read from memory; `false` otherwise. isInMemory() Provides a hint as to whether or not the file contents will be read from memory.
public void	setFieldName(String The name of the form field. name) Sets the field name used to reference this file item.
public void	setFormField(boolean `true` if the instance represents a simple form field; `false` if it represents an uploaded file. state) Specifies whether or not a `FileItem` instance represents a simple form field.
public void	write(File The `File` into which the uploaded item should be stored. file) A convenience method to write an uploaded item to disk.

Inherited from org.apache.tomcat.util.http.fileupload.FileItemHeadersSupport:: getHeaders setHeaders

Method Detail

delete	back to summary
public 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.

get	back to summary
public byte[] get() throws UncheckedIOException Returns the contents of the file item as an array of bytes. Returns:byte[] The contents of the file item as an array of bytes. Exceptions UncheckedIOException: if an I/O error occurs

get

back to summary

public byte[] get() throws UncheckedIOException

Returns the contents of the file item as an array of bytes.

Returns:byte[]

The contents of the file item as an array of bytes.

Exceptions

UncheckedIOException:: if an I/O error occurs

getContentType back to summary

getContentType	back to summary
public String getContentType() Returns the content type passed by the browser or `null` if not defined. Returns:String The content type passed by the browser or `null` if not defined.

public String getContentType()

Returns the content type passed by the browser or null if not defined.

Returns:String: The content type passed by the browser or null if not defined.

getFieldName	back to summary
public String getFieldName() Returns the name of the field in the multipart form corresponding to this file item. Returns:String The name of the form field.

getFieldName

back to summary

public String getFieldName()

Returns the name of the field in the multipart form corresponding to this file item.

Returns:String: The name of the form field.

getInputStream back to summary

getInputStream	back to summary
public InputStream getInputStream() throws IOException Returns an `InputStream` that can be used to retrieve the contents of the file. Returns:InputStream An `InputStream` that can be used to retrieve the contents of the file. Exceptions IOException: if an error occurs.

public InputStream getInputStream() throws IOException

Returns an InputStream that can be used to retrieve the contents of the file.

Returns:InputStream

An InputStream that can be used to retrieve the contents of the file.

Exceptions

IOException:: if an error occurs.

getName	back to summary
public String getName() 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. Returns:String The original file name in the client's file system. Exceptions 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().

getName

back to summary

public String getName()

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.

Returns:String

The original file name in the client's file system.

Exceptions

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().

getOutputStream back to summary

getOutputStream	back to summary
public OutputStream getOutputStream() throws IOException Returns an `OutputStream` that can be used for storing the contents of the file. Returns:OutputStream An `OutputStream` that can be used for storing the contents of the file. Exceptions IOException: if an error occurs.

public OutputStream getOutputStream() throws IOException

Returns an OutputStream that can be used for storing the contents of the file.

Returns:OutputStream

An OutputStream that can be used for storing the contents of the file.

Exceptions

IOException:: if an error occurs.

getSize	back to summary
public long getSize() Returns the size of the file item. Returns:long The size of the file item, in bytes.

getSize

back to summary

public long getSize()

Returns the size of the file item.

Returns:long: The size of the file item, in bytes.

getString back to summary

getString	back to summary
public String getString(String encoding) throws UnsupportedEncodingException, IOException 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. Parameters encoding:String The character encoding to use. Returns:String The contents of the item, as a string. Exceptions UnsupportedEncodingException: if the requested character encoding is not available. IOException: if an I/O error occurs

public String getString(String encoding) throws UnsupportedEncodingException, IOException

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.

Parameters

encoding:String: The character encoding to use.

Returns:String

The contents of the item, as a string.

Exceptions

UnsupportedEncodingException:: if the requested character encoding is not available.
IOException:: if an I/O error occurs

getString back to summary

getString	back to summary
public String getString() 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:String The contents of the item, as a string.

public String getString()

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:String: The contents of the item, as a string.

isFormField back to summary

isFormField	back to summary
public boolean isFormField() Determines whether or not a `FileItem` instance represents a simple form field. Returns:boolean `true` if the instance represents a simple form field; `false` if it represents an uploaded file.

public boolean isFormField()

Determines whether or not a FileItem instance represents a simple form field.

Returns:boolean: true if the instance represents a simple form field; false if it represents an uploaded file.

isInMemory back to summary

isInMemory	back to summary
public boolean isInMemory() Provides a hint as to whether or not the file contents will be read from memory. Returns:boolean `true` if the file contents will be read from memory; `false` otherwise.

public boolean isInMemory()

Provides a hint as to whether or not the file contents will be read from memory.

Returns:boolean: true if the file contents will be read from memory; false otherwise.

setFieldName	back to summary
public void setFieldName(String name) Sets the field name used to reference this file item. Parameters name:String The name of the form field.

setFieldName

back to summary

public void setFieldName(String name)

Sets the field name used to reference this file item.

Parameters

name:String: The name of the form field.

setFormField back to summary

setFormField	back to summary
public void setFormField(boolean state) Specifies whether or not a `FileItem` instance represents a simple form field. Parameters state:boolean `true` if the instance represents a simple form field; `false` if it represents an uploaded file.

public void setFormField(boolean state)

Specifies whether or not a FileItem instance represents a simple form field.

Parameters

state:boolean: true if the instance represents a simple form field; false if it represents an uploaded file.

write back to summary

write	back to summary
public void write(File file) throws Exception 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 file:File The `File` into which the uploaded item should be stored. Exceptions Exception: if an error occurs.

public void write(File file) throws Exception

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

file:File: The File into which the uploaded item should be stored.

Exceptions

Exception:: if an error occurs.

public Interface FileItem

Method Summary

Method Detail