er.coolcomponents
Class CCAjaxLongResponsePage

java.lang.Object
  com.webobjects.appserver.WOElement
      com.webobjects.appserver.WOComponent
          er.coolcomponents.CCAjaxLongResponsePage

All Implemented Interfaces:

com.webobjects.appserver.WOActionResults, com.webobjects.foundation.NSKeyValueCoding, com.webobjects.foundation.NSKeyValueCoding.ErrorHandling, com.webobjects.foundation.NSKeyValueCodingAdditions, com.webobjects.foundation.NSValidation, java.io.Serializable, java.lang.Cloneable

public class CCAjaxLongResponsePage
extends com.webobjects.appserver.WOComponent

A generic long response page that controls the execution of and provides user feedback on a long running task. This is designed to be really easy, and flexible, for the developer to re-use.

The common case of running a task and automatically returning to the same originating page is really simple and requires just a few lines of code, for example:

 
        public WOActionResults runLongTask() {
                Runnable task = new LongRunningTask();

                CCAjaxLongResponsePage nextPage = pageWithName(CCAjaxLongResponsePage.class);
                nextPage.setLongRunningRunnable(task);

                return nextPage;
        }

 
 

Usage:

1. Create a Runnable task, or a Callable task, that returns some result.
   1. Optionally implement the ERXStatusInterface interface (just one method to return status message) to have the task's status displayed in the long response page.
   2. Optionally implement the ERXTaskPercentComplete interface (just one method to return percentage complete) to have a progress bar and a percentage complete automatically displayed in the long response page.
   3. Optionally implement the IERXStoppable interface to allow stopping of the task by the user.
2. If you don't just want the originating page to be returned (default behavior) then
   1. Create a simple class that implements @link IERXPerformWOActionForResult interface, or use ERXNextPageForResultWOAction, which provides a fairly generic implementation of that interface
   2. This controller class will get the result pushed into it when the task is complete. If the task threw an uncaught error during execution, then the error is pushed in as the result.
   3. The nextPage method of this controller class can do whatever it needs to do with the result and return a new page according to your logic in IERXPerformWOActionForResult#performAction().
3. In your component action, simply create an instance of this long response page just as you would create any other page.
4. Push in an instance of your Runnable (or Callable) task into the long response page using CCAjaxLongResponsePage#setLongRunningCallable(Callable)
5. Optionally push in your custom next page controller for execution when the task is finished using setNextPageForResultController(IERXPerformWOActionForResult)
6. Just return the long response page in your action method

Customizing the CCAjaxLongResponsePage for your Application

This long response page can be easily customized using a custom CSS style sheet and a few system properties.

Customizing the Appearance with CSS

You can create a custom CSS style sheet, place it in any framework (or your app) and set the following two properties to have it used instead of the default CSS style-sheet:

er.coolcomponents.CCAjaxLongResponsePage.stylesheet.framework

Set this the name of the framework that contains the custom css style sheet, or set it to "app" if the style-sheet is in the application bundle.

er.coolcomponents.CCAjaxLongResponsePage.stylesheet.filename

Set this to the filename of the css style sheet.

er.coolcomponents.CCAjaxLongResponsePage.stayOnLongResponsePageIndefinitely

As a convenience for CSS style sheet development, you can temporarily set this property to true to prevent ajax refresh on the long response page and to keep the page open indefinitely even after the task has completed. The property is ignored in deployment mode.

Further Configuration Options

The following properties can be used to implement additional custom behavior:

er.coolcomponents.CCAjaxLongResponsePage.defaultStatus

This determines the default status text when the task does not implement ERXStatusInterface

er.coolcomponents.CCAjaxLongResponsePage.refreshInterval

This value in seconds determines a custom refresh interval for the update container on the page. The default is 2 seconds

er.coolcomponents.CCAjaxLongResponsePage.nextPageForErrorResultControllerClassName

Defines a custom subclass of IERXPerformWOActionForResult as the default controller class, other than the hard-coded default, for handling task errors for the application. Note that if you declare a constructor that takes a single WOComponent argument, that constructor will be used and the originating page will be passed in as the constructor argument for you to use as you please in your custom error handling logic.

See Also:

Serialized Form

Author:

kieran

Nested Class Summary

Nested classes/interfaces inherited from class com.webobjects.appserver.WOComponent

com.webobjects.appserver.WOComponent._EventLoggingEnabler, com.webobjects.appserver.WOComponent.Event

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

