org.wings
Class SFileChooser

java.lang.Object
  org.wings.SComponent
      org.wings.SFileChooser

All Implemented Interfaces:

Serializable, Cloneable, EventListener, SParentFrameListener, LowLevelEventListener, Renderable

public class SFileChooser
extends SComponent
implements LowLevelEventListener, SParentFrameListener

Shows a textfield with a browse-button to enter a filename. The file is uploaded via HTTP and made accessible to the WingS application.

The uploaded file is stored temporarily in the filesystem of the server with a unique name, so that uploaded files with the same filename do not clash. You can access this internal name with the getFileDir() and getFileId() methods. The user provided filename can be queried with the getFileName() method.

Since the file is stored temporarily in the filesystem, you should File.delete() it, when you are done with it. However, if you don't delete the file yourself, it is eventually being removed by the Java garbage collector, if you haven't renamed it (see getFile()).

The form, you add this SFileChooser to, needs to have the encoding type multipart/form-data set (form.setEncodingType("multipart/form-data")). This is handled by the form. You can explicitly set it via the above method, though, in order to increase speed.

You can limit the size of files to be uploaded, so it is hard to make a denial-of-service (harddisk, bandwidth) attack from outside to your server. You can modify the maximum content length to be posted in Session.setMaxContentLength(int). This is 64 kByte by default, so you might want to change this in your application.

The SFileChooser notifies the form if something has gone wrong with uploading a file.

Szenario Files that are too big to be uploaded are blocked very early in the upload-process (if you are curious: this is done in MultipartRequest). At that time, only a partial input is read, the rest is discarded to thwart denial of service attacks. Since we read only part of the input, we cannot make sure, that all parameters are gathered from the input, thus we cannot just deliver the events contained, since they might be incomplete. However, the file chooser needs to be informed, that something went wrong as to present an error message to the user. So in that case, only one event is delivered to the enclosing form, that contains this SFileChooser.

Note, that in this case, this will not trigger the action listener that you might have added to the submit-button. This means, that you always should add your action listener to the SForm (SForm.addActionListener(java.awt.event.ActionListener)), not the submit button.

Author:

Holger Engels, Henner Zeller

See Also:

Serialized Form

Field Summary

protected int	columns maximum visible amount of characters in the file chooser.
protected org.wings.SFileChooser.TempFile	currentFile the temporary file created on upload.
protected IOException	exception the temporary file created on upload.
protected String	fileDir
protected String	fileId
protected String	fileName
protected String	fileNameFilter
protected String	fileType
protected Class	filter

Fields inherited from class org.wings.SComponent

DONE_RENDERING, dynamicStyles, enabled, propertyChangeSupport, SELECTOR_ALL, START_RENDERING, visible, WHEN_FOCUSED_OR_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_IN_FOCUSED_FRAME

Constructor Summary

SFileChooser()
Creates a new FileChooser.

Method Summary

void	fireIntermediateEvents() fire events which describes a "in progress" state change, like TreeWillExpand, or ListSelectionEvent with getIsAdjusting() true, ...
int	getColumns() returns the number of visible columns.
File	getFile() Deprecated. use getSelectedFile() instead.
String	getFileDir() Returns the name of the system directory, the file has been stored temporarily in.
String	getFileId() Returns the internal ID of this file, that has been assigned at upload time.
String	getFileName() Returns the filename, that has been given by the user in the upload text-field.
String	getFileNameFilter() returns the current filename filter.
String	getFileType() Returns the mime type of this file, if known.
protected SForm	getParentForm() Find the form, this FileChooser is embedded in.
File	getSelectedFile() returns the file, that has been uploaded.
Class	getUploadFilter() Returns the upload filter set in setUploadFilter(Class)
FilterOutputStream	getUploadFilterInstance()
boolean	isEpochCheckEnabled() Asks the low-level event listener if epoch checking should be perfomed on it.
protected void	notifyParentForm() notifies the parent form, to fire action performed.
void	parentFrameAdded(SParentFrameEvent e) Called, whenever a parentFrame reference is added to the container.
void	parentFrameRemoved(SParentFrameEvent e) Called, whenever a parentFrame reference is removed from the container.
void	processLowLevelEvent(String action, String[] values) Deliver low level/http events (parameters).
void	reset() resets this FileChooser (no file selected).
void	setCG(FileChooserCG cg)
void	setColumns(int c) Set the visible amount of columns in the textfield.
void	setEpochCheckEnabled(boolean epochCheckEnabled)
void	setFileNameFilter(String mimeFilter) Unlike the swing filechooser that allows to match certain file-suffices, this sets the mimetype to be accepted.
void	setUploadFilter(Class filter) An FilterOutputStream, that filters incoming files.

Methods inherited from class org.wings.SComponent

