The solution

The solution draws together elements of processing seen in the earlier scenarios:
Coding the solution involves these steps:

Create a class variable to hold the DAO

This step is identical to that in You want to read some data from a database table above.

Use the DAO to retrieve the instance of the entity

This step is identical to that in You want to read some data from a database table above.

Access the entity instance to set field values from the client struct

This step is identical to that in You want to insert a new row onto a database table above.

It is likely that a façade class will contain both of the following methods:
  • a method which insert a new row onto a database table; and
  • a method which modifies an existing row on a database table.

For facades which contain both of these kinds of methods, it is likely that the steps to map client data to setters are very similar. Any identical processing should be factored into a common method:

Figure 1. Factoring out common calls to setter methods
// ...
  /**
   * Maps client details to the setters on the service-layer API
   *
   * @param someEntity
   *          the service-layer instance of the entity
   * @param someEntityDtls
   *          the client details to map
   *
   */
  private void setSomeEntityDetails(final SomeEntity someEntity,
      final SomeEntityDtls someEntityDtls) {

    // map the details
    someEntity.setName(someEntityDtls.name);

    final DateRange dateRange =
      new DateRange(someEntityDtls.startDate,
        someEntityDtls.endDate);
    someEntity.setDateRange(dateRange);
    // ...more mappings
  }
  // ...

Note that this method cannot be modeled as the entity interface argument is not present in the Cúram model; thus this method is private to the Java implementation.

Instruct the entity instance to modify its data on the database

Once the entity instance has been populated with data supplied by the client, you must code a call for the entity instance to store its changes:

Figure 2. Calling the modify persistence method on an entity
// do the modify, passing the version number from the client
       someEntity.modify(details.details.versionNo);
The entity instance will:
  • perform additional validation, including:
    • mandatory field validation (i.e. check that all mandatory fields have been set);
    • cross-field validation; and
    • cross-entity validation;
  • modify its data on the database.
Important: For an entity which supports optimistic locking, you must pass the version number held by the client struct. Do not be tempted to use the version number on the entity instance which has been retrieved, as this would render the optimistic lock mechanism useless and allow one user's updates to be overwritten by another user's updates:
Figure 3. Incorrect - bypassing optimistic locking safeguards
/** ********** VERY VERY BAD - DO NOT DO THIS! ********** */
       // do the modify, passing the version number from the entity
       // instance
       someEntity.modify(someEntity.getVersionNo());
       /** ********** VERY VERY BAD - DO NOT DO THIS! ********** */
Parent topic: You want to modify a row on a database table