org.universAAL.middleware.ui
Interface IUIBus

All Known Implementing Classes:

UIBusImpl

public interface IUIBus

The IUIBus is responsible for brokerage between applications that need to reach human users (in order to present information to them and / or ask them for intervention) and the so-called UIHandlers that can handle the interaction with human users through UI channels under their control. This bus is a call-based bus without any support for synchronized delivery of replies (replies will always be delivered in a new thread). It defines protocols for suspending and resuming dialogs, dynamic adaptation of "rendering" by a previously selected UIHandler during the dialog is running, and transfer of responsibility to another UIHandler. It accepts registration parameters from UIHandlers (when they register to the bus) and allows removing and/or updating of these parameters.

Author:

mtazari, eandgrg

Method Summary

void	abortDialog(String callerID, String dialogID) Aborts the dialog upon request from the application or Dialog Manager.
void	adaptationParametersChanged(IDialogManager dm, UIRequest uicall, String changedProp) Only the Dialog Manager (DM) can call this method.
void	addNewProfile(String handlerID, UIHandlerProfile uiHandlerProfile) Extends the profile of a registered subscriber (UIHandler) with regard to UIRequests that it can handle.
void	brokerUIRequest(String callerID, UIRequest uicall) Can be used by applications to send a UIRequest.
void	dialogFinished(String handlerID, UIResponse uiResponse) Whenever a dialog is finished, UIHandlers must inform the IUIBus by calling this method.
void	dialogSuspended(IDialogManager dm, String dialogID) Only the Dialog Manager (DM) can call this method.
UIHandlerProfile[]	getMatchingProfiles(String modalityRegex) Retrieves all registered UIHandlerProfiles that has restriction for modality matched by modalityRegex
void	removeMatchingProfile(String handlerID, UIHandlerProfile oldUIHandlerProfile) Removes matching patterns of UIRequests from the profile of the UIHandler.
void	resumeDialog(String callerID, String dialogID, Resource dialogData) Applications can use this method to ask the IUIBus to resume a dialog that was interrupted due to the activation of a sub-dialog of it.
void	unregister(String callerID, UICaller uicaller) Unregisters an application's caller from the bus.
void	unregister(String handlerID, UIHandler uiHandler) Unregisters the given UIHandler from the bus..
void	userLoggedIn(String handlerID, Resource user, AbsLocation loginLocation) Notifies IUIBus that the human user has logged in (using UIHandler).

Method Detail

abortDialog

void abortDialog(String callerID,
                 String dialogID)

Aborts the dialog upon request from the application or Dialog Manager. No matter which one has requested the abort, the bus informs both when the operation is finished (informing the caller as a sort of acknowledgment and informing the other one to prevent unnecessary waiting).

Parameters:

callerID - ID of the application that had originally started the dialog

dialogID - ID of the dialog

adaptationParametersChanged

void adaptationParametersChanged(IDialogManager dm,
                                 UIRequest uicall,
                                 String changedProp)

Only the Dialog Manager (DM) can call this method. When the DM notices that personal and / or situational parameters relevant for a running dialog have changed, it notifies the IUIBus by calling this method. The IUIBus may then either notify the UIHandler in charge of that dialog to consider the changes (if the changes in the adaptation parameters still match its profile -- see also UIHandler.adaptationParametersChanged(String, String, Object)) or switch to another UIHandler (if the new situation cannot be handled by the previous UIHandler). In the latter case, the previous UIHandler is notified to abort the dialog while returning any intermediate user input collected so far (by calling UIHandler.cutDialog(String)), and then the new UIHandler is mandated (by calling UIHandler.handleUICall(UIRequest)) to continue with the dialog presentation without loss of data.

Parameters:

dm - Dialog Manager

uicall - The whole call context that is affected by the change, including the dialog ID and the the new value of the changed property

changedProp - the property (from among all properties of the call context) that has changed

addNewProfile

