1 package org.lsst.ccs.bus;
2
3 import java.io.Closeable;
4 import java.io.IOException;
5 import java.util.List;
6
7 /**
8 * Interface defining the access to the Transport Layer of Buses
9 * @author bamade
10 * TODO: create an accept URI
11 *
12 */
13 public interface BusMessagingLayer extends Closeable {
14 public static final String ANONYMOUS_AGENT = "__" ;
15 /**
16 * Creates low level communication entry points for a subsystem.
17 * Abstract vision is that there is a different entry point for each bus/topic.
18 *
19 * @param agentName name of the sending/receiving point as will be known by transport
20 * null or empty string means that the local agent will receive all messages
21 * (whatever the destination of the message is : "anonymous agent")
22 * if an agent with same name is already locally registered for these buses nothing happens (the call is
23 * idempotent), but if another agent has the same name on the network a <TT>DuplicateBusNameException</TT>
24 * may be fired (this is an optional behaviour) but this exception is reported only to the corresponding
25 * <TT>BusMembershipListener</TT>
26 *
27 * @param buses list of buses we want to connect to, if empty connects to all buses
28 * @throws IOException if connection impossible,
29 */
30 public void register(String agentName, Bus... buses) throws IOException;
31
32 /**
33 * close entry points for a bus for an agent.
34 * calls should be idempotent.
35 * @param agentName (if empty voids the "anonymous" agent capabilities
36 * @param buses if empty all registered buses for the agent will be closed
37 * @throws IllegalArgumentException if you do not "own" the agent corresponding to the name.
38 */
39 public void closeFor(String agentName, Bus... buses);
40
41 /**
42 * Close the Transport Layer. Subsequent method calls will have no effect.
43 * @throws IOException
44 */
45 @Override
46 public void close() throws IOException ;
47
48 /**
49 * sends a message on a bus: note that BusMessage should have sender and
50 * destination information but it is not the role of the communication layer
51 * to parse destination information such as "subsystem1, subsystem2" or
52 * "subsystem3/module"a.
53 * <P>
54 * The message will be sent to all destinations plus to all the "anonymous" agents
55 * </P>
56 *
57 * @param senderAgent which agent is supposed to be the initiator of the message
58 * (anonymous agents are not supposed to send message: that may fire an exception)
59 * @param bus
60 * @param message
61 * @param destinations could be empty (means broadcast) of a single "" or a single"*" (again means broadcast)
62 * or a list of destinations (DO NOT use things such as "*", "dest1", "dest2" : this will not work!)
63 * @throws IOException this could have a list of causes if some destinations fail.
64 * as much as possible implementers will ensure that all correct destinationa are adressed:
65 * if some fail it is not mandatory to report with a special subclass of IOexception that lists all destination
66 * that failed.
67 * @see org.lsst.ccs.bus.DestinationsException
68 */
69 public <T extends BusPayload> void sendMessage(String senderAgent, Bus<T> bus, T message,String... destinations) throws IOException ;
70
71 /**
72 * Sets up callback configuration for a topic and subsystem.
73 * There could be multiple <TT>Forwarder</TT> for a given bus.
74 * <B>All callbacks are supposed to be multithreaded</B>
75 * @param agentName if empty adds a forwarder to "anonymous" agent that receives all messages
76 * @param forwarder code that handles the incoming messages
77 * @param buses if empty the forwarder listens to all buses.
78 * @throws IllegalArgumentException if the subsystem is not registered to one of the buses
79 * or if forwarder is null
80 */
81 public void addMessageListener(String agentName, BusMessageForwarder forwarder, Bus... buses) ;
82
83 /**
84 * Removes a message listener from the forwarder list.
85 * @param agentName
86 * @param forwarder
87 * @param buses if empty forwarder is removed from all buses
88 * @throws IllegalArgumentException if forwarder is null
89 * (but no exception if the subsystem is not registered, or forwarder not present)
90 */
91 public void removeMessageListener(String agentName, BusMessageForwarder forwarder, Bus... buses) ;
92
93 /**
94 * optional operation.
95 * registers a listener for knowing about the agents that connect/disconnect on a bus.
96 * This method is more useful if called before any agent registration (for instance
97 * duplicate agent names will be reported to these listeners)
98 *
99 * @param buses if empty register to all buses
100 * @param listener can be null if we want to deregister a previous listener
101 * @throws UnsupportedOperationException if not supported
102 */
103 public void setMembershipListener( BusMembershipListener listener, Bus... buses);
104
105
106 /**
107 * Tries to return the name of a list of agents connected to a bus.
108 * @param bus
109 * @return a (possibly empty) list of agent's names connected to a bus
110 * if the current calling code is not connected to this bus the list will be empty
111 */
112 public List<String> getConnectedNames(Bus bus) ;
113
114 }