Package com.xpn.xwiki.plugin.fileupload

Class FileUploadPlugin

java.lang.Object

com.xpn.xwiki.plugin.XWikiDefaultPlugin

com.xpn.xwiki.plugin.fileupload.FileUploadPlugin

All Implemented Interfaces:

XWikiPluginInterface

public class FileUploadPlugin
extends XWikiDefaultPlugin

Plugin that offers access to uploaded files. The uploaded files are automatically parsed and preserved as a list of FileItems.

Version:

$Id: a2c8e3f2ad8ff824795bb4d56734745a2ae7d0b3 $

Field Summary

Fields

Modifier and Type	Field	Description
static String	FILE_LIST_KEY	The context name of the uploaded file list.
static String	PLUGIN_NAME	The name of the plugin; the key that can be used to retrieve this plugin from the context.
static long	UPLOAD_DEFAULT_MAXSIZE	The default maximum size for uploaded documents.
static String	UPLOAD_MAXSIZE_PARAMETER	The name of the parameter that can be set in the global XWiki preferences to override the default maximum file size.
static String	UPLOAD_SIZETHRESHOLD_PARAMETER	The name of the parameter that can be set in the global XWiki preferences to override the default size threshold for on-disk storage.

Constructor Summary

Constructors

Constructor	Description
FileUploadPlugin(String name, String className, XWikiContext context)

Method Summary

Modifier and Type	Method	Description
void	cleanFileList(XWikiContext context)	Deletes all temporary files of the upload.
void	endRendering(XWikiContext context)	Hook method, called after the 1.0 rendering engine finished processing a wiki document.
org.apache.commons.fileupload.FileItem	getFile(String formfieldName, XWikiContext context)	Return the FileItem corresponding to the file uploaded for a form field.
String	getFileItem(String formfieldName, XWikiContext context)	Deprecated. not well named, use getFileItemAsString(String, com.xpn.xwiki.XWikiContext)
String	getFileItemAsString(String formfieldName, XWikiContext context)	Allows to retrieve the contents of an uploaded file as a string.
byte[]	getFileItemData(String formfieldName, XWikiContext context)	Allows to retrieve the contents of an uploaded file as a sequence of bytes.
InputStream	getFileItemInputStream(String formfieldName, XWikiContext context)	Allows to retrieve the contents of an uploaded file as a stream.
List<String>	getFileItemNames(XWikiContext context)	Retrieves the list of FileItem names.
List<org.apache.commons.fileupload.FileItem>	getFileItems(XWikiContext context)	Allows to retrieve the current list of uploaded files, as a list of FileItems.
int	getFileItemSize(String formfieldName, XWikiContext context)	Retrieve the size of a file content in byte.
String	getFileName(String formfieldName, XWikiContext context)	Get the name of the file uploaded for a form field.
String	getName()	The name which can be used for accessing this plugin from XWiki.getPlugin(String, XWikiContext).
Api	getPluginApi(XWikiPluginInterface plugin, XWikiContext context)	Get a public scriptable API that can be used to call methods of the (privileged) plugin.
void	init(XWikiContext context)	Global initialization, called when the platform is started and the plugin list is initialized.
void	loadFileList(long uploadMaxSize, int uploadSizeThreshold, String tempdir, XWikiContext context)	Loads the list of uploaded files in the context if there are any uploaded files.
void	loadFileList(XWikiContext context)	Loads the list of uploaded files in the context if there are any uploaded files.
void	virtualInit(XWikiContext context)	Initialization method called each time a virtual wiki is started, allowing plugins to perform initialization tasks needed in each wiki.

Methods inherited from class com.xpn.xwiki.plugin.XWikiDefaultPlugin

beginParsing, beginRendering, commonTagsHandler, downloadAttachment, endParsing, endRenderingHandler, flushCache, flushCache, getClassName, getLocalization, insidePREHandler, localizePlainOrKey, outsidePREHandler, setClassName, setName, startRenderingHandler

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PLUGIN_NAME

public static final String PLUGIN_NAME

The name of the plugin; the key that can be used to retrieve this plugin from the context.

See Also:

XWikiPluginInterface.getName(), Constant Field Values

FILE_LIST_KEY

public static final String FILE_LIST_KEY