com.webobjects.foundation.NSKeyValueCodingAdditions.DefaultImplementation, com.webobjects.foundation.NSKeyValueCodingAdditions.Utility

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCoding

com.webobjects.foundation.NSKeyValueCoding._BooleanFieldBinding, com.webobjects.foundation.NSKeyValueCoding._BooleanMethodBinding, com.webobjects.foundation.NSKeyValueCoding._FieldBinding, com.webobjects.foundation.NSKeyValueCoding._ForwardingBinding, com.webobjects.foundation.NSKeyValueCoding._KeyBinding, com.webobjects.foundation.NSKeyValueCoding._KeyBindingCreation, com.webobjects.foundation.NSKeyValueCoding._MethodBinding, com.webobjects.foundation.NSKeyValueCoding._NumberFieldBinding, com.webobjects.foundation.NSKeyValueCoding._NumberMethodBinding, com.webobjects.foundation.NSKeyValueCoding._ReflectionKeyBindingCreation, com.webobjects.foundation.NSKeyValueCoding.ErrorHandling, com.webobjects.foundation.NSKeyValueCoding.Null, com.webobjects.foundation.NSKeyValueCoding.UnknownKeyException, com.webobjects.foundation.NSKeyValueCoding.ValueAccessor

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSValidation

com.webobjects.foundation.NSValidation._MethodBinding, com.webobjects.foundation.NSValidation._ValidationBinding, com.webobjects.foundation.NSValidation.DefaultImplementation, com.webobjects.foundation.NSValidation.Utility, com.webobjects.foundation.NSValidation.ValidationException

Field Summary

Fields inherited from class com.webobjects.appserver.WOComponent

_Extension, _IsEventLoggingEnabled, _keyAssociations

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

_CLASS

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

_CLASS, _KeyPathSeparatorChar, KeyPathSeparator

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSValidation

_CLASS

Constructor Summary

CCAjaxLongResponsePage(com.webobjects.appserver.WOContext context)

Method Summary

java.lang.String	controlScriptContent()
java.lang.String	defaultStatus()
java.lang.String	elapsedTime()
java.lang.String	finishedPercentage()
ERXFutureTask<?>	future()
boolean	hideUnfinishedProgressTableCell()
boolean	isDebugMode()
com.webobjects.appserver.WOActionResults	nextPage()
IERXPerformWOAction	nextPageForCancelController()
IERXPerformWOActionForResult	nextPageForErrorController()
IERXPerformWOActionForResult	nextPageForResultController()
java.lang.Integer	refreshInterval()
java.lang.Object	result()
void	setDefaultStatus(java.lang.String defaultStatus)
void	setNextPageForCancelController(IERXPerformWOAction nextPageForCancelController)
void	setNextPageForErrorController(IERXPerformWOActionForResult nextPageForErrorController)
void	setNextPageForResultController(IERXPerformWOActionForResult nextPageForResultController)
void	setRefreshInterval(java.lang.Integer refreshInterval)
void	setTask(java.lang.Object task)
boolean	stayOnLongResponsePageIndefinitely()
com.webobjects.appserver.WOActionResults	stopTask() User action to stop the task if it implements IERXStoppable.
ERXStopWatch	stopWatch()
java.lang.String	styleSheetFilename()
java.lang.String	styleSheetFramework()
java.lang.Object	task()
boolean	wasStoppedByUser()

Methods inherited from class com.webobjects.appserver.WOComponent

_associationWithName, _awakeInContext, _childTemplate, _componentDefinition, _componentUnroll, _isPage, _setContext, _setIsPage, _setParent, _setSubcomponent, _sleepInContext, _subcomponentForElementWithID, _templateNameForClass, _unroll, appendToResponse, application, awake, baseURL, bindingKeys, canAccessFieldsDirectly, canGetValueForBinding, canSetValueForBinding, clone, context, debugString, descriptionForResponse, ensureAwakeInContext, frameworkName, generateResponse, handleQueryWithUnboundKey, handleTakeValueForUnboundKey, hasBinding, hasSession, invokeAction, isCachingEnabled, isEventLoggingEnabled, isStateless, logString, name, pageWithName, parent, path, pathURL, performParentAction, pullValuesFromParent, pushValuesToParent, reset, session, set_componentUnroll, set_unroll, setCachingEnabled, setValueForBinding, sleep, synchronizesVariablesWithBindings, takeValueForKey, takeValueForKeyPath, takeValuesFromRequest, template, templateWithHTMLString, templateWithName, toString, unableToSetNullForKey, validateTakeValueForKeyPath, validateValueForKey, validationFailedWithException, valueForBinding, valueForKey, valueForKeyPath

