Creating a new entity is equivalent to inserting a new row into the database. The first thing
you need is to have the framework create a new instance of the correct Data Transfer
Object for you, so that you can set properties for the new entity instance. This can be
done via one of the standard framework methods accessible from the abstract superclasses
of classes holding business logic. This method can be told which DTO to create by
passing the business interface class for the entity. In the example below, we are
creating a new Person_DTO
.
Person_DTO personDTO = (Person_DTO) createDTO(Person.class);
Alternatively, if you find that you have a reference to an Id class, the appropriate DTO can be created via a method generated onto that Id class.
Person_Id aPersonId = new Person_Id("123467890");
Person_DTO personDTO = aPersonId.newDTO();
Now let's set some values for the new Person instance:
personDTO.setStateId(state.getId());
personDTO.setLanguageId(language.getId());
Finally, we try to create a persistent instance based on these values. This is equivalent to doing the insert against the underlying table except that: (1) required validation occurs, and (2) the timing of actual insert occurs at the discretion of the framework.
Person person = (Person) createBusinessEntity(personDTO);
That's it. When the current transaction is committed, a new person will be added to the database.