org.apache.shale.dialog
Interface DialogContextManager

All Known Implementing Classes:

AbstractDialogContextManager

public interface DialogContextManager

Management functions for the DialogContext instances related to a particular user's session.

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

Since:

1.0.4

Method Summary

void	addDialogContextManagerListener(DialogContextManagerListener listener) Register given DialogContextManagerListener for this DialogContextManager.
DialogContext	create(javax.faces.context.FacesContext context, String name) Create a new instance of the specified dialog configuration, returning the newly created instance.
DialogContext	create(javax.faces.context.FacesContext context, String name, DialogContext parent) Create a new instance of the specified dialog configuration, returning the newly created instance.
DialogContext	get(String id) Return the DialogContext instance for the specified identifier (if any); otherwise, return null.
DialogContext	getActiveDialogContext(javax.faces.context.FacesContext context) Return the currently active DialogContext instance for the current request, if there is one; otherwise, return null.
DialogContextManagerListener[]	getDialogContextManagerListeners() Return the set of currently registered DialogContextManagerListeners.
void	remove(DialogContext instance) Remove the specified DialogContext instance from the set of active instances for the current user.
void	removeDialogContextManagerListener(DialogContextManagerListener listener) Remove this previously registered DialogContextManagerListener for this DialogContextManager.

Method Detail

create

DialogContext create(javax.faces.context.FacesContext context,
                     String name)

Create a new instance of the specified dialog configuration, returning the newly created instance. This instance must contain an id value that is guaranteed to be unique among all active instances for the current user. The instance must also have been stored as a request scope attribute under key Constants.INSTANCE_BEAN. The new instance will not be associated with any parent instance.

Parameters:

context - FacesContext for the current request

name - Logical name of the dialog to be created

Returns:

The newly created DialogContext instance, with no parent dialog association

Throws:

IllegalArgumentException - if no dialog definition can be found for the specified logical name

create

DialogContext create(javax.faces.context.FacesContext context,
                     String name,
                     DialogContext parent)

Create a new instance of the specified dialog configuration, returning the newly created instance. This instance must contain an id value that is guaranteed to be unique among all active instances for the current user. The instance must also have been stored as a request scope attribute under key Constants.INSTANCE_BEAN. The new instance will be associated with the specified parent instance, which must be managed by this DialogContextManager and therefore belong to the same user.

IMPLEMENTATION NOTE - Applications should generally not call this method directly, because it will be awkward to associate the newly created DialogContext instance with a different view instance. Instead, this method is primarily intended to support the ability to automatically associate the DialogContext for, say, a pop-up window with the DialogContext of the corresponding main window. This facility is supported automatically by the phase listener that manages saving and restoring the association of a DialogContext and its corresponding JSF view.

Parameters:

context - FacesContext for the current request

name - Logical name of the dialog to be executed

parent - Parent DialogContext with which the new instance will be assocated (if any)

Returns:

The newly created "child" DialogContext instance

Throws:

IllegalArgumentException - if no dialog definition can be found for the specified logical name

IllegalStateException - if the specified parent instance is not managed by this DialogContextManager

get

DialogContext get(String id)

Return the DialogContext instance for the specified identifier (if any); otherwise, return null.

Parameters:

id - Dialog identifier for which to return an instance

Returns:

The DialogContext instance for this identifier, may be null

getActiveDialogContext

DialogContext getActiveDialogContext(javax.faces.context.FacesContext context)

Return the currently active DialogContext instance for the current request, if there is one; otherwise, return null.

Parameters:

context - FacesContext for the current request

Since:

1.1.0

remove

void remove(DialogContext instance)

Remove the specified DialogContext instance from the set of active instances for the current user.

Parameters:

instance - DialogContext instance to be removed

addDialogContextManagerListener

void addDialogContextManagerListener(DialogContextManagerListener listener)

Register given DialogContextManagerListener for this DialogContextManager. Listener cannot be null.

Parameters:

listener - The DialogContextManagerListener instance.

getDialogContextManagerListeners

DialogContextManagerListener[] getDialogContextManagerListeners()

Return the set of currently registered DialogContextManagerListeners.

removeDialogContextManagerListener

void removeDialogContextManagerListener(DialogContextManagerListener listener)

Remove this previously registered DialogContextManagerListener for this DialogContextManager. The listener will no longer receive any associated callbacks.

Parameters:

listener - The DialogContextManagerListener instance.