org.cometd.server

Class AbstractService

java.lang.Object

org.cometd.server.AbstractService

public abstract class AbstractService
extends Object

AbstractService provides convenience methods to assist with the creation of a CometD services.

A CometD service runs application code whenever a message is received on a particular channel.

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.

Subclasses should call addService(String, String) in order to map channel subscriptions to method invocations, usually in the subclass constructor.

Each CometD service has an associated LocalSession that can be used as the source for messages published via ServerChannel#publish(Session, Mutable) or ServerSession#deliver(Session, Mutable).

See Also:

BayeuxServer#newLocalSession(String)} as an alternative to {@link AbstractService}.

Field Summary

Fields

Modifier and Type	Field and Description
protected org.slf4j.Logger	_logger

Constructor Summary

Constructors

Constructor and Description
AbstractService(BayeuxServer bayeux, String name) Instantiates a CometD service with the given name.
AbstractService(BayeuxServer bayeux, String name, int maxThreads) Instantiate a CometD service with the given name and max number of pooled threads.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	addService(String channelName, String methodName) Maps the method of a subclass with the given name to a ServerChannel.MessageListener on the given channel, so that the method is invoked for each message received on the channel.
protected void	doInvoke(Method method, ServerSession fromClient, ServerMessage msg)
protected void	exception(String method, ServerSession fromClient, LocalSession toClient, ServerMessage msg, Throwable x) Handles exceptions during the invocation of a mapped method.
BayeuxServer	getBayeux()
LocalSession	getLocalSession()
String	getName()
ServerSession	getServerSession()
org.eclipse.jetty.util.thread.ThreadPool	getThreadPool()
boolean	isSeeOwnPublishes()
protected void	removeService(String channelName) Unmaps all the methods that have been mapped to the given channel.
protected void	removeService(String channelName, String methodName) Unmaps the method with the given name that has been mapped to the given channel.
protected void	send(ServerSession toClient, String onChannel, Object data, String id) Sends data to an individual remote client.
void	setSeeOwnPublishes(boolean seeOwnPublishes)
void	setThreadPool(org.eclipse.jetty.util.thread.ThreadPool pool) Sets the thread pool associated to this CometD service.

Methods inherited from class java.lang.Object

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

Field Detail

_logger

protected final org.slf4j.Logger _logger

Constructor Detail

AbstractService

public AbstractService(BayeuxServer bayeux,
               String name)

Instantiates a CometD service with the given name.

Parameters:

bayeux - The BayeuxServer instance.

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

AbstractService

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

Instantiate a CometD service with the given name and max number of pooled threads.

Parameters:

bayeux - The BayeuxServer instance.

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

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

Method Detail

getBayeux

public BayeuxServer getBayeux()

getName

public String getName()

getLocalSession

public LocalSession getLocalSession()

Returns:

The LocalSession associated with this CometD service

getServerSession

public ServerSession getServerSession()

Returns:

The ServerSession of the LocalSession associated with this CometD service

getThreadPool

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

Returns:

The thread pool associated with this CometD service, or null

See Also:

AbstractService(BayeuxServer, String, int)

setThreadPool

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

Sets the thread pool associated to this CometD service.

If the ThreadPool is a LifeCycle instance, and it is not already started, then it will started.

Parameters:

pool - The ThreadPool

isSeeOwnPublishes

public boolean isSeeOwnPublishes()

Returns:

whether this CometD service receives messages published by itself on channels it is subscribed to (defaults to false).

See Also:

setSeeOwnPublishes(boolean)

setSeeOwnPublishes

public void setSeeOwnPublishes(boolean seeOwnPublishes)

Parameters:

seeOwnPublishes - whether this CometD service receives messages published by itself on channels it is subscribed to (defaults to false).

See Also:

isSeeOwnPublishes()

addService

protected void addService(String channelName,
              String methodName)

Maps the method of a subclass with the given name to a ServerChannel.MessageListener on the given channel, so that the method is invoked for each message received on the channel.

The channel name may be a wildcard channel name.

The method must have a unique name and one of the following signatures:

• myMethod(ServerSession from, Object data)
• myMethod(ServerSession from, Object data, String messageId)
• myMethod(ServerSession from, String channel, Object data, String messageId)

The data parameter can be a specific type if the type of the data object published by the client is known by the server. If it is not known will be Map<String, Object>.

If the type of the data parameter is Message (or a subinterface such as ServerMessage.Mutable then the message object itself is passed rather than just the message's data.

Typically a service will be used to a channel in the /service/** space which is not a broadcast channel.

Any object returned by a mapped method is delivered back to the client that sent the message and not broadcast. If the method returns void or null, then no response is sent.

A mapped method may also call send(ServerSession, String, Object, String) to deliver message(s) to specific clients and/or channels.

A mapped method may also publish to different channels via ServerChannel#publish(Session, Mutable).

Parameters:

channelName - The channel to listen to

methodName - The name of the method on this subclass to call when messages are received on the channel

See Also:

removeService(String, String)

removeService

protected void removeService(String channelName,
                 String methodName)

Unmaps the method with the given name that has been mapped to the given channel.

Parameters:

channelName - The channel name

methodName - The name of the method to unmap

See Also:

addService(String, String), removeService(String)

removeService

protected void removeService(String channelName)

Unmaps all the methods that have been mapped to the given channel.

Parameters:

channelName - The channel name

See Also:

addService(String, String), removeService(String, String)

send

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

Sends data to an individual remote 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, but instead delivered directly to the target client.

Typically this method is only required if a service method sends response(s) to clients other than the sender, or on different channels. If the response is to be sent to the sender on the same channel, then the data can simply be the return value of the method.

Parameters:

toClient - The target client

onChannel - The channel of the message

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)

Handles exceptions during the invocation of a mapped method.

This method is called when a mapped 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)