The context name of the uploaded file list. It can be used to retrieve the list of uploaded files from the context. Note that the order of the list is not guaranteed and might depend of the servlet engine used.

See Also:

Constant Field Values

UPLOAD_MAXSIZE_PARAMETER

public static final String UPLOAD_MAXSIZE_PARAMETER

The name of the parameter that can be set in the global XWiki preferences to override the default maximum file size.

See Also:

Constant Field Values

UPLOAD_DEFAULT_MAXSIZE

public static final long UPLOAD_DEFAULT_MAXSIZE

The default maximum size for uploaded documents. This limit can be changed using the upload_maxsize XWiki preference.

See Also:

Constant Field Values

UPLOAD_SIZETHRESHOLD_PARAMETER

public static final String UPLOAD_SIZETHRESHOLD_PARAMETER

The name of the parameter that can be set in the global XWiki preferences to override the default size threshold for on-disk storage.

See Also:

Constant Field Values

Constructor Detail

FileUploadPlugin

public FileUploadPlugin(String name,
                        String className,
                        XWikiContext context)

Parameters:

name - the plugin name

className - the plugin classname (used in logs for example)

context - the XWiki Context

See Also:

XWikiDefaultPlugin(String,String,com.xpn.xwiki.XWikiContext)

Method Detail

getName

public String getName()

Description copied from interface: XWikiPluginInterface

The name which can be used for accessing this plugin from XWiki.getPlugin(String, XWikiContext).

Specified by:

getName in interface XWikiPluginInterface

Overrides:

getName in class XWikiDefaultPlugin

Returns:

the plugin name, usually a lowercase identifier

init

public void init(XWikiContext context)

Description copied from interface: XWikiPluginInterface

Global initialization, called when the platform is started and the plugin list is initialized.

Specified by:

init in interface XWikiPluginInterface

Overrides:

init in class XWikiDefaultPlugin

Parameters:

context - the current context, should not be stored since it will become mostly unreliable once the initial request is terminated

virtualInit

public void virtualInit(XWikiContext context)

Description copied from interface: XWikiPluginInterface

Initialization method called each time a virtual wiki is started, allowing plugins to perform initialization tasks needed in each wiki.

Specified by:

virtualInit in interface XWikiPluginInterface

Overrides:

virtualInit in class XWikiDefaultPlugin

Parameters:

context - the current request context

getPluginApi

public Api getPluginApi(XWikiPluginInterface plugin,
                        XWikiContext context)

Description copied from interface: XWikiPluginInterface

Get a public scriptable API that can be used to call methods of the (privileged) plugin.

Specified by:

getPluginApi in interface XWikiPluginInterface

Overrides:

getPluginApi in class XWikiDefaultPlugin

Parameters:

plugin - the plugin instance to wrap

context - the current request context

Returns:

an instance of the corresponding API, or null if the plugin doesn't want to expose a public API

endRendering

public void endRendering(XWikiContext context)

Hook method, called after the 1.0 rendering engine finished processing a wiki document. This allows a plugin to clean up its per-rendering variables, or to modify the (velocity) context. This method can be called multiple times per request, once for each time the 1.0 rendering engine is invoked. At this point the content is processed by all of the rendering components and is ready to be included in the response.

Make sure we don't leave files in temp directories and in memory.

Specified by:

endRendering in interface XWikiPluginInterface

Overrides:

endRendering in class XWikiDefaultPlugin

Parameters:

context - the current request context

See Also:

allows to also alter the rendering result

cleanFileList

public void cleanFileList(XWikiContext context)

Deletes all temporary files of the upload.

Parameters:

context - Context of the request.

See Also:

FileUploadPluginApi.cleanFileList()

loadFileList

public void loadFileList(XWikiContext context)
                  throws XWikiException,
                         AttachmentValidationException

Loads the list of uploaded files in the context if there are any uploaded files.

Parameters:

context - Context of the request.

Throws:

XWikiException - An XWikiException is thrown if the request could not be parsed.

AttachmentValidationException - in case of error when validating the attachment (e.g., the maximum filesize is reached)

See Also:

FileUploadPluginApi.loadFileList()

loadFileList

public void loadFileList(long uploadMaxSize,
                         int uploadSizeThreshold,
                         String tempdir,
                         XWikiContext context)
                  throws XWikiException,
                         AttachmentValidationException

