Hello World

Printer-friendly version

It always help to have an example to follow when working through new ideas. Below is the Hello World Agent that will take you how a real live Agent works.

Before we go into detail, you might want to grab the source of the Agent from here. You will notice that it is a Java application, at the moment FedOne only has a Java API.

So let's start by declaring the class for our Hello World Agent:

public class Fedone_helloworld extends AbstractAgent {
  private static final Log LOG = Log.get(Fedone_helloworld.class);
  private static final String MAIN_DOCUMENT_ID = "main";

Every Agent is an extension of the AbstractAgent class. This parent class defines the basic connection and communication methods which the higher level functionality depends on.

private Fedone_helloworld(String username, String hostname, int port) {
    super(AgentConnection.newConnection(username, hostname, port));
  }

The method that is called when a new Fedone_helloworld object is created.

private void appendLines(WaveletData wavelet, List<String> lines) {
    BufferedDocOp openDoc = wavelet.getDocuments().get(MAIN_DOCUMENT_ID);
    int docSize = (openDoc == null) ? 0 : ClientUtils.findDocumentSize(openDoc);
    DocOpBuilder builder = new DocOpBuilder();

    if (docSize > 0) {
      builder.retain(docSize);
    }
    builder.elementStart(ConsoleUtils.LINE, new AttributesImpl(
        ImmutableMap.of(ConsoleUtils.LINE_AUTHOR, getParticipantId())));
    builder.elementEnd();
    for (String line : lines) {
      if (!line.isEmpty()) {
        builder.characters(line);
        LOG.info("LINE: " + line);
      }
    }
    WaveletDocumentOperation op =
        new WaveletDocumentOperation(MAIN_DOCUMENT_ID, builder.build());
    sendWaveletOperation(wavelet.getWaveletName(), op);
  }

The appendLines method builds a document operation to be applied against the wavelet.

private void appendText(WaveletData wavelet, String text) {
    if (text.isEmpty()) {
      return;
    }
    List<String> lines = new ArrayList<String>(1);
    lines.add(text);
    appendLines(wavelet, lines);
  }

The appendText method is a wrapper around the appenLines method. Instead of having to construct the list of strings yourself, appendText does the work for you.

Event Methods:

The Hello World Agent inherets a set of Event Methods from the AgentEventProvider and AgentEventListerner classes. These methods can be overridden to allow you to build what functionality you require into your Agent.

In the case of the Hello World Agent we have overridden the onSelfAdded event method, so that when the Agent is added to a new wave it creates a new document with the text "Hello World".

@Override
  public void onSelfAdded(WaveletData wavelet) {
    LOG.info("onSelfAdded: " + wavelet.getWaveletName());
    appendText(wavelet, "Hello World.");
  }

Each of the methods needs to be overridden so I have included them below.

@Override
  public void onDocumentChanged(WaveletData wavelet, WaveletDocumentOperation documentOperation) {
    LOG.info("onDocumentChanged: " + wavelet.getWaveletName());
  }

  @Override
  public void onParticipantAdded(WaveletData wavelet, ParticipantId participant) {
    LOG.info("onParticipantAdded: " + participant.getAddress());
  }

  @Override
  public void onParticipantRemoved(WaveletData wavelet, ParticipantId participant) {
    LOG.info("onParticipantRemoved: " + participant.getAddress());
  } 

  @Override
  public void onSelfRemoved(WaveletData wavelet) {
    LOG.info("onSelfRemoved: " + wavelet.getWaveletName());
  }

Building your Agent:

Building the Hello World Agent is as simple as going to the root of the code directory and typing:

$: ant

This will start the ant building process, at the end of which you should have a Fedone_helloword.jar file in the dist directory.

Operating your Agent:

To connect your agent to a wave server run the following:

$: java -jar helloworld@[PUT_YOUR_WAVE_DOMAIN_HERE] [WAVE_SERVER_ADDRESS] [WAVE_SERVER_CLIENT_PORT]

You should get the following:

org.waveprotocol.wave.examples.fedone.agents.agent.AbstractAgent connect
INFO: Connected as helloworld@[YOUR_WAVE_DOMAIN_NAME]