Programming Systems Laboratory
Worklets Documentation


The Worklets system provides micro-workflow through mobile agents that adapt computation to component context. It is designed as a mobile code infrastructure intended for dynamic re-configuration of third-party systems. Instead of bringing down entire components of a distributed system at runtime for recompilation, Worklets carrying Java mobile code can be injected transparently into system components for incremental adaptation. Host components must include, or be wrapped with, a generic Worklet Virtual Machine (WVM) and host-specific adapters exposing indigenous reconfiguration capabilities. The Worklets System depends on Java 1.4.

The system is principally composed of WVM's, Worklets and WorkletJunctions. The WVM provides the execution environment as well as harboring the interface to the system. A Worklet is composed of WorkletJunctions which contain the execution code and addressing information for the Worklet. The Worklet thus acts as an agent bringing the WorkletJunction to the WVM to perform actions which are specified in the WorkletJunction.

The typical use of Worklets is to insert WorkletJunctions into a Worklet and send it into a system running a WVM to monitor the system by probing or to effect it by modifying system components. A JunctionPlanner can also be added to WorkletJunctions to specify meta-data such as the number of iterations to execute. Examples of these Worklets are included in the distribution and a walk through of a simple system is provided at the end of the documentation.


For Worklets to act on a target system the WVM must be "installed" into the system. The WVM provides the execution environment in which the Worklets operate. To install the WVM you need to create a WVM and pass it a reference to the system to be instrumented:

WVM _wvm = new WVM(this);

This constructor defaults many values which can be specified through other constructors (please see the Worklets' Javadocs). In the code above, this is a reference to the system. The Worklets system uses this reference to invoke methods provided through a host adaptor interface (please see the examples section below).

After the WVM has been installed, Worklets can be sent in to do a variety of tasks such as invoking interface methods or executing other bits of code. Since the Workets are transported between WVMs, a Worklet must be bootstrapped into the Worklets system by an originating WVM. This can be done by creating a WVM on the originating system and installing and deploying the Worklet from that WVM.

WVM wvm = new WVM(new Object(), InetAddress.getLocalHost().getHostAddress(), "newWVM");
Worklet wkl = new Worklet(null); // create a Worklet
wkl.deployWorklet(wvm); // send it away!

Worklets themselves are composed of WorkletJunctions which contain the execution points. Each WorkletJunction has an execute method that is invoked when the Worklet reaches the destination specified in the WorkletJunction. Thus one Worklet can act on several systems, provided the WVM is installed. Also, the Worklet can be communicated (between WVMs) through different methods, namely sockets or Java RMI. Additionally, there are ways to secure Worklet transportation, as described in the security section.

Here is a basic Worklet construction with one WorkletJunction that is bootstraped with a WVM:

import psl.worklets.*;

public class DispatchWorklet implements Serializable {
// create an originating WVM
WVM wvm = new WVM(new Object(), "localhost", "DispatchWorklet");

WorkletJunction originJunction = null;
WorkletJunction wj = new WorkletJunction("localhost", "target") {
public void init(Object _system, WVM _wvm) {

public void execute() {
System.out.println("Hello System");

Worklet wkl = new Worklet(originJunction);

The code above creates a WorkletJunction to be sent to a local system under the name of "target". Once it gets there, the WorkletJunction will simply print out "Hello System". The originJunction used above specifies where the Worklet is to return to when finished with all of its WorkletJunctions. If null is specified, as above, then it doesn't have to return.

As the range of Worklet applications vary widely, we provide an example of Worklets being used to probe a system and then again to effect it. Also, please see the Worklets' Javadocs for API information.


In this example a simple system is created, instrumented, probed, and effected.

Example system: Greeter

The example shown here is a simple system where two entities communicate continuously through a given protocol. provides the interface for all Greeters and implements the Greeter. The polite Greeters simply exchange greetings back and forth while being prompted by a preset greeting. To start the Greeter system, compile the and run, on one terminal:
java politeGreeter localhost 9200 wvm1 localhost 9221 true

and on another terminal run:
java politeGreeter localhost 9201 wvm2 localhost 9220 true

The first and second arguments are the local hostname and socket number to try binding to. The third argument is the WVM name. The fourth and fifth arguments are the remote host and port number to communicate with. The last (sixth) argument is whether to initially allow communciation and whether to try to initiate a conversation. When the first invocation above is executed, the other Greeter is not created yet, so nothing happens. When the second Greeter is created it starts the conversation with the first Greeter.

We "instrument" the system, or install the WVM, on the line:
WVM wvm = new WVM(this);
by creating a WVM from within the politeGreeter and passing it a reference to the parent system. By doing this, Worklets can interact with the system through the API (

Probing the Greeter

Now we want to probe the system to see what's going on inside. For DASADA related probing, it is important to conform to the Probelet API. In the following example I do not implement this API, but in the FAQ section I discuss the API as related to Worklets.

The probe is sent into the politeGreeter system to find out the greeting being used and whether they are currently talking. Look at the Probelet class to see the interaction with the host system.
(ie. the line: String greeting = ((Greeter)_system).getGreeting(); )

To execute probeGreeter, run:

java probeGreeter localhost wvm1 9200)

Effecting the Greeter

Now let's suppose the politeGreeter system wasn't working so great and that they weren't talking.

run, on one terminal:
java politeGreeter localhost 9200 wvm1 localhost 9221 false

and on another terminal run:
java politeGreeter localhost 9201 wvm2 localhost 9220 false

Now we'll send in an effector to remedy the system so that the Greeters are again talking to each other. We do this in In effectGreeter, we invoked the neccessary methods for the Greeters to talk to each other.

To execute effectGreeter, run:

java effectGreeter

In effectGreeter we hardcode in the destinations of the WorkletJunctions simply for convenience. Notice that the probeGreeter and effectGreeter files are very much the same. The only difference is in the methods invoked and, of course, the names of the classes (ie. Probelet vs. Effectlet).

Example Summary

In this example we showed a system being installed with the WVM. We then showed the system being probed and effected. Though this was a very simple example, it can be used to do further testing and learning of how Worklets can be used. For example we can actually change the "protocol", or language, that the Greeters are using. Also, we restricted ourselves to only invoking API methods but any execution code can be specified in the execute method (as allowed through security policy.) Applications can be sent in for execution as well. These examples are included in the Worklets distribution.

Frequently Asked Questions (FAQ)


Please email me for bug reports.

Questions, Contact

Any questions or comments can be directed to Dan Phung.

Copyright 2002: The Trustees of Columbia University in the City of New York. All Rights Reserved
Author: Dan Phung
Last Modified 20 October 2002