Token API user guide

PageBox

PageBox for Java

API

Demo

Background

Token API user guide

Objective

This document describes how to use the token API to send and receive messages in a Web application deployed by PageBox.

Audience

Archive developers.

Registration

The Web application implements a TokenCallbackIF interface, registers and un-register this implementation on the PageBox with the registerCallback and unregisterCallback methods of PageBoxAPI.

registerCallback

Signature: boolean registerCallback(TokenCallbackIF tci);

registerCallback takes an instance of the class implementing the TokenCallbackIF interface as parameter and returns true in case of success.

A Web application typically calls this method only once, either on load or on the first use. If the application wants to temporarily stop receiving messages it can call unregisterCallback and call registerCallback again when it is again ready to receive messages.

unregisterCallback

Signature: boolean unregisterCallback();

unregisterCallback returns true in case of success.

A Web application typically calls this method only once, when it is unloaded.

TokenCallbackIF

To use the token API a Web application must implement the TokenCallbackIF interface, defined in the PageBoxLib package like this:

interface TokenCallbackIF {

void setSender(TokenSendIF tsi);

Serializable call(String from, String type, int corrid, Serializable data);

void poll();

void response(String type, int corrid, Map codes);

}

setSender

The setSender method is called when the Web application calls registerCallback. This method has for parameter an object implementing the TokenSendIF interface. The Web application must use this object to insert messages on the ring and send these messages to other Web application instances in the constellation.

The TokenSendIF interface is defined like this:

interface TokenSendIF {

int send(String type, String target, Serializable data);

boolean isRegistered();

}

The send method allows sending messages to other Web application instances in the constellation. It takes three parameters:

type: uniquely identifies the data type. A Web application may send different data type. The type allows the receiver to properly cast the received data.
target: target PageBox URL. If target is null the message is a broadcast message and will be sent to all Web application instances on the ring.
data: message to send

send returns a correlation ID. The Web application can store this ID and use it later to correlate a response to the sent message.

The isRegistered method returns true if the Web application is still registered on the ring and false otherwise.

call

The Token API calls this method of the Web application TokenCallbackIF object for each message that it receives for this Web application.

The call method has four parameters:

from: URL of the PageBox where this message was issued
type: uniquely identifies the data type. The sender sets up the type when it calls the TokenSendIF send method. Use it to cast the data into the proper type.
corrid: correlation ID returned to the sender when it calls the TokenSendIF send method
data: received message

The Web application should return:

null if the Web application has no response to return to the sender or
a response object implementing Serializable

Don’t return a response if you don’t have useful information to send. When the message was broadcasted, return the smallest possible response because the original sender will receive a frame with (number of instances on the ring - 1) * messages.

response

The Token API calls this method of the Web application TokenCallbackIF object when it receives a response for a message sent by this Web application.

The response method has three parameters:

type: uniquely identifies the data type. The sender sets up the type when it calls the TokenSendIF send method. Use it to cast the codes entries into the proper type.
corrid: correlation ID returned to the sender when it calls the TokenSendIF send method
codes: map whose key is the URL of the target Web application PageBox and the value is the object returned by the call method of this target Web application

poll

The Token API calls this method of the Web application TokenCallbackIF object each time it receives a frame. You can implement message sending in this method.

Note: call, response and poll methods are called in this order.