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",
				"Empty",
				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 " +
			"  " +
			" ");
		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 ground 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",
			"data element one",
			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
		);
}