How Do I Create a New Business Entity Instance?

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.