Planet 7 Technologies XML Application Server Beta Edition
for Java on Linux/Win32

DEV-HOWTO.txt : Developer's Quick Instructions on Getting Started with
the XML Application Server

The XML Application Server (XAS) is designed to make it incredibly easy for 
you to write real-time, collaboration-enabled applications.  The API that XAS
offers is simple and flexible, and with XAS based on XML, the type of apps
you can create are infinite.

This document will walk you through the basic concepts of creating simplest
of XAS applications.  We'll detail the creation of the xastest.java utility 
that is included in the Beta Edition distribution.  This Java class file is full
XAS client, although it only offers simple text capabilities, and the ability to
time round-trip communication with the server to gauge your bandwidth.

REQUIREMENTS

In order to run this example, you must have downloaded and installed the
XML Application Server Beta Edition for Java on either Linux/Unix or 
Windows NT/98/95.

GETTING STARTED

In order to create a Java client for XAS, you'll need to include the
Codec and XASReceiver classes that are inlcuded in the client directory
of your installation location (i.e., C:\xasd\client or /usr/local/xasd/client).

Within the client directory you'll see at least the following Java classes:

ClientCodec.class  - The XAS Codec for use in your apps.
ClientDecoder.class  - The decoding component of the Codec
ClientEncoder.class  - The encoding component of the Codec
XASReceiver.class - An abstract event-based Interface your app implements

If you have these classes, and you have an operative XAS server, you can
create a client.

BASIC CONCEPTS

The concept behind an XAS application is that you have three functions
supplied by the Codec for updating the global XML document shared by
everyone.  The first function connects you to the shared document, the 
second allows you to update it, and the final allows you to disconnect from
the shared document.  Using XAS Codec, the functions are as follows:

public void connectXASEntity()
public void sendUpdateData(String strSendData)
public void disconnectXASEntity()

As you can see, only one of these functions takes a parameter.  In normal
use, this would be the XML or textual data that you wish to insert into the
document as your client's data.  The details of what server to connect with,
what ID your client should use, and what initial data should be associated
with your client is indicated in the Codec's constructor method:

public ClientCodec(String hostname,
		int nServerIncomingPort,
		int nServerOutgoingPort,
		String id, 
		String type,
		String initialData, 
		XASReceiver xasrInterface)

This contains all of the specifics of your client.  Once completed, you can
use the three methods above to contribute to the shared document, and
to manage your client. 

The constructor shown above takes a hostname, 2 port numbers, your
client's ID (either textual, freeform, or whatever), your client's type,
your client's initial XML data, and finally a reference to an object
implementing the XASReceiver interface to be used for callbacks as
events occur on the server.

Lets examine these parameters more closely:

hostname - This parameter is the name of the server XAS is running on.
nServerIncomingPort - The first port associated with XAS
nServerOutgoingPort - The second port associated with XAS
id - This is a unique identifier you supply representing your client.  This can
      be something as simple as "Bob", or something like a GUID or UUID.
type - This is the XML data type that your client is.  Under most apps, clients
         can be of differnet types such as "chatter", or "administrator", or
         represent more abstract entities such as "vending machine" or whatever
         you need.
initialData - This is the first data to be associated with your client.  This does
                not have to be XML as it will already be embedded in the shared
	   document between tags associated with your client.
xasrInterface - This is the name of an object implementing the XASRecevier
                     Interface.  As you'll see in a few moments, by supplying
                     your own object that implements this simple interface, you
	        will receive real-time callbacks from the Codec in regards to
                     events happening on the server.

So what does all this mean??  Well, if you were to call the Codec constructor
above like this:

ClientCodec codec = new ClientCodec("xas.yourcompany.com",
				2001,
				2002,
				"343-AOIUOUIE",
				"Customer",
				"<basket>Empty</basket>",
				this);

The server would create an XML entity into the shared document as
follows:

<Customer id="343-AOIUOUIE">
	<data>
		<basket>Empty</basket>
	</data>
</Customer>

This would be inserted into whatever document the XAS server is hosting
at that point.  Of course, the server would have to be running on the 
machine xas.yourcompany.com listening on ports 2001 and 2002.

The final 'this' parameter indicates that whatever class this call is in, is also
the class implementing the XASReceiver interface.

IMPLEMENTING THE INTERFACE

To put everything together, let's walk through the xastest.java source file
included in the XAS distribution.  This file is located in the client directory
of your installation point.

At the beginning of the source file, we include the standard Java IO routines,
and declare our class as implementing XASReceiver.  We also declare a
ClientCodec as a class member:

//
// xastest
//
import java.io.*;

