Package org.astrogrid.samp.client

# Class AbstractMessageHandler

java.lang.Object
org.astrogrid.samp.client.AbstractMessageHandler

All Implemented Interfaces:
  `MessageHandler`

public abstract class AbstractMessageHandler extends Object implements MessageHandler
Partial implementation of MessageHandler interface which helps to ensure correct client behaviour. Concrete subclasses just need to specify the MTypes they subscribe to and implement the `processCall(org.astrogrid.samp.client.HubConnection, java.lang.String, org.astrogrid.samp.Message)` method.

Since:
  16 Jul 2008
Author:
  Mark Taylor

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`AbstractMessageHandler(String mtype)`
Constructor using a single subscribed MType.
`protected`
`AbstractMessageHandler(String[] mtypes)`
Constructor using a given list of subscribed MTypes.
`protected`
`AbstractMessageHandler(Map subscriptions)`
Constructor using a given subscriptions map.

## Method Summary

Modifier and Type
Method
Description
`protected Response`
`createResponse(Map processOutput)`
Invoked by `receiveCall` to create a success response from the result of calling `processCall`.
`Map`
`getSubscriptions()`
Returns a Subscriptions map corresponding to the messages handled by this object.
`abstract Map`
`processCall(HubConnection connection, String senderId, Message message)`
Implements message processing.
`void`
`receiveCall(HubConnection connection, String senderId, String msgId, Message message)`
Calls `processCall(org.astrogrid.samp.client.HubConnection, java.lang.String, org.astrogrid.samp.Message)`, generates a response from the result using `createResponse(java.util.Map)`, and sends the resulting response as a reply to the hub.
`void`
`receiveNotification(HubConnection connection, String senderId, Message message)`
Calls `processCall(org.astrogrid.samp.client.HubConnection, java.lang.String, org.astrogrid.samp.Message)` and discards the result.
`void`
`setSubscriptions(Map subscriptions)`
Sets the subscriptions map.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### AbstractMessageHandler

protected AbstractMessageHandler(Map subscriptions)
Constructor using a given subscriptions map.

Parameters:
  `subscriptions` - `Subscriptions`-like map defining which MTypes this handler can process

### AbstractMessageHandler

protected AbstractMessageHandler(String[] mtypes)
Constructor using a given list of subscribed MTypes.

Parameters:
  `mtypes` - list of MTypes which this handler can process

### AbstractMessageHandler

protected AbstractMessageHandler(String mtype)
Constructor using a single subscribed MType.

Parameters:
  `mtype` - single MType which this handler can process

## Method Details

### processCall

public abstract Map processCall(HubConnection connection, String senderId, Message message) throws Exception
Implements message processing. Implementations should normally return a map which contains the `samp.result` part of the call response, that is the MType-specific return value name->value map. As a special case, returning null is equivalent to returning an empty map. However, if `createResponse(java.util.Map)` is overridden, the return value semantics may be different.

Parameters:
  `connection` - hub connection
  `senderId` - public ID of sender client
  `message` - message with MType this handler is subscribed to
Returns:
  result of handling this message; exact semantics determined by `createResponse` implementation
Throws:
  `Exception`

### createResponse

protected Response createResponse(Map processOutput)
Invoked by `receiveCall` to create a success response from the result of calling `processCall`.

The default implementation calls `Response.createSuccessResponse(java.util.Map)`(processOutput), first transforming a null value to an empty map for convenience. However, it may be overridden for more flexibility (for instance in order to return non-OK responses).

Parameters:
  `processOutput` - a Map returned by `processCall`

### setSubscriptions

public void setSubscriptions(Map subscriptions)
Sets the subscriptions map. Usually this is called by the constructor, but it may be reset manually.

Parameters:
  `subscriptions` - `Subscriptions`-like map defining which MTypes this handler can process

### getSubscriptions

public Map getSubscriptions()
Description copied from interface: `MessageHandler`
Returns a Subscriptions map corresponding to the messages handled by this object. Only messages with MTypes which match the keys of this map will be passed to this object.

Specified by:
  `getSubscriptions` in interface `MessageHandler`
Returns:
  `Subscriptions`-like map

### receiveNotification

public void receiveNotification(HubConnection connection, String senderId, Message message)
Calls `processCall(org.astrogrid.samp.client.HubConnection, java.lang.String, org.astrogrid.samp.Message)` and discards the result.

Specified by:
  `receiveNotification` in interface `MessageHandler`
Parameters:
  `connection` - hub connection
  `senderId` - public ID of client which sent the message
  `message` - message

### receiveCall

public void receiveCall(HubConnection connection, String senderId, String msgId, Message message) throws SampException
Calls `processCall(org.astrogrid.samp.client.HubConnection, java.lang.String, org.astrogrid.samp.Message)`, generates a response from the result using `createResponse(java.util.Map)`, and sends the resulting response as a reply to the hub. In case of an exception, a suitable error response is sent instead.

Specified by:
  `receiveCall` in interface `MessageHandler`
Parameters:
  `connection` - hub connection
  `senderId` - public ID of client which sent the message
  `msgId` - message ID
  `message` - message
Throws:
  `SampException`