Introduction to TinyServer

TinyServer is an experimental HTTP server. It only handles the "GET" message. TinyServer is developed to experiment with various XML/DOM/XSL technologies. It provides configuration for:

  1. XSL Processor,
  2. DOM Implemetation, and
  3. XML Parser.

TinyServer gives an example for:

Configuration

Server reads its configuration from the file (default configuration file name is server.properties). The possible settings are:

org.xml.sax.driver org.xml.sax.SAXDriver implementation.
org.w3c.domFactory iwt.web.xmldomxsl.DOMFactory implementation.
org.w3c.xslProcessor iwt.web.xmldomxsl.XSLProcessor implementation.
org.w3c.xmldomxsl iwt.web.xmldomxsl.XMLDOMXSL implementation.
uriextention.resource URI extention based handlers.
uriprefix.resource URI prefix based handlers.

For example, a possible server.properties file looks like as follows:

org.xml.sax.driver=com.microstar.xml.SAXDriver
#org.w3c.domFactory=edu.npac.iwt.IWTDOMFactory
org.w3c.domFactory=test.xml4j.XMLJDOMFactory
#org.w3c.xslProcessor=edu.npac.iwt.IWTXSLProcessor
#org.w3c.xslProcessor=test.lotus.LotusXSLProcessor
org.w3c.xslProcessor=test.xslp.XSLPXSLProcessor
org.w3c.xmldomxsl=edu.npac.iwt.XMLDOMXSLImpl
uriextention.resource=ext.resources

Packages in TinyServer

org.w3c.dom DOM Level 1.
org.xml.sax SAX package for XML parsers.
iwt.web.server A simple HTTP server interface definitions.
iwt.web.xmldomxsl A simple interfaces for XML Parser/DOM Implementation/XSL Processors.
iwt.rdf An experimental RDF interfaces for easy RDF processing.
com.microstar.xml Microstar's free non validating XML Parser.
edu.npac.iwt TinyServer implementation.
edu.npac.iwt.dom DOM implementation in TinyServer.
edu.npac.iwt.domUtil A printDOM utility object to print DOM.
edu.npac.iwt.rdf Implementation of RDF interfaces given in iwt.rdf package.
fr.dyade.koala.xml Koala XSL Processor. Conforms with the old XSL Spec (August,1998).
test.lotus An implementation of iwt.web.xmldomxsl.XMLDOMXSL interface for LotusXSL XSL Processor.
test.xslp An implementation of iwt.web.xmldomxsl.XMLDOMXSL interface for XSLP XSL Processor.
test.xml4j An implementation of iwt.web.xmldomxsl.DOMFactory interface for IBM's XML4J.

Introduction to iwt.web.server Interfaces

This package contains implementation of two utility objects: one for http request message (HttpRequest) and one for a query string (QueryString) given as a part of URI. HttpRequest object contains the following methods:

getMethod() Returns the HTTP Method.
getUri() Returns the URI part of HTTP request after stripping the query string part.
getQStr() Returns the Query String in the URI part of HTTP request.
getProtocol() Returns the HTTP protocol version.
getInputStream() Returns the input stream pointer after the HTTP headers. This stream can be used to read the data portion of the POST message.
getPrefix() Returns the prefix of URI.
toString() Returns the first line of HTTP request message.

QueryString object is extended from java.util.Properties object and it defines a buildQueryString(String) method to build a collection of name-value pairs. After that, getProperty() method can be used to obtain the value of given parameters. This package also defines two abstract interfaces for HTTP servers (HttpServer) and resource handlers (HttpResource). HttpServer interface tries to define a set of methods which can be expected from the server implementation. HttpServer interface contains:

String getProperty(String propName) Returns the value of queried property. Possible property names are:
server.port The port number of the socket on which the server is accepting HTTP Requests.
server.docroot The root of document tree served by this server.
server.address IP address of the machine on which the server is running.
org.xml.sax.driver org.xml.sax.SAXDriver implementation.
org.w3c.domFactory iwt.web.xmldomxsl.DOMFactory implementation.
org.w3c.xslProcessor iwt.web.xmldomxsl.XSLProcessor implementation.
org.w3c.xmldomxsl iwt.web.xmldomxsl.XMLDOMXSL implementation.
String getRootDirectory() Returns the root of the document tree served by the server.
int getServerPort() Returns the port number of the socket on which the server is listening.
String getServerAddress() Returns the IP address of the machine on which the server is running.

edu.npac.iwt.TServer implements the HttpServer interface. The second interface allows to define resource handlers. HttpResource has two methods:

void handleResource (Properties sProps, String resourceName, QueryString qStr, OutputStream pStream, Properties props, HttpRequest req)
sProps Server Properties
resourceName URI of the HTTP Request Message after query part is stripped.
qStr Query String("?")
pStream Output
props HTTP Request Headers.
req HttpRequest Object.
void setServer(HttpServer aServer) Sets the HttpServer object.

edu.npac.iwt.FileResource implements the HttpResource interface and this is the default resource handler if there is no registered handler for the requested URI. Resource Handlers can be registered based on the extention part of the URI, for example, all the "*.xml" files can be handled by the edu.npac.iwt.XMLEHandler object. It is also possible to define such handlers based on the prefix of URI. The prefix of the URI is the first string between the first two "/" characters in the URI. As you recall "/" refers to the root of the document tree while resources starting with "/cgi-bin/" refer to CGI Scripts and "/servlet/" refer to the SUN Servlets. Prefix based resource handling is defined based on this observed scheme (de facto standard). When the server is started up, it looks at uriextention.resource parameter to find the name of configuration file for extention based resource handlers. If it contains a valid file name, then the server reads the settings from this file and loads the necessary handlers to its registry. Registry of prefix based resource handlers is processed the same way except that uriprefix.resource property is used to obtain the name of the configuration file. The server decides in favour of a prefix based handler when there is a tie. If the server can not find any kind of registered handler matching with the current requested URI, then it uses its default resource handler (edu.npac.iwt.FileResource). For example, let's assume that uriextention.resource has a value ext.resources and this file is readable by the server. The file should conform to the following format:

xml=edu.npac.iwt.XMLEHandler

The key gives the extention (or prefix) of the possible resource and the value gives the class name of the object responsible for this process. Ofcourse, the implementation should support the HttpResource interface otherwise it won't be registered by the server.

Introduction to iwt.web.xmldomxsl Interfaces

XMLUtilityException

Defines a possible Runtime exception.

XMLUtility

Defines an abstract setProperty() method to set the class name of implementations for DOMFactory, XSLProcessor, and XMLDOMXSL interfaces.

DOMFactory

Defines methods to obtain a Document object of an XML document from several possible sources and extends from XMLUtility interface.

Document openDocument (String xmlFileName)
Document openDocument (InputStream in, String xmlFileName)
Document openDocument (URL url)

XSLProcessor

Defines operations to apply XSL processing and extends from DOMFactory interface.

void applyXSLRules (URL doc, URL xsl, OutputStream pout)
void applyXSLRules (String doc, String xsl, OutputStream pout)
void applyXSLRules (Document doc, Document xsl,OutputStream pout)

XMLDOMXSL

Defines methods to set up XML parser, DOM Implementation and XSL Processor. It extends from XSLProcessor interface.

void setAll (Properties aProps)
void setSAXDriver (String sax_driver)
void setDOMDriver (String dom_driver)
void setXSLProcessor (String xsl_driver)
A Class diagram of iwt.web.xmldomxsl interfaces.

Introduction to iwt.rdf Interfaces

A Class diagram of org.w3c.dom interfaces. edu.npac.iwt.dom package implements these interfaces. This package started from the previous release of Freedom (by Docuverse) and upgraded but not fully tested.
A Class diagram of iwt.rdf interfaces.

iwt.rdf package introduces a set of interfaces to make the programming with RDF Data model easy.

