Tomcat 10.1.19 · org.apache.tomcat.util.http.fileupload.disk.DiskFileItem

Field Summary

Modifier and Type	Field and Description
private byte[]	cachedContent Cached contents of the file.
private final String	contentType The content type passed by the browser, or `null` if not defined.
private static final AtomicInteger	COUNTER Counter used in unique identifier generation.
public static final String	DEFAULT_CHARSET Default content charset to be used when no explicit charset parameter is provided by the sender.
private String	defaultCharset Default content charset to be used when no explicit charset parameter is provided by the sender.
private transient DeferredFileOutputStream	dfos Output stream for this item.
private String	fieldName The name of the form field as provided by the browser.
private final String	fileName The original file name in the user's file system.
private FileItemHeaders	headers The file items headers.
private boolean	isFormField Whether or not this item is a simple form field.
private final File	repository The directory in which uploaded files will be stored, if stored on disk.
private long	size The size of the item, in bytes.
private final int	sizeThreshold The threshold above which uploads will be stored on disk.
private transient File	tempFile The temporary file to use.
private static final String	UID UID used in unique file name generation.

Constructor Summary

Access Constructor and Description

Access	Constructor and Description
public	DiskFileItem(final String The name of the form field. fieldName, final String The content type passed by the browser or `null` if not specified. contentType, final boolean Whether or not this item is a plain form field, as opposed to a file upload. isFormField, final String The original file name in the user's file system, or `null` if not specified. fileName, final int The threshold, in bytes, below which items will be retained in memory and above which they will be stored as a file. sizeThreshold, final File The data repository, which is the directory in which files will be created, should the item size exceed the threshold. repository) Constructs a new `DiskFileItem` instance.

public

DiskFileItem(final String

The name of the form field.

fieldName, final String

The content type passed by the browser or null if not specified.

contentType, final boolean

Whether or not this item is a plain form field, as opposed to a file upload.

isFormField, final String

The original file name in the user's file system, or null if not specified.

fileName, final int

The threshold, in bytes, below which items will be retained in memory and above which they will be stored as a file.

sizeThreshold, final File

The data repository, which is the directory in which files will be created, should the item size exceed the threshold.

repository)

Constructs a new DiskFileItem instance.

Method Summary

Modifier and Type	Method and Description
public void	delete() Implements org.apache.tomcat.util.http.fileupload.FileItem.delete. Deletes the underlying storage for a file item, including deleting any associated temporary disk file.
public byte[]	Returns: The contents of the file as an array of bytes or `null` if the data cannot be read get() Implements org.apache.tomcat.util.http.fileupload.FileItem.get. Returns the contents of the file as an array of bytes.
public String	Returns: The content charset passed by the agent or `null` if not defined. getCharSet() Returns the content charset passed by the agent or `null` if not defined.
public String	Returns: The content type passed by the agent or `null` if not defined. getContentType() Implements org.apache.tomcat.util.http.fileupload.FileItem.getContentType. Returns the content type passed by the agent or `null` if not defined.
public String	Returns: the default charset getDefaultCharset() Returns the default charset for use when no explicit charset parameter is provided by the sender.
public String	Returns: The name of the form field. getFieldName() Implements org.apache.tomcat.util.http.fileupload.FileItem.getFieldName. Returns the name of the field in the multipart form corresponding to this file item.
public FileItemHeaders	Returns: The file items headers. getHeaders() Implements org.apache.tomcat.util.http.fileupload.FileItemHeadersSupport.getHeaders. Returns the file item headers.
public InputStream	Returns: An `InputStream` that can be used to retrieve the contents of the file. getInputStream() Implements org.apache.tomcat.util.http.fileupload.FileItem.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() Implements org.apache.tomcat.util.http.fileupload.FileItem.getName. Returns the original file name in the client's file system.
public OutputStream	Returns: An `OutputStream` that can be used for storing the contents of the file. getOutputStream() Implements org.apache.tomcat.util.http.fileupload.FileItem.getOutputStream. Returns an `OutputStream` that can be used for storing the contents of the file.
public long	Returns: The size of the file, in bytes. getSize() Implements org.apache.tomcat.util.http.fileupload.FileItem.getSize. Returns the size of the file.
public File	Returns: The data file, or `null` if the data is stored in memory. getStoreLocation() Returns the `java.io.File` object for the `FileItem`'s data's temporary location on the disk.
public String	Returns: The contents of the file, as a string. getString(final String The charset to use. charset) Implements org.apache.tomcat.util.http.fileupload.FileItem.getString. Returns the contents of the file as a String, using the specified encoding.
public String	Returns: The contents of the file, as a string. getString() Implements org.apache.tomcat.util.http.fileupload.FileItem.getString. Returns the contents of the file as a String, using the default character encoding.
protected File	Returns: The `File` to be used for temporary storage. getTempFile() Creates and returns a `File` representing a uniquely named temporary file in the configured repository path.
private static String	Returns: A String with the non-random looking instance identifier. getUniqueId() Returns an identifier that is unique within the class loader used to load this class, but does not have random-like appearance.
public boolean	Returns: `true` if the instance represents a simple form field; `false` if it represents an uploaded file. isFormField() Implements org.apache.tomcat.util.http.fileupload.FileItem.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() Implements org.apache.tomcat.util.http.fileupload.FileItem.isInMemory. Provides a hint as to whether or not the file contents will be read from memory.
public void	setDefaultCharset(final String the default charset charset) Sets the default charset for use when no explicit charset parameter is provided by the sender.
public void	setFieldName(final String The name of the form field. fieldName) Implements org.apache.tomcat.util.http.fileupload.FileItem.setFieldName. Sets the field name used to reference this file item.
public void	setFormField(final boolean `true` if the instance represents a simple form field; `false` if it represents an uploaded file. state) Implements org.apache.tomcat.util.http.fileupload.FileItem.setFormField. Specifies whether or not a `FileItem` instance represents a simple form field.
public void	setHeaders(final FileItemHeaders The file items headers. pHeaders) Implements org.apache.tomcat.util.http.fileupload.FileItemHeadersSupport.setHeaders. Sets the file item headers.
public String	Returns: a string representation of this object. toString() Overrides java.lang.Object.toString. Returns a string representation of this object.
public void	write(final File The `File` into which the uploaded item should be stored. file) Implements org.apache.tomcat.util.http.fileupload.FileItem.write. A convenience method to write an uploaded item to disk.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

cachedContent	back to summary
private byte[] cachedContent Cached contents of the file.

contentType	back to summary
private final String contentType The content type passed by the browser, or `null` if not defined.

COUNTER	back to summary
private static final AtomicInteger COUNTER Counter used in unique identifier generation.

DEFAULT_CHARSET	back to summary
public static final String DEFAULT_CHARSET Default content charset to be used when no explicit charset parameter is provided by the sender. Media subtypes of the "text" type are defined to have a default charset value of "ISO-8859-1" when received via HTTP.

defaultCharset	back to summary
private String defaultCharset Default content charset to be used when no explicit charset parameter is provided by the sender.

dfos	back to summary
private transient DeferredFileOutputStream dfos Output stream for this item.

fieldName	back to summary
private String fieldName The name of the form field as provided by the browser.

fileName	back to summary
private final String fileName The original file name in the user's file system.

headers	back to summary
private FileItemHeaders headers The file items headers.

isFormField	back to summary
private boolean isFormField Whether or not this item is a simple form field.

repository	back to summary
private final File repository The directory in which uploaded files will be stored, if stored on disk.

size	back to summary
private long size The size of the item, in bytes. This is used to cache the size when a file item is moved from its original location.

sizeThreshold	back to summary
private final int sizeThreshold The threshold above which uploads will be stored on disk.

tempFile	back to summary
private transient File tempFile The temporary file to use.

UID	back to summary
private static final String UID UID used in unique file name generation.

Constructor Detail

DiskFileItem back to summary

DiskFileItem	back to summary
public DiskFileItem(final String fieldName, final String contentType, final boolean isFormField, final String fileName, final int sizeThreshold, final File repository) Constructs a new `DiskFileItem` instance. Parameters fieldName:String The name of the form field. contentType:String The content type passed by the browser or `null` if not specified. isFormField:boolean Whether or not this item is a plain form field, as opposed to a file upload. fileName:String The original file name in the user's file system, or `null` if not specified. sizeThreshold:int The threshold, in bytes, below which items will be retained in memory and above which they will be stored as a file. repository:File The data repository, which is the directory in which files will be created, should the item size exceed the threshold.

public DiskFileItem(final String fieldName, final String contentType, final boolean isFormField, final String fileName, final int sizeThreshold, final File repository)

Constructs a new DiskFileItem instance.

Parameters

fieldName:String: The name of the form field.
contentType:String: The content type passed by the browser or null if not specified.
isFormField:boolean: Whether or not this item is a plain form field, as opposed to a file upload.
fileName:String: The original file name in the user's file system, or null if not specified.
sizeThreshold:int: The threshold, in bytes, below which items will be retained in memory and above which they will be stored as a file.
repository:File: The data repository, which is the directory in which files will be created, should the item size exceed the threshold.

Method Detail

delete	back to summary
public void delete() Implements org.apache.tomcat.util.http.fileupload.FileItem.delete. Deletes the underlying storage for a file item, including deleting any associated temporary disk file. This method can be used to ensure that this is done at an earlier time, thus preserving system resources. Annotations @Override

delete

back to summary

public void delete()

Implements org.apache.tomcat.util.http.fileupload.FileItem.delete.

Deletes the underlying storage for a file item, including deleting any associated temporary disk file. This method can be used to ensure that this is done at an earlier time, thus preserving system resources.

Annotations

@Override

get back to summary

get	back to summary
public byte[] get() throws UncheckedIOException Implements org.apache.tomcat.util.http.fileupload.FileItem.get. Returns the contents of the file as an array of bytes. If the contents of the file were not yet cached in memory, they will be loaded from the disk storage and cached. Returns:byte[] The contents of the file as an array of bytes or `null` if the data cannot be read Annotations @Override Exceptions UncheckedIOException: if an I/O error occurs

public byte[] get() throws UncheckedIOException

Implements org.apache.tomcat.util.http.fileupload.FileItem.get.

Returns the contents of the file as an array of bytes. If the contents of the file were not yet cached in memory, they will be loaded from the disk storage and cached.

Returns:byte[]

The contents of the file as an array of bytes or null if the data cannot be read

Annotations

@Override

Exceptions

UncheckedIOException:: if an I/O error occurs

getCharSet back to summary

getCharSet	back to summary
public String getCharSet() Returns the content charset passed by the agent or `null` if not defined. Returns:String The content charset passed by the agent or `null` if not defined.

public String getCharSet()

Returns the content charset passed by the agent or null if not defined.

Returns:String: The content charset passed by the agent or null if not defined.

getContentType back to summary

getContentType	back to summary
public String getContentType() Implements org.apache.tomcat.util.http.fileupload.FileItem.getContentType. Returns the content type passed by the agent or `null` if not defined. Returns:String The content type passed by the agent or `null` if not defined. Annotations @Override

public String getContentType()

Implements org.apache.tomcat.util.http.fileupload.FileItem.getContentType.

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

Returns:String

The content type passed by the agent or null if not defined.

Annotations

@Override

getDefaultCharset	back to summary
public String getDefaultCharset() Returns the default charset for use when no explicit charset parameter is provided by the sender. Returns:String the default charset

getDefaultCharset

back to summary

public String getDefaultCharset()

Returns the default charset for use when no explicit charset parameter is provided by the sender.

Returns:String: the default charset

getFieldName back to summary

getFieldName	back to summary
public String getFieldName() Implements org.apache.tomcat.util.http.fileupload.FileItem.getFieldName. Returns the name of the field in the multipart form corresponding to this file item. Returns:String The name of the form field. Annotations @Override See Also `setFieldName(String)`

public String getFieldName()

Implements org.apache.tomcat.util.http.fileupload.FileItem.getFieldName.

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

Returns:String

The name of the form field.

Annotations

@Override

See Also

setFieldName(String)

getHeaders	back to summary
public FileItemHeaders getHeaders() Implements org.apache.tomcat.util.http.fileupload.FileItemHeadersSupport.getHeaders. Returns the file item headers. Returns:FileItemHeaders The file items headers. Annotations @Override

getHeaders

back to summary

public FileItemHeaders getHeaders()

Implements org.apache.tomcat.util.http.fileupload.FileItemHeadersSupport.getHeaders.

Returns the file item headers.

Returns:FileItemHeaders

The file items headers.

Annotations

@Override

getInputStream back to summary

getInputStream	back to summary
public InputStream getInputStream() throws IOException Implements org.apache.tomcat.util.http.fileupload.FileItem.getInputStream. 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. Annotations @Override Exceptions IOException: if an error occurs.

public InputStream getInputStream() throws IOException

Implements org.apache.tomcat.util.http.fileupload.FileItem.getInputStream.

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.

Annotations

@Override

Exceptions

IOException:: if an error occurs.

getName back to summary

getName	back to summary
public String getName() Implements org.apache.tomcat.util.http.fileupload.FileItem.getName. Returns the original file name in the client's file system. Returns:String The original file name in the client's file system. Annotations @Override 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 `org.apache.tomcat.util.http.fileupload.InvalidFileNameException#getName()`.

public String getName()

Implements org.apache.tomcat.util.http.fileupload.FileItem.getName.

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

Returns:String

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

Annotations

@Override

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 org.apache.tomcat.util.http.fileupload.InvalidFileNameException#getName().

getOutputStream back to summary

getOutputStream	back to summary
public OutputStream getOutputStream() Implements org.apache.tomcat.util.http.fileupload.FileItem.getOutputStream. 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. Annotations @Override

public OutputStream getOutputStream()

Implements org.apache.tomcat.util.http.fileupload.FileItem.getOutputStream.

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.

Annotations

@Override

getSize	back to summary
public long getSize() Implements org.apache.tomcat.util.http.fileupload.FileItem.getSize. Returns the size of the file. Returns:long The size of the file, in bytes. Annotations @Override

getSize

back to summary

public long getSize()

Implements org.apache.tomcat.util.http.fileupload.FileItem.getSize.

Returns the size of the file.

Returns:long

The size of the file, in bytes.

Annotations

@Override

getStoreLocation back to summary

getStoreLocation	back to summary
public File getStoreLocation() Returns the `java.io.File` object for the `FileItem`'s data's temporary location on the disk. Note that for `FileItem`s that have their data stored in memory, this method will return `null`. When handling large files, you can use `java.io.File#renameTo(java.io.File)` to move the file to new location without copying the data, if the source and destination locations reside within the same logical volume. Returns:File The data file, or `null` if the data is stored in memory.

public File getStoreLocation()

Returns the java.io.File object for the FileItem's data's temporary location on the disk. Note that for FileItems that have their data stored in memory, this method will return null. When handling large files, you can use java.io.File#renameTo(java.io.File) to move the file to new location without copying the data, if the source and destination locations reside within the same logical volume.

Returns:File: The data file, or null if the data is stored in memory.

getString back to summary

getString	back to summary
public String getString(final String charset) throws UnsupportedEncodingException, IOException Implements org.apache.tomcat.util.http.fileupload.FileItem.getString. Returns the contents of the file as a String, using the specified encoding. This method uses `get()` to retrieve the contents of the file. Parameters charset:String The charset to use. Returns:String The contents of the file, as a string. Annotations @Override Exceptions UnsupportedEncodingException: if the requested character encoding is not available. IOException: Doc from org.apache.tomcat.util.http.fileupload.FileItem.getString. if an I/O error occurs

public String getString(final String charset) throws UnsupportedEncodingException, IOException

Implements org.apache.tomcat.util.http.fileupload.FileItem.getString.

Returns the contents of the file as a String, using the specified encoding. This method uses get() to retrieve the contents of the file.

Parameters

charset:String: The charset to use.

Returns:String

The contents of the file, as a string.

Annotations

@Override

Exceptions

UnsupportedEncodingException:

if the requested character encoding is not available.

IOException:

Doc from org.apache.tomcat.util.http.fileupload.FileItem.getString.

if an I/O error occurs

getString back to summary

getString	back to summary
public String getString() Implements org.apache.tomcat.util.http.fileupload.FileItem.getString. Returns the contents of the file as a String, using the default character encoding. This method uses `get()` to retrieve the contents of the file Todo Consider making this method throw UnsupportedEncodingException. Returns:String The contents of the file, as a string. Annotations @Override

public String getString()

Implements org.apache.tomcat.util.http.fileupload.FileItem.getString.

Returns the contents of the file as a String, using the default character encoding. This method uses get() to retrieve the contents of the file

Todo

Consider making this method throw UnsupportedEncodingException.

Returns:String

The contents of the file, as a string.

Annotations

@Override

getTempFile back to summary

getTempFile	back to summary
protected File getTempFile() Creates and returns a `File` representing a uniquely named temporary file in the configured repository path. The lifetime of the file is tied to the lifetime of the `FileItem` instance; the file will be deleted when the instance is garbage collected. Note Subclasses that override this method must ensure that they return the same File each time. Returns:File The `File` to be used for temporary storage.

protected File getTempFile()

Creates and returns a File representing a uniquely named temporary file in the configured repository path. The lifetime of the file is tied to the lifetime of the FileItem instance; the file will be deleted when the instance is garbage collected.

Note

Subclasses that override this method must ensure that they return the same File each time.

Returns:File: The File to be used for temporary storage.

getUniqueId	back to summary
private static String getUniqueId() Returns an identifier that is unique within the class loader used to load this class, but does not have random-like appearance. Returns:String A String with the non-random looking instance identifier.

getUniqueId

back to summary

private static String getUniqueId()

Returns an identifier that is unique within the class loader used to load this class, but does not have random-like appearance.

Returns:String: A String with the non-random looking instance identifier.

isFormField back to summary

isFormField	back to summary
public boolean isFormField() Implements org.apache.tomcat.util.http.fileupload.FileItem.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. Annotations @Override See Also `setFormField(boolean)`

public boolean isFormField()

Implements org.apache.tomcat.util.http.fileupload.FileItem.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.

Annotations

@Override

See Also

setFormField(boolean)

isInMemory back to summary

isInMemory	back to summary
public boolean isInMemory() Implements org.apache.tomcat.util.http.fileupload.FileItem.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. Annotations @Override

public boolean isInMemory()

Implements org.apache.tomcat.util.http.fileupload.FileItem.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.

Annotations

@Override

setDefaultCharset	back to summary
public void setDefaultCharset(final String charset) Sets the default charset for use when no explicit charset parameter is provided by the sender. Parameters charset:String the default charset

setDefaultCharset

back to summary

public void setDefaultCharset(final String charset)

Sets the default charset for use when no explicit charset parameter is provided by the sender.

Parameters

charset:String: the default charset

setFieldName back to summary

setFieldName	back to summary
public void setFieldName(final String fieldName) Implements org.apache.tomcat.util.http.fileupload.FileItem.setFieldName. Sets the field name used to reference this file item. Parameters fieldName:String The name of the form field. Annotations @Override See Also `getFieldName()`

public void setFieldName(final String fieldName)

Implements org.apache.tomcat.util.http.fileupload.FileItem.setFieldName.

Sets the field name used to reference this file item.

Parameters

fieldName:String: The name of the form field.

Annotations

@Override

See Also

getFieldName()

setFormField back to summary

setFormField	back to summary
public void setFormField(final boolean state) Implements org.apache.tomcat.util.http.fileupload.FileItem.setFormField. 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. Annotations @Override See Also `isFormField()`

public void setFormField(final boolean state)

Implements org.apache.tomcat.util.http.fileupload.FileItem.setFormField.

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.

Annotations

@Override

See Also

isFormField()

setHeaders	back to summary
public void setHeaders(final FileItemHeaders pHeaders) Implements org.apache.tomcat.util.http.fileupload.FileItemHeadersSupport.setHeaders. Sets the file item headers. Parameters pHeaders:FileItemHeaders The file items headers. Annotations @Override

setHeaders

back to summary

public void setHeaders(final FileItemHeaders pHeaders)

Implements org.apache.tomcat.util.http.fileupload.FileItemHeadersSupport.setHeaders.

Sets the file item headers.

Parameters

pHeaders:FileItemHeaders: The file items headers.

Annotations

@Override

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Returns a string representation of this object. Returns:String a string representation of this object. Annotations @Override

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Returns a string representation of this object.

Returns:String

a string representation of this object.

Annotations

@Override

write back to summary

write	back to summary
public void write(final File file) throws Exception Implements org.apache.tomcat.util.http.fileupload.FileItem.write. 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 implementation first attempts to rename the uploaded item to the specified destination file, if the item was originally written to disk. Otherwise, the data will be copied to the specified file. This method is only guaranteed to work once, the first time it is invoked for a particular item. This is because, in the event that the method renames a temporary file, that file will no longer be available to copy or rename again at a later time. Parameters file:File The `File` into which the uploaded item should be stored. Annotations @Override Exceptions Exception: if an error occurs.

public void write(final File file) throws Exception

Implements org.apache.tomcat.util.http.fileupload.FileItem.write.

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 implementation first attempts to rename the uploaded item to the specified destination file, if the item was originally written to disk. Otherwise, the data will be copied to the specified file.

This method is only guaranteed to work once, the first time it is invoked for a particular item. This is because, in the event that the method renames a temporary file, that file will no longer be available to copy or rename again at a later time.

Parameters

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

Annotations

@Override

Exceptions

Exception:: if an error occurs.

public Class DiskFileItem

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail