Start of Content Area

Process documentation Error Handling  Locate the document in its SAP Library structure

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

·        Message Editor

·        Processing a Message

·        Example for Using Messages

.

Description of Interface IWDMessageManager

Simple, String-Based Methods of the Message Manager

/**

 * Report error message <code>message</code>..

 *

 * @param message is the human readable message that will be
 * displayed on the client. Success phase of the Web Dynpro
 * request / response cycle are not executed anymore

 */

 public void reportException(String message, boolean cancelNavigation);

 

/**

 * Report warning message <code>message</code>.

 *

 * @param message is the human readable message that will be displayed
 * on the client

 */

  public void reportWarning(String message);

     

/**

 * Report an message <code>message</code>.

 *

 * @param message is the human readable message that will be displayed
 * on the client

 */

  public void reportSuccess(String message);

 

Context-Specific Methods of the Message Manager

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);

 

Message-Based Methods of the Message Manager

A message-based method of the Message Manager is described below:

/**

  * Report a message item caused by an invalid context attribute
  * value.
  *

  * @param element is a reference to the context node element
  * containing the invalid attribute

  * @param attributeName is the name of the attribute which is invalid

  * @param messageItem is the message associated with the context
  * attribute

  * @param args are the arguments for the message parameters in the
   * same way as used in @see java.text.MessageFormat

  */

  public void reportContextAttributeMessage(

IWDNodeElement element,
IWDAttributeInfo attrInfo,
IWDMessage messageItem, Object[] args,
boolean cancelNavigation);

 

/**

  * Raises a message caused by an invalid context attribute value. This
  * method
internally raises a Runtime exception and execution

  * continues in the Web Dynpro framework. It is not recommended to
  * call this method with warnings

  * and success messages.

  *

  * @param messageItem is the message associated with the context

  * attribute

  * @param args are the arguments for the message parameters in the
   * same way as used in @see java.text.MessageFormat

  */

  public void raiseMessage(IWDMessage messageItem, Object[] args,

boolean cancelNavigation);

 

 /**

   * Report a message item caused by an invalid context attribute
   * value.Depending on the type of the message item

   * and on user settings this method may either return or raise a
   * runtime exception in order to return to the

   * framework error handling.

   *

   *

   * @param messageItem is the message associated with the context
  * attribute

   * @param args are the arguments for the message parameters in the
   * same way as used in @see java.text.MessageFormat

   */

  public void reportMessage(IWDMessage messageItem, Object[]args,

 boolean cancelNavigation);

 

 

Error Handling and Navigation

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

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

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.

Raise and Report Methods

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.

Caution

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.

  

  

 

End of Content Area