RDFElementFactory
RDFElement getRDFElement (URL url)
RDFElement getRDFElement (String fileName)
RDFElement getRDFElement (Document doc)
RDFElement getRDFElement (Element aNode)
RDFException
A RDFException definition.
RDFElement
DescriptionList getDescriptionElements
ElementSet
Node item(int i)
Node next()
void reset()
int getLength()
SequenceElement
BagElement
AlternativeElement
DescriptionElement
boolean isAbout()
String getAbout()
boolean isID()
String getID()
PropertyList getProperties()
DescriptionList
DescriptionElement item(int i)
DescriptionElement next()
void reset()
int getLength()
PropertyElement
String getTagName()
boolean isResource()
String getResource()
Node getValue()
PropertyList
PropertyElement item(int i)
PropertyElement next()
void reset()
int getLength()

RDFElementFactory interface allows to obtain RDFElement of the document from an XML file pointed by URL, an XML file pointed with name, a Document or an Element object. RDFElement interface allows to navigate on the RDF Data model. edu.npac.iwt.rdf package implements these interfaces.

Demos

demos directory contains four demo examples for:

DOM Programming with student database example.

demos/studentdb contains the code related to this example. This example uses Java Swing for GUI and edu.npac.iwt.dom package for DOM implementation. The idea is very simple: assume that all the student records (our case a couple of student records) are stored in an XML formatted file. This example reads this file, gets the DOM representation of XML document, extracts each student record, and produces a Swing JTable to render this information.

A snapshot of the GUI after student records in XML document are converted to Swing JTable object for rendering. See DemoHelp for more information.

RDF Programming with student database example.

demos/student1 contains the code related to this example. This example uses Java Swing for GUI and edu.npac.iwt.rdf package for RDF implementation. In this example, it is assumed that each record also contains a file name pointing at a vCard of each student. vCard definition contains a person's bussiness related information and recently there are some studies for RDF based serialization of vCard. In this example, student table contains one more column to display the vCard information related to the student. The process is exactly the same as in previous example, except that when user clicks on the button on the last column (vCard column), program gets the file name of vCard definition from student record and displays a very limited information in another window.

A snapshot of the GUI after user clicks on the vCard button of the student. See DemoHelp for more information.

An XML based information exchange between server and client with TinyBrowser/0.1.

demos/tinybrowser contains the code related to this example. This example uses Java Swing for GUI and iwt.web.xmldomxsl package for XML/DOM/XSL implementations.

OpenURL option allows user to enter the URL of Web resource. Exit terminates the program. See DemoHelp for more information.
A window to get the URL of the Web page from the user.

This address points to a directory in the document tree without index.html file. TinyServer sends an XML formatted directory description when it realizes that the client is TinyBrowser by User-Agent HTTP header. TinyBrowser/0.1 converts this XML document to the org.w3c.Document object and produces an HTML formatted presentation. See DemoHelp for more information.

A snapshot of the GUI after user selects an XML document In this example, TinyServer realizes that the requested document is XML then it looks at xsl parameter in the query string. If it specifies a valid xsl file, then it applies these rules on the document and returns the result. If no value for xsl is specified in the query string, then it looks at default.xsl file in the document's directory. If it is available, then server returns the processed result. See DemoHelp for more information.

A snapshot of the GUI after user selects an XML document with xsl parameter in the query string. TinyServer applies these rules on the document and returns the result. See DemoHelp for more information.

Experimenting with XSL Processor on the client side by using TinyBrowser/0.2.

demos/tinybrowser2 contains the code related to this example. This example uses Java Swing for GUI and iwt.web.xmldomxsl package for XML/DOM/XSL implementations.

TinyServer detects that the client is TinyBrowser/0.2 then it returns the XML representation of document. Unlike TinyBrowser/0.1, v0.2 uses XSL processor to render the received XML document. See DemoHelp for more information.

Here the same student file is browsed by processing XSL on the client side to produce the HTML presentation.

How to run

TinyServer and TinyBrowser uses configuration files to get the imlemenation of iwt.web.xmldomxsl interfaces. Since we have experimented with different DOM implementation and XSL processors there are some configuration combinations that works correctly.

When edu.npac.iwt.IWTDOMFactory is used as an DOM implementation,

IWTXSLProccessor LotusXSLProcessor XSLPXSLProcessor

