org.apache.shale.dialog
Interface DialogContext

All Known Implementing Classes:

AbstractDialogContext

public interface DialogContext

Interface describing the current state of a particular dialog context instance.

IMPLEMENTATION NOTE - Implementations of this interface will be stored in session scope, so they should be serializable.

Since:

1.0.4

Method Summary

void	addDialogContextListener(DialogContextListener listener) Register given DialogContextListener for this DialogContext.
void	advance(javax.faces.context.FacesContext context, String outcome) Advance the execution of this DialogContext instance, until an interaction with the user is required.
Object	getData() Return the generic data object representing model state for this dialog instance.
DialogContextListener[]	getDialogContextListeners() Return the set of currently registered DialogContextListeners.
String	getId() Return the context identifier for this instance of the specified dialog.
String	getName() Return the logical name of the dialog being executed by this instance.
Object	getOpaqueState() Return an opaque object containing any state information (besides the context identifier, which is already saved) that this DialogContext instance would like to have saved in the JavaServer Faces component tree, and then restored (via a call to setOpaqueData() on the subsequent form submit.
DialogContext	getParent() Return the parent DialogContext instance associated with this child DialogContext, if any; otherwise, return null.
boolean	isActive() Return true if this DialogContext is currently active (created but not yet removed).
void	removeDialogContextListener(DialogContextListener listener) Remove this previously registered DialogContextListener for this DialogContext.
void	setData(Object data) Set the generic data object representing model state for this dialog instance.
void	setOpaqueState(Object opaqueState) Restore state information that was previously returned by a call to getOpaqueState() on this DialogContext instance.
void	start(javax.faces.context.FacesContext context) Start the execution of this DialogContext instance, advancing until an interaction with the user is required.
void	stop(javax.faces.context.FacesContext context) Stop the execution of this DialogContext instance, resulting in no currently active dialog for the current JavaServer Faces view.

Method Detail

isActive

boolean isActive()

Return true if this DialogContext is currently active (created but not yet removed).

Returns:

Whether this dialog instance is active

getData

Object getData()

Return the generic data object representing model state for this dialog instance.

Returns:

The data object for this dialog instance

setData

void setData(Object data)

Set the generic data object representing model state for this dialog instance. As a value added feature, if the class of the specified data object implements DialogContextListener, ensure that the data object is registered as a listener with this DialogContext, and deregistered when the DialogContext is completed (or this instance is replaced).

Parameters:

data - The new data instance

getId

String getId()

Return the context identifier for this instance of the specified dialog.

Returns:

The identifier for this dialog instance, unique for the manager associated with this dialog instance

getName

String getName()

Return the logical name of the dialog being executed by this instance.

Returns:

The logical name of the dialog which this DialogContext is an instance of

getOpaqueState

Object getOpaqueState()

Return an opaque object containing any state information (besides the context identifier, which is already saved) that this DialogContext instance would like to have saved in the JavaServer Faces component tree, and then restored (via a call to setOpaqueData() on the subsequent form submit. If there is no such information to be recorded, return null.

IMPLEMENTATION NOTE - Because this object will be stored as part of the JSF component tree, it must be Serializable.

WARNING - This method should ONLY be called by the dialog framework infrastructure. It should NOT be called by the application.

setOpaqueState

void setOpaqueState(Object opaqueState)

Restore state information that was previously returned by a call to getOpaqueState() on this DialogContext instance. If the previous call to getOpaqueState() returned null, this method will NOT be called.

WARNING - This method should ONLY be called by the dialog framework infrastructure. It should NOT be called by the application.

Parameters:

opaqueState - The opaque state object that was previously returned by a call to getOpaqueState() after potentially being serialized and deserialized by the JSF state saving functionality

getParent

DialogContext getParent()

Return the parent DialogContext instance associated with this child DialogContext, if any; otherwise, return null.

Returns:

The parent DialogContext, may be null

Throws:

IllegalStateException - if a parent DialogContext initially associated with this DialogContext is no longer available

advance

void advance(javax.faces.context.FacesContext context,
             String outcome)

Advance the execution of this DialogContext instance, until an interaction with the user is required. At that point, navigate to the appropriate view, call FacesContext.renderResponse(), and return.

Parameters:

context - FacesContext for the current request

outcome - Logical outcome to use for driving a transition out of a state that was waiting for user input, or null if no transition should be performed

Throws:

IllegalStateException - if this DialogContext instance has not yet been started

start

void start(javax.faces.context.FacesContext context)

Start the execution of this DialogContext instance, advancing until an interaction with the user is required. At that point, navigate to the appropriate view, call FacesContext.renderResopnse(), and return.

Parameters:

context - FacesContext for the current request

Throws:

IllegalStateException - if this DialogContext instance has already been started

stop

void stop(javax.faces.context.FacesContext context)

Stop the execution of this DialogContext instance, resulting in no currently active dialog for the current JavaServer Faces view.

Parameters:

context - FacesContext for the current request

Throws:

IllegalStateException - if this DialogContext instance has not yet been started

addDialogContextListener

void addDialogContextListener(DialogContextListener listener)

Register given DialogContextListener for this DialogContext. Listener cannot be null.

Parameters:

listener - The DialogContextListener instance.

getDialogContextListeners

DialogContextListener[] getDialogContextListeners()

Return the set of currently registered DialogContextListeners.

removeDialogContextListener

void removeDialogContextListener(DialogContextListener listener)

Remove this previously registered DialogContextListener for this DialogContext. The listener will no longer receive any associated callbacks.

Parameters:

listener - The DialogContextListener instance.