Java application programming interface to Tango Interactive system

Tango API becomes available by inclusion of webwisdom.tango package in a Java program:

import webwisdom.tango.*;

System interface

Applications use TAgent as a Tango system proxy.

public class TAgent
{
  public TAgent(TLAgent agent);
  public void exit();

  public String getUserName();
  public boolean isMaster();
  public String getMasterName();
  public String[] getParticipantNames();
  public boolean isAudioAvailable();

  public void send(byte[] data);
  public void selectiveSend(String[] participantNames,byte[] data);

  public void addTControlListener(TControlListener l);
  public void removeTControlListener(TControlListener l);
  public void addTDataListener(TDataListener l);
  public void removeTDataListener(TDataListener l);
}

There is one TAgent per application. Application must create its own TAgent:

TAgent agent=new TAgent(/*params*/);

TAgent provides methods for acquiring asynchronuosly certain system information:

getUserName() - name of the user owning the agent;
isMaster() - master of the session status;
getMasterName() - master name;
getParticipantNames() - session participants names;
isAudioAvailable() - availability of audio (note that this is only a workaround to deal with poor media interface in Java).

TAgent allows sending data to other participants of the same session:

send() - brodcast data to all session participants;
selectiveSend() - sends data to selected participants;

The constructor of TAgent takes as a parameter TLAgent. A class implementing TLAgent is specific for an application type. For applets, for example, TAgent is implemented by TLAgentApplet:

public class TLAgentApplet implements TLAgent
{
    public TLAgentApplet(Applet app) throws TangoException;
}

Creating TAgent for applets can be coded as follows:

public class AnApplet extends Applet
{
    public void init()
    {
      try
      {
        TAgent agent=new TAgent(new TLAgentApplet(this));
      }
      catch(TangoException e)
      {
        //cannot connect to Tango
      }
    }
}

Application interface

Asynchronous communication can be assured by the mean of callbacks from the Tango system. The listener interfaces lists available callbacks:

TDataListener - interface for receiving application specific data

public interface TDataListener
{
    public void receive(byte[] data);
}

TControlListener - interface for receiving system information

public interface TControlListener
{
    public void masterChanged(boolean isMaster,String masterName);
    public void participantJoined(String participantName);
    public void participantLeft(String participantName);
    public void audioRequested(boolean isRequested);
}

Application must implement one of the listener interfaces and add itself to the TAgent in order to receive asynchronous notification about the Tango system:

class AnApplication implements TControlListener
{
    TAgent agent;
    agent.addTControlListener(this);
    //implementation of TControlListener interface
}

Reception of the private session data is implemented in the similar fashion:

class AnApplication implements TDataListener
{
    TAgent agent;
    agent.addTDataListener(this);
    //implementation of TDataListener interface follows
}

class AnApplication
{
    TAgent agent;
    TDataListener listener;
    agent.addTDataListener(listener);
}

Example

The code of a Tango enabled chat applet is presented here.

import java.awt.*;
import java.applet.Applet;
import webwisdom.tango.*;

public class JExamp extends Applet implements TDataListener
{
    TextField text;
    TAgent agent=null;

    public JExamp()
    {
      text=new TextField();
      setLayout(new BorderLayout());
      add("North",text);
    }

    public void init()
    {
      try
      {
        agent=new TAgent(new TLAgentApplet(this));
        agent.addTDataListener(this);
        text.setText(agent.getUserName());
      }
      catch(TangoException e)
      {
        e.printStackTrace();
      }
    }

    public void destroy()
    {
      if(agent!=null)
        agent.exit();
      super.destroy();
    }

    public boolean handleEvent(Event evt)
    {
      if((evt.target==text)&&(evt.id==Event.ACTION_EVENT))
        if(agent!=null)
          agent.send(stringToBytes(text.getText()));

      return super.handleEvent(evt);
    }

    public void receive(byte b[])
    {
      text.setText(bytesToString(b));
    }

    private String bytesToString(byte t[])
    {
      return new String(t,0);
    }

    private byte[] stringToBytes(String s)
    {
      int l=s.length();
      byte[] t=new byte[l];
      s.getBytes(0,l,t,0);
      return t;
    }
}

Browserless testing

Fake Tango is provided for testing applications outside the browser environment.

package webwisdom.tango.fake;

public class TLAgentFake implements TLAgent
{
    public TLAgentFake(String userName,boolean isMaster,
                       String serverAddress,int serverPort);
}

public class TServerFake
{
    public TServerFake(int portNumber);
    public static void main(String[] params);
}

In such a setting there is no real Tango: TAgent connects to the fake server, which broadcasts application's private data, but privides no meaningful information about the system itself. Only master status is mainatined in a manner guaranteeing that there is exactly one master.

In order to use this testbed, the fake Tango server must be started:

$ java webwisdom.tango.fake.TServerFake <portNumber>

and the application must use TLAgentFake:

new TAgent(new TLAgentFake(/*serverHostName*/,/*serverPortNumber*/));

Multiple applications in one session

Two additional methods extends TAgent by so called channel interface:

addTDataListener(int channelId,TControlListener l);
send(int channelId,byte[] data);

These methods allows for selecting an arbitrary numerical identifier of the virtual data channel. which can be used for integrating multiple distinct applications in one Tango session. Using this interface for the purposes of a single application is strongly discouraged.

Last modified: Wed Oct 13 18:59:35 EDT 1999
Address questions related to Tango API to support@webwisdom.com.