Transferring an Entity

What does an Entity transfer mean?

An Entity is held within an EntityContainer and this entity can be transferred to another container. Entities are also containers so this forms a tree structure and when an Entity so this requires the ability to move an entity around without killing and re-creating it. The underlying EntityFactory controls all tree manipulation (including transfers) so the methods that can be used to achieve this will be explained.

Transferring the Entity

A transfer can be done by both Entity and EntityContainer.

Entity e = /* To transfer */
EntityContainer dest = /* Destination */

e.transfer(dest);

or

UUID id = /* ID of entity to transfer*/
EntityContainer src = /* Source*/
EntityContainer dest = /* Destination */

src.transferEntity(id, dest);

This transfer should really call container.receiveEntity(Entity) but it depends on the implementation (DefaultEntityContainer does).

When it comes to listeners

An EntityListener methods are triggered when the entity tree is manipulated. entityTransferred(EventEvent) is fired when an entity is transferred within the tree. entityReceived(EntityEvent) is fired when an entity is received externally. Ultimately it is down to the EntityContainer implementation but the above is the desired behaviour.

Additional information

For more information see What is an EntityFactory.