echopoint.tucana
Class FileUploadSelector

java.lang.Object
  nextapp.echo.app.Component
      echopoint.internal.AbstractContainer
          echopoint.tucana.FileUploadSelector

All Implemented Interfaces:

Serializable, RenderIdSupport

public class FileUploadSelector
extends AbstractContainer

The file upload selector component. This component is a re-implementation of the original tucana file upload selector component for Echo2.

Note: It is critical that this component be set absolute height and width properties. Percentage based values can cause problems if using a progress bar.

The following code shows sample usage of this component:

  import nextapp.echo.app.Border;
  import nextapp.echo.app.Color;
  import echopoint.tucana.ButtonMode;
  import echopoint.tucana.ButtonDisplay;
  import echopoint.tucana.FileUploadSelector;
  import echopoint.tucana.ProgressBar;
  import static echopoint.tucana.UploadSPI;
  import echopoint.tucana.event.DefaultUploadCallback;

    ...
    final FileUploadSelector selector = new FileUploadSelector();
    selector.setButtonMode( ButtonMode.image );
    selector.setButtonDisplayMode( ButtonDisplay.right );
    selector.setInputSize( 20 );
    selector.setUploadSizeLimit( NO_SIZE_LIMIT );
    selector.setBackground( new Color( 0xa1a1a1 ) );
    selector.setBorder( new Border( 1, Color.BLUE, Border.STYLE_GROOVE ) );
    selector.setProgressBar( new ProgressBar() );
    selector.setUploadCallback( new DefaultUploadCallback( new File( "/tmp" ) ) );
    selector.addActionListener( ... );

    // Allow only the following types of files to be uploaded.
    final HashSet<String> set = new HashSet<String>();
    set.add( "image/gif" );
    set.add( "image/jpeg" );
    set.add( "image/png" );
    selector.setContentTypeFilter( set );

    parent.add( selector );
 

There are two different (equivalent) ways to process a completed upload:

1. UploadCallback based. It is best to use a sub-class of either DefaultUploadCallback or UploadCallbackAdapter since they ensure removal of the task queue used to enqueue processing from the call back methods to the UI thread. If you sub-class please note that calls to super.uploadXxx methods should be invoked at the end of your over-ridden implementation and not at the top. The super class implementations destroys the queue and sets it to null. If you implement your own handler please make sure that you invoke removeTaskQueue() at the end of your handler methods. The queue will be automatically cleaned up when the component is removed from the hierarchy, so it may be acceptable to not invoke removeTaskQueue depending upon how your application logic works.
2. ActionListener based. Two types of events are recieved by the event handler:
   1. START_ACTION - The action command that indicates that the file upload has commenced.
   2. COMPLETE_ACTION - The action command that indicates that the file upload has finished.

   Please note that it is safest to check on the command value rather than check one and default action for the other value.

