The solution

Coding the solution involves these steps:

create a class variable to hold the DAO;
use the DAO to create a new instance of the entity;
access the entity instance to set field values from the client struct;
instruct the entity instance to insert itself onto the database; and
map the entity instance key back to the client (if required).

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.

In general more than one façade method will require to use the DAO object. Of course, you only need to create the DAO object class member once for the façade class!

Use the DAO to create a new instance of the entity

In your façade method, code a variable to hold an instance of the entity interface, and set its value by calling.newInstance() on the DAO, passing the key of the database row:

Figure 1. Calling a DAO to create a new instance of an entity

// create a new entity instance
    final SomeEntity someEntity = someEntityDAO.newInstance();

Here, the DAO instance has "dished up" a new instance of the entity interface, which does not (yet) exist on the database. The entity itself takes care of setting its data fields to sensible defaults.

someEntity now holds an object which "knows" how to:

get at data (via "getter" methods);
set data (via "setter" methods); and
"do things" with that data (via other methods).

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

Now code calls to the entity "setters" to map fields values from your input struct:

Figure 2. Calling setter methods on an entity instance

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

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

Points to note:

Often, an entity may have a getter to allow retrieval of a data field, but have no corresponding setter. This is because the entity manages the setting of such fields, and does not allow the field to be set by calling code. Common examples include:
- the entity's ID;
- the "logical delete" record status; and
- lifecycle state.

Some setters do not take primitive types, but instead take objects, e.g. there are no someEntity.setStartDate() or.setEndDate() methods, only a.setDateRange() method which takes a DateRange object which contains a start and end date.
When you call a setter on an entity instance, the entity instance will perform any single-field validation on the field being set.

You must code a mapping for each field that you need to populate from the client.

Instruct the entity instance to insert itself onto 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 itself:

Figure 3. Calling the insert persistence method on an entity instance

// do the insert
    someEntity.insert();

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;
assign a primary key value; and
insert its data into the database.

Map the entity instance key back to the client (if required)

Some façade methods require to return back to the client the key of a new row stored.

If required, code a mapping to return the key:

Figure 4. Retrieving the ID of an entity instance

// map the key assigned
    key.someEntityID = someEntity.getID();