TinyServer processes the XML documents in xsl1 directory correctly. TinyBrowser processes the XML documents in xsl1 directory correctly. xsl/dir.xsl file should be the copy of xsl/dir1.xsl file because of the XSLProcessor version.

TinyServer does no processes the XML documents correctly in any directory. TinyBrowser does no processes the XML documents correctly in any directory.

TinyServer does no processes the XML documents correctly in any directory. TinyBrowser does no processes the XML documents correctly in any directory.

When test.xsm4j.XMLJDOMFactory is used as an DOM implementation,

IWTXSLProccessor LotusXSLProcessor XSLPXSLProcessor

TinyServer processes the XML documents in xsl2 directory correctly. TinyBrowser processes the XML documents in xsl2 directory correctly. xsl/dir.xsl file should be the copy of xsl/dir2.xsl file because of the XSLProcessor version.

TinyServer processes the XML documents in xsl2 directory correctly. TinyBrowser processes the XML documents in xsl2 directory correctly. xsl/dir.xsl file should be the copy of xsl/dir2.xsl file because of the XSLProcessor version.

In summary, IWTDOMFactory with IWTXSLProcessor works on documents in xsl1 directory and xsl/dir.xsl should be the copy of xsl/dir1.xsl file because this file is used by TinyBrowser/0.2 for rendering and it contains the XSL rules based on August 1998 version. XMLJDOMFactory with LotusXSLProcessor or XSLPXSLProcessor works on documents in xsl2 directory and xsl/dir.xsl should be the copy of xsl/dir2.xsl file because it conforms to the last XSL spec (December 1998). We provided two version of configuration files for server and browser with correct settings. server1.properties and server2.properties contain the right combination for TinyServer. browser1.properties and browser2.properties contain the right combination for TinyBrowser. Similarly document directories under public_html contain two version of documents. xsl1 directory contains the documents which can be browsed without any problem with IWTDOMFactory/IWTXSLProcessor pair. xsl2 directory contains the documents which can be browsed without any problem with XMLJDOMFactory/(LotusXSLProcessor or XSLPXSLProcessor) pair. Since TinyBrowser/0.2 uses XSL engine to render the directory data, xsl/dir.xsl should be set to correct version based on browser's settings.

How to build on NT
Please enter the following command
build

mk/config.win contains the settings for compiling. You can set the directory of Java installation and put the proper path for the packages.

How to build on Unix
Please enter the following command
build

mk/config.mk contains the settings for compiling. You can set the directory of Java installation and put the proper path for the packages.

How to build demos on NT
Please enter the following command
builddemos

How to build demos on Unix
Please enter the following command
builddemos

How to run the server on NT
Please enter the following command
runserver

The server has the following command line parameters:

-root Root directory of the document tree. (def: public_html)
-port Port number of the server socket on which the server accepts HTTP Requests. (def: 5005)
-prop The name of the configuration file. (def: server.properties)

If you want to change any option, the you have to edit the Makefile.win.

How to run the server on Unix
Please enter the following command
runserver

The same command line options are available on Unix also. If you want to change it, you have to edit the Makefile.

How to obtain XML4J
This is IBM's implementation of XML Parser and DOM. Source code is available. You can download this package from
http://www.alphaWorks.ibm.com/aw.nsf/home/current

How to obtain LotusXSL
This is IBM's implementation of XSL Engine. Source code is available. You can download this package from
http://www.alphaWorks.ibm.com/aw.nsf/home/current

How to obtain XSLP
This is another open source code implementation of XSL Engine in Java. You can download this package from
http://www.clc-marketing.com/xslp/

XSLP can also use FESI ECMAScript interpreter. FESI written in Java and source can be downloaded: http://home.worldcom.ch/jmlugrin/fesi/

What comes with TinyBrowser for XML/DOM/XSL?
TinyServer sources contain:

  1. Microstar XML parser. This package conatins the sources and developed in Java.

  2. DOM implementation in Java. This package originally started from Freedom package of Docuverse. This source is upgraded to the last specification but we kept most of the class names unchanged. Note that this implementation is not fully tested.

  3. Koala XSL Engine. This package is a free Java implementation of August 1998 XSL Spec. You can also obtain this package from: http://www.inria.fr/koala/