addComponentListener, addDynamicStyle, addEventListener, addNotify, addParentFrameListener, addPropertyChangeListener, addPropertyChangeListener, addRenderListener, addScriptListener, addStyle, clone, fireComponentChangeEvent, fireFinalEvents, fireKeyEvents, fireRenderEvent, getActionMap, getBackground, getBorder, getCG, getClientProperty, getComponentPopupMenu, getDynamicStyle, getDynamicStyles, getFocusTraversalIndex, getFont, getForeground, getHorizontalAlignment, getInputMap, getInputMap, getListenerCount, getListenerList, getListeners, getLowLevelEventId, getName, getParent, getParentFrame, getPreferredSize, getRequestURL, getResidesInForm, getScriptListenerList, getScriptListeners, getSession, getShowAsFormComponent, getStyle, getToolTipText, getVerticalAlignment, invite, isDifferent, isEnabled, isFocusOwner, isRecursivelyVisible, isReloadForced, isUpdatePossible, isVisible, paramString, processComponentEvent, processKeyEvents, putClientProperty, reload, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, removeComponentListener, removeDynamicStyle, removeEventListener, removeNotify, removeParentFrameListener, removePropertyChangeListener, removePropertyChangeListener, removeRenderListener, removeScriptListener, removeStyle, requestFocus, scrollRectToVisible, setActionMap, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributes, setBackground, setBorder, setCG, setComponentPopupMenu, setDynamicStyles, setEnabled, setFocusTraversalIndex, setFont, setForeground, setHorizontalAlignment, setInputMap, setInputMap, setName, setNameRaw, setParent, setParentFrame, setPreferredSize, setReloadForced, setShowAsFormComponent, setStyle, setToolTipText, setVerticalAlignment, setVisible, toString, update, updateCG, write

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.wings.LowLevelEventListener

fireFinalEvents, getLowLevelEventId, getName, isEnabled

Field Detail

columns

protected int columns

maximum visible amount of characters in the file chooser.

fileNameFilter

protected String fileNameFilter

filter

protected Class filter

fileDir

protected String fileDir

fileName

protected String fileName

fileId

protected String fileId

fileType

protected String fileType

currentFile

protected org.wings.SFileChooser.TempFile currentFile

the temporary file created on upload. This file is automatically removed if and when it is not accessible anymore.

exception

protected IOException exception

the temporary file created on upload. This file is automatically removed if and when it is not accessible anymore.

Constructor Detail

SFileChooser

public SFileChooser()

Creates a new FileChooser.

Method Detail

getParentForm

protected final SForm getParentForm()

Find the form, this FileChooser is embedded in.

notifyParentForm

protected final void notifyParentForm()

notifies the parent form, to fire action performed. This is necessary, if an exception in parsing a MultiPartRequest occurs, e.g. upload file is too big.

parentFrameAdded

public void parentFrameAdded(SParentFrameEvent e)

Description copied from interface: SParentFrameListener

Called, whenever a parentFrame reference is added to the container. This i.e. happens on frame.add(component).

Specified by:

parentFrameAdded in interface SParentFrameListener

parentFrameRemoved

public void parentFrameRemoved(SParentFrameEvent e)

Description copied from interface: SParentFrameListener

Called, whenever a parentFrame reference is removed from the container.

Specified by:

parentFrameRemoved in interface SParentFrameListener

setColumns

public void setColumns(int c)

Set the visible amount of columns in the textfield.

Parameters:

c - columns; '-1' sets the default that is browser dependent.

getColumns

public int getColumns()

returns the number of visible columns.

Returns:

number of visible columns.

setFileNameFilter

public void setFileNameFilter(String mimeFilter)

Unlike the swing filechooser that allows to match certain file-suffices, this sets the mimetype to be accepted. This filter may be fully qualified like text/html or can contain a wildcard in the subtype like text/ *. Some browsers may as well accept a file-suffix wildcard as well.

In any case, you hould check the result, since you cannot assume, that the browser actually does filter. Worse, browsers may not guess the correct type so users cannot upload a file even if it has the correct type. So, bottomline, it is generally a good idea to let the file name filter untouched, unless you know bugs of the browser at the other end of the wire...

Parameters:

mimeFilter - the mime type to be filtered.

getFileNameFilter

public String getFileNameFilter()

returns the current filename filter. This is a mimetype-filter

Returns:

the current filename filter or 'null', if no filename filter is provided.

See Also:

setFileNameFilter(String)

getFileName

public String getFileName()
                   throws IOException

Returns the filename, that has been given by the user in the upload text-field.

Returns:

the filename, given by the user.

Throws:

IOException - if something went wrong with the upload (most likely, the maximum allowed filesize is exceeded, see Session.setMaxContentLength(int))

getFileDir

public String getFileDir()
                  throws IOException

Returns the name of the system directory, the file has been stored temporarily in. You won't need this, unless you want to access the file directly. Don't store the value you receive here for use later, since the SFileChooser does its own garbage collecting of unused files.