The following callback class and associated runnable may be used to update the UI after an upload.

  import nextapp.echo.app.ApplicationInstance;
  import nextapp.echo.app.Component;
  import nextapp.echo.app.TaskQueueHandle;
  import echopoint.DirectHtml;
  import echopoint.tucana.event.UploadCallbackAdapter;

  public class UploadCallbackImpl extends UploadCallbackAdapter
  {
    private static final long serialVersionUID = 1l;
    private final Component parent;

    private UploadCallbackImpl( final Component parent )
    {
      this.parent = parent;
    }

    @Override
    public void uploadSucceeded( final UploadFinishEvent event )
    {
      final StringBuilder builder = new StringBuilder( 128 );
      builder.append( "Upload of file: <b>" );
      builder.append( event.getFileName() );
      builder.append( "</b> succeeded.  File size is: <i>");
      builder.append( event.getFileSize() / 1000 );
      builder.append( "</i> kilobytes." );
      final DirectHtml html = new DirectHtml( builder.toString() );
      parent.add( child );
      super.uploadSucceeded( event );
    }

    @Override
    public void uploadFailed( final UploadFailEvent event )
    {
      final StringBuilder builder = new StringBuilder( 128 );
      builder.append( "File upload failed." );
      if ( event.getFileName() != null )
      {
        builder.append( "  Failed file: <i>" );
        builder.append( event.getFileName() );
        builder.append( "</i>." );
      }

      if ( event.getException() != null )
      {
        builder.append( "Exception: <p><pre>" );
        builder.append( event.getException().toString() );
        builder.append( "</pre></p>" );
      }

      final DirectHtml html = new DirectHtml( builder.toString() );
      parent.add( child );
      super.uploadFailed( event );
    }
 

Processing UI updates after upload completion is much simpler (and more network friendly) when using an action listener. A simple action listener may be configured as follows:

  import nextapp.echo.app.Component;
  import nextapp.echo.app.event.ActionEvent;
  import nextapp.echo.app.event.ActionListener;
  import echopoint.tucana.FileUploadSelector;
  import echopoint.tucana.event.UploadCallback;
  import echopoint.tucana.event.UploadFinishEvent;
  import echopoint.DirectHtml;

  public class FinishListener implements ActionListener
  {
    private static final long serialVersionUID = 1l;

    public void actionPerformed( final ActionEvent event )
    {
      final FileUploadSelector upload = ( FileUploadSelector) event.getSource();
      final UploadCallback callback = upload.getUploadCallback();
      if ( callback != null )
      {
        final StringBuilder builder = new StringBuilder( 128 );
        final boolean success = ( callback.getEvent() instanceof UploadFinishEvent );

        if ( success )
        {
          builder.append( "Upload of file: <b>" );
          builder.append( callback.getEvent().getFileName() );
          builder.append( "</b> succeeded.  File size is: <i>");
          builder.append( callback.getEvent().getFileSize() / 1000 );
          builder.append( "</i> kilobytes." );
        }
        else
        {
          builder.append( "Upload " );
          if ( callback.getEvent() != null )
          {
            builder.append( " of file: <b>" );
            builder.append( callback.getEvent().getFileName() );
            builder.append( "</b>" );
          }

          builder.append( " failed/cancelled." );
        }

        upload.getParent().add( new DirectHtml( builder.toString() ) );

        if ( upload.getProgressBar() != null )
        {
          upload.getProgressBar().setText( ( success ) ?
              "Finished upload!" : "Cancelled upload!" );
        }
      }
    }
  }
 

Note: Development of this component was sponsored by TCN Broadcasting. We are grateful for their support and sponsorship.

Version:

$Id: FileUploadSelector.java 204 2009-05-20 18:50:57Z sptrakesh $

Author:

jvolkman (Echo2), Rakesh 2008-11-2

See Also:

Serialized Form

Field Summary

static String	COMPLETE_ACTION The name of the action that is fired by the client upon completion (regardless of complete or cancel) of the upload process.
static String	PROPERTY_BUTTON_DISPLAY
static String	PROPERTY_BUTTON_IMAGE_CANCEL
static String	PROPERTY_BUTTON_IMAGE_UPLOAD
static String	PROPERTY_BUTTON_IMAGE_WAIT
static String	PROPERTY_BUTTON_MODE
static String	PROPERTY_BUTTON_TEXT_CANCEL
static String	PROPERTY_BUTTON_TEXT_UPLOAD
static String	PROPERTY_BUTTON_TEXT_WAIT
static String	PROPERTY_CANCEL_ENABLED
static String	PROPERTY_INPUT_SIZE The size (indicates number of characters) for the input field.
static String	PROPERTY_POLLING_INTERVAL The interval (in milliseconds) at which the progress service is to be polled for updates.
static String	PROPERTY_UPLOAD_SIZE_LIMIT The maximum size of file that is allowed to be uploaded.
static String	START_ACTION The name of the action that is fired by the client upon start of the upload process.

Fields inherited from class echopoint.internal.AbstractContainer

ACTION_COMMAND_PROPERTY, ACTION_LISTENERS_CHANGED_PROPERTY, INPUT_ACTION, PROPERTY_ALIGNMENT, PROPERTY_BACKGROUND_IMAGE, PROPERTY_BORDER, PROPERTY_HEIGHT, PROPERTY_INSETS, PROPERTY_WIDTH

Fields inherited from class nextapp.echo.app.Component

CHILD_VISIBLE_CHANGED_PROPERTY, CHILDREN_CHANGED_PROPERTY, ENABLED_CHANGED_PROPERTY, FOCUS_NEXT_ID_CHANGED_PROPERTY, FOCUS_PREVIOUS_ID_CHANGED_PROPERTY, LAYOUT_DIRECTION_CHANGED_PROPERTY, LOCALE_CHANGED_PROPERTY, PROPERTY_BACKGROUND, PROPERTY_FONT, PROPERTY_FOREGROUND, PROPERTY_LAYOUT_DATA, STYLE_CHANGED_PROPERTY, STYLE_NAME_CHANGED_PROPERTY, VISIBLE_CHANGED_PROPERTY

Constructor Summary

FileUploadSelector()
Default constructor.

Method Summary

void	addActionListener(ActionListener listener) Add the specified action listener to this component.
void	dispose() Over-ridden to clean up taskQueue if not already cleaned up.
ImageReference	getButtonCancelImage() Gets the current cancel button image.
String	getButtonCancelText() Gets the current cancel button text.
ButtonDisplay	getButtonDisplayMode() Get the configuration for display of the submit button.
ButtonMode	getButtonMode() Get the current upload button display mode.
ImageReference	getButtonUploadImage() Gets the current upload button image.
String	getButtonUploadText() Gets the current upload button text.
ImageReference	getButtonWaitImage() Gets the current wait button image.
String	getButtonWaitText() Gets the current wait button text.
Set<String>	getContentTypeFilter() Accessor for property 'contentTypeFilter'.
int	getInputSize() Return the value of the PROPERTY_INPUT_SIZE property.
int	getPollingInterval() Return the value of the PROPERTY_POLLING_INTERVAL property.
ProgressBar	getProgressBar() Return the progress bar component configured for this component.
TaskQueueHandle	getTaskQueue() Return the task queue that may be used to enqueue asynchronous tasks (usually from callback handlers).
UploadCallback	getUploadCallback() Get the callback used when a file is uploaded.
long	getUploadSizeLimit() Return the value of the PROPERTY_UPLOAD_SIZE_LIMIT property.
boolean	isCancelEnabled() Accessor for property 'cancelEnabled'.
boolean	isValidChild(Component child) The only allowed sub-component is a ProgressBar.
protected void	notifyCallback(UploadEvent e) Notifies the listener that the given event has occurred.
void	processInput(String name, Object value) Over-ridden to fire action events with action commands that are set to START_ACTION or COMPLETE_ACTION depending upon whether the event represents start of the upload or completion of the upload.
void	removeActionListener(ActionListener listener) Remove the specified action listener from the component.
void	removeTaskQueue() Remove the current task queue.
void	setButtonCancelImage(ImageReference image) Sets the cancel button image.
void	setButtonCancelText(String text) Sets the cancel button text.
void	setButtonDisplayMode(ButtonDisplay mode) Set the button display mode for the input submit button.
void	setButtonMode(ButtonMode mode) Sets the upload button display mode
void	setButtonUploadImage(ImageReference image) Sets the upload button image.
void	setButtonUploadText(String text) Sets the upload button text.
void	setButtonWaitImage(ImageReference image) Sets the wait button image.
void	setButtonWaitText(String text) Sets the wait button text.
void	setCancelEnabled(boolean enabled) Mutator for property 'cancelEnabled'.
void	setContentTypeFilter(Set<String> contentTypeFilter) Mutator for property 'contentTypeFilter'.
void	setInputSize(int size) Set the value of the PROPERTY_INPUT_SIZE property.
void	setPollingInterval(int interval) Set the value of the PROPERTY_POLLING_INTERVAL property.
void	setProgressBar(ProgressBar progressBar) Add the specified progress bar to this component.
void	setTaskQueue(TaskQueueHandle taskQueue) Set the task queue for the component.
void	setUploadCallback(UploadCallback callback) Set the callback used when a file is uploaded.
void	setUploadSizeLimit(long limit) Set the value of the PROPERTY_UPLOAD_SIZE_LIMIT property.

Methods inherited from class echopoint.internal.AbstractContainer

fireActionPerformed, getAlignment, getBackgroundImage, getBorder, getHeight, getInsets, getWidth, hasActionListeners, setAlignment, setBackgroundImage, setBorder, setHeight, setInsets, setWidth

Methods inherited from class nextapp.echo.app.Component

add, add, addPropertyChangeListener, addPropertyChangeListener, firePropertyChange, get, getApplicationInstance, getBackground, getComponent, getComponent, getComponentCount, getComponents, getEventListenerList, getFocusNextId, getFocusPreviousId, getFont, getForeground, getId, getIndex, getLayoutData, getLayoutDirection, getLocale, getLocalStyle, getParent, getRenderId, getRenderIndexedProperty, getRenderIndexedProperty, getRenderLocale, getRenderProperty, getRenderProperty, getStyle, getStyleName, getVisibleComponent, getVisibleComponentCount, getVisibleComponents, hasEventListenerList, indexOf, init, isAncestorOf, isEnabled, isFocusTraversalParticipant, isRegistered, isRenderEnabled, isRenderVisible, isValidParent, isVisible, remove, remove, removeAll, removePropertyChangeListener, removePropertyChangeListener, set, setBackground, setComponents, setEnabled, setFocusNextId, setFocusPreviousId, setFocusTraversalParticipant, setFont, setForeground, setId, setIndex, setLayoutData, setLayoutDirection, setLocale, setRenderId, setStyle, setStyleName, setVisible, validate, verifyInput, visibleIndexOf

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_BUTTON_TEXT_UPLOAD

public static final String PROPERTY_BUTTON_TEXT_UPLOAD

See Also:

Constant Field Values

PROPERTY_BUTTON_TEXT_CANCEL

public static final String PROPERTY_BUTTON_TEXT_CANCEL

See Also:

Constant Field Values

PROPERTY_BUTTON_TEXT_WAIT

public static final String PROPERTY_BUTTON_TEXT_WAIT

See Also:

Constant Field Values

PROPERTY_BUTTON_IMAGE_UPLOAD

public static final String PROPERTY_BUTTON_IMAGE_UPLOAD

See Also:

Constant Field Values

PROPERTY_BUTTON_IMAGE_CANCEL

public static final String PROPERTY_BUTTON_IMAGE_CANCEL

See Also:

Constant Field Values

PROPERTY_BUTTON_IMAGE_WAIT

public static final String PROPERTY_BUTTON_IMAGE_WAIT

See Also:

Constant Field Values

PROPERTY_BUTTON_MODE

public static final String PROPERTY_BUTTON_MODE

See Also:

Constant Field Values

PROPERTY_BUTTON_DISPLAY

public static final String PROPERTY_BUTTON_DISPLAY

See Also:

Constant Field Values

PROPERTY_CANCEL_ENABLED

public static final String PROPERTY_CANCEL_ENABLED

See Also:

Constant Field Values

PROPERTY_INPUT_SIZE

public static final String PROPERTY_INPUT_SIZE

The size (indicates number of characters) for the input field. This is the same as the old PROPERTY_WIDTH_SIZE. This property is best styled.

See Also:

Constant Field Values

PROPERTY_POLLING_INTERVAL

public static final String PROPERTY_POLLING_INTERVAL

The interval (in milliseconds) at which the progress service is to be polled for updates. Note that upload completion and cancellation are inferred through the response from the service. This property is best styled.

See Also:

Constant Field Values

PROPERTY_UPLOAD_SIZE_LIMIT

public static final String PROPERTY_UPLOAD_SIZE_LIMIT

The maximum size of file that is allowed to be uploaded.

See Also:

Constant Field Values

COMPLETE_ACTION

public static final String COMPLETE_ACTION

The name of the action that is fired by the client upon completion (regardless of complete or cancel) of the upload process. "complete"

See Also:

Constant Field Values

START_ACTION

public static final String START_ACTION

The name of the action that is fired by the client upon start of the upload process. "start"

See Also:

Constant Field Values

Constructor Detail

FileUploadSelector

public FileUploadSelector()

Default constructor. Add DefaultUploadListener as a listener for this component to initialise the taskQueue.

Method Detail

setButtonUploadImage

public void setButtonUploadImage(ImageReference image)

Sets the upload button image.

Parameters:

image - The new upload button image.

getButtonUploadImage

public ImageReference getButtonUploadImage()

Gets the current upload button image.

Returns:

The current upload button image.

setButtonCancelImage

public void setButtonCancelImage(ImageReference image)

Sets the cancel button image.

Parameters:

image - The new cancel button image.

getButtonCancelImage

public ImageReference getButtonCancelImage()

Gets the current cancel button image.

Returns:

The current cancel button image.

setButtonWaitImage

public void setButtonWaitImage(ImageReference image)

Sets the wait button image.

Parameters:

image - The new wait button image.

getButtonWaitImage

public ImageReference getButtonWaitImage()

Gets the current wait button image.

Returns:

The current wait button image.

setButtonUploadText

public void setButtonUploadText(String text)

Sets the upload button text.

Parameters:

text - The new upload button text.

getButtonUploadText

public String getButtonUploadText()

Gets the current upload button text.

Returns:

The current upload button text.

setButtonCancelText

public void setButtonCancelText(String text)

Sets the cancel button text.

Parameters:

text - The new cancel button text.

getButtonCancelText

public String getButtonCancelText()

Gets the current cancel button text.

Returns:

The current cancel button text.

setButtonWaitText

public void setButtonWaitText(String text)

Sets the wait button text.

Parameters:

text - The new wait button text.

getButtonWaitText

public String getButtonWaitText()

Gets the current wait button text.

Returns:

The current wait button text.

setButtonMode

public void setButtonMode(ButtonMode mode)

Sets the upload button display mode

Parameters:

mode - The new upload button display mode

getButtonMode

public ButtonMode getButtonMode()

Get the current upload button display mode.

Returns:

The current display mode, or ButtonMode.submit if not set.

setButtonDisplayMode

public void setButtonDisplayMode(ButtonDisplay mode)

Set the button display mode for the input submit button.

Parameters:

mode - Set to configure the location of the submit button.

getButtonDisplayMode

public ButtonDisplay getButtonDisplayMode()

Get the configuration for display of the submit button.

Returns:

The current mode, or ButtonDisplay.auto if not set.

setCancelEnabled

public void setCancelEnabled(boolean enabled)

Mutator for property 'cancelEnabled'.

Parameters:

enabled - Value to set for property 'cancelEnabled'.

isCancelEnabled

public boolean isCancelEnabled()

Accessor for property 'cancelEnabled'.

Returns:

Value for property 'cancelEnabled'.

getInputSize

public int getInputSize()

Return the value of the PROPERTY_INPUT_SIZE property.

Returns:

The size of the input text field.

setInputSize

public void setInputSize(int size)

Set the value of the PROPERTY_INPUT_SIZE property.

Parameters:

size - The size of the input text field.

getPollingInterval

public int getPollingInterval()

Return the value of the PROPERTY_POLLING_INTERVAL property.

Returns:

The time interval at which the progress service will be polled

setPollingInterval

public void setPollingInterval(int interval)

Set the value of the PROPERTY_POLLING_INTERVAL property.

Parameters:

interval - The time interval at which the progress service will be polled

getUploadSizeLimit

public long getUploadSizeLimit()

Return the value of the PROPERTY_UPLOAD_SIZE_LIMIT property. If not set the implementation defaults to echopoint.tucana.AbstractFileUploadProvider#DEFAULT_UPLOAD_SIZE_LIMIT.

Returns:

The maximum size in bytes that is allowed to be uploaded.

setUploadSizeLimit

public void setUploadSizeLimit(long limit)

Set the value of the PROPERTY_UPLOAD_SIZE_LIMIT property. Specify echopoint.tucana.UploadSPI#NO_SIZE_LIMIT to prevent size checking.

Parameters:

limit - The maximum size in bytes that is allowed.

setUploadCallback

public void setUploadCallback(UploadCallback callback)

Set the callback used when a file is uploaded.

Parameters:

callback - The upload callback.

getUploadCallback

public UploadCallback getUploadCallback()

Get the callback used when a file is uploaded.

Returns:

The upload callback.

getProgressBar

public ProgressBar getProgressBar()

Return the progress bar component configured for this component.

Returns:

The progress bar if one was added or null.

setProgressBar

public void setProgressBar(ProgressBar progressBar)

Add the specified progress bar to this component.

Parameters:

progressBar - The progress bar component to add.

getContentTypeFilter

public Set<String> getContentTypeFilter()

Accessor for property 'contentTypeFilter'. Returns the content-types that are allowed to be uploaded by this component.

Returns:

Value for property 'contentTypeFilter'.

setContentTypeFilter

public void setContentTypeFilter(Set<String> contentTypeFilter)

Mutator for property 'contentTypeFilter'.

Parameters:

contentTypeFilter - Value to set for property 'contentTypeFilter'.

isValidChild

public boolean isValidChild(Component child)

The only allowed sub-component is a ProgressBar.

Overrides:

isValidChild in class Component

Parameters:

child - The child component that is to be added if allowed.

Returns:

Return true if child is an instance of ProgressBar and a progress bar has not already been assigned.

getTaskQueue

public TaskQueueHandle getTaskQueue()

Return the task queue that may be used to enqueue asynchronous tasks (usually from callback handlers).

Returns:

Value for property 'taskQueue'.

setTaskQueue

public void setTaskQueue(TaskQueueHandle taskQueue)

Set the task queue for the component.

Parameters:

taskQueue - Value to set for property 'taskQueue'.

removeTaskQueue

public void removeTaskQueue()

Remove the current task queue. It is strongly recommended that this method be used rather than wait for dispose().

notifyCallback

protected void notifyCallback(UploadEvent e)

Notifies the listener that the given event has occurred.

Parameters:

e - the event

addActionListener

public void addActionListener(ActionListener listener)

Add the specified action listener to this component.

Overrides:

addActionListener in class AbstractContainer

Parameters:

listener - The action listener to add.

See Also:

Component.firePropertyChange(String, Object, Object)

removeActionListener

public void removeActionListener(ActionListener listener)

Remove the specified action listener from the component.

Overrides:

removeActionListener in class AbstractContainer

Parameters:

listener - The listener that is to be removed.

See Also:

Component.firePropertyChange(String, Object, Object)

processInput

public void processInput(String name,
                         Object value)

Over-ridden to fire action events with action commands that are set to START_ACTION or COMPLETE_ACTION depending upon whether the event represents start of the upload or completion of the upload.

Overrides:

processInput in class Component

See Also:

Component.processInput(String, Object)

dispose

public void dispose()

Over-ridden to clean up taskQueue if not already cleaned up.

Overrides:

dispose in class Component

See Also:

removeTaskQueue(), Component.dispose()