Applets and Adobe Atmosphere

Warning: The following page documents discoveries made about working Applets with Atmosphere and includes graphic descriptions of Java and coding. If you are not comfortable with Java or coding, then shield your eyes and quickly close the browser. Otherwise, please continue.

Introduction

Applets are a widely spread part of Internet browsers these days - you rarely find one without some kind of Java capabilities enabled. So why not use them to their full extent in Adobe Atmosphere?  This tutorial aims to help you get started quickly with working your Applet with Atmosphere.

What does it add to my Atmosphere world?

• Applets can be used as session objects. Combined with session ids from cgi's, you have a powerful medium to maintain Atmosphere state content whilst being able to switch between Atmosphere worlds within the same browser page.
• Security. Applets can be used to hide important code about your Atmosphere, encrypt information and keep that valuable Atmosphere-javascript code away from prying eyes.
• Threading. Imaging freeing your Atmosphere resources to be used for running the virtual world, whilst you send computationally intensive jobs to the Applet? Applet threading permits this.
• Networking. Your Atmosphere world can talk to the Applet, which talks to a Server and vice versa, giving you a full client-server architecture. For a basic introduction see here. 

And much more including a whole range of Java specific code already written waiting to be taken advantage of.

To continue, you should probably already have prior knowledge of Java and applets before we continue. If you don't, the following may be difficult to understand. If you wish to learn about the basics, please visit the java.sun site, where they have excellent tutorials on Java and 'writing applets'.

Getting started
Setting it up
Starting with Communication

Getting started

Hopefully, you are reasonably familiar with Adobe Atmosphere. If not, then this tutorial is probably not right for you. Check out the Adobe Atmosphere site and follow the links from "training" and "community" page sections.

If you are then you will need the following installations: Atmosphere Player/Atmosphere Plugin.

It is also important to know that Atmosphere currently only supports Internet Explorer. These networking examples definitely work with IE. Other browsers, I'm not so certain of.

Prior to learning about these methods, a few important features of Atmosphere are required knowledge. Javascript features heavily in the way Atmosphere interacts with the networking components, so this is a must.

Setting It Up

Lets run through an example of how we'd set up your applet.

Write up your world with Adobe Atmosphere Builder. Attach a javascript component to someplace (this can be any component). Here's one I prepared earlier. For simplicity sake, I've attached a javascript component to the world itself named "tuteworld.js". You will need to edit this soon in order to interact with the browser javascript.

Next you'll need to embed your world within your browser (for the time being, this will have to be Internet Explorer). To do this, you'll need to generate some special html. To generate it, go to http://www.roce.org/articles/embedworlds.html and read about how to embed your plugin/world into the html (eg "c:\virtualwork\tutorial\tuteworld.aer", or "http://www.myplace.com/world/tuteworld.aer", etc). Here's an example of what it might look like after you've generated the html. Store it in a new .html file.

So now if you open this .html file with your browser, you will notice the embedded Atmosphere world. This is good. Now you must embed your applet into the browser.  The code to be added to your html file is shown below (insert the proper applet name in place of the <appletname>.class, for example MyAtmoApplet.class):

 <APPLET
         CODEBASE = "."
         CODE = "<appletname>.class"
         NAME = "atmoapplet"
         WIDTH = 0  HEIGHT = 0  HSPACE = 0  VSPACE = 0  ALIGN = middle MAYSCRIPT>
</APPLET>

So in the end, your html file should look like this.

Of course, you need an applet, so here's an example I prepared earlier. Rename it to MyAtmoApplet.java to compile. Find the already compiled class here.

For the remainder of this tutorial, we will refer to this embedded html page. It's a good idea to open it up in a new window.

Starting with Communication

In any relationship, communication is the most important part. Atmosphere -> Applets is no different.

How do I communicate to my Applet from within Atmosphere?

Lets first distinguish between Atmosphere Javascript (AJS) and Browser Javascript (JS). One is executed in atmosphere, the other, as part of the browser. In general, you can talk to an applet via JS with the code:

document.atmoapplet.<methodname>([parameter1, parameter2, etc]);

Thus, you can talk to an applet from AJS with the code:

sendJS("document.atmoapplet.<methodname>([parameter1, parameter2, ...]);");

For example, using our tutetest.html, we see an example of this method being used:

sendJS("document.atmoapplet.setHelloMessage('Good day sir');");

As you can see, the above line of code sets a variable (String helloMessage) within the Applet to 'Good day sir'. We'll get the contents of the variable in the next step.

How do I communicate to Atmosphere from my Applet?

It's a little bit more complicated to go from your Applet to Atmosphere. In order to do so, you need to have a couple of additional classes. Netscape have written these classes you can download here. To use them, place them in your applet directory (or add them to your classpath when compiling your applet). Import netscape.javascript.* and you're done.

One of the classes is the JSObject class. This is the class you use to speak to the JS. To use it, from within the Applet class, call:

JSObject.getWindow(<appletclassname>.this).eval(<JS>);

For example, you can do

JSObject.getWindow(MyAtmoApplet.this).eval("alert('Good morning people.')");

Then how do you go from the JS to Atmosphere? There's an addition command you can use what the Atmosphere Plugin provides you, and that is
"vmp1.Execute(<AJS>);". If you have a look at the auto-generated html plugin code, you'll see the javascript object 'vmp1' is really the 'MTSPlugin' object, ie your Atmosphere Plugin, and allows you to call AJS from within the JS via this 'Execute' method. Consequently, the following JS command works:

vmp1.Execute('chat.print("Js talking to Ajs")');

And if you put it all together, from the Applet to AJS:

JSObject.getWindow(<appletclassname>.this).eval("vmp1.Execute('chat.print(\"Applet talking to AJS via JS!\")')");

And to complete our exercise, we'll just check on that helloMessage variable we set in the previous step. So to tell AJS the contents of our variable, we need a method within the AJS to call, lets make it a trivial method:

function showVariable(thevariable) {
  chat.print(thevariable);
}

And our Java Applet code looks like:

JSObject.getWindow(MyAtmoApplet.this).eval("vmp1.Execute('showVariable(\""+helloMessage+"\")')");

Concepts: Threading

Imagine if you had some networking information to retrieve or some computationally intensive activities to undertake in your Atmosphere script. If you were to code them into the Atmosphere Javascript, Atmosphere would spend it's time executing code and not allow you to roam the world and would freeze up your console/plugin. What if there was a way to farm off this code to be executed in another place leaving Atmosphere itself free? With Applets, you can do this.

Threading is a feature you can take advantage of with Applets and incorporate it into Atmosphere