Methods inherited from class java.lang.Object

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

Constructor Detail

CCAjaxLongResponsePage

public CCAjaxLongResponsePage(com.webobjects.appserver.WOContext context)

Method Detail

nextPageForResultController

public IERXPerformWOActionForResult nextPageForResultController()

Returns:

the page controller that will be given the result of the long task and return the next page except for the case where the user stops the task.

setNextPageForResultController

public void setNextPageForResultController(IERXPerformWOActionForResult nextPageForResultController)

Parameters:

nextPageForResultController - the page controller that will be given the result of the long task and return the next page except for the case where the user stops the task.

nextPageForCancelController

public IERXPerformWOAction nextPageForCancelController()

Returns:

the controller that handles the scenario where the user stops a stoppable task

setNextPageForCancelController

public void setNextPageForCancelController(IERXPerformWOAction nextPageForCancelController)

Parameters:

nextPageForCancelController - the controller that handles the scenario where the user stops a stoppable task

nextPageForErrorController

public IERXPerformWOActionForResult nextPageForErrorController()

Returns:

controller to handle an error result

setNextPageForErrorController

public void setNextPageForErrorController(IERXPerformWOActionForResult nextPageForErrorController)

task

public java.lang.Object task()

Returns:

the Runnable and/or Callable task

setTask

public void setTask(java.lang.Object task)

Parameters:

task - the Runnable and/or Callable task

defaultStatus

public java.lang.String defaultStatus()

Returns:

a status message that is displayed if the task does not provide a status message

setDefaultStatus

public void setDefaultStatus(java.lang.String defaultStatus)

Parameters:

defaultStatus - a status message that is displayed if the task does not provide a status message

refreshInterval

public java.lang.Integer refreshInterval()

Returns:

the refresh interval in seconds. Defaults to value of er.coolcomponents.CCAjaxLongResponsePage.refreshInterval

setRefreshInterval

public void setRefreshInterval(java.lang.Integer refreshInterval)

Parameters:

refreshInterval - the refresh interval in seconds. Defaults to value of er.coolcomponents.CCAjaxLongResponsePage.refreshInterval or 2 seconds.

future

public ERXFutureTask<?> future()

Returns:

the Future that is bound to the long running task. The first time this method is accessed, it is lazily initialized and it starts the long running task.

nextPage

public com.webobjects.appserver.WOActionResults nextPage()

result

public java.lang.Object result()

Returns:

the result of the task

elapsedTime

public java.lang.String elapsedTime()

Returns:

the elapsedTime since the task started running

stopWatch

public ERXStopWatch stopWatch()

Returns:

a stopwatch timer, lazy initialized and started on first call of this method

controlScriptContent

public java.lang.String controlScriptContent()

Returns:

the javascript snippet that will call the nextPage action when the task is done.

finishedPercentage

public java.lang.String finishedPercentage()

Returns:

the table cell width value for the finished part of the progress bar, for example "56%". The same string can be used to display user-friendly percentage complete value.

hideUnfinishedProgressTableCell

public boolean hideUnfinishedProgressTableCell()

Returns:

boolean to hide the unfinished table cell to avoid a tiny slice of unfinished when we are at 100%

isDebugMode

public boolean isDebugMode()

Returns:

true if logging is Debug level. Used to display page config info in the long response page itself during development.

styleSheetFramework

public java.lang.String styleSheetFramework()

Returns:

the framework containing the CSS stylesheet for this page

styleSheetFilename

public java.lang.String styleSheetFilename()

Returns:

the filename of the CSS stylesheet webserver resource for this page

stopTask

public com.webobjects.appserver.WOActionResults stopTask()

User action to stop the task if it implements IERXStoppable. If the task is not stoppable, this action has no effect.

Returns:

null

wasStoppedByUser

public boolean wasStoppedByUser()

Returns:

true if the user stopped the task while it was in progress.

stayOnLongResponsePageIndefinitely

public boolean stayOnLongResponsePageIndefinitely()

Returns:

flag to prevent update container refresh and thus keep the long response page displayed indefinitely for the purpose of developing a CS stylesheet.