Xervlet Tutorial/Example

Xervlet Tutorial

What is a Xervlet...and why am I on the tutorial page already?
The first question is easy...see below. The second, visit the Xervlet API homepage on SourceForge

A 'Xervlet' is a Servlet on Steroids that makes developing web-based applications very easy to do. This API was started over 2 years ago and uses what is now called an MVC [Model View Controller] When I started this project, there wasn't a cool name like that, and Java Servlets were young. As the times changed, the API had to change. I'm hoping that this API can help others get their feet wet in the web-based java world without pulling out their hair or just giving up. and may God forbid...moving to .NET. In laymen's terms they simple separate the data from the display.

The Xervlet API simples extends the Servlet API that SUN provides and gives the user a very powerful tool for creating web based applications with a minimal amount of development.

Downloads

About Xervlets

Compile the API

Obfuscator Config

Example Xervlet Config

Here is a brief tutorial to just get you started.

Downloads

Download the Latest Version of the Xervlet API [ Xervlet 7.1.5 ] [ xervlet.src.tar.gz ]
Download this tutorial [ gz ]

Tell me something about how this works

There are 3 parts to a Xervlet
A) Model (Xervlet API)
B) Controller (Your Servlet that extends Xervlet)
C) View (Html Files)

The Model consist of the Xervlet API. (That much is already done for you)
The Controller is what the Model/Xervlet Engine calls when it receives a command.
Then passes off all the work to the it, which in turns reads the data and passes it on to
the HtmlParser (View) which controls how it looks on the screen.

Before we can do anything, we need to create/edit a couple of control files.
These files tells the Xervlet Engine what to do based on the command passed to it

A long time ago there was only one config file, but due to the ever tightening need to
provide more and more security I finally had to move to a pure obfuscated (I dare say
lightly encrypted) configuration file.
So the two files we need are:
xervlet.obf.xml: This file tells the obfuscator what file to read and were to put
the output. Please allow me to make a very important not. Due to the high level of
security I am required to work in (at my real job, the one that pays the bills) once the
file is encrypted the ASCII version WILL BE DELETED.

Compiling the Xervlet API

Obfuscator Config

xervlet.obf.xml: Obfuscator Config File Download

<PROPERTIES>
        <CONFIG>
                <INPUTFILE>/usr/local/beans/xervlet.tutorial/web/xervlet.xml</INPUTFILE>
                <OUTPUTFILE>/usr/local/beans/xervlet.tutorial/web/xervlet.conf.obf</OUTPUTFILE>
                <HASHMAP>$XERVLET_EXAMPLE$</HASHMAP>
        </CONFIG>
</PROPERTIES>

<INPUTFILE> The file we are about to obfuscate

<OUTPUTFILE> The file we are going to create, this will be the obfuscated config file

<HASHMAP> The hash map which is our obfuscation key. (your public/private key..I told you I dare not say encrypted)

This config file is used by the Xervlet API to map commands into Servlet calls. It's in a simple XML format, is very flexible and requires that only a single parent/child entry be made. This is then used by the Xervlet API and is therefore required.

Example Xervlet Config

xervlet.xml: Xervlet MVC config map Download

<xervlet>
<!-- Xervlet Example Config File -->
	<execute>
		<XERTEST>xervlet.XervletDateTime</XERTEST>
	</execute>

<!-- HTML Control -->
	<htmlfiles>
		<EXAMPLE>/usr/local/beans/xervlet.tutorial/web/example.htm</EXAMPLE>
	</htmlfiles>
		
<!-- message: parent and root tags -->
	<message>
		<SAYHELLO>Hello World</SAYHELLO>
		<SAYGOODBYE>Goodbye cruel world</SAYGOODBYE>
	</message>

</xervlet>

<xervlet> Config Root [REQUIRED]

<execute> Config Root Execute Tag [REQUIRED]

Our Controller Xervlet

On to the Control Servlet. This is, I admit, the most difficult part of the puzzle. If this gets messed up, nothing works.
Lets create the controller XervletExample.java Download

