com.sdm.quasar.client.core.dialog.impl
Interface DialogManager

All Superinterfaces:

Disposable, LifeCycleListenerSupport

All Known Implementing Classes:

DefaultDialogManager

public interface DialogManager

extends Disposable, LifeCycleListenerSupport

Manages the dialogs of a session.

DialogManager is responsible for

• creating a dialog instance (#createDialog(String, DialogServiceManager, Object))
• storing the information about existing dialog instances (hasDialog(DialogInstanceId))
• managing the configuration information for dialogs (canCreateDialog(String))
• assigning unique DialogInstanceIds within a session.
• managing the life cycle of a dialog within a hierarchy of dialogs (see LifeCycle)

The following rules describe the dependencies of the life cycle states along the hierarchy of dialogs.

• If the parent is prepared then the child is prepared.
• If the child is prepared then the parent is prepared.
• If the parent is active then the child may be prepared or active
• If the child is active then the parent is active
• It depends on a parent which of its children it activates
• The session as parent is considered to be in state active.
• When a dialog is created and its parent is prepared or active, the new dialog is prepared.
• When a dialog is prepared then all of its children are prepared.
• When a dialog is activated then none of its children are activated automatically.
• When a dialog is deactivated then all of its active children are deactivated.
• When a dialog is released then all of its children are released

Note: Implementations of this interface must be threadsafe and be aware that while executing one method the same or any other method may be called again by the same or another thread. Avoid implementations that might deadlock.

Version:

1.0

Author:

Martin Haft, sd&m AG, Carsten Lucke, sd&m AG, Bernd Olleck, sd&m AG

See Also:

com.sdm.quasar.client.comp.dlgdef.Dialog

Method Summary

boolean	canCreateDialog(java.lang.String dialogId) Tests, whether the dialog with the given id can be created by this dialog manager.
void	collectSystemInfo(ID id, SystemInfoNode root, SystemInfoOptions options) Builds the system information tree upon local information of the implementor about the dialog with the ID given.
DialogInstance	createDialog(java.lang.String dialogId, DialogInstanceId lifeCycleParentDiid, java.lang.Object context) Creates a dependent dialog.
DialogInstance	createRootDialog(DialogInstanceId rootDialogInstanceId, java.lang.Object context) Creates the root dialog instance.
DialogInstanceId	createRootDialogInstanceId() Creates a root dialog id.
void	disposeDialog(DialogInstanceId diid) Disposes a dialog by calling com.sdm.quasar.client.comp.dlgdef.Dialog#dispose().
LifeCycleState	getLifeCycleState(ID id) Returns a LifeCycleState for the given id.
boolean	hasDialog(DialogInstanceId diid) Tests, whether a dialog with a given instance id exists.

Methods inherited from interface com.sdm.quasar.client.core.common.Disposable

dispose

Methods inherited from interface com.sdm.quasar.client.core.dialog.lifecycle.LifeCycleListenerSupport

addLifeCycleListener, removeLifeCycleListener

Method Detail

canCreateDialog

public boolean canCreateDialog(java.lang.String dialogId)

Tests, whether the dialog with the given id can be created by this dialog manager.

Parameters:

dialogId - the id of the dialog

Returns:

true, iff the dialog can be created

createRootDialogInstanceId

public DialogInstanceId createRootDialogInstanceId()

Creates a root dialog id.

Note: This is the first step in creating a root dialog node. A call to #createRootDialog(DialogInstanceId, DialogServiceManager, Object) should follow to finish creation of a root dialog.

Returns:

the DialogInstanceId for the root dialog, that will be created later by calling #createRootDialog(DialogInstanceId, DialogServiceManager, Object).

createRootDialog

public DialogInstance createRootDialog(DialogInstanceId rootDialogInstanceId,
                                       java.lang.Object context)
                                throws DialogException

Creates the root dialog instance.

Note: This is the second step in creating a root dialog node. The given rootDialogInstanceId must already exist. To create a root id use #createRootDialogInstanceId(String) in advance.

It uses the given dialog id and the context object. Based on the dialog id additional configuration may be used.

Parameters:

context - the dialog context object, used as initialization parameter by the dialog

Throws:

java.lang.IllegalArgumentException - if the dialog id is unknown

DialogException - if the dialog could not be created due to an error in configuration or dialog implementation.

createDialog

public DialogInstance createDialog(java.lang.String dialogId,
                                   DialogInstanceId lifeCycleParentDiid,
                                   java.lang.Object context)
                            throws DialogException

Creates a dependent dialog. The dialog will be created and added to the hierarchy as a child to the given parent dialog.

The dialog will be disposed automatically before its parent dialog is disposed.

Parameters:

dialogId - the id of the dialog to be created

lifeCycleParentDiid - the dialog instance id of the parent

context - the dialog context object, used as initialization parameter by the dialog

Returns:

the instance id of the new dialog

Throws:

java.lang.IllegalArgumentException - if the dialog id is unknown

java.lang.IllegalArgumentException - if the parent id is unknown

DialogException - if the dialog could not be created due to an error in configuration or dialog implementation.

disposeDialog

public void disposeDialog(DialogInstanceId diid)
                   throws DialogException

Disposes a dialog by calling com.sdm.quasar.client.comp.dlgdef.Dialog#dispose().

Note: The implementation must not return before the dialog is disposed. Any threads or asynchronous calls started must be completed before this method returns.

Parameters:

diid - diid the dialog instance id of the dialog to be disposed

Throws:

java.lang.IllegalArgumentException - if the dialog instance id is unknown

DialogException - if the dialog could not be correctly disposed due to an error in the dialog implementation.

hasDialog

public boolean hasDialog(DialogInstanceId diid)

Tests, whether a dialog with a given instance id exists.

Parameters:

diid - diid the dialog instance id to be tested

Returns:

true, iff the dialog exists

getLifeCycleState

public LifeCycleState getLifeCycleState(ID id)

Returns a LifeCycleState for the given id. If the id is a known dialog instance id, the returned state is equal to the state of the acssociated dialog instance. Additionally this method assures, that for any other id given, a valid LifeCycleState is returned.

Parameters:

id - the id to get a LifeCycleState for

Returns:

the LifeCycleState for the id

collectSystemInfo

public void collectSystemInfo(ID id,
                              SystemInfoNode root,
                              SystemInfoOptions options)

Builds the system information tree upon local information of the implementor about the dialog with the ID given.

Parameters:

id - the ID to append system information to the node given

root - the SystemInfoNode to add information to (guaranteed to be not null)

options - contains additional options, that might influence the amount of information added to the tree (guaranteed to be not null)