Informational Manager

The standard exception handling and string presentation features described in this chapter do not address one scenario. In a number of situations it is useful to present multiple informational messages at one time. For example, during the course of validation a number of warnings, or errors, may occur independently as they are based on different elements of the user input. These should be reported together to simplify the corrective actions that a user must take. The InformationalManager class allows for exceptions and informationals to be grouped together in this manner. Informational Manager shows the use of this class to group informational messages for presentation:

Figure 1. Use of the Informational Manager

import curam.util.exception.InformationalElement;
import curam.util.exception.InformationalException;
import curam.util.exception.InformationalManager;
import curam.util.exception.LocalisableString;
import curam.util.internal.security.struct.LoginMessage;
import curam.util.internal.security.struct.LoginMessageList;
import curam.util.message.INFRASTRUCTURE;
import curam.util.resources.GeneralConstants;

class InformationalManagerDemo {

  public LoginMessageList checkLoginStatus()
  throws InformationalException {

    // Create an informational manager to store the
    // results of the validation checks. A transaction wide
    // version can be obtained via
    // TransactionInfo.getInformationalManager().
    final InformationalManager informationalManager =
      new InformationalManager();

    // Informational #1
    // Create an informational string for presentation to
    // the client: this specifies the password will expire
    // in 6 days
    LocalisableString infoMessage1 = new LocalisableString(
        INFRASTRUCTURE.INFO_ID_PASSWORD_EXPIRING);
    infoMessage1.arg(6);
    // Add this informational string to the informational
    // manager
    informationalManager.addInformationalMsg(infoMessage1,
        GeneralConstants.kEmpty,
        InformationalElement.InformationalType.kWarning);

    // Informational #2
    // Create an informational string for presentation to
    // the client: this specifies the user will be locked
    // out if they do not change their password in the next
    // 10 logins.
    LocalisableString infoMessage2 = new LocalisableString(
        INFRASTRUCTURE.INFO_ID_LOG_ATTEMPTS_EXPIRING);
    infoMessage1.arg(10);
    // Add this informational string to the informational
    // manager
    informationalManager.addInformationalMsg(infoMessage2,
        GeneralConstants.kEmpty,
        InformationalElement.InformationalType.kWarning);

    // The informationals must now be converted to a format
    // suitable for return to the client.
    final String[] informationalArray = informationalManager
        .obtainInformationalAsString();
    // The array of informational strings must be
    // transferred to an array of structs because we
    // cannot return an array of strings directly. Each
    // string goes into one struct (LoginMessage) and
    // this is aggregated into a list by struct
    // LoginMessageList.
    // LoginMessage : A struct containing one string
    // named 'message'.
    // LoginMessageList : A struct which aggregates
    // LoginMessage as member 'dtls'.
    final LoginMessageList result = new LoginMessageList();
    for (int i = 0; i != informationalArray.length; i++) {
      LoginMessage warning = new LoginMessage();
      warning.message = informationalArray[i];
      result.dtls.addRef(warning);
    }
    return result;
  }

}

There are a number of points worth emphasizing in this code fragment:

This sample is based around the presentation of informationals to the client. It does not throw an exception, and therefore it is a successful invocation of the method. This means the transaction will be committed and any database updates will be made permanent. It is the responsibility of the client screen for this sample to handle the return value of the operation as a collection of informationals.
InformationalManager. failOperation() can be used to fail the invocation depending on whether or not the informational manager contains any warnings or errors. If the informational manager contains an error or warning then this method will throw an exception which means the transaction will be rolled-back. Otherwise this method does nothing and the transaction is allowed to continue. The full details of this operation are described in the API documentation (JavaDoc) shipped with IBM Cúram Social Program Management.
The second parameter to InformationalManager.addInformationalMsg currently populated with GeneralConstants.kEmpty (as in Informational Manager) is intended to name a field. However, this is not supported in the current release

The Cúram Web Client Reference Manual should be consulted to determine the client side configuration that is necessary to use the InformationalManager; at its simplest the field in the struct containing the informationals must be named in the UIM.

The InformationalManager logs informationals to the Curam log. Please see Logging for details on Logging.The informationals are logged in the following way:

Logging of the informationals is only performed at the time when they are added to the InformationalManager (i.e. when calling InformationalManager. addInformationalMsg()).
Fatal errors and errors are logged at the top level logger using the error level.
Warnings are logged at the top level logger using the info level.