README

The Mamba application server provides a standalone implementation of the Simple API for serving both dynamic and static content. It serves static content such as HTML files and images in much the same way as a traditional HTTP server would. However, if dynamic content is required then the Simple API provides a means to extend the servers functionaly. Serving dynamic content can be achieved by implementing Service objects, writing Velocity templates, or writing BeanShell scripts. A more comprehensive explanation of how to write Service objects can be found on the Simple homepage.

Getting Started

Getting the Mamba application server up and running could'nt be simpler. It requires no administration or configuration and is fully operational once it is started. Firstly it must be downloaded. The downloaded file is a "zipped" or "compressed" in the GZIP format. This can be unzipped by both the WinZip and PKZIP applications for Windows, and by gzip and tar on Linux or any other UNIX platform. Within the compressed file there are several directories, these contain tools that help in the development of Service objects as well as various icons and a Java Archive (JAR) files that contain the "executable" byte code. The JAR files that contain the "executable" byte code can be seen in the diagram of the directory structure shown below.

[+] mamba-1.1
 |
 +---[+] bin
 |    |
 |    +--- mamba
 |
 +---[+] class
 |    |
 |    +--- build.xml
 |
 +---[+] html
 |    |
 |    +---[+] icons
 |
 +---[+] lib
 |    |
 |    +--- beanshell-2.0.jar
 |    |
 |    +--- mamba-1.1.jar
 |    |
 |    +--- simple-2.4.jar
 |    |
 |    +--- velocity-1.3.1.jar
 |
 +---[+] log
 |
 +--- mapper.properties
 |
 +--- server.properties
 |
 +--- velocity.properties

The lib directory contains JAR files for Mamba, Simple, Velocity, and BeanShell, there are no unresolved external dependancies. All that is required to start the server is to edit a Java properties file named server.properties. Typically you will only need to edit the port number if it is other that the default port number 80, however the the web root (the directory that the files are served from), and the service classpath (the directory that service classes are located) can also be edited. By default Mamba has a predefined directory layout and does not require these locations to be specified.

Linux and UNIX

Starting the server on a UNIX or Linux platform can be done using the provided shell script. The script has been tested on both Solaris and Linux and can be used to start Mamba each time the system boots. The script is located in the bin directory and requires three environment variables to be set. Firstly the MAMBA_HOME environment variable is used to locate the directory that Mamba has been installed in. This is used when the script is copied from the bin directory to another directory, such as the /etc/init directory on a Linux system. To clearly illustrate what the MAMBA_HOME environment variable is used for consider the directory /INSTALL_DIR on a Linux system. This is the directory where the Mamba archive mamba-1.1.tar.gz was downloaded and unzipped. So the directory contains a single subdirectory named mamba-1.1, which has the structure illustrated in the above diagram. Without moving the script /INSTALL_DIR/mamba-1.1/bin/mamba the server can be started by executing that script, as it will simply assume that the MAMBA_HOME environment variable is the parent directory by default, which is /INSTALL_DIR/mamba-1.1. However, if the mamba script is moved to /etc/init so it cant start each time the system boots the MAMBA_HOME environment variable needs to be set, as the default value is the parent directory will be incorrect. So simple open the copied file /etc/init/mamba and add the line MAMBA_HOME=/INSTALL_DIR/mamba-1.1 to ensure it starts correctly. The two other environment variables are MAMBA_JAVA_HOME and MAMBA_LIB, which point to the location of your Java Runtime Environment (JRE) and the JAR files used by Mamba respectively. If your Java Virtual Machine (JVM) is located at a path other than /usr/bin/java then the MAMBA_JAVA_HOME environment variable needs to be set. By default the MAMBA_JAVA_HOME is set to JAVA_HOME or /usr if that is not set. The value of MAMBA_JAVA_HOME should be such that MAMBA_JAVA_HOME plus /bin/java equals the full path to your installed JRE. The table below provides a short summary of the environment variables and their purpose.

