1 package cz.cuni.amis.pogamut.base.agent.navigation;
2
3 import java.util.List;
4 import java.util.concurrent.ExecutionException;
5 import java.util.concurrent.Future;
6 import java.util.concurrent.TimeUnit;
7 import java.util.concurrent.TimeoutException;
8
9 import cz.cuni.amis.utils.future.FutureStatus;
10 import cz.cuni.amis.utils.future.IFutureListener;
11
12 /**
13 * Returns a path as the future result of {@link IPathPlanner} computation.
14 * <p><p>
15 * You should read the javadoc for {@link Future} first to know the concept first.
16 *
17 * @author Jimmy
18 *
19 * @param <PATH_ELEMENT>
20 */
21 public interface IPathFuture<PATH_ELEMENT> extends Future<List<PATH_ELEMENT>>{
22
23 /**
24 * First, see {@link Future#get()}.
25 * <p><p>
26 * May return null if no such path exist.
27 * <p><p>
28 * Throws some runtime exception if the path could not be computed (exact type of exception
29 * depends on the implementor of the interface).
30 *
31 * @return computed path
32 */
33 @Override
34 public List<PATH_ELEMENT> get();
35
36 /**
37 * Returns a path from {@link IPathFuture#getPathFrom()} to {@link IPathFuture#getPathTo()}. "From" is the first
38 * element of the path, "To" is the last element of the path.
39 * <p><p>
40 * First, see {@link Future#get(long, TimeUnit)}.
41 * <p><p>
42 * May return null if no such path exist.
43 * <p><p>
44 * Throws some runtime exception if the path could not be computed (exact type of exception
45 * depends on the implementor of the interface).
46 */
47 @Override
48 public List<PATH_ELEMENT> get(long timeout, TimeUnit unit);
49
50 /**
51 * Where does the path start. Note that this point might not be the first item of the path element list, this element
52 * marks the start location from which the planner has begun.
53 *
54 * @return
55 */
56 public PATH_ELEMENT getPathFrom();
57
58 /**
59 * Where does the path end. Note that this point might not be the last item of the path element list, this
60 * element marks the end location to which the planner should plan the path.
61 *
62 * @return
63 */
64 public PATH_ELEMENT getPathTo();
65
66 /**
67 * Current status of the path computation.
68 * @return
69 */
70 public FutureStatus getStatus();
71
72 /**
73 * Adds a listener on a future status (using strong reference). Listeners are automatically
74 * removed whenever the future gets its result (or is cancelled or an exception happens).
75 * @param listener
76 */
77 public void addFutureListener(IFutureListener<List<PATH_ELEMENT>> listener);
78
79 /**
80 * Removes a listener from the future.
81 * @param listener
82 */
83 public void removeFutureListener(IFutureListener<List<PATH_ELEMENT>> listener);
84
85 /**
86 * Whether some listener is listening on the future.
87 * @param listener
88 * @return
89 */
90 public boolean isListening(IFutureListener<List<PATH_ELEMENT>> listener);
91
92 }