Notification

Example: Error Checking a Window (C#)

In Figure 1 I have a simplistic form to submit to judge an insurance claim. I have three bits of data to submit: the policy number (a string), the type of claim (text from a pick list), and the date of the incident (a DateTime).

If my data is simplistic, just wait for my validity checks:

• Check that none of the three bits of data are missing (null or blank for the strings.
• Check that the policy number is present in the data store.
• Check that the date of the incident is later than the inception date of the policy.

We want to give as much information back to the user as possible, so if we can reasonably detect multiple errors we should.

I'll start the discussion with the domain layer. The basic interface to the domain logic is in a Service Layer.

class ClaimService...

  public void RegisterClaim (RegisterClaimDTO claim) {
    RegisterClaim cmd = new RegisterClaim(claim);
    cmd.Run();
  }

This method just creates and runs a command object to do the actual work. Wrapping command objects behind a method call service layer can help simplify a server API and make it easier to build a Remote Facade.

I use a Data Transfer Object, to transfer the data over. The RegisterClaimDTO contains the main data.

RegisterClaimDTO : DataTransferObject

  private string _policyID;
  private string _Type;
  private DateTime _incidentDate = BLANK_DATE;

  public string PolicyId {
    get { return _policyID; }
    set { _policyID = value; }
  }
  public string Type {
    get { return _Type; }
    set { _Type = value; }
  }
  public DateTime IncidentDate {
    get { return _incidentDate; }
    set { _incidentDate = value; }
  }

DataTransferObject is a Layer Supertype for all the DTOs. This contains general code to create and access a Notification to go with the interaction.

class DataTransferObject...

  private Notification _notification = new Notification();
  public Notification Notification {
    get { return _notification; }
    set { _notification = value; }
  }

The notification class is what we'll use to capture the errors in the domain layer. Essentially it's a collection of errors, each one of which is a simple wrapper around a string.

class Notification...

  private IList _errors = new ArrayList();

  public IList Errors {
    get { return _errors; }
    set { _errors = value; }
  }
  public bool HasErrors {
    get {return 0 != Errors.Count;}      
  }

class Notification.Error

  private string message;
  public Error(string message) {
    this.message = message;
  }

The command's run method is very simple.

class class RegisterClaim : ServerCommand...

  public RegisterClaim(RegisterClaimDTO claim) : base(claim) {}
  public void Run() {
    Validate();
    if (!notification.HasErrors)
      RegisterClaimInBackendSystems();    
  }

Again the Layer Supertype provides some general functionality to store the DTO and access the notification.

class ServerCommand...

  public ServerCommand(DataTransferObject data){
    this._data = data;
  }
  protected DataTransferObject _data;
  protected Notification notification {
    get {return _data.Notification;}
  }

The validate method carries out the validations that I talked about above. Essentially all it does is run a series of conditional checks, adding errors into the notification if anything fails.

class RegisterClaim...

  private void Validate() {
    failIfNullOrBlank(Data.PolicyId, RegisterClaimDTO.MISSING_POLICY_NUMBER);
    failIfNullOrBlank(Data.Type, RegisterClaimDTO.MISSING_INCIDENT_TYPE);
    fail (Data.IncidentDate == RegisterClaimDTO.BLANK_DATE, RegisterClaimDTO.MISSING_INCIDENT_DATE);
    if (isNullOrBlank(Data.PolicyId)) return;
    Policy policy = FindPolicy(Data.PolicyId);
    if (policy == null) {
      notification.Errors.Add(RegisterClaimDTO.UNKNOWN_POLICY_NUMBER);
    }
    else {
      fail ((Data.IncidentDate.CompareTo(policy.InceptionDate) < 0), 
            RegisterClaimDTO.DATE_BEFORE_POLICY_START);
    }
  }

The most complex thing about much of this is that certain validation checks only make sense if others haven't failed - which leads to conditional logic in the validate method. With more realistic size methods it's important to break them out into smaller chunks.

Common generic bits of validation can (and should) be extracted and put in the Layer Supertype.

protected bool isNullOrBlank(String s) {
  return (s == null || s == "");
}
protected void failIfNullOrBlank (string s, Notification.Error error) {
  fail (isNullOrBlank(s), error);
}
protected void fail(bool condition, Notification.Error error) {
  if (condition) notification.Errors.Add(error);
}

The very simplest form of error for the Notification would be just to use strings as error messages. I prefer at least a minimal wrapping, defining a simple error class and defining a fixed list of errors for the interaction in the DTO.

class RegisterClaimDTO...

  public static Notification.Error MISSING_POLICY_NUMBER = new Notification.Error("Policy number is missing");
  public static Notification.Error UNKNOWN_POLICY_NUMBER = new Notification.Error("This policy number is unknown");
  public static Notification.Error MISSING_INCIDENT_TYPE = new Notification.Error("Incident type is missing");
  public static Notification.Error MISSING_INCIDENT_DATE = new Notification.Error("Incident Date is missing");
  public static Notification.Error DATE_BEFORE_POLICY_START 
    = new Notification.Error("Incident Date is before we started doing this business");

If you are communicating across tiers you may need to add an ID field to the error to allow comparisons to work properly when errors are being serialized across the wire.

That pretty much is all the interesting behavior in the domain layer. For the presentation I'll use an Autonomous View. The behavior we're interested in occurs when the submit button is pressed.

class FrmRegisterClaim...

  RegisterClaimDTO claim;
  public void Submit() {
    saveToClaim();
    service.RegisterClaim(claim);
    if (claim.Notification.HasErrors) {
      txtResponse.Text = "Not registered, see errors";
      indicateErrors();
    }
    else txtResponse.Text = "Registration Succeeded";
  }
  private void saveToClaim() {
    claim = new RegisterClaimDTO();
    claim.PolicyId = txtPolicyNumber.Text;
    claim.IncidentDate = pkIncidentDate.Value;
    claim.Type = (string) cmbType.SelectedItem;
  }

The method pulls information out of the controls to fill the DTO and sends the data to the domain layer. If the returning DTO contais errors, then we need to display them.

class FrmRegisterClaim...

  private void indicateErrors() {
    checkError(RegisterClaimDTO.MISSING_POLICY_NUMBER, txtPolicyNumber);
    checkError(RegisterClaimDTO.MISSING_INCIDENT_TYPE, cmbType);
    checkError(RegisterClaimDTO.DATE_BEFORE_POLICY_START, pkIncidentDate);
    checkError(RegisterClaimDTO.MISSING_INCIDENT_DATE, pkIncidentDate);
    checkError(RegisterClaimDTO.DATE_BEFORE_POLICY_START, pkIncidentDate);
  }
  private void checkError (Notification.Error error, Control control) {
    if (claim.Notification.IncludesError(error)) 
      showError(control, error.ToString());
  }

Here I'm using the errors defined in the DTO and mapping them to fields in the form, so the right field shows the right errors.

To actually display the errors, I use the standard error provider that comes with .NET. This displays an error icon next to fields in trouble, and a tooltip to reveal the error message that's the cause of the problem.

class FrmRegisterClaim...

  private ErrorProvider errorProvider = new ErrorProvider();
  void showError (Control arg, string message) {
    errorProvider.SetError(arg, message);
  }

I clear the error information if anything in the fields change.

class FrmRegisterClaim...

  void clearError (Control arg) {
    errorProvider.SetError(arg, null);
  }
  private void txtPolicyNumber_TextChanged(object sender, EventArgs e) {
    clearError((Control)sender);
  }
  private void cmbType_TextChanged(object sender, EventArgs e) {
    clearError((Control)sender);
  }
  private void pkIncidentDate_ValueChanged(object sender, EventArgs e) {
    clearError((Control)sender);    
  }