1 package cz.cuni.amis.pogamut.base.communication.connection;
2
3 import com.google.inject.ImplementedBy;
4
5 import cz.cuni.amis.pogamut.base.communication.connection.exception.AlreadyConnectedException;
6 import cz.cuni.amis.pogamut.base.communication.connection.impl.socket.SocketConnection;
7 import cz.cuni.amis.pogamut.base.communication.exception.CommunicationException;
8 import cz.cuni.amis.pogamut.base.component.IControllable;
9 import cz.cuni.amis.pogamut.base.utils.guice.AgentScoped;
10
11 /**
12 * Interface for the connection to a remote world.
13 * <p><p>
14 * Simple methods that are needed to make connection read/write messages.
15 * <p><p>
16 * Implementor is required to implement the interface as reusable. Meaning that one
17 * instance of object may serve first as the connection to one server and then to another.
18 * <p><p>
19 * Control the object through {@link IControllable} interface.<p>
20 * Example scenario 1:
21 * <p><p>
22 * <ol>
23 * <li>instantiate</li>
24 * <li>set address through setAddress()</li>
25 * <li>start()</li>
26 * <li>do some work with reader/writer</li>
27 * <li>stop()</li>
28 * </ol><p>
29 * Or more advance scenario 2 (reconnection):
30 * <ol>
31 * <li>instantiate</li>
32 * <li>set address through setAddress()</li>
33 * <li>start()</li>
34 * <li>do some work with reader/writer</li>
35 * <li>stop()</li>
36 * <li>set address again</li>
37 * <li>start() ... this connects again</li>
38 * <li>do some work on other server</li>
39 * <li>stop()</li>
40 * </ol>
41 * There is a nice abstract implementation AbstractConnection where all you have to do
42 * is implement inner methods for connect / close / getting raw readers and writers.
43 *
44 * @author Jimmy
45 */
46 public interface IWorldConnection<ADDRESS extends IWorldConnectionAddress> extends IWorldReaderProvider, IWorldWriterProvider {
47
48 /**
49 * Sets whether to log the messages that are sent/received through writer/reader. Note
50 * that logging those messages is costly operation and may slow things a lot. That's
51 * why this is <b>OFF as DEFAULT</b>.
52 *
53 * @param logMessages
54 */
55 public void setLogMessages(boolean logMessages);
56
57 /**
58 * Get the descriptor of the connection's remote side.
59 * @return
60 */
61 public ADDRESS getAddress();
62
63 /**
64 * Sets the connection address to the object.
65 * <p><p>
66 * If the object is connected - it throws exception {@link AlreadyConnectedException}
67 *
68 * @param address
69 * @throws CommunicationException
70 */
71 public void setAddress(ADDRESS address) throws CommunicationException;
72
73 }