arlut.csd.ganymede
Class GanymediatorWizard

java.lang.Object
  |
  +--java.rmi.server.RemoteObject
        |
        +--java.rmi.server.RemoteServer
              |
              +--java.rmi.server.UnicastRemoteObject
                    |
                    +--arlut.csd.ganymede.GanymediatorWizard

All Implemented Interfaces:

Ganymediator, java.rmi.Remote, java.io.Serializable

public abstract class GanymediatorWizard

extends java.rmi.server.UnicastRemoteObject

implements Ganymediator

This class is a template for all Wizards implemented on the server. Custom plug-in GanymediatorWizards may be authored to handle step-by-step interactions with a user. GanymediatorWizards are typically created on the server when a client attempts an operation that requires a bit of hand-holding on the part of the server. A remote handle to the newly instantiated GanymediatorWizard is returned to the client, which presents a matching dialog to the user, retrieves input, and calls the respond() method. The respond() method takes the input from the user and considers whether it has enough information to perform the initially requested action. If not, it will update its internal state to keep track of where it is with respect to the user, and will return another ReturnVal which requests the client present another dialog and call back this GanymediatorWizard to continue along the process.

After a GanymediatorWizard is constructed, the respond() method will first call processDialog0(). processDialog0() can generate a return value using the continueOn() method to return a dialog that will ask the user for more information, or it can use the fail() or success() to return a dialog with an encoded success or failure indication, or it can return null to indicate success with no dialog. If the return result from processDialog0() was generated using continueOn(), the client's response to that dialog will be forwarded to processDialog1().

For processDialog1() and after, the wizard can use the getKeys() method to get an enumeration of labeled values passed back from the client, and getParam() to get the value for a specific key. Based on values passed back from the client, processDialog1() can decide to continue the interaction, or to return a dialog indicating success or failure, or a silent success result.

Typically, a continueOn() will cause the wizard system to proceed to the next highest processDialogXX() method. If a wizard needs to skip to a specific step, it can use the setNextState() method to set the number for the next processDialog method before returning a continueOn() result.

If at any time after processDialog0() the user hits cancel on a dialog, the GanymediatorWizard respond() mechanism will call the wizard's cancel() method to retrieve a final dialog for the user.

A wizard may only have 99 steps, from processDialog0() to processDialog98().

The GanymedeSession class keeps track of the client's active wizard. It is an error for there to be more than one wizard active at a time for a given client. respond() is responsible for calling unregister() when a wizard is through talking to the client.

Server-side code that is meant to return a ReturnVal object will pass control to a wizard by constructing a new wizard subclass and doing a

return wizard.respond(null);

to return the results of processDialog0() to the client. From that point on, the client will communicate back to the wizard as required to iterate through the processDialog steps.

See Also:

ReturnVal, Ganymediator, Serialized Form

Field Summary

protected boolean	active
static int	DONE
(package private) ReturnVal	result
protected java.util.Hashtable	returnHash
protected GanymedeSession	session
static int	STARTUP
int	state
(package private) boolean	stateSet

Fields inherited from class java.rmi.server.UnicastRemoteObject

csf, port, portFactoryParamTypes, portParamTypes, serialVersionUID, ssf

Fields inherited from class java.rmi.server.RemoteServer

log, logname

Fields inherited from class java.rmi.server.RemoteObject

ref

Constructor Summary

GanymediatorWizard(GanymedeSession session)
Constructor

Method Summary

ReturnVal	callDialog(int state) This method uses the Java Reflection API to call a method named processDialogX() in the derived class, where X is a positive integer corresponding to <state>.
ReturnVal	cancel() This method provides a default response if a user hits cancel on a wizard dialog.
protected ReturnVal	continueOn(java.lang.String title, java.lang.String body, java.lang.String ok, java.lang.String cancel, java.lang.String image) This method returns a ReturnVal that indicates that the wizard sequence has not yet finished.
protected ReturnVal	fail(java.lang.String title, java.lang.String body, java.lang.String ok, java.lang.String cancel, java.lang.String image) This method returns a ReturnVal that indicates that the wizard sequence has finished without success.
protected java.util.Enumeration	getElements() This method allows a processDialog*() method in a GanymediatorWizard subclass to get access to an enum of values returned to the wizard from a previous dialog.
protected java.util.Enumeration	getKeys() This method allows a processDialog*() method in a GanymediatorWizard subclass to get access to an enum of keys returned to the wizard from a previous dialog.
protected java.lang.Object	getParam(java.lang.Object key) This method allows a processDialog*() method in a GanymediatorWizard subclass to get access to a value returned to the wizard from a previous dialog.
ReturnVal	getStartDialog() Deprecated. getStartDialog() has been deprecated.. use processDialog0() in your GanymediatorWizard subclasses instead.
int	getState() This method lets us know where the wizard is in its process
boolean	isActive() This method is used to allow server code to determine whether this GanymediatorWizard is in the middle of an interaction with the client.
ReturnVal	respond(java.util.Hashtable returnHash) This method is used to provide feedback to the server from a client in response to a specific request.
protected void	setNextState(int state) This method should be called by a processDialog*() method that does not intend to proceed to the next state.
protected ReturnVal	success(java.lang.String title, java.lang.String body, java.lang.String ok, java.lang.String cancel, java.lang.String image) This method returns a ReturnVal that indicates that the wizard sequence has terminated successfully.
void	unregister() This method is used to inform this GanymediatorWizard that the client has logged out or otherwise aborted the transaction that this wizard is part of, and that it should release any references to checked out DBEditObjects.

