1 package cz.cuni.amis.pogamut.base.communication.translator.event;
2
3 import cz.cuni.amis.pogamut.base.communication.translator.event.IWorldObjectUpdateResult.Result;
4 import cz.cuni.amis.pogamut.base.communication.translator.event.IWorldObjectUpdateResult.WorldObjectUpdateResult;
5 import cz.cuni.amis.pogamut.base.communication.worldview.IWorldView;
6 import cz.cuni.amis.pogamut.base.communication.worldview.object.IWorldObject;
7 import cz.cuni.amis.pogamut.base.communication.worldview.object.WorldObjectId;
8 import cz.cuni.amis.pogamut.base.communication.worldview.object.event.WorldObjectDestroyedEvent;
9 import cz.cuni.amis.pogamut.base.communication.worldview.object.event.WorldObjectFirstEncounteredEvent;
10 import cz.cuni.amis.pogamut.base.communication.worldview.object.event.WorldObjectUpdatedEvent;
11 import cz.cuni.amis.utils.NullCheck;
12 import cz.cuni.amis.utils.exception.PogamutException;
13
14 /**
15 * Interface for the event that suppose to update the informations about the
16 * object in the world.
17 * <p><p>
18 * Each event should return an id of the object it is meant to update, this
19 * event is processed by the {@link IWorldViewEventInput} implementor that should
20 * look up the object in it's view and update it with the method defined
21 * by the implementor of this interface.
22 * <p><p>
23 * Update event may have four different outcomes according to {@link IWorldObjectUpdateResult#getResult()}.
24 * <ol>
25 * <li>{@link IWorldObjectUpdateResult.Result}.CREATED = <b>new object appeared in the world</b> - this is the case when the object's id is
26 * unknown to the world view thus 'null' is passed to the update() method AND update()
27 * returns new world object</li>
28 * <li>{@link IWorldObjectUpdateResult.Result}.UPDATED = <b>update state of the existing object in the world</b> - this is the case
29 * when the object's id is known to the world view so the according world object is passed
30 * to the update() method AND update() returns the same instance (but updated, i.e., some of its fields changes)
31 * of the world object</li>
32 * <li>{@link IWorldObjectUpdateResult.Result}.SAME = <b>object was not updated</b> (no new information has been set to it).
33 * </li>
34 * <li>{@link IWorldObjectUpdateResult.Result}.DESTROYED = <b>object disappeared from the world</b> - this is the case when the object's id
35 * is known to the world and should be destroyed.
36 * </ol>
37 * <p>
38 * <b>It's forbidden for the instance of update event to create a new world object instance in the
39 * 2) case, it must always work over the instance passed to the update() method</b>
40 * <p><p>
41 * For the case 1), {@link IWorldView} will generate {@link WorldObjectFirstEncounteredEvent} followed
42 * by {@link WorldObjectUpdatedEvent},
43 * for the case 2) the world view will generate just {@link WorldObjectUpdatedEvent} and for the case 4) {@link WorldObjectDestroyedEvent}.
44 * No event is generated for the case 3 as it does not bring new information.
45 *
46 * @author Jimmy
47 */
48 public interface IWorldObjectUpdatedEvent extends IWorldChangeEvent {
49
50 public WorldObjectId getId();
51
52 public IWorldObjectUpdateResult<IWorldObject> update(IWorldObject obj);
53
54 /**
55 * Shortcut implementation of {@link IWorldObjectUpdatedEvent} that informs that some object has been destroyed.
56 *
57 * @author Jimmy
58 */
59 public static class DestroyWorldObject implements IWorldObjectUpdatedEvent {
60
61 private IWorldObject object;
62 private long simTime;
63
64 public DestroyWorldObject(IWorldObject object, long simTime) {
65 this.object = object;
66 NullCheck.check(this.object, "object");
67 NullCheck.check(this.object.getId(), "object.getId()");
68 this.simTime = simTime;
69 }
70
71 @Override
72 public WorldObjectId getId() {
73 return object.getId();
74 }
75
76 @Override
77 public IWorldObjectUpdateResult<IWorldObject> update(IWorldObject obj) {
78 if (obj == null) throw new PogamutException("Could not destroy 'null' object.", this);
79 if (obj.getId() == null || !obj.getId().equals(object.getId())) throw new PogamutException("Could not destroy object " + object + " as provided object for update is different: " + obj, this);
80 return new WorldObjectUpdateResult(Result.DESTROYED, null);
81 }
82
83 @Override
84 public long getSimTime() {
85 return simTime;
86 }
87
88
89 }
90
91 }