Networking with Adobe Atmosphere
This document serves as a short introductory lesson into networking with Adobe Atmosphere over the internet. An attempt has been made to keep information to a short and succinct level to hopefully get you going quickly on the road to networking. :)
What is Adobe Atmosphere?
Adobe Atmosphere is a new, cutting edge technology to represent virtual worlds on the internet. In other words, its a kind of virtual reality technology which you may enable your internet browser with. At the moment, it is still in Beta, and release is expected to be early next year (2003).
There are all sorts of things to which the term 'networking' could be applied. In this instance, we are talking about a particular model - client server model. It sort of looks like this:
It helps to refer back to this picture when discussing the subsequent methods in this lesson.
What's happening here is that your browser displays the Atmosphere content. You enter the virtual world and somewhere inside the world an object inside the world is reporting to you some information gathered outside somewhere on the Internet. For example, this could be the top 10 latest headlines from the Sydney Morning Herald (online newspaper) website for today.
Having your Atmosphere & browser enabled with network & internet information access could provide infinite amounts of worlds with an infinite amounts of knowledge and allow an infinite amounts of services. For example, all of a sudden, you can create a supermarket virtual world where customers may enter, choose their products virtually (as if they were really in a supermarket) and pay for it all within the world itself.
Networked virtual world capabilities brings a whole new dimension to the way you perceive information and interact with people.
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 will only work with IE.
In this tutorial, we will learn 2 ways to interact with our server - via Applets and via SOAP.
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.
Basically, what happens is your atmosphere components talk to their assigned javascript (JS) component, which may then talk to the the javascript (JS) of the browser, which then talk to either talk to an applet, or utilising SOAP, talks to the server directly.
Lets run through an example of how we'd set up both networking services.
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/pluginhtml.html and enter the location of your world file (for example, "c:\virtualwork\tutorial\tuteworld.aer", or "http://www.myplace.com/world/tuteworld.aer", etc). The reason for this is that Atmosphere uses Viewpoint technology to embed its content within browsers (but you don't need to know this). Here's an example of what it might look like after you've generate the html. Store it 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.
Interaction: From Browser to Atmosphere
Take your html file containing the embedded Atmosphere world. Lets add some simple javascript code to this file.
<BUTTON onclick="test();">Interact with Atmosphere</BUTTON>
<script language=javascript>
function test() {
document.all.MetaStreamCtl.PluginCommand('chat.print(\"Message from Browser\");', 0, 0);
}
</script>
Whoa! What does this mean? Lets dissect it.
<BUTTON onclick="test();">Interact with Atmosphere</BUTTON>
This means you've added a button. Attached to it is some simple javascript to run a method called "test()".
function test() {
document.all.MetaStreamCtl.PluginCommand('chat.print(\"Message from Browser\");', 0, 0);
}
This is your implementation of "test()". The purpose of this method is to tell the Atmosphere component you want it to run a command for you. The way you do this is to get a handle to the MetaStreamCtl object (effectively your Atmosphere component) and run a method on it called "PluginCommand". By using this method, you can send any command to the Atmosphere component you wish. The command we want to run in this instance is a simple chat.print() command to show that it works. Give it a try in your browser.
Interaction: From Atmosphere to Applets
First, you need to create an applet to talk to. Any simple applet will do with a public method. Here's one I prepared earlier: AtmoBaseApplet.java, AtmoBaseApplet.class. Put these in the same directory as your .html file.
Next, you'll add some .html code to your .html file which tells the browser to load your applet. Here is some which will work with the above applet.
To communicate from Atmosphere to an Applet, in one of your Atmo-attached javascript components (eg, "tuteworld.js") all you need to do is add the command:
sendJS("document.appletname.appletmethod()");
For example, using our AtmoBaseApplet class we can test this out by adding to "tuteworld.js":
sendJS("document.atmobaseapplet.runFetchData()");
And this is how you can interact with your applet. What you are doing here is getting applet from the browers javascript 'document' object and running the applet method directly. How do we know it has worked? Lets set up a little experiment. Add the following lines of javascript code to your .html file:
function execCommand(commandRes) {
document.all.MetaStreamCtl.PluginCommand("showResult('"+command+"');", 0, 0);
}We create a function called execCommand() which takes the result
of a command and puts the result as a parameter to an Atmosphere function called
showResult(). Now, add the following javascript code to your "tuteworld.js":
sendJS("execCommand(document.atmobaseapplet.runFetchData())");
function showResult(result) {
chat.print(result);
}
What this is doing is telling the browser javascript to run the applet method runFetchData(), passes the result to execCommand() method which in turn calls back showResult() with the result. Looks a bit long winded, right? Well it is, but hopefully it makes it clear what is happening here. If you REALLY wanted to, you could do the whole example above in a single line added to "tuteworld.js":
sendJS("document.all.MetaStreamCtl.PluginCommand(\"chat.print('\"+document.atmobaseapplet.runFetchData()+\"');\",
0, 0)");
But that looks evil.
From here, you can code your applet to talk to a server & vice versa. I won't cover that here, but for an excellent starter on networking with java, start here at the java.sun.com site. You'll also notice with the AtmoBaseApplet.java included is a method for some basic networking with a server. I've also written a basic server which you may attempt to run here.
Interaction: From Atmosphere to Server via SOAP
This is a slightly more complicated example of how to network with Atmosphere. In this section, we'll cover some really basic principles behind SOAP and how it operates as part of the larger Web Services infrastructure. For more reading material, I suggest go to the http://safari.oreilly.com website and/or the http://www.webreference.com website. Look for "web services" and "SOAP". It's a good idea to get reasonably comfortable with these topics before going ahead.
SOAP stands for Simple Object Access Protocol. It is an XML formatted messaging protocol which is designed to allow code & platform independent interaction with services provided by a server on the web. There are many services on the web provided by third party servers which can be taken advantage of by our virtual world environment, but are only accessible via the SOAP messaging format. This is why it is useful to understand SOAP and how to interact with these. In addition, you may decide at some point in time to implement your own services which you may like to provide to other users (eg, Atmosphere world builders) which could in SOAP enabled aswell.
Now. Getting things setup is probably the most complicated step to the whole scenario. Lets start with the SOAP server, from which you will maintain your services. To set this up, go to the safari.oreilly site, http://safari.oreilly.com/main.asp?bookname=webservess&snode=44. There is a quick start tutorial to setting up Apache SOAP. It is very excellent, and is the fastest way to get your server going. Deploy their "Hello, SOAP!" example - we'll be using this as the first component our Atmosphere world will interact with. Also read up on the safari.oreilly site's following tutorial on WSDL (http://safari.oreilly.com/main.asp?bookname=webservess&cnode=58), because you'll also need the .wsdl file that goes along with the "Hello, SOAP!" service (helloService.wsdl). If you are already very familiar SOAP, this will be straight forward to you.
Important things to note/do at this stage:
The next step is to look at how we'll use our new Hello service. Take a look at this page. Try viewing the source. We'll dissect it below. This page has been abstracted from a tutorial given by webreference.com. You can find it here: http://www.webreference.com/js/column97 Check it out if you are after a more detailed explanation on anything. Save a copy of the page (soapexample.html) and this file (webservice.htc) in the same directory on your local machine. What does it do? The soapexample.html is what you will use to interact with your SOAP Hello service. If you have started up your Tomcat server, you will notice that upon clicking the button that an alert will pop up with "Successful Call. Result is Hello World!". This means you've sent and received a message from the Tomcat server. How? Lets look below at the html source.
<BODY ID="webServiceCallerBody" onload="loadService()" STYLE="behavior:url(webservice.htc)">
A couple of things here. loadService() is defined below as a javascript method. It gets run as soon as the page is loaded. The second thing is behaviour:url(webservice.htc). This file enables the browser with all sorts of Web Service behaviour essential to the operation of Web Service components, such as SOAP. Always, when defining a behaviour as we have with soapexample.html, include the webservice.htc component in the same directory. Once we have defined the behaviour, we can reference it with the ID we've specified, webServiceCallerBody.
function loadService() {
webServiceCallerBody.useService("http://localhost:8080/helloService.wsdl","hello");
}After the page has loaded, we load our service information as "hello". Now we can reference it below.
function callService() {
iCallID = webServiceCallerBody.hello.callService(handleResult, "sayHello", "World!");
}Anytime we want to use the service, we call this method. In this case, it is called every time we click the button. handleResult is the method we want as the call back (specified below), "sayHello" is our service method, and "World!" is our first and only parameter to the method. Basically, webServiceCallerBody.hello.callService() method handles the SOAP format for us as it interacts with the SOAP enabled server (ie, Tomcat).
function handleResult(res) {
if (!res.error) {
alert("Successful call. Result is " + res.value);
} else {
alert("Unsuccessful call. Error is " + res.errorDetail.string);
}
}This is our call back once the service method is complete. If the service is available, an alert will be "Successfull". If the service is unavailable (this could be for any number of reasons), an alert will pop up with "Unavailable..".
That's all there is to interacting with your browser to a SOAP enabled server (and service). As you can see, there's a little bit of work to be done here, but once overcome, the benefits can far outweigh the set up costs.
If you now want to add SOAP service functionality to your Atmosphere world, you can now interact directly with the browser javascript methods (such as callService()) by using the sendJS() and document.all.MetaStreamCtl.PluginCommand() methods as discussed earlier.