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:proxyorg.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:
  • botBot 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:
  • botBot instance sending the reply
  • data – Data to send privately as a response to the original request

Table Of Contents

Previous topic

Extension points

Next topic

Java Moderator

This Page