Debian Codegraph @

src/java/org/astrogrid/samp/client/AbstractMessageHandler.java

raw
1 package org.astrogrid.samp.client;
2
3 import java.util.HashMap;
4 import java.util.Map;
5 import java.util.logging.Level;
6 import java.util.logging.Logger;
7 import org.astrogrid.samp.ErrInfo;
8 import org.astrogrid.samp.Message;
9 import org.astrogrid.samp.Response;
10 import org.astrogrid.samp.SampMap;
11 import org.astrogrid.samp.Subscriptions;
12
13 /**
14 * Partial implementation of MessageHandler interface which helps to ensure
15 * correct client behaviour.
16 * Concrete subclasses just need to specify the MTypes they subscribe to
17 * and implement the {@link #processCall} method.
18 *
19 * @author Mark Taylor
20 * @since 16 Jul 2008
21 */
22 public abstract class AbstractMessageHandler implements MessageHandler {
23
24 private Subscriptions subscriptions_;
25 private final Logger logger_ =
26 Logger.getLogger( AbstractMessageHandler.class.getName() );
27
28 /**
29 * Constructor using a given subscriptions map.
30 *
31 * @param subscriptions {@link org.astrogrid.samp.Subscriptions}-like map
32 * defining which MTypes this handler can process
33 */
34 protected AbstractMessageHandler( Map subscriptions ) {
35 setSubscriptions( subscriptions );
36 }
37
38 /**
39 * Constructor using a given list of subscribed MTypes.
40 *
41 * @param mtypes list of MTypes which this handler can process
42 */
43 protected AbstractMessageHandler( String[] mtypes ) {
44 Map subs = new HashMap();
45 for ( int i = 0; i < mtypes.length; i++ ) {
46 subs.put( mtypes[ i ], new HashMap() );
47 }
48 setSubscriptions( subs );
49 }
50
51 /**
52 * Constructor using a single subscribed MType.
53 *
54 * @param mtype single MType which this handler can process
55 */
56 protected AbstractMessageHandler( String mtype ) {
57 this( new String[] { mtype } );
58 }
59
60 /**
61 * Implements message processing. Implementations should normally
62 * return a map which contains the <code>samp.result</code> part
63 * of the call response, that is the MType-specific return value
64 * name-&gt;value map.
65 * As a special case, returning null is equivalent to returning an empty
66 * map.
67 * However, if {@link #createResponse} is overridden, the return value
68 * semantics may be different.
69 *
70 * @param connection hub connection
71 * @param senderId public ID of sender client
72 * @param message message with MType this handler is subscribed to
73 * @return result of handling this message; exact semantics determined
74 * by {@link #createResponse createResponse} implementation
75 */
76 public abstract Map processCall( HubConnection connection, String senderId,
77 Message message )
78 throws Exception;
79
80 /**
81 * Invoked by {@link #receiveCall receiveCall} to create a success
82 * response from the result of calling {@link #processCall processCall}.
83 *
84 * <p>The default implementation calls
85 * {@link Response#createSuccessResponse}(processOutput),
86 * first transforming a null value to an empty map for convenience.
87 * However, it may be overridden for more flexibility (for instance
88 * in order to return non-OK responses).
89 *
90 * @param processOutput a Map returned by {@link #processCall processCall}
91 */
92 protected Response createResponse( Map processOutput ) {
93 Map result = processOutput == null ? SampMap.EMPTY : processOutput;
94 return Response.createSuccessResponse( result );
95 }
96
97 /**
98 * Sets the subscriptions map. Usually this is called by the constructor,
99 * but it may be reset manually.
100 *
101 * @param subscriptions {@link org.astrogrid.samp.Subscriptions}-like map
102 * defining which MTypes this handler can process
103 */
104 public void setSubscriptions( Map subscriptions ) {
105 Subscriptions subs = Subscriptions.asSubscriptions( subscriptions );
106 subs.check();
107 subscriptions_ = subs;
108 }
109
110 public Map getSubscriptions() {
111 return subscriptions_;
112 }
113
114 /**
115 * Calls {@link #processCall} and discards the result.
116 */
117 public void receiveNotification( HubConnection connection, String senderId,
118 Message message ) {
119 try {
120 processCall( connection, senderId, message );
121 }
122 catch ( Throwable e ) {
123 logger_.log( Level.INFO,
124 "Error processing notification " + message.getMType()
125 + " - ignored", e );
126 }
127 }
128
129 /**
130 * Calls {@link #processCall}, generates a response from the result
131 * using {@link #createResponse}, and sends the resulting response
132 * as a reply to the hub. In case of an exception, a suitable error
133 * response is sent instead.
134 */
135 public void receiveCall( HubConnection connection, String senderId,
136 String msgId, Message message )
137 throws SampException {
138 Response response;
139 try {
140 response =
141 createResponse( processCall( connection, senderId, message ) );
142 }
143 catch ( Throwable e ) {
144 response = Response.createErrorResponse( new ErrInfo( e ) );
145 }
146 connection.reply( msgId, response );
147 }
148 }