void addNewProfile(String handlerID,
                   UIHandlerProfile uiHandlerProfile)

Extends the profile of a registered subscriber (UIHandler) with regard to UIRequests that it can handle. Responsible (together with removeMatchingProfile(String, UIHandlerProfile)) for changing the handler's profile dynamically.

Parameters:

handlerID - ID of the UIHandler introducing the new registration parameters

uiHandlerProfile - the new class of UIRequests that can additionally be handled by the given UIHandler

dialogFinished

void dialogFinished(String handlerID,
                    UIResponse uiResponse)

Whenever a dialog is finished, UIHandlers must inform the IUIBus by calling this method.

Parameters:

handlerID - ID of the UIHandler that has finished the dialog

{@link - UIHandler} response The user input constructed by calling UIResponse.UIResponse(Resource, AbsLocation, Submit)

dialogSuspended

void dialogSuspended(IDialogManager dm,
                     String dialogID)

Only the Dialog Manager (DM) can call this method. When the DM wants that a running dialog is substituted by another dialog (e.g., because a new UIRequest with a higher priority than the running one is addressing the same user, or because the user wants to switch to another dialog using the "standard buttons"), then it must notify the IUIBus by calling this method. The IUIBus will then ask the UIHandler in charge of handling the running dialog to cut that dialog (see UIHandler.cutDialog(String)) and return all user input collected so far so that the dialog can be resumed later without loss of data.

Parameters:

dm - Dialog Manager

dialogID - ID of the dialog to suspend

removeMatchingProfile

void removeMatchingProfile(String handlerID,
                           UIHandlerProfile oldUIHandlerProfile)

Removes matching patterns of UIRequests from the profile of the UIHandler. Responsible (together with addNewProfile(String, UIHandlerProfile)) for changing the handler's profile dynamically.

Parameters:

handlerID - ID of the calling UIHandler that had previously registered 'oldProfile'

oldProfile - the profile registered previously

resumeDialog

void resumeDialog(String callerID,
                  String dialogID,
                  Resource dialogData)

Applications can use this method to ask the IUIBus to resume a dialog that was interrupted due to the activation of a sub-dialog of it. This is the only case where the applications are aware about a dialog having been suspended because the resumption depends on them having processed the user input in the context of the sub-dialog and having incorporated it into the form data of the parent dialog if needed. Then, they can activate the parent dialog using this method.

Parameters:

callerID - ID of the application that had originally started the dialog

dialogID - ID of the dialog

dialogData - dialog data (see Form.getData())

brokerUIRequest

void brokerUIRequest(String callerID,
                     UIRequest uicall)

Can be used by applications to send a UIRequest.

Parameters:

callerID - ID of the caller that is sending the UI request

uicall - The actual UI request

unregister

void unregister(String callerID,
                UICaller uicaller)

Unregisters an application's caller from the bus.

Parameters:

callerID - ID of the caller to be unregistered

uicaller - the caller to be unregistered

unregister

void unregister(String handlerID,
                UIHandler uiHandler)

Unregisters the given UIHandler from the bus..

Parameters:

handlerID - ID of the handler to be unregistered

uiHandler - the handler to be unregistered

userLoggedIn

void userLoggedIn(String handlerID,
                  Resource user,
                  AbsLocation loginLocation)

Notifies IUIBus that the human user has logged in (using UIHandler).

Parameters:

handlerID - id of the UIHandler which is received when registering to the IUIBus. It must be passed to the bus when calling bus methods.

user - human User. It is declared as Resource because the type User is defined in the Profiling Ontology. The type is not needed for for matchmaking Either.

loginLocation - login Location of the User

getMatchingProfiles

UIHandlerProfile[] getMatchingProfiles(String modalityRegex)

Retrieves all registered UIHandlerProfiles that has restriction for modality matched by modalityRegex

Parameters:

modalityRegex - - regular expression used for matching UIHandlerProfiles modalities

Returns:

Array of matched UIHandlerProfiles