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

README

Thank you for downloading the XML Application Server Beta Edition.  This
document contains installation and configuration information for the Java
version of the XML Application Server (XAS) with respect to Linux and
Microsoft Windows.  For developer instructions on creating client
applications, see the file DEV-HOWTO.txt in the <install-dir>/client folder.

REQUIREMENTS

To run the XML Application Server Beta Edition, you will need to have a
Java Virtual Machine or Java SDK.  This software has been tested using the
Blackdown and Kaffee JDK's for Linux, as well as Sun Microsystems' JDK for
Microsoft Windows.

INSTALLATION

*Linux Installation*

To install XAS for Linux, simply change directory to /usr/local as root, and
unpack the TGZ file with the following:

$> gzip -d xas-java-linx-base_X_X_XXX.tgz
$> tar -xvf xas-java-linx-base_X_X_XXX.tar

Once unpacked, change into the newly created directory and you will see
this file (README.txt), inside the docs directory, along with a few other 
directories.  Proceed to the next section labeled CONFIGURATION for 
instructions on configuring the software before first time use.

*Windows Installation*

To install XAS for Windows, double click on the

 xas-java-win32-base_X_X_XXX.exe

 file.  Unpack the files wherever you like, but we
recommend using C:\ as the base.  This will create a directory named 
C:\Planet7Technolgoies with the necessary files.  If you choose to install in 
a different location you will need to update the Docroot inside the config file.  
Proceed to the CONFIGURATION section for details.

CONFIGURATION (All Platforms)

The XAS configuration file is located in the<install-dir>/xasd/config directory beneath
wherever your installation point.  The file is named xasconfig.txt, and can
be edited with any text editor.

The only parameter you may need to change in a default configuration is the
Docroot.  By default this points to the xml-docs directory beneath the XAS
default install point.  You can change this to wherever you like.  When
launching XAS, it will look for application XML files using this information.  Similar to
how HTTP servers operate, XAS will look for the documents relative to the
docroot.  If you installed in the default locations, you will not need
to alter the Docroot variable.  For example, if you installed in /opt:

Docroot=file:/opt/Planet7Technolgoies/xasd/xml-docs

On Windows, if you installed in D:\XAS you might use:

Docroot=file:/D:/XAS/Planet7Technologies/xasd/xml-docs

If you accepted the default locations, you will not need to change anything.

FIRST TIME USE

To put XAS through an exercise, you can launch the xastest command-line
application that is located in the client directory after launching
the server.

*Launching the Server*

To launch the server with a default document loaded, you can change directory
using a command prompt to the xasd/p7bin directory beneath your installation
point.  Once there, you can launch XAS accordingly:

(linux:)
bash$ java xasd

(win32:)
C:\ jview xasd

Note: The name of your Java VM may be different, for example kaffe is the
name of Java VM executable on some Linux machines, whereas jview is the name
of Microsoft's Javav VM.

This should output some configuration information about each XML Application 
specified in the config file, and whether or not each XML application intialized.
After this, XAS will run indefinately.
You can exit XAS with a [control-c] combination on most platforms, or by
issuing the 'Kill Switch' command.  (remember, this is the Beta Edition).  Our
1.0 release will have an administrative application to manage the launching and
stopping of XAS.

*Launching the Client*

To run the client portion of XAS, open another command prompt or shell
window and change directory to the client directory under the
installation point.  Once there, you can connect to XAS using:

(linux:)
bash$ java xastest localhost YourName 2001 2002

(win32:)
C:\ jview xastest localhost YourName 2001 2002

This will connect you to the XAS server running on localhost-- and in
particular to the XML application running at ports 2001 and 2002.  
It will connect you as the entity you specify for 'YourName'.  While running
the xastest program, you can type sentences and see them communicated back
to you or any other connected clients.  You can run as many copies of
xastest as you want at the same time, from different computers on your 
network.  You can also time the round trip capabilities of XAS by typing
"time" while running xastest.  A client can exit xastest by typing "exit".

THE CONFIGURATION FILE:

The <install-dir>/xasd/config directory is where you configure each XML
file/application you wish to serve.  One of the sample applications is named
Default and has an entry like this:

#
# Default Application
Application=Default
XmlFile=/default.xml
InPort=2001
OutPort=2002

This indicates that file to be the base for the app is default.xml, located at
the top of docroot, which is relative to your installation location and platform.
As you can see, the in ports, and out ports are specfied as well.  You can use
any ports you like, but they are configurable for each application.  You should
avoid using ports that are for other services (like 80 for HTTP, 25 for Mail) or
that are blocked by your corporate firewall.

When XAS launches, it will load and start an application instance for each
Application listed in the configuration file.

XML DOCUMENTS

XAS allows clients to sequence XML data between themselves.  However, XAS
also allows you to associate server-side XML documents with any one application,
and merge client XML into the server document, thus allowing a true collaborative
view of XML data between all clients, with the clients themselves being represented
in the document.  This section details the requirements for server-side XML documents
using the Beta Edition of XAS.

To provide collaborative editing and viewing of any XML document, the Beta
Edition of XAS requires that you provide two attributes to each XML entity
you wish to make available to clients.  For example, if you were to write an
XML document that detailed a menu, and wanted each item available for
alteration by clients, you would need to provide an ID attribute, and a data
tag for your entity:

<menu>
	<entree id="Chicken Pot Pie">
		<data>
			<calories>800</calories>
			<fat>25 grams</fat>
			<yumminess>4</yumminess>
		</data>
	</entree>
</menu>

In this abridge file, XAS as well as clients would be able to treat this menu item
as an <entree> whose ID is "Chicken Pot Pie", and contains a data segment
of:
	<calories>800</calories>
	<fat>25 grams</fat>
	<yumminess>4</yumminess>

This is the data structure that the client Codec and API's will provide for you.
Using this technique, parsing of the data portion of the "entree" entity must
be done on the client.  In version 1.0 of XAS, we will be providing access to
any node on the server-side XML document.  In the beta edition, you must
enclose the particular pieces of XML you wish to use on the client inside <data>
tags.  Please note: Many robust applications can be built using XAS with an
empty server-side document... in these type of applications, the server is
only used to sequence XML between clients.

Please visit our Developer's Solutions area of our website for in-depth details
on the amazing applications fo XAS.

FINAL NOTES

Please visit the Planet 7 Technologies web site for the latest release of
XAS, and the latest documentation and notes.

http://www.planet7tech.com

------------------------------------------------------------------------
(c)1999-2000 Planet 7 Technologies
The XML Application Server is redistributable under the terms of the
GNU General Public License.