Returns:

the pathname of the system directory, the file is stored in.

Throws:

IOException - if something went wrong with the upload (most likely, the maximum allowed filesize is exceeded, see Session.setMaxContentLength(int))

getFileId

public String getFileId()
                 throws IOException

Returns the internal ID of this file, that has been assigned at upload time. This ID is unique to prevent clashes with other uploaded files. You won't need this, unless you want to access the file directly. Don't store the value you receive here for later use, since the SFileChooser does its own garbage collecting of unused files.

Returns:

the internal, unique file id given to the uploaded file.

Throws:

IOException - if something went wrong with the upload (most likely, the maximum allowed filesize is exceeded, see Session.setMaxContentLength(int))

getFileType

public String getFileType()
                   throws IOException

Returns the mime type of this file, if known.

Returns:

the mime type of this file.

Throws:

IOException - if something went wrong with the upload (most likely, the maximum allowed filesize is exceeded, see Session.setMaxContentLength(int))

getSelectedFile

public File getSelectedFile()
                     throws IOException

returns the file, that has been uploaded. Use this, to open and read from the file uploaded by the user. Don't use this method to query the actual filename given by the user, since this file wraps a system generated file with a different (unique) name. Use getFileName() instead.

The file returned here will delete itself if you loose the reference to it and it is garbage collected to avoid filling up the filesystem (This doesn't mean, that you shouldn't be a good programmer and delete the file yourself, if you don't need it anymore :-). If you rename() the file to use it somewhere else, it is regarded not temporary anymore and thus will not be removed from the filesystem.

Returns:

a File to access the content of the uploaded file.

Throws:

IOException - if something went wrong with the upload (most likely, the maximum allowed filesize is exceeded, see Session.setMaxContentLength(int))

reset

public void reset()

resets this FileChooser (no file selected). It does not remove an upload filter!. reset() will not remove a previously selected file from the local tmp disk space, so as long as you have a reference to such a file, you can still access it. If you don't have a reference to the file, it will automatically be removed when the file object is garbage collected.

getFile

public File getFile()
             throws IOException

Deprecated. use getSelectedFile() instead.

returns the file, that has been uploaded. Use this, to open and read from the file uploaded by the user. Don't use this method to query the actual filename given by the user, since this file wraps a system generated file with a different (unique) name. Use getFileName() instead.

The file returned here will delete itself if you loose the reference to it and it is garbage collected to avoid filling up the filesystem (This doesn't mean, that you shouldn't be a good programmer and delete the file yourself, if you don't need it anymore :-). If you rename() the file to use it somewhere else, it is regarded not temporary anymore and thus will not be removed from the filesystem.

Returns:

a File to access the content of the uploaded file.

Throws:

IOException - if something went wrong with the upload (most likely, the maximum allowed filesize is exceeded, see Session.setMaxContentLength(int))

setUploadFilter

public void setUploadFilter(Class filter)

An FilterOutputStream, that filters incoming files. You can use UploadFilters to inspect the stream or rewrite it to some own format.

Parameters:

filter - the Class that is instanciated to filter incoming files.

getUploadFilter

public Class getUploadFilter()

Returns the upload filter set in setUploadFilter(Class)

getUploadFilterInstance

public FilterOutputStream getUploadFilterInstance()

setCG

public void setCG(FileChooserCG cg)

processLowLevelEvent

public void processLowLevelEvent(String action,
                                 String[] values)

Description copied from interface: LowLevelEventListener

Deliver low level/http events (parameters). The name-value-pairs of the HTTPRequest are considered low level events.

Specified by:

processLowLevelEvent in interface LowLevelEventListener

Overrides:

processLowLevelEvent in class SComponent

Parameters:

action - the name-value-pair's name

values - the name-value-pair's values

fireIntermediateEvents

public void fireIntermediateEvents()

Description copied from interface: LowLevelEventListener

fire events which describes a "in progress" state change, like TreeWillExpand, or ListSelectionEvent with getIsAdjusting() true, ...

Specified by:

fireIntermediateEvents in interface LowLevelEventListener

isEpochCheckEnabled

public boolean isEpochCheckEnabled()

Description copied from interface: LowLevelEventListener

Asks the low-level event listener if epoch checking should be perfomed on it. If true the Dispatcher will ignore request originating from old views (typically iniated by triggering browser back and clicking somewhere.)

Specified by:

isEpochCheckEnabled in interface LowLevelEventListener

Returns:

true if epoch checking should be perfomed, false if all request for this component should be processed.

See Also:

LowLevelEventListener.isEpochCheckEnabled()

setEpochCheckEnabled

public void setEpochCheckEnabled(boolean epochCheckEnabled)

See Also:

LowLevelEventListener.isEpochCheckEnabled()