class xastest implements XASReceiver 
{
	//
	// this client will attempt to contact the 
	// localhost, and then do some XAS stuff to it...
	public static ClientCodec codec;

From henceforth, we can use 'codec' to call methods on the ClientCodec.  
Next, we implement a main line that will check some command-line
arguments, and then instantiate an instance of this class, and call its
runClient() method:

public static void main(String Args[])
	{
	/* verify command line arguments */
	if (Args.length < 4) {
		System.out.println("Usage: java xastest " +
			"<hostname> <username> <server in-port>" +
			" <server out-port>");
		System.exit(1);
	}
	System.out.println("Connecting you to [" 
		+ Args[0] + "] on in-port [" + Args[2] + 
		"], out-port [" + Args[3] + "] as [" + Args[1] + "]");
	//
	// Create instance of this class
	xastest testInstance = new xastest();
	
	//
	// Call the run method
	testInstance.runClient(Args[0], 
	   Args[1],
	   new Integer(Args[2]).intValue(),
	   new Integer(Args[3]).intValue());
}

The above code isn't necessarily XAS specific, and is just used to get our
little app off the groudn with the correct parameters.

The runClient() method is where the real functionality is.  Lets take a closer
look at its implementation:

public void runClient(String strHostname, 
		    String strUsername,
		    int nServerIncomingPort, 
		    int nServerOutgoingPort)
{
	codec = new ClientCodec(strHostname,
			nServerIncomingPort,
			nServerOutgoingPort,
			strUsername,
			"person",
			"<info>data element one</info>",
			this);
	//
	// Connect the codec to XAS
	codec.connectXASEntity();

After this code, the client has established its target server, and its initial
data, and has connected with the call to connectXASEntity();

At this point, the client can proceed to call codec.sendUpdateData() each
time the client want to change the data associated with it on the server.
So now our application goes into a loop reading text off the command line,
and using it to update the server:

	boolean keepitup = true;
	while(keepitup)
	{
		String data;
		data = new String();
		try {
			DataInputStream is = new 
				DataInputStream(System.in);
			//
			// Read input from command line
			data = is.readLine();
			//
			// Check for exit command
			if (data.startsWith("exit")) 
			{
				//
				// Prepare to exit
				codec.disconnectXASEntity();
				keepitup = false;
				continue;
			} else {

We check to see if the command-line starts with 'exit', and if so we make
a call to codec.disconnectXASEntity() that removes us from the shared
document, and disconnects the Codec from the server.

If the user doesn't wish to exit, then we update the server with whatever
they typed in:

				codec.sendUpdateData(data);
			}
		}
	} catch (Exception e) {
		System.out.println("Exception! : " + e.getMessage());
	}

The xastest.java application also allows for timing, but we've omitted that
portion of the source for clarity, please review xastest.java for the actual
details.

This is all that is needed to update a client.

GETTING THE CALLBACKS

Now you may be asking, "How does my client see what other clients are
doing?".  The answer is in the three methods of XASReceiver that your
client application implements.  When we declared this xastest class, we
indicated that it 'implements XASReceiver'.  Without supplying the
implementation of those three methods, this class won't compile.  As you
will see, their implementation is very simple.

XASReceiver is defined as the following:

public interface XASReceiver 
{
	public void addEntity(
		java.lang.String strId,
		java.lang.String strType,
		java.lang.String strData
		);

	public void updateEntity(
		java.lang.String strId,
		java.lang.String strType,
		java.lang.String strData
		);

	public void disconnectEntity(
		java.lang.String strId,
		java.lang.String strType,
		java.lang.String strData
		);
}

These methods will be called by one of the Codec's thread against your
class everytime an update occurs on the server.

For our xastest class, we just have these methods write the data to
STDOUT:

public void addEntity(String Id, String tagName, String data)
{
	System.out.println("Adding:" + Id);
}

Everytime another person connects to XAS, you will be notified when
xastest writes the persons ID out to the command-line.  The other
two updates are just as simple:

public void updateEntity(String Id, String tagName, String data)
{
	// Write XAS update directly to STDOUT
	System.out.println(Id + " says: " + data);
}

public void disconnectEntity(String Id, String tagName, String data)
{
	System.out.println("Disconnecting: " + Id);
}

Of course, the actual class file deals with more timing features here that
have been omitted for clarity.

FINISHING UP

This all that is needed for a complete XAS application.  As you can see,
there is no networking code, or any management on the client side of
the shared XML document.  The XAS server and codec encapsulate you
from all of these features, allowing you to concentrate on the functionality
of your collaborative or real-time application.

Please visit the Developer Solutions area of the Planet 7 Technologies web
site for more comprehensive documentation on using XAS to implement
real-world solutions such as chat server with whiteboard capability, and
a real-time, page-level event site tracking utility that lets you watch all visitors
to your site simultaneously as they trigger page-level Javascript events
that are fed into a super lightweight XAS client component embedded in a
hidden frame.

VISIT US!
http://www.planet7tech.com

(c)1999-2000 Planet 7 Technologies




------------------------------------------------------------------------