MAMBA_HOME	Points to the directory that contains the Mamba application server.
MAMBA_JAVA_HOME	Points the the directory that your JRE is installed in, thish should contain the path that can be used to prefix `/bin/java` to create the full path the the JVM. For example if MAMBA_JAVA_HOME was `/JRE` the full path to the JVM would be `/JRE/bin/java`.
MAMBA_LIB	Points to the directory that contains the Mamba JAR files, typically this will not need to be set unless it is in a location other that the `lib` directory illustrated in the above diagram.

Windows

Starting Mamba on a Windows platform such as Windows XP or Windows 2000 is a simple matter of executing a command using the command console. The commands shown below can be used to start Mamba and can also be used to create a .CMD or .BAT file to avoid having to retype the command. For clarity assume that the Mamba archive mamba-1.1.tar.gz has been downloaded and unzipped in the directory c:\INSTALL_DIR.

c:\> cd c:\INSTALL_DIR\mamba-1.1

c:\INSTALL_DIR\mamba-1.1\> set CLASSPATH=lib\simple-2.4.jar

c:\INSTALL_DIR\mamba-1.1\> set CLASSPATH=%CLASSPATH%;lib\velocity-1.3.1.jar

c:\INSTALL_DIR\mamba-1.1\> set CLASSPATH=%CLASSPATH%;lib\beanshell-2.0.jar

c:\INSTALL_DIR\mamba-1.1\> set CLASSPATH=%CLASSPATH%;lib\mamba-1.1.jar

c:\INSTALL_DIR\mamba-1.1\> java -Dserver.properties=server.properties mamba.serve.Server

Configuration

Before the discussion on configuration proceeds a breif description of the initialization process is provided. The initialization process for Mamba is centered on system properties, that is, properties within the java.lang.System object. This object can have properties set using the -D flag with the JVM, as illustrated above. The properties used by Mamba are obtained from a Java properties file identified by the system property server.properties. This file contains a set of name and value pairs that are used for configuration. Although all of the properties within this file can be specified to the JVM using the -D flag, storing then in a Java properties file is preferred. Once Mamba starts it gathers the properties specified in the Java properties file and pushes them into the java.util.System so that they can be accessed throughout the system by various objects. The following sections describe the various configuration details for Mamba.

Server

Mamba is configured directly using the Java properties file server.properties, which can be specified using the -D flag to the JVM with the property name server.properties. The properties specified in this file will be loaded into the java.lang.System object so that they are globaly accessable to objects within the system. The various properties that can be set in this file that are specific to the server are described below.

server.properties	This specifies where the `server.properties` file is loaded from. If this is not specified then the properties must be set using the command line.
server.port	This specifies the port the server listens to for incomming HTTP requests. This will typically be port `80`, the default for HTTP servers.
server.path.class	This specifies where the service objects are loaded from. This should be seperate from the CLASSPATH used so that the service objects can be reloaded when the byte codes change.
server.path.log	This specifies where the log files are kept for the server. Typically this will house the `access.log`, `error.log`, and `output.log`. The `access.log` will contain details on the client access to the server. The `error.log` and `output.log` files will contain the output from the `System.err` and `System.out` streams respectively.
server.path.context	This specifies where the files that can be accessed by the service implementations are kept. This acts much like the traditional `html` folder usied by servers like Apache. However, not all files will be served from here as the templating system can specify a path that it can use for loading template files. By default the templating system used is for the Velocity templating system which uses a `velocity.properties` file to specify where the template files are loaded from. This should be the same as the `server.path.context` property for simplicity.
server.ssl.port	This specifies the SSL port to listen to for HTTPS connections. This will enable content to be encrypted and secured from interception. This is optional and can be left unspecified if no HTTPS connections are required.
server.ssl.keystore	This specifies a JKS keystore that is used to store SSL certificates that will be used to exchange keys for use in HTTPS communication. The keystore will typically be created using the keytool application that is packaged with the Sun JDK.
simple.ssl.keystorePassword	To access the JKS keystore and acquire a key a keystore password needs to be specified.
simple.ssl.keyPassword	To access the key within the JKS keystore a key password needs to be specified.

