PageBox for Java: Web application deployment using Java PageBox

 PageBox for Java 
Deployment Token API Active naming Trusted

Token API


Each PageBox on the ring acts as a station.

More than one token may be active on the ring at the same time. The number of tokens is determined by a refresh time. Because there may be more than one token the ring size is not limited.

The Deploy and RepoQuery Web services are used for networking.

The PageBox API allows Web applications to register on the ring:

  • The Web application must implement a Receiver callback interface

  • The Web application can insert data to the ring with a send method


A frame contains a token and a set of messages.

A message contains:

  • The Web application name

  • The origin PageBox

  • The target PageBox or a broadcast address

  • Data sent by the Web application on the origin PageBox

  • In case of broadcast, the return code of the Web application instances that have already processed the message

The message is uniquely identified by the application name, the origin and target PageBox and a frame sequence number.

The message set is represented by a HashMap whose keys are Web application names and values are linked lists of messages. A message is represented by a TokenMsg class defined like this:

class TokenMsg {

String origin;

String target;

Object data;

HashMap codes;



  • origin is the URL of the Deploy Web service of the origin PageBox

  • target is the URL of the Deploy Web service of the target PageBox or null in case of broadcast

  • data is the payload

  • codes is a map whose keys are PageBox URLs and values are Web application return codes


Message processing

A message remains on the frame up to the time it is received by the sending Web application.

When it receives a frame a PageBox enumerates the Web applications in the received HashMap. When the Web application registered a callback class with the PageBox API the PageBox calls the callback class. Then the PageBox adds the return code of the callback method to the codes LinkedList if the code is not null. If the message was a message with a target the PageBox nullifies the payload.

The PageBox API implements the send method in the following way:

  • Queues the payload. [If send is called in the callback method queuing is not needed.]

  • When the token is received dequeues the payload and inserts a message in the frame

  • When the token comes back removes the message from the frame and returns the codes map

The send can be implemented either in asynchronous mode (the send method provides a callback class and returns when the payload is queued) or in synchroneous mode (the send waits up to the time the token comes back).

Adjacency list

In a token ring network a station is connected to two stations, the station from where frames are sent and the station to which the considered station sends frames. In a PageBox constellation such hardware connections don't exist.

The Repository that knows the URLs of subscribed PageBoxes orders this list in an adjacency list and acts as the ring controller.

The Repository generates token frames that include an empty message map and this adjacency list. The Repository sends a token frame to the first station in the adjacency list. The first station may fill the message map and sends the updated frame to the second station in the adjacency list and so on. When the last station in the adjacency list receives the frame it sends the updated frame to the Repository.

The frameSend method is defined on a TokenIF interface defined like this:

interface TokenIF {

class Frame {

int nb;

LinkedList adjacencyList;

HashMap msgMap;


Status frameSend(Frame frame);



  • nb is the frame number

  • adjacencyList is the adjacency list

  • msgMap is the message HashMap

The DeployIF and RepoQueryIF interfaces implement the TokenIF interface.

Station insertion

When a first Web application registers on the ring the PageBox calls a tokenRegister method of the RepoQuery Web service. Then the Repository adds the PageBox to the adjacency list.

Error handling

To the opposite of a token ring network case a station get notified when it is unable to contact the next station. In that case the station (1) removes the failing station from the adjacency list (2) sends the updated frame to the next station in the adjacency list (3) calls a tokenUnregister method of the RepoQuery web service of the Repository to unregister the failed station.

A station may be able to receive a frame and not be able to send the updated frame to the next station. In that case the next station doesn't receive a token before last_token_reception_time + refresh_time. In this case the next station checks if the Repository is alive. If it is alive it does nothing, the Repository being responsible for generating new tokens. If the Repository is dead there is a problem: more than one station probably detect that they did not receive the token. So stations issue the new token after a random amount of time. The first station to issue the new token wins.

When a station is no longer able to process frames messages where this station is the destination are removed from the message HashMap. This action is performed by a station when the next station returns an error or when the previous station failed to send a frame.

Repository recovery

Once a station has received a frame it has an adjacency list, can contact neighbors stations and update adjacency lists.

The Repository is the point where stations can be inserted on the ring. The failure of the Repository doesn't prevent the ring to run but it prevents the ring to accept new stations.

A ring failure can be detected either by the last station on the ring (frameSend failure) or by the first station on the ring (timeout). The station that detects the failure updates the frame status. Each time it receives again the frame the station before the Repository calls the frameSend method of the RepoQuery Web service. When the Repository is up again it rebuilds its adjacency list and manage again frames.
2002-2004 Alexis Grandemange. Last modified .