6.2 The very first steps

In this section you will learn how to:

1.: Set up an HTML page with an embedded VRML scene and a EAI Java Applet.
2.: How get a handle from Java to the VRML browser.
3.: How to print out messages to the Java console from the Applet (in order to trace errors, understand program flow etc.)

6.2.1 The application: HTML plus VRML plus a Java Applet

As we said before the EAI is designed to interface an external program with a VRML Scene. Typically you would first create an HTML page containing:

1.: A VRML scene with a least a single DEFed Group or Transform Node
2.: A Java Applet that controls the scene.

A typical template would look like this:

<HTML>
  <HEAD>
    <TITLE>Typical HTML EAI/VRML/JAVA file</TITLE>

  </HEAD>
  <BODY>
    <H1>Typical HTML EAI/VRML/JAVA file</H1>

    <!-- VRML plugged-in scene -->
    <embed src="vrml-scene.wrl" border=0 height="250" width="375">

    <!-- EAI Java applet -->
    <applet code="MyEAIapplet.class" mayscript height="200" width=500">
    </applet>

  </BODY>
</HTML>

Note, that you can copy this template for your own use. Also make sure to include the MAYSCRIPT parameter in the <applet> tag. Finally, if you never have seen any EAI applet you can browse though our examples if you wish.

The Java classes you need are all in the vrml.external package. Make sure that you do not include the vrml, vrml.node and vrml.field packages in the Java Classpath. These are reserved for the scripting interface and will conflict. ^6.1 Therefore a typical applet skeleton would look like this:

import java.awt.*;
import java.applet.*;
import vrml.external.*;

public class MyEAIapplet extends Applet {
   .......
    public void init () {
     .....
    }
  }

See the next section (6.2.2) for a complete minimal example.

Writing simple Java applets

Again, this section is not a fine introduction to Java programming. In case you are learning Java along with EAI just remember this:

The name of the applet class (``MyEAIapplet'' here) has to be the same as the file name (``MyEAIapplet.java''), else it will not be found.
When the applet class is loaded into your Browser, it will first call the init() method to make any one-off initializations. There exists one per default, but you may as well redefine it to initialize things properly before the applets starts running. (e.g. getting references to VRML scene and painting Java widgets).
Usually an applet also has method definitions for start(), destroy() and stop() as well as action() (user input handling).... more later.
It is good practise to declare all global variables at the beginning of the code and give them meaningful self-documenting names.

6.2.2 Getting a reference to the VRML browser

In this section you will learn:

1.: how to get a reference to the VRML browser from the Java applet,
2.: how to print out messages to the Java console of your HTML browser (for debugging purposes).

For everything you want to do you need to establish communication with the browser. In order to do so you first declare a variable to hold an instance of the browser object in your Java applet:

    Browser browser;

We then can use the getBrowser method of the Browser class to get a browser reference:

   browser = Browser.getBrowser(this);

Now let's look at a complete applet that does just about this and nothing much else:

Example 6.2.1 EAI: The do nothing applet

Contents:	getBrowser(),
HTML page:	eai/getbrowser/get-browser.html
JAVA code:	eai/getbrowser/get-browser.java
(dir):	(dir)

// Example applet illustrating getting a browser reference

import java.awt.*;
import java.applet.*;
import vrml.external.*;

public class MyEAIapplet extends Applet {

  Browser browser = null;

  public void init() {

    // Paint something to the applet so that you can see something :)
    add (new Label ("This is the Java Applet with a "));
    add (new Button ("No nothing button"));

    // get the Browser
    browser = Browser.getBrowser(this);

    // Test if we really got and print a message to the Java Console
    if (browser == null) {
      System.out.println("FATAL ERROR! no browser :( ");
    }
    System.out.println("Got the browser: "+browser);
    // Now we could do something with what we got
  }
}

Note that getBrowser() is a static method that ought to work with most modern browsers. In some older code that floats around or in tricky situations (e.g. finding an embedded something within a table I believe) you can find the following alternative:

    import netscape.javascript.JSObject;
    ....
    JSObject win = JSObject.getWindow(this);
    JSObject doc = (JSObject) win.getMember("document");
    JSObject embeds = (JSObject) doc.getMember("embeds");
    browser = (Browser) embeds.getSlot(0);

We never used this Netscape/Lifewire specific method.

Feedback/tracing messages for the developer:

If you start playing around with Java programming (and not only then) it is useful to print out messages to the Java Console (which the end user usually does not enable). The two following lines will exactly do that:

    System.out.println("FATAL ERROR! no browser :( ");
    System.out.println("Got the browser: "+browser);

Java Widgets:

The example's last piece of code we need to discuss relates to the ``user interface'':

    // Paint something to the applet so that you can see something :)
    add (new Label ("This is the Java Applet with a "));
    add (new Button ("No nothing button"));

Those two lines add a label and a button. Note that it is a good idea to start learning some basic widget programming if you haven't already done so. However we will explain somewhat the simple widgets we use in the other examples of this chapter.

Trouble with getBrowser():

Chances are there that the above will not work (even if you did install a recent VRML browser and did compile the classes as you should have). One reason might be that your applet needs more than one trial in order to get the browser reference. Instead of the code above you will have to to use something like this:

Browser browser = null; 
    for (int count = 0; count < 10; count++) {
         browser = Browser.getBrowser (this);
         if (browser != null) break;  
       try {Thread.sleep (200);}
         catch (InterruptedException ignored) {}
         System.out.println ("browser was null, trying again");     }
     if (browser == null) {
         throw new Error ("Failed to get the browser after 10 tries!");     }
     System.out.println ("Got browser\n");

This template is also available on-line. Now let's start for real !

Next: 6.3 Essential EAI tricks Up: 6. The External Authoring Previous: 6.1 What can we

D.K.S. - 1998-03-18