Mapping Scheme

Mapping is the act of mapping a URL to a Service object. Those farmiliar with Java Servlets will know that mapping involves providing a URL string that is matched with incomming HTTP requests so that a suitable Servlet can be selected to process the request. The concept of mapping in Mamba is exactly the same. The configuration of the mapping scheme used is determined by a Java properties file named mapper.properties which is stored in the root directory of your installation, as can be seen in the diagram above.

The mapper.properties file contains the mapping used to resolve a request URL to a service implementation. There are various mapping schemes that can be used by the server each implemented as a unique Mapper object. Below is a list of the current Mapper implementations provided.

The simple.http.load.DefaultMapper object
The simple.http.load.PrefixMapper object
The simple.http.load.PatternMapper object

A specific scheme can be specified to the server by using the simple.http.load.mapper property, which can be specified to the JVM using the -D or using the server.properties file. Each of the mappers has various advantages, and each applies a unique mapping technique.

Default Mapper

The DefaultMapper is used to provide URI mapping for Java class names using a specific URI path structure. This uses only the path part of the URI to identify the class name. The structure used is formed using an initial, optional, class name followed by a path part. Examples are shown below.

    http://hostname/demo/DemoService.class/index.html
    http://hostname/demo/DemoService.class
    http://hostname/index.html

All of the above path structures are valid. The first shows a reference to the class demo.DemoService with the path part /index.html. The class is identified by the ".class" extension, which terminates the name of the class name. If there is no ".class" this means the URI has no reference to a class. This does not require the mapper.properties file and can adapt to changes in implemented services.

Prefix Mapper

The PrefixMapper provides a mapper that is used to perform mapping using prefix paths. This provides a scheme like the Servlet context mapping scheme. This Mapper allows arbitrary path configurations to be mapped directly to a service class, which can be autoloaded to serve content.

This can break the URI path into three components, the prefix, the class name, and the relative path. The prefix is the path part that is used to acquire the service name. A prefix is a URI directory path, such as /path/, which is unique. The relative path is the remaining path, after the prefix is removed. So a path of /path/bin/README has the relative path of /bin/README.

Pattern Mapper

The PatternMapper provides a mapper that is used to perform mapping using patterns. This provides a scheme like the Servlet wild card mapping scheme. This scheme allows arbitrary path configurations to be mapped directly to a service class, which can be autoloaded to serve content.

This uses the wild card characters * and ? to specify patterns for matching URI paths with service class names. For example take the pattern *.html, this will match any URI path that ends with .html, such as /index.html or /example.html. Unlike most Servlet engines this allows a ? mark character which specifies a single character. For example, index.??? can be used to match /index.htm or /index.jsp.

    *index.??_??.html = example.LocaleService
    /*secure*.* = example.SecureService

Taking the above example mappings as the Java properties file loaded, matches for URI paths such as /index.en_US.html and /index.fr_CA.html will match the LocaleService. Any number of wild card characters can be specified and the order they appear in the Java properties is signifigant. The first pattern has the lowest priority and the last has the highest. For example taking the above specification, a URI path such as /secure/index.en_US.html will match to the SecureService as it appears last within the Java properties file mapper.properties.

Velocity

Velocity is configured directly using the Java properties file velocity.properties, which contains various properties that can specified. Properties in this file influence how templates are loaded and processed as well as where the log files for Velocity are kept. Typically there are only two properties that need to be set within this file, they are described below.

runtime.log	This specifies where the log file for the Velocity runtime is kept. This should typically refer to a file within the `server.path.log` path so that all log files exist within the same place.
file.resource.loader.path	This specifies where the templates are loaded from by the Velocity runtime. This should be the same directory as the `server.path.context` so that all resources are within the same directory.