The Message Manager, represented by the interface IWDMessageManager, enables you to handle messages and can be used to display information or report errors on the screen. Using relevant methods and depending on the message type, the runtime environment provides the user with a dialog with the Web Dynpro application. Error messages and other messages can be displayed by calling a method of the Message Manager. The Message Manager also provides a number of methods that allow the generation of different error messages and different user interactions to correct the errors.
Error and message handling is closely linked with event handling, validation, and a cycle of questions/answers for a query sent to the server. The runtime environment processes a specific sequence of phases – that is, specific program steps – that are executed within a question/answer cycle. If errors occur when the Message Manager IWDMessageManager is called or when an exception WDNonFatalRutimeException is raised, the subsequent phases of a current question/answer cycle are no longer processed. For example, the system highlights the errors so that the user can easily correct errors caused by incorrect input (see following description). Afterwards, all subsequent phases of the question/answer cycle can be executed.
For more detailed information about creating, editing and changing messages and for a source text example for using messages, see
· Messages
.
/** * Report error message <code>message</code>.. *
*
@param message is the human
readable message that will be */ public void reportException(String message, boolean cancelNavigation);
/** * Report warning message <code>message</code>. *
*
@param message is the human
readable message that will be displayed */ public void reportWarning(String message);
/** * Report an message <code>message</code>. *
*
@param message is the human
readable message that will be displayed */ public void reportSuccess(String message);
|
In many cases, an
error is caused by invalid data input by the user. To help the user correct
invalid data, the Message Manager IWDMessageManager provides a number of methods that allow you to link
errors or warnings with a specific context attribute. In this case, the error
is not signified by a simple error message, but instead the UI element that is
linked with the invalid context attribute is highlighted – that is, is
framed in red. Furthermore, you can simply choose the error message and are
then automatically taken to a UI element. You can then correct the error. To
link a context attribute with a specific warning or error, the Message Manager
provides a number of methods with which you can pass a node element and the
name of the context attribute as a parameter. The naming convention for
methods that can be linked with a context attribute is:
reportInvalidContextAttribute<method
suffix>.
For example:
public void reportInvalidContextAttributeException( IWDNodeElement element, String attributeName, WDNonFatalException ex boolean cancelNavigation);
public void reportInvalidContextAttributeException( IWDNodeElement element, String attributeName, String message boolean cancelNavigation);
|
A message-based method of the Message Manager is described below:
/**
*
Report a
message item caused by an invalid context attribute
*
@param element is a reference
to the
context node element * @param attributeName is the name of the attribute which is invalid
*
@param messageItem is the message
associated with the context
*
@param args are the arguments
for the
message parameters in the */ public void reportContextAttributeMessage( IWDNodeElement
element,
/**
*
Raises a
message caused by an invalid
context attribute value.
This
* continues
in the
Web Dynpro framework.
It is
not recommended to * and success messages. * * @param messageItem is the message associated with the context * attribute
*
@param args are the arguments
for the
message parameters in the */ public void raiseMessage(IWDMessage messageItem, Object[] args, boolean cancelNavigation);
/**
* Report a message
item caused by an invalid
context attribute
* and on user settings this method may
either return or raise a * framework error handling. * *
* @param
messageItem is the message associated
with the
context
* @param args are the arguments
for the
message parameters in the */ public void reportMessage(IWDMessage messageItem, Object[]args, boolean cancelNavigation);
|
All the methods of interface IWDMessageManager that refer to error messages have parameter cancelNavigation. This parameter is of type boolean. If you set the parameter to true, all subseqquent navigation links and doModifyView methods are not called and are executed for the current question-answer cycle. In this way you can protect the system against a loss of unstored data.
In some cases, however, navigation is also required if there is an error. In this case you msut set the parameter to false. The error will not have an effect on subsequent phase processing, but the error is displayed.
Resetting Messages:
The Web Dynpro runtime environment resets the Message Manager for each question-answer cycle. The contents of the Message Manager are not changed for system and service events. Once the action has been performed, the Web Dynpro runtime environment deletes the contents of the Message Manager.
Note that
§ the Message Manager is reset if a UI element event triggers an action that is activated
§ the Message Manager for service events of the Web Dynpro runtime environment such as load-on-demand events or the input help are not reset
General Rules Concerning Behavior in Case of Errors:
Since Web Dynpro divides a question/answer cycle into various phases, the behavior of the runtime services depends on the phase that is currently running. For example, you cannot trigger an exception and thereby cancel execution of the application if navigation is being performed. The explanation for this is very simple: While navigation is being perforemd, the view group is only in a consistent state before navigation is started and after navigation has been performed. The view group can have any value in between. At this time the Web Dynpro runtime environment therefore cannot determine if navigation was performed if an exception is triggered at this time. This is also true if a doModifyView method is executed.
In this phase the source text of the application can modify the hierarchic UI element structure of a view dynamically. If an exception now occurs, you cannot be sure that this structure is in a consistent state.
Note that exceptions are triggered for error handling if they are edited during event handling for actions. Otherwise the Web Dynpro framework ends the application. The same is true for all methods of the interface of the IWDMessageManager that can output a message on the screen.
Ideally the methods of the Message Manager should only be called within the implementation of an action event handler. However, other methods are often called in the action event handler. The Message Manager should not call these methods directly, but only trigger tested exceptions. These exceptions should be caught by the implementation of an action event handler and reported to the Message Manager.
When handling errors, note that
· Source text that is not called with an action event handler cannot trigger a WDNonFatalRuntimeException. Instead, the source text should trigger an exception that is caught by the calling method.
· Source text that is not called from an action event handler cannot call raise and report methods of the Message Manager. Instead, the source text should trigger an exception that is caught by the calling method.
· Supply functions do not trigger a WDNonFatalRuntimeException and cannot call raise methods of the Message Manager.
· Inbound plugs and methoden within the wdDoInit method do not trigger a WDNonFatalRuntimeException or cannot call raise methods of the Message Manager.
Most of the methods provided by the Message Manager are available both as raise and as report methods. The difference between these methods is that:
· Report methods save the message and pass it back to the object that called the method
·
Raise methods also save the message, but do not pass it back to the object that called
the method. Instead, they
interrupt the current execution phase and proceed directly to the error
handling.
The raise methods are not returned to the object that called
them, since the runtime environment raises a private exception.
Other methods should not be used for the error handling of a Web Dynpro application.
If you use report methods, you can output several errors within a single one. This means that all errors are displayed at the same time. The user can correct errors in a single step and does not have to process any additional requests.