Entity initialization

Business model initialization

An entity that is defined in the model can be implicitly initialized by using a statement for each entity type you want to initialize. The initialization is always in response to one or more events. If an incoming event is related to an entity that does not exist, then an entity with the identifier is created by the initialization.

An initialization statement cannot contain conditions, and actions are optional. For example, the following statement defines how an entity named vehicle is initialized from an event named vehicle activity.

a vehicle is initialized from a vehicle activity, where this vehicle comes from the vehicle of this vehicle activity.  

An initialization statement forces the run time to process the event that initializes the entity, whether an agent listens for this event type or not. If the bound entity exists the event is still routed.

The initialization of an entity happens before any rule agent reacts to an incoming event. However, when an event triggers the initialization of several entities, a rule might be executed before a remote entity is initialized. To make sure that all entities are initialized before a rule executes, you can add a condition in the rule so that it sends an event if the entity is null.

Java API entity initialization

When you implement an initialization by using the Java API, you use the Entity Initialization Extension wizard to create a dedicated EntityInitializer API class. The class is associated to an entity type by using the @EntityInitializerDescriptor annotation. A Java entity initialization extension is used when an instance of the entity type that is specified in the @EntityInitializerDescriptor is created from an event. The entity initialization is defined in a business model statement or is requested by REST/test driver APIs. If the entity type named in the business model initialization statement or REST API call does not have an EntityInitializer, it inherits the EntityInitializer of the parent entity type. A solution cannot have more than one Java EntityInitializer for each entity type.

The generated EntityInitializer class contains two methods.

createEntityFromEvent(Event)

The createEntityFromEvent(Event) method is called when a specific event type occurs, the business model contains an initialization statement for the entity type, and the bound entity does not exist. Use the method to create an entity instance or choose to create an instance of any subtype. You can overrule the request for the entity initialization in the business model by returning the value null. Or you can read the event and initialize the bound entity with data that is inside the event.

The default implementation creates an uninitialized instance of the entity type that is defined in the business model.

@Override
public Vehicle createEntityFromEvent(Event event) throws ComponentException {
   Vehicle entity = super.createEntityFromEvent(event);
   // TODO Initialize the attributes of the entity that depend on the event 
   return entity;
}

intializeEntity(Entity)

The intializeEntity(Entity) method is called when an entity is initially created. You can use this method to access external data sources, update the bound entity, and emit events. The emitted events can modify other entities if they are processed by an agent.

The method also has access to the solution properties and the model factories, but it cannot access the initializing event. The intializeEntity(Entity) method is also called if you create the entity with the REST or TestDriver methods.

The default implementation does nothing.

@Override
public void initializeEntity(Vehicle entity) throws ComponentException {
   super.initializeEntity(entity);  
   // TODO Initialize the attributes of the entity 
}

It is possible to call one EntityInitializer implementation from another. For example, a CarInitializer extension might extend an extension that is named VehicleInitializer.

Referencing remote entities during initialization

When you use a single event to create an entity (a passenger for example) and update a reference to this entity (for example add the passenger to a list of passengers on a flight), the safest option to manipulate the remote entity references is to use a Java agent. Rule agents cannot use remote entities that are not initialized.

The following example code shows how to add a passenger to a list of passengers in a flight entity. A Java agent can access the remote passenger entity at the same time as another agent creates the entity.

Flight flight = (Flight)getBoundEntity();
Relationship<Passenger> passenger = ((CreatePassengerEvent)event).getPassenger();
flight.addTo_passengers(passenger);
updateBoundEntity(flight);

Similarly, rule agents cannot use remote entities that are already deleted.

The following example code shows how to remove a passenger from a list of passengers in a flight entity. A Java agent can access the remote passenger entity at the same time as another agent deletes the entity.

Flight flight = (Flight)getBoundEntity();
Relationship<Passenger> passenger = ((CreatePassengerEvent)event).getPassenger();
flight.removeFrom_passengers(passenger);
updateBoundEntity(flight);