A PART "Hello world" program

All programs developed using PART will typically perfom most of the following tasks:

• Adding an event handler - This allows PART to notify the program code about events concerning for instance the establishment of network connections and changes to distributed objects, and also events sent from remote process.
• Setting a debug level - Is typically used during program developement to see various PART debug messages
• Setting up network connections - Allows the program to participate in a session with other PART programs, sharing distributed objects and communicating via network events.

The following sections describe how to create a simple Java program that uses PART.

The program main class

We introduce a class called PartHelloWorld, which will be the main class of our sample program.

public class PartHelloWorld {

    public PartHelloWorld()
    {
    }

    public static void main(String [] args)
    {
       new PartHelloWorld();
    }
}

So far we have just added a constructor and a main method to the class. The main method allows the program to be compiled and started from the command line (assuming a J2SE platform):

>javac -classpath part_j2se.jar PartHelloWorld.java

>java -classpath "part_j2se.jar;." PartHelloWorld

Adding an event handler

Event handlers are added via the addEventHandler method of the IpSystem class:

IpSystem.addEventHandler(handler);

The handler object must implement the IpEventHandler interface:

public interface IpEventHandler {
    public void handleEvent(IpEvent event);
}

The easiest way is just for us to have the PartHelloWorld class implement the IpEventHandler interface, and then add the event handler in the constructor. We also need to add the handleEvent method to the program main class:

public class PartHelloWorld implements IpEventHandler {

    public PartHelloWorld()
    {
        IpSystem.addEventHandler(this);
    }

    public void handleEvent(IpEvent event)
    {
        System.out.println("Got an event of type " + event.getType());
    }

    public static void main(String [] args)
    {
       new PartHelloWorld();
    }
}


Setting the debug level

The debug level can be increased in order to see debug messages generated internally by PART. Setting the debug level is not in any way necessary, but it might be interesting to see what goes on "inside" PART as the program is running. By default, the debug level is 0. The greater the level, the more debug messages will be printed on stdout.

The debug level is set via the setDebugLevel method of the IpSystem class:

IpSystem.setDebuglevel(2);

In our sample application, we set the debug level in the program class constructor:

public class PartHelloWorld implements IpEventHandler {

    public PartHelloWorld()
    {
        IpSystem.addEventHandler(this);
        IpSystem.setDebugLevel(2);
    }

    public void handleEvent(IpEvent event)
    {
        System.out.println("Got an event of type " + event.getType());
    }

    public static void main(String [] args)
    {
       new PartHelloWorld();
    }
}

Setting up network connections

In order for our program to take part in a session with other programs developed using PART, it either has to connect to one of those other programs, or some of those programs need to connect to our program. PART provides the connect and listen methods, which can be used to connect to remote programs (connect), or listen for and accept connections from other programs.

We will extend the main program class so that it can do both, that is, connect to another program, or accept a connection from another program. owever, it won't be able to do both at the same time. Instead we introduce a command line argument by which it's possible to tell the program whether it should do a connect or listen. We modify the main method like so:

public static void main(String [] args)
{
    if ((args.length > 0) && args[0].equals("connect")) {
      new PartHelloWorld(true);
    } else {
      new PartHelloWorld(false);
    }
}

The idea is that by writing 'connect' on the command line when starting the program, it will do a connect, otherwise a listen:

>java -classpath part_j2se.jar PartHelloWorld connect

As seen in the modified main method, we added a parameter to the constructor in order to tell the main class wheter to do a connect or not.  No we can code to the constructor to either do the connect or listen. In order to make things easy, we will use a Tcp protocol and assume that all programs runs on the same host ('localhost'). We use the port number 4321. Now we can modify the constructor:

public PartHelloWorld(boolean doConnect)
{
    IpSystem.addEventHandler(this);
    IpSystem.setDebugLevel(2);

    try {
        if (doConnect) {
            IpSystem.connect(new IpUrl("tcp://localhost:4321"), 10000, false);
        } else {
            IpSystem.listen(new IpUrl("tcp://localhost:4321"));
        }
    } catch (Exception ex) {
        System.out.println("Exception: " + ex.getMessage());
    }
}

Note that we had to add a try-catch clause around the connect and listen calls, since PART can throw a number of exceptions if these methods fail.

The result

We're done! The final program code looks like this:

import org.iperg.part.core.*;

public class PartHelloWorld implements IpEventHandler {

    public PartHelloWorld(boolean doConnect)
    {
        IpSystem.addEventHandler(this);
        IpSystem.setDebugLevel(2);

        try {
            if (doConnect) {
                IpSystem.connect(new IpUrl("tcp://localhost:4321"), 10000, false);
            } else {
                IpSystem.listen(new IpUrl("tcp://localhost:4321"));
            }
        } catch (Exception ex) {
            System.out.println("Exception: " + ex.getMessage());
        }
    }

    public PartHelloWorld()
    {
        IpSystem.addEventHandler(this);
    }

    public void handleEvent(IpEvent event)
    {
        System.out.println("Got an event of type " + event.getType());
    }

    public static void main(String [] args)
    {
        if ((args.length > 0) && args[0].equals("connect")) {
            new PartHelloWorld(true);
        } else {
            new PartHelloWorld(false);
        }
    }
}

Note that we added the import-declaration at the top, this is needed in order to compile to program. We can now start two instances of the program, one that listens for incoming connections, and one that tries to set up a connection to another program. We start the program doing the listening first:

>java -classpath "part_j2se.jar;." PartHelloWorld

We then start the same program, and use the 'connect' command line argument to instruct it to set up a connection:

>java -classpath "part_j2se.jar;." PartHelloWorld connect

If you have set the debug level as described above, you should see a number of debug messages and then (hopefully) the line:

Got an event of type _connEstablished

This message is printed from the handleEvent method when the program receives and event saying that a new network connection has been created.