DialogContext Class

Package:
com.microsoft.bot.dialogs
Maven Artifact:
com.microsoft.bot:bot-dialogs:4.14.3
  • java.lang.Object
    • com.microsoft.bot.dialogs.DialogContext

public class DialogContext

Provides context for the current state of the dialog stack.

Constructor Summary

Constructor Description
DialogContext(DialogSet withDialogs, TurnContext withTurnContext, DialogState withState)

Initializes a new instance of the DialogContext class from the turn context.
DialogContext(DialogSet withDialogs, DialogContext withParentDialogContext, DialogState withState)

Initializes a new instance of the DialogContext class from the turn context.

Method Summary

Modifier and Type Method and Description
java.util.concurrent.CompletableFuture<DialogTurnResult> beginDialog(String dialogId)

Starts a new dialog and pushes it onto the dialog stack.
java.util.concurrent.CompletableFuture<DialogTurnResult> beginDialog(String dialogId, Object options)

Starts a new dialog and pushes it onto the dialog stack.
java.util.concurrent.CompletableFuture<DialogTurnResult> cancelAllDialogs()

Helper method for cancelAllDialogs(boolean cancelParents, String eventName, Object eventValue) that does not cancel parent dialogs or pass and event.
java.util.concurrent.CompletableFuture<DialogTurnResult> cancelAllDialogs(boolean cancelParents, String eventName, Object eventValue)

Deletes any existing dialog stack thus canceling all dialogs on the stack.
java.util.concurrent.CompletableFuture<DialogTurnResult> continueDialog()

Continues execution of the active dialog, if there is one, by passing the current DialogContext to the active dialog's continueDialog(DialogContext dc) method.
java.util.concurrent.CompletableFuture<java.lang.Boolean> emitEvent(String name)
java.util.concurrent.CompletableFuture<java.lang.Boolean> emitEvent(String name, Object value, boolean bubble, boolean fromLeaf)
java.util.concurrent.CompletableFuture<DialogTurnResult> endDialog()

Helper method that supplies a null result to endDialog(Object result).
java.util.concurrent.CompletableFuture<DialogTurnResult> endDialog(Object result)

Ends a dialog by popping it off the stack and returns an optional result to the dialog's parent.
Dialog findDialog(String dialogId)

Find the dialog id for the given context.
DialogInstance getActiveDialog()

Gets the cached instance of the active dialog on the top of the stack or null if the stack is empty.
DialogContext getChild()

Gets dialog context for child if there is an active child.
TurnContext getContext()

Gets the context for the current turn of conversation.
DialogSet getDialogs()

Gets the set of dialogs which are active for the current dialog container.
java.lang.String getLocale()

Obtain the locale in DialogContext.
DialogContext getParent()

Gets the parent DialogContext, if any.
TurnContextStateCollection getServices()

Gets the services collection which is contextual to this dialog context.
java.util.List<DialogInstance> getStack()

Gets the current dialog stack.
DialogStateManager getState()

Gets or sets the DialogStateManager which manages view of all memory scopes.
java.util.concurrent.CompletableFuture<DialogTurnResult> prompt(String dialogId, PromptOptions options)

Helper function to simplify formatting the options for calling a prompt dialog.
java.util.concurrent.CompletableFuture<DialogTurnResult> replaceDialog(String dialogId)

Helper method for replaceDialog(String dialogId, Object options) that passes null for options.
java.util.concurrent.CompletableFuture<DialogTurnResult> replaceDialog(String dialogId, Object options)

Starts a new dialog and replaces on the stack the currently active dialog with the new one.
java.util.concurrent.CompletableFuture<java.lang.Void> repromptDialog()

Calls the currently active dialog's repromptDialog(TurnContext turnContext, DialogInstance instance) method.
void setParent(DialogContext withDialogContext)

Set the parent DialogContext.

Methods inherited from java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.toString java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Constructor Details

DialogContext

public DialogContext(DialogSet withDialogs, TurnContext withTurnContext, DialogState withState)

Initializes a new instance of the DialogContext class from the turn context.

Parameters:

withDialogs - The dialog set to create the dialog context for.
withTurnContext - The current turn context.
withState - The state property from which to retrieve the dialog context.

DialogContext

public DialogContext(DialogSet withDialogs, DialogContext withParentDialogContext, DialogState withState)

Initializes a new instance of the DialogContext class from the turn context.

Parameters:

withDialogs - The dialog set to create the dialog context for.
withParentDialogContext - Parent dialog context.
withState - Current dialog state.

Method Details

beginDialog

public CompletableFuture beginDialog(String dialogId)

Starts a new dialog and pushes it onto the dialog stack.

Parameters:

dialogId - ID of the dialog to start.

Returns:

If the task is successful, the result indicates whether the dialog is still active after the turn has been processed by the dialog.

beginDialog

public CompletableFuture beginDialog(String dialogId, Object options)

Starts a new dialog and pushes it onto the dialog stack.

Parameters:

dialogId - ID of the dialog to start.
options - Optional, information to pass to the dialog being started.

Returns:

If the task is successful, the result indicates whether the dialog is still active after the turn has been processed by the dialog.

cancelAllDialogs

public CompletableFuture cancelAllDialogs()

Helper method for cancelAllDialogs(boolean cancelParents, String eventName, Object eventValue) that does not cancel parent dialogs or pass and event.

Returns:

If the task is successful, the result indicates that dialogs were canceled after the turn was processed by the dialog or that the stack was already empty.

cancelAllDialogs

public CompletableFuture cancelAllDialogs(boolean cancelParents, String eventName, Object eventValue)

