Service bots

A transport-agnostic Java service bot implements the informal org.coweb.bots.Bot interface to receive data from users in a coweb session. The bot uses a org.coweb.bots.Proxy implementation to send data back to a coweb session. The bot configuration determines what transport the server uses to communicate with the bot.

A Java bot must meet these criteria:

1. The bot must implement the org.coweb.bots.Bot interface.
2. The bot must meet the criteria of its requested transport (e.g., reside in the coweb server class path for org.coweb.bots.transport.LocalTransport).

Declaring bot metadata

Bots declare their metadata and configuration in standard Java properties file. The property file resides with the deployed coweb server and describes how the server should expect to communicate with the bot.

The following are the known properties. Any property except those noted as required may be omitted.

name

Human readable name of the service bot.

description

Human readable description of the service bot.

author

Human readable author of the service bot.

version

Version number of the bot implementation.

service

Required unique name of the service offered by the bot.

class

Required name of the class implementing the org.coweb.bots.Bot interface.

broker

Name of the org.coweb.bots.transport.Transport class the bot should use to communicate with the coweb server. Defaults to org.coweb.bots.transport.LocalTransport if omitted.

Implementing a bot

class org.coweb.bots.Bot

Formal interface for a service bot with callbacks for session events.

init() → void

A bot proxy invokes this method upon the first message delivered to the bot (i.e., when it joins the session).

onRequest(Map<String, Object> params, String replyToken, String username) → void

A bot proxy calls this method when a coweb application posts a private request to the bot.

Parameters:

• params – Arbitrary name/value pairs sent to the bot by a JavaScript application
• replyToken – Token to use when responding privately to this request
• username – Authenticated username of the requestor

onShutdown() → void

A bot proxy calls this method when the coweb server is about to shutdown the bot. The bot should cleanup its resources gracefully.

onSubscribe(String username) → void

A bot proxy calls this method when a coweb application subscribes to messages published by this bot.

Parameters:username – Authenticated username of the subscriber

onSync(Map<String, Object> params, String username) → void

A bot proxy calls this method when a coweb application publishes a cooperative event to the session.

Parameters:

• params – Cooperative event data observed in the session
• username – Authenticated username of the sender

onUnsubscribe(String username) → void

A bot proxy calls this method when a coweb application unsubscribes from messages published by this bot or when a user leaves the session.

Parameters:username – Authenticated username of the unsubscriber

setProxy(Proxy proxy)

A bot proxy calls this method to provide the bot with a reference to itself for sending broadcasts and responses.

Parameters:proxy – org.coweb.bots.Proxy instance

Using the bot proxy

class org.coweb.bots.Proxy

Formal interface for a service bot with methods for sending public and private messages back to a coweb server for delivery to a session.

reply(Bot bot, String replyToken, Map<String, Object> data) → void

A bot delegate calls this method to send a private response to an application that previously sent it a request.

Parameters:

• bot – Bot instance sending the reply
• replyToken – Token from Bot.onRequest()
• data – Data to send privately as a response to the original request

publish(Bot bot, Map<String, Object> data) → void

A bot calls this method to publish data to all subscribers of the bot service.

Parameters:

• bot – Bot instance sending the reply
• data – Data to send privately as a response to the original request