NOTE: Please take not that this file is not packaged. It can be placed in one of two places. It may (although this is the easiest, it's not the most sane) reside in your servlet home directory. Otherwise it will be placed in our classes folder of WEB-INF in the war (for this example that is where it will go)

import gsoft.xervlet.*;

public class XervletExample extends BaseObfuscatedXervlet{
    public String getIniFileName(){return "/usr/local/beans/xervlet.tutorial/web/xervlet.conf.obf";}
    public String getHashMap(){return "$XERVLET_EXAMPLE$";}
}

getIniFileName: This will need to point to your config file. It should match the OUTPUTFILE tag in your Obfuscator config file. It doesn't have to, however, make sure that this location is correct.

getHashMap: This MUST match the HASHMAP entry in your Obfuscator config file. This is how the Obfuscated file gets converted back into something readable.

As far as the hard stuff...that's it. The Xervlet Engine will now handle all of the "work" for you...
but lets get on to the cool stuff. and finish building this app.

The last development step is to write the Xervlet that we will be calling. (personally I dislike examples that try to show you everything an API can do....so to keep myself happy this one will be very, very short :)

Our first Xervlet

xervlet.XervletDateTime is one of many classes that can now easily be created. All of the web-interface items have already been instantiated and are now available. One simply way of looking at this is like a java-only version of a jsp page. Download

package xervlet;

import gsoft.xervlet.*;

public class XervletDateTime extends Xervlet{
    public void execute() {
        try {
            display("<center><b>XervletDateTime Working Fine</b></center>");
            showError("This is what it looks like if you call showError(String s)");

            HtmlParser hp = new HtmlParser(tReader.getTagValue("htmlfiles","EXAMPLE"));
            hp.addElement("DATE",new java.util.Date().toString());
            hp.addElement("HELLO",tReader.getTagValue("message","SAYHELLO"));
            hp.addElement("GOODBYE",tReader.getTagValue("message","SAYGOODBYE"));
            display(hp.alterPage());

            }catch(Exception e) {
                showError("Error initializing xervlet.XervletDateTime: " + e);
                e.printStackTrace();
            }//end try-catch
    }//end execute
}

First thing we want to do here is extend Xervlet. This is where we hand over all the nastiness of web-development to the API and free up our time to get down to business.

execute( ) is an abstract method defined in Xervlet. So we'll have to make sure we add that in there. The rest of this is just examples. You could compile it like that...but nothing would happen :)

HtmlParser parser....this is the "View" of the MVC model. This web page could have been written by another team member, departement...whatever. Personally, as this page shows, I'm very poor at HTML and making it look good.

HtmlParser Input File [ example.htm ]

This is the externally controlled HTML file: Download

<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Xervlet Example</title>
</head>

<body>

<table border="1" width="100%">
  <tr>
    <td width="100%">This is the Xervlet API Example</td>
  </tr>
  <tr>
    <td width="100%">Date/Time: <|DATE/></td>
  </tr>
  <tr>
    <td width="100%">Say Hello: <|HELLO/></td>
  </tr>
  <tr>
    <td width="100%">Say Good bye: <|GOODBYE/></td>
  </tr>
</table>

</body>

</html>

Tag Values: the HtmlParser uses the <| 'yourTagName' /> as a control value. So everything between the <| (that's a pipe by the way) the /> is going to be replaced by whatever is mapped in your config file.
In this example: <|HELLO> will be replaced with 'I'm working....Yeah!'

Controller HTML

Were going to need a an xervlet.example.htm page so we can fire up this app.
Lets do something simple and go with the "One Big Button" theory. Download

<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Xervlet Example Index</title>
</head>

<body>

<form method="POST" action="/xervtest/servlet/XervletExample">
  <p align="center"><input type="submit" value="RUN XERVLET EXAMPLE" name="commXERTEST"></p>
</form>

</body>

</html>

2 Very important Notes:
1: action="<yourServletRoot>/<theNameOfYourServletThatExtendedBaseXervlet>"
2: the button name MUST start with "comm", the must match EXACTLY the name you want to map it to in the config file.
comm stands for command and the name is the mapped reference. By doing this you hide ALL behind the scenes class name. And since all of your xervlets will use an HtmlParser, NONE of the Html files live in the root directory. This alone give you near limitless security by simply removing the files to non-reachable locations.

Example build.xml

Here is my build.xml file. You may wish to edit some of the values. Download

<?xml version="1.0"?>
<project name="xervlet.tutorial" default="war">
  <description>
     Rebuild the Xervlet API
  </description>

  <property name="build.compiler"   value="jikes" />
  <property name="CLASSPATH"        value="/usr/local/beans/lib/xerces.jar;/usr/local/beans/lib/j2ee.jar;/usr/local/beans/lib/xervlet.jar"/>
<!-- ======================================================================  -->
    <property name="CLASS.DIR"      value="/usr/local/beans/xervlet.tutorial/classes"/>
    <property name="MVC.HOME.DIR"   value="/usr/local/beans/xervlet.tutorial/webapp/WEB-INF/classes"/>
    <property name="MVC"            value="XervletExample.java"/>
    <property name="MVC.FILE"       value="/usr/local/beans/xervlet.tutorial/webapp/WEB-INF/classes/XervletExample.java"/>
    <property name="ROOT.SRC"       value="/usr/local/beans/xervlet.tutorial/src"/>
    <property name="JAR.FILE"       value="/usr/local/beans/xervlet.tutorial/webapp/WEB-INF/lib/xervlet.tutorial.jar"/>
    <property name="WAR"            value="/usr/local/orion/applications/xervtest.war"/>
    <property name="WAR.SRC"        value="/usr/local/beans/xervlet.tutorial/webapp"/>
<!-- ======================================================================  -->
    <property name="XERVLET.CONFIG"       value="/usr/local/beans/xervlet.tutorial/config.files/xervlet.xml"/>
    <property name="XERVLET.CONFIG.COPY"  value="/usr/local/beans/xervlet.tutorial/web/xervlet.xml"/>
    <property name="OBFUSCATOR.CONFIG"    value="/usr/local/beans/xervlet.tutorial/config.files/xervlet.obf.xml"/>
    <property name="XERVLET.LIB"          value="/usr/local/beans/xervlet.tutorial/WEB-INF/lib/xervlet.jar"/>
<!-- ======================================================================  -->
    <property name="USER.NAME"       value="Steve Gee"/>
    <property name="USER.EMAIL"      value="stevesgee@cox.net"/>
<!-- ======================================================================  -->

    <target name="clean"  description="remove any old files">
        <delete file="${XERVLET.LIB}" />
        <delete file="${MVC.FILE}" />
        <delete dir="${CLASS.DIR}" />
        <mkdir dir="${CLASS.DIR}" />
    </target>

    <target name="obfuscate" depends="clean" description="Obfuscate the config file">
      <copy file="${XERVLET.CONFIG}" tofile="${XERVLET.CONFIG.COPY}"/>

      <java classname="gsoft.util.FileObfuscator">
              <arg value="-c${OBFUSCATOR.CONFIG}"/>
              <arg value="-e" />
               <classpath>
                     <pathelement location="${XERVLET.LIB}"/>
                     <pathelement path="${CLASSPATH}"/>
               </classpath>
             </java>
    </target>


    <target name="compileMVCXervlet" depends="obfuscate" >
       <javac srcdir="${ROOT.SRC}"
            destdir="${MVC.HOME.DIR}"
            includes="${MVC}"
            classpath="${CLASSPATH}"
         />
     </target>

    <target name="compile" depends="compileMVCXervlet" >
       <delete dir="${CLASS.DIR}"/>
       <mkdir dir="${CLASS.DIR}" />
       <javac srcdir="${ROOT.SRC}"
            destdir="${CLASS.DIR}"
            includes="xervlet/**"
            classpath="${CLASSPATH}"
         />
     </target>

    <target name="jar" depends="compile" >
        <delete file="${JAR.FILE}" />
        <jar jarfile="${JAR.FILE}"
            basedir="${CLASS.DIR}"
            includes="**">
            <manifest>
                <attribute name="Built-By" value="${USER.NAME}"/>
                <attribute name="user-Email" value="${USER.EMAIL}"/>
            </manifest>
        </jar>
    </target>

    <target name="war" depends="jar" >
        <delete file="${WAR}" />
        <jar jarfile="${WAR}"
            basedir="${WAR.SRC}"
            includes="**">
            <manifest>
                <attribute name="Built-By" value="${USER.NAME}"/>
                <attribute name="user-Email" value="${USER.EMAIL}"/>
            </manifest>
        </jar>
    </target>

</project>

Lets wrap it up and test it

Move your index file to orion root/default-web-app/xervlet and go.
I haven't said this, but make sure you have created the directory structure and moved all of the files into their correct locations.

Running the App

Now for each version of Web Server that's out there, there is going to be a different way of doing this. For this example, I'm using Orion http://www.orionserver.com If you would like example for other systems, simply shoot me an email and I'll do what I can. PLEASE do NOT ask for any Microsoft example. I don't do MS.

Once we get everything to compile. Move the xervlet package to your Orion root directory, then to default-web-app/WEB-INF/classes. (for other systems, just put it in your defined Servlet folder)

Were going to need a xervlet.example.htm page so we can fire up this app. Lets do something simple and go with the "One Big Button" theory. Download

<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Xervlet Example Index</title>
</head>

<body>

<form method="POST" action="/servlet/XervletExample">
  <p align="center"><input type="submit" value="RUN XERVLET EXAMPLE" name="commXERTEST"></p>
</form>

</body>

</html>

Configure Orion

Edit default-web-site.xml and add the following:

<web-app application="default" name="XervletExample" root="/xervtest"/>

Edit applicaiont.xml and add the following:

<web-module id="XervletExample" path="../applications/xervtest.war"/>

Run the build.xml file and restart the server. You should see the app deploy when it restarts.

Test the App

Start up Mozilla and point it to: http://localhost/xervlet/xervlet.example.htm
When the page comes up...click that "one big button" and you should be well on your way.

If you can't seem to get it up and running, feel free to email me

I depart with a nice quote from Keenan Maynard, front-man for Tool:

Throughout human history, as our species has faced the frightening,
terrorizing fact that we do not know who we are, or where we are going in
this ocean of chaos, it has been the authorities, the political, the
religious, the educational authorities who attempted to comfort us by
giving us order, rules, regulations, informing, forming in our minds their
view of reality. To think for yourself you must question authority and
learn how to put yourself in a state of vulnerable, open-mindedness;
chaotic, confused, vulnerability to inform yourself.

Think for yourself.
Question authority.