Methods inherited from class java.rmi.server.UnicastRemoteObject

, clone, exportObject, exportObject, exportObject, exportObject, readObject, reexport, unexportObject

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub, writeObject

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, registerNatives, wait, wait, wait

Field Detail

STARTUP

public static final int STARTUP

DONE

public static final int DONE

active

protected boolean active

state

public int state

session

protected GanymedeSession session

returnHash

protected java.util.Hashtable returnHash

stateSet

boolean stateSet

result

ReturnVal result

Constructor Detail

GanymediatorWizard

public GanymediatorWizard(GanymedeSession session)
                   throws java.rmi.RemoteException

Constructor

Method Detail

respond

public ReturnVal respond(java.util.Hashtable returnHash)

This method is used to provide feedback to the server from a client in response to a specific request. Calls to this method drive the wizard from state to state.

This method is not final, and adopters are free to totally override this method in their wizard classes to provide custom logic. Generally, though, adopters are encouraged to take advantage of the state machine implemented in this method and use methods called processDialog1(), processDialog2(), and so on to handle the dialogs at each stage of a wizard sequence.

Specified by:

respond in interface Ganymediator

Parameters:

returnHash - a hashtable mapping strings to values. The strings are titles of fields specified in a dialog that was provided to the client. If returnHash is null, this corresponds to the user hitting cancel on such a dialog.

See Also:

Ganymediator, ReturnVal

cancel

public ReturnVal cancel()

This method provides a default response if a user hits cancel on a wizard dialog. This should be subclassed if a wizard wants to provide a more detailed cancel response.

setNextState

protected void setNextState(int state)

This method should be called by a processDialog*() method that does not intend to proceed to the next state. By default, if a processDialog() returns a ReturnVal that does not indicate completion or failure _without_ the callback being set, respond() will call the next processDialog() method in the ordinal sequence.

continueOn

protected ReturnVal continueOn(java.lang.String title,
                               java.lang.String body,
                               java.lang.String ok,
                               java.lang.String cancel,
                               java.lang.String image)

This method returns a ReturnVal that indicates that the wizard sequence has not yet finished.

fail

protected ReturnVal fail(java.lang.String title,
                         java.lang.String body,
                         java.lang.String ok,
                         java.lang.String cancel,
                         java.lang.String image)

This method returns a ReturnVal that indicates that the wizard sequence has finished without success.

success

protected ReturnVal success(java.lang.String title,
                            java.lang.String body,
                            java.lang.String ok,
                            java.lang.String cancel,
                            java.lang.String image)

This method returns a ReturnVal that indicates that the wizard sequence has terminated successfully.

getParam

protected java.lang.Object getParam(java.lang.Object key)

This method allows a processDialog*() method in a GanymediatorWizard subclass to get access to a value returned to the wizard from a previous dialog.

getKeys

protected java.util.Enumeration getKeys()

This method allows a processDialog*() method in a GanymediatorWizard subclass to get access to an enum of keys returned to the wizard from a previous dialog.

getElements

protected java.util.Enumeration getElements()

This method allows a processDialog*() method in a GanymediatorWizard subclass to get access to an enum of values returned to the wizard from a previous dialog.

callDialog

public ReturnVal callDialog(int state)

This method uses the Java Reflection API to call a method named processDialogX() in the derived class, where X is a positive integer corresponding to <state>.

unregister

public void unregister()

This method is used to inform this GanymediatorWizard that the client has logged out or otherwise aborted the transaction that this wizard is part of, and that it should release any references to checked out DBEditObjects.

isActive

public boolean isActive()

This method is used to allow server code to determine whether this GanymediatorWizard is in the middle of an interaction with the client.

getState

public int getState()

This method lets us know where the wizard is in its process

getStartDialog

public final ReturnVal getStartDialog()

Deprecated. getStartDialog() has been deprecated.. use processDialog0() in your GanymediatorWizard subclasses instead.

This method starts off the wizard process.

This method will always be overridden in GanymediatorWizard subclasses. It is critical that if this method returns null (indicating that the wizard doesn't need to interact with the client), that this method calls unregister() to clear the wizard from the GanymedeSession.