org.cometd.server
Class AbstractService

java.lang.Object
  org.cometd.server.AbstractService

public abstract class AbstractService
extends Object

Abstract Bayeux Service

This class provides convenience methods to assist with the creation of a Bayeux Services typically used to provide the behaviour associated with a service channel (see Channel.isService()). Specifically it provides:

• Mapping of channel subscriptions to method invocation on the derived service class.
• Optional use of a thread pool used for method invocation if handling can take considerable time and it is desired not to hold up the delivering thread (typically a HTTP request handling thread).
• The objects returned from method invocation are delivered back to the calling client in a private message.

See Also:

BayeuxServer#getSession(String)} as an alternative to AbstractService.

Constructor Summary

AbstractService(BayeuxServer bayeux, String name)
Instantiate the service.

AbstractService(BayeuxServer bayeux, String name, int maxThreads)
Instantiate the service.

Method Summary

protected void	addService(String channelId, String methodName) Add a service.
protected void	doInvoke(Method method, ServerSession fromClient, ServerMessage msg)
protected void	exception(String method, ServerSession fromClient, LocalSession toClient, ServerMessage msg, Throwable x) Handle Exception.
BayeuxServer	getBayeux()
LocalSession	getLocalSession()
ServerSession	getServerSession()
org.eclipse.jetty.util.thread.ThreadPool	getThreadPool()
boolean	isSeeOwnPublishes()
protected void	send(ServerSession toClient, String onChannel, Object data, String id) Send data to a individual client.
void	setSeeOwnPublishes(boolean own)
void	setThreadPool(org.eclipse.jetty.util.thread.ThreadPool pool) Set the threadpool.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractService

public AbstractService(BayeuxServer bayeux,
                       String name)

Instantiate the service. Typically the derived constructor will call @ #subscribe(String, String)} to map subscriptions to methods.

Parameters:

bayeux - The bayeux instance.

name - The name of the service (used as client ID prefix).

AbstractService

public AbstractService(BayeuxServer bayeux,
                       String name,
                       int maxThreads)

Instantiate the service. Typically the derived constructor will call @ #subscribe(String, String)} to map subscriptions to methods.

Parameters:

bayeux - The bayeux instance.

name - The name of the service (used as client ID prefix).

maxThreads - The size of a ThreadPool to create to handle messages.

Method Detail

getBayeux

public BayeuxServer getBayeux()

getLocalSession

public LocalSession getLocalSession()

getServerSession

public ServerSession getServerSession()

getThreadPool

public org.eclipse.jetty.util.thread.ThreadPool getThreadPool()

setThreadPool

public void setThreadPool(org.eclipse.jetty.util.thread.ThreadPool pool)

Set the threadpool. If the ThreadPool is a LifeCycle, then it is started by this method.

Parameters:

pool -

isSeeOwnPublishes

public boolean isSeeOwnPublishes()

setSeeOwnPublishes

public void setSeeOwnPublishes(boolean own)

addService

protected void addService(String channelId,
                          String methodName)

Add a service.

Listen to a channel and map a method to handle received messages. The method must have a unique name and one of the following signatures:

• myMethod(ServerSession from,Object data)
• myMethod(ServerSession from,Object data,String|Object id)
• myMethod(ServerSession from,String channel,Object data,String|Object id)
The data parameter can be typed if the type of the data object published by the client is known (typically Map). If the type of the data parameter is Message then the message object itself is passed rather than just the data.

Typically a service will be used to a channel in the "/service/**" space which is not a broadcast channel. Messages published to these channels are only delivered to server side clients like this service.

Any object returned by a mapped subscription method is delivered to the calling client and not broadcast. If the method returns void or null, then no response is sent. A mapped subscription method may also call send(ServerSession, String, Object, String) to deliver a response message(s) to different clients and/or channels. It may also publish methods via the normal Bayeux API.

Parameters:

channelId - The channel to subscribe to

methodName - The name of the method on this object to call when messages are received.

send

protected void send(ServerSession toClient,
                    String onChannel,
                    Object data,
                    String id)

Send data to a individual client. The data passed is sent to the client as the "data" member of a message with the given channel and id. The message is not published on the channel and is thus not broadcast to all channel subscribers. However to the target client, the message appears as if it was broadcast.

Typically this method is only required if a service method sends response(s) to channels other than the subscribed channel. If the response is to be sent to the subscribed channel, then the data can simply be returned from the subscription method.

Parameters:

toClient - The target client

onChannel - The channel the message is for

data - The data of the message

id - The id of the message (or null for a random id).

exception

protected void exception(String method,
                         ServerSession fromClient,
                         LocalSession toClient,
                         ServerMessage msg,
                         Throwable x)

Handle Exception. This method is called when a mapped subscription method throws and exception while handling a message.

Parameters:

method - the name of the method invoked that threw an exception

fromClient - the remote session that sent the message

toClient - the local session associated to this service

msg - the message sent by the remote session

x - the exception thrown

doInvoke

protected void doInvoke(Method method,
                        ServerSession fromClient,
                        ServerMessage msg)