Introduction

 This tutorial will coach you through building a simple "virtual apparatus" using the template supplied. We assume that you are already comfortable in writing Applets and we shall point out the differences of writing an Applet and writing a "virtual apparatus" by building a simple "virtual apparatus". If you are unfamiliar with the "virtual apparatus" specification, please review it first. We will then discuss the guidelines which can help to make your "virtual apparatus" more generic and useful.

Your First "virtual apparatus" Applet

Step 1: Extending from the template

All your virtual apparatus applet, refered to simply as applet hereafter, should extend from the virtualApparatus.class provided.

public class statusbar extends virtualApparatus implements Runnable

Step 2: Initializing the applet

Instead of writing your initializing code in the function Init(), use vaInit(). vaInit() will be called by the Init() function in the virtualApparatus.class after it has its opportunity to do its own initialization. Do not override Init() function.

Similarly, write your start up code in the function vaStart() instead of Start().

public void vaInit(){
vaInfo="Name:Sample Applet written to VA Spec. 0.5";
....

If your applet supports initializing parameters, which would always be the case, using getParameter() method. Please remember to document the parameters your applet expects from the web page.

//get parameters here
totalTime=getParameter("totalTime");
String t1= new String(getParameter("remindTime"));
Integer i = Integer.valueOf(t1);
remindTime = i.intValue();

Step 3: Providing public methods

By declaring your methods as public, it will automatically be available to your user. However, remember to document all your public methods in your vaInfo.

public void startCounting(String msg){
txtMsg.setText(msg);
started=true;

}
public void stopCounting(String msg){
txtMsg.setText(msg);
started=false;

}
public void displayMessage(String msg){
txtMsg.setText(msg);
}

Step 4: Providing messages to the browser

To send out a message, call sendEvents(String message, String channel) method provided by the virtualApparatus.class. You should make your message meaningful to the content author. Content author, typically, would not be interested in mouse_click events.

if ( i == remindTime){
sendEvents("reminding","0");
txtMsg.setBackground(Color.red);
txtCurrentTime.setBackground(Color.red);
txtRemainTime.setBackground(Color.red);
}
if (i==0){
sendEvents("timeup","0");
txtMsg.setBackground(Color.green);
txtCurrentTime.setBackground(Color.green);
txtRemainTime.setBackground(Color.green);
txtMsg.setText("Time up");
started=false;
finished=true;
}

Step 5: Finishing Off

Similar to vaInit() and vaStart(), implement your finishing codes in vaStop() and vaDestroy() methods. Do not override Stop() and Destroy().

Guidelines

Your Applet's Ability

The "virtual apparatus" specification provides a standard mechanism for content author to discover the ability of your applet. However, if you do not exercise discipline in implementing this, there is no way for the content author to learn about the ability your applet has. As a general rule, you should always put all public methods, variables, messages and the initializing parameters in the vaInfo variable in the vaInit() method. When a content author queries the getVaInfo(), vaInfo will be returned.

public void vaInit(){
vaInfo="Name:Sample Applet written to VA Spec. 0.5";
vaInfo=vaInfo+"\n" +"Public properties:";
vaInfo=vaInfo+"\n" +" none";
vaInfo=vaInfo+"\n" +"Parameters accepted:";
vaInfo=vaInfo+"\n" +" totalTime";
vaInfo=vaInfo+"\n" +" remindTime";
vaInfo=vaInfo+"\n" +"Public methods";
vaInfo=vaInfo+"\n" +" startCounting(String msg) ";
vaInfo=vaInfo+"\n" +" stopCounting(String msg)";
vaInfo=vaInfo+"\n" +" displayMessage(String msg)";
vaInfo=vaInfo+"\n" +" reset()";
vaInfo=vaInfo+"\n" +"Messages";
vaInfo=vaInfo+"\n" +" reminding - send when remindTime is up";
vaInfo=vaInfo+"\n" +" timeUp - send when TotalTime is up";

Design for Scripting

The <param> tag provides a standard mechanism for your applet to get initializing parameters from the web page. The more you can rely on this, the more generic your applet may become and hence you may expect more usage of the same applet over different content.

Your public methods should allow calling by any order. Do not depend on the content author to know the calling sequence of your public method to make your applet work the way you expect. If there is a particular sequence that must be followed, it is best to encapsulate the sequence into another public method while hidding the intermediate steps from the user.

Try to send as much messages as realistic. You may never predict how content author may use your applet. By providing more messages, you provide more ways of using your applet.

Communication with the server

For "virtual apparatus" which requires large initialization data (such as question items in testing), a url referring to a file on the server side is acceptable. However, take care to ensure that the expected data format of your "virtual apparatus" has been explicitly described carefully.

Since server-side programming is usually a more involved exercise, it is best to assume that your "virtual apparatus"’s users would not be able to do too much on this issue.