Deletes any existing dialog stack thus canceling all dialogs on the stack.

In general, the parent context is the dialog or bot turn handler that started the dialog. If the parent is a dialog, the stack calls the parent's resumeDialog(DialogContext dc, DialogReason reason, Object result) method to return a result to the parent dialog. If the parent dialog does not implement Dialog#resumeDialog, then the parent will end, too, and the result is passed to the next parent context.

Parameters:

cancelParents - If true the cancellation will bubble up through any parent dialogs as well.
eventName - The event. If null, CANCEL_DIALOG is used.
eventValue - The event value. Can be null.

Returns:

If the task is successful, the result indicates that dialogs were canceled after the turn was processed by the dialog or that the stack was already empty.

continueDialog

public CompletableFuture continueDialog()

Continues execution of the active dialog, if there is one, by passing the current DialogContext to the active dialog's continueDialog(DialogContext dc) method.

Returns:

If the task is successful, the result indicates whether the dialog is still active after the turn has been processed by the dialog.

emitEvent

public CompletableFuture emitEvent(String name)

Parameters:

name - Name of the event to raise.

Returns:

emitEvent

emitEvent

public CompletableFuture emitEvent(String name, Object value, boolean bubble, boolean fromLeaf)

Parameters:

name - Name of the event to raise.
value - Value to send along with the event.
bubble - Flag to control whether the event should be bubbled to its parent if not handled locally. Defaults to a value of true.
fromLeaf - Whether the event is emitted from a leaf node.

Returns:

completedFuture

endDialog

public CompletableFuture endDialog()

Helper method that supplies a null result to endDialog(Object result).

Returns:

If the task is successful, the result indicates that the dialog ended after the turn was processed by the dialog.

endDialog

public CompletableFuture endDialog(Object result)

Ends a dialog by popping it off the stack and returns an optional result to the dialog's parent. The parent dialog is the dialog the started the on being ended via a call to either beginDialog(String dialogId, Object options) or prompt(String dialogId, PromptOptions options). The parent dialog will have its resumeDialog(DialogContext dc, DialogReason reason, Object result) method invoked with any returned result. If the parent dialog hasn't implemented a resumeDialog(DialogContext dc, DialogReason reason) method, then it will be automatically ended as well and the result passed to its parent. If there are no more parent dialogs on the stack then processing of the turn will end.

Parameters:

result - Optional, result to pass to the parent context.

Returns:

If the task is successful, the result indicates that the dialog ended after the turn was processed by the dialog.

findDialog

public Dialog findDialog(String dialogId)

Find the dialog id for the given context.

Parameters:

dialogId - dialog id to find.

Returns:

dialog with that id, or null.

getActiveDialog

public DialogInstance getActiveDialog()

Gets the cached instance of the active dialog on the top of the stack or null if the stack is empty.

Returns:

The cached instance of the active dialog on the top of the stack or null if the stack is empty.

getChild

public DialogContext getChild()

Gets dialog context for child if there is an active child.

Returns:

Dialog context for child if there is an active child.

getContext

public TurnContext getContext()

Gets the context for the current turn of conversation.

Returns:

The context for the current turn of conversation.

getDialogs

public DialogSet getDialogs()

Gets the set of dialogs which are active for the current dialog container.

Returns:

The set of dialogs which are active for the current dialog container.

getLocale

public String getLocale()

Obtain the locale in DialogContext.

Returns:

A String representing the current locale.

getParent

public DialogContext getParent()

Gets the parent DialogContext, if any. Used when searching for the ID of a dialog to start.

Returns:

The parent "DialogContext, if any. Used when searching for the ID of a dialog to start.

getServices

public TurnContextStateCollection getServices()

Gets the services collection which is contextual to this dialog context.

Returns:

Services collection.

getStack

public List getStack()

Gets the current dialog stack.

Returns:

The current dialog stack.

getState

public DialogStateManager getState()

Gets or sets the DialogStateManager which manages view of all memory scopes.

Returns:

DialogStateManager with unified memory view of all memory scopes.

prompt

public CompletableFuture prompt(String dialogId, PromptOptions options)

Helper function to simplify formatting the options for calling a prompt dialog. This helper will take an PromptOptions argument and then call beginDialog(String dialogId, Object options)

Parameters:

dialogId - ID of the prompt dialog to start.
options - Information to pass to the prompt dialog being started.

Returns:

If the task is successful, the result indicates whether the dialog is still active after the turn has been processed by the dialog.

replaceDialog

public CompletableFuture replaceDialog(String dialogId)

Helper method for replaceDialog(String dialogId, Object options) that passes null for options.

Parameters:

dialogId - ID of the new dialog to start.

Returns:

If the task is successful, the result indicates whether the dialog is still active after the turn has been processed by the dialog.

replaceDialog

public CompletableFuture replaceDialog(String dialogId, Object options)

Starts a new dialog and replaces on the stack the currently active dialog with the new one. This is particularly useful for creating loops or redirecting to another dialog.

Parameters:

dialogId - ID of the new dialog to start.
options - Optional, information to pass to the dialog being started.

Returns:

If the task is successful, the result indicates whether the dialog is still active after the turn has been processed by the dialog.

repromptDialog

public CompletableFuture repromptDialog()

Calls the currently active dialog's repromptDialog(TurnContext turnContext, DialogInstance instance) method. Used with dialogs that implement a re-prompt behavior.

Returns:

A task that represents the work queued to execute.

setParent

public void setParent(DialogContext withDialogContext)

Set the parent DialogContext.

Parameters:

withDialogContext - The DialogContext to set the parent to.

Applies to