Loads the list of uploaded files in the context if there are any uploaded files.

Parameters:

uploadMaxSize - Maximum size of the uploaded files.

uploadSizeThreshold - the threshold over which the file data should be stored on disk, and not in memory.

tempdir - Temporary directory to store the uploaded files that are not kept in memory.

context - Context of the request.

Throws:

XWikiException - if the request could not be parsed, or the maximum file size was reached

AttachmentValidationException - in case of error when validating the attachment (e.g., the maximum filesize is reached)

See Also:

FileUploadPluginApi.loadFileList(long, int, String)

getFileItems

public List<org.apache.commons.fileupload.FileItem> getFileItems(XWikiContext context)

Allows to retrieve the current list of uploaded files, as a list of FileItems. loadFileList(XWikiContext) needs to be called beforehand. Note that the order of this list is not guaranteed and might be different depending on the servlet engine used.

Parameters:

context - Context of the request.

Returns:

A list of FileItem elements.

See Also:

FileUploadPluginApi.getFileItems()

getFileItemData

public byte[] getFileItemData(String formfieldName,
                              XWikiContext context)
                       throws XWikiException

Allows to retrieve the contents of an uploaded file as a sequence of bytes. loadFileList(XWikiContext) needs to be called beforehand.

Parameters:

formfieldName - The name of the form field.

context - Context of the request.

Returns:

The contents of the file.

Throws:

XWikiException - if the data could not be read.

See Also:

FileUploadPluginApi.getFileItemData(String)

getFileItemInputStream

public InputStream getFileItemInputStream(String formfieldName,
                                          XWikiContext context)
                                   throws IOException

Allows to retrieve the contents of an uploaded file as a stream. loadFileList(XWikiContext) needs to be called beforehand.

Parameters:

formfieldName - The name of the form field.

context - Context of the request.

Returns:

a InputStream on the file content

Throws:

IOException - if I/O problem occurs

Since:

2.3M2

getFileItemSize

public int getFileItemSize(String formfieldName,
                           XWikiContext context)

Retrieve the size of a file content in byte. loadFileList(XWikiContext) needs to be called beforehand.

Parameters:

formfieldName - The name of the form field.

context - Context of the request.

Returns:

the size of the file in byte

Since:

2.3M2

getFileItemAsString

public String getFileItemAsString(String formfieldName,
                                  XWikiContext context)
                           throws XWikiException

Allows to retrieve the contents of an uploaded file as a string. loadFileList(XWikiContext) needs to be called beforehand.

Parameters:

formfieldName - The name of the form field.

context - Context of the request.

Returns:

The contents of the file.

Throws:

XWikiException - if the data could not be read.

See Also:

FileUploadPluginApi.getFileItemAsString(String)

getFileItem

@Deprecated
public String getFileItem(String formfieldName,
                          XWikiContext context)
                   throws XWikiException

Deprecated.

not well named, use getFileItemAsString(String, com.xpn.xwiki.XWikiContext)

Allows to retrieve the contents of an uploaded file as a string. loadFileList(XWikiContext) needs to be called beforehand.

Parameters:

formfieldName - The name of the form field.

context - Context of the request.

Returns:

The contents of the file.

Throws:

XWikiException - Exception is thrown if the data could not be read.

See Also:

FileUploadPluginApi.getFileItemAsString(String)

getFileItemNames

public List<String> getFileItemNames(XWikiContext context)

Retrieves the list of FileItem names. loadFileList(XWikiContext) needs to be called beforehand.

Parameters:

context - Context of the request

Returns:

List of strings of the item names

getFileName

public String getFileName(String formfieldName,
                          XWikiContext context)

Get the name of the file uploaded for a form field.

Parameters:

formfieldName - The name of the form field.

context - Context of the request.

Returns:

The file name, or null if no file was uploaded for that form field.

getFile

public org.apache.commons.fileupload.FileItem getFile(String formfieldName,
                                                      XWikiContext context)

Return the FileItem corresponding to the file uploaded for a form field.

Parameters:

formfieldName - The name of the form field.

context - Context of the request.

Returns:

The corresponding FileItem, or null if no file was uploaded for that form field.