Introduction to ThinWire

Running a ThinWire Application

Okay, now that you have the framework downloaded (you have downloaded already, right?), let's walk through the process of creating and running a ThinWire application. The old standby in first programming examples is the Hello World program. It never fully conveys the features of a given platform, but it does provide an adequate example of how to configure a ThinWire application. First, let's consider the Java Swing Hello World program (see Listing 1).

public class Hello {
    public static void main(String[] args) {
      JOptionPane.showMessageDialog(new Frame(), "Hello World!");
   }
}

This is not a handbook on desktop Java, so we won't dwell on this code very long, but let's take a look at its structure. First of all, it is a class definition that has one static method. This is the main method. If you were to compile this file and run it from the command line, the JVM would look for a public static main method and execute it, passing in any command-line arguments as a String array. Inside the main method is one line. It causes a standard message dialog box to appear with this message: "Hello World!" Now let's take a look at the ThinWire Hello World program (see Listing 2).

import thinwire.ui.*;
public class Hello {
   public static void main(String[] args) {
      MessageBox.confirm("Hello World!");
   }
}

Notice anything similar? Again we have a class definition with one method: a main method. This main method accepts a String array as its sole parameter. Inside the method is one line of code. Any guesses as to what this does?

If you've ever done any Java Web programming before, your head must be spinning right now. Your brain is queuing up questions like "I know the JVM calls the main method in the Swing example, but what calls it for ThinWire?" Excellent question, move to the front of the class.

The ThinWire Entry Point

So, as much as we try to hide the fact that we're doing Web programming, we can't completely live in denial. At this point, it's assumed that you have downloaded Apache Tomcat 5.5. (What, you haven't downloaded it yet? You better get on over to http://tomcat.apache.org and start that download.) Obviously, you can use ThinWire with any Web server that implements the Java Servlet Specification (version 2.3), but to keep it simple, let's all use the same thing.

Okay, so you have Tomcat downloaded and extracted. Go to the webapps subdirectory and create a new directory named hello. Inside of that new directory, create another directory named WEB-INF. Inside that directory, create a directory named lib. If you haven't done so already, download the latest binary snapshot build. Extract the contents into the WEB-INF/lib directory. Back in the WEB-INF directory, create another directory named classes. Inside that directory, create a file named Hello.java and paste the preceding code into that file. So, at this point, you should have a directory structure that looks like this:

$TOMCAT_HOME
|-webapps
  |-hello
    |-WEB-INF
    | |-lib
    | |-thinwire.jar
    | |-commons-fileupload-1.0.jar
    |-classes
      |-Hello.java

Now, on the command line in the WEB-INF/classes directory, enter the following:

javac -cp ..\lib\thinwire.jar Hello.java

This should create a new file: Hello.class

Back in the WEB-INF directory, create a new file named web.xml. In servlet speak, this is the deployment descriptor. Basically, it tells the server about the application. Listing 3 shows what goes in that file.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
   PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
   "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
   <display-name>ThinWire</display-name
   <servlet>
      <servlet-name>thinwire</servlet-name>
      <description>ThinWire Servlet Engine</description>
      <servlet-class>thinwire.render.web.WebServlet</servlet-class>
      <init-param>
         <param-name>mainClass</param-name>
         <param-value>Hello</param-value>
      </init-param>
      <init-param>
         <param-name>extraArguments</param-name>
         <param-value>initParam,clientInfo,header</param-value>
      </init-param>
</servlet>
    <servlet-mapping>
       <servlet-name>thinwire</servlet-name>
       <url-pattern>/</url-pattern>
    </servlet-mapping>
    <session-config>
       <session-timeout>30</session-timeout> <!-- 30 minutes -->
    </session-config>
</web-app>

Most of the content is standard configuration information. With this file, we're telling the server that we have a servlet defined in thinwire.render.web.WebServlet, and that all HTTP requests sent to this path should be sent to that servlet. Now that the servlet is part of the ThinWire framework, all you have to do is define it here in the web.xml.

What is really important here are the init-params. The first init-param is named mainClass, and its value is defined as Hello. That's the name of the class we defined earlier. The mainClass init-param tells the ThinWire servlet where to find the main method to start executing the application. The other init-param is named extraArguments and has a list of values: initParam, clientInfo, header. The extraArguments init-param defines the arguments that get passed into the main method in the String array. In this case, we have three types of arguments that will be passed. First, all remaining init-params will be passed as a String in the form "INIT_PARAM_name=value". Second, the following information about the client will be included in the array:

• CLIENT_INFO_USER=value
• CLIENT_INFO_HOST=value
• CLIENT_INFO_ADDRESS=value

Finally, all the HTTP request headers will be included in the array in the form "HEADER_name=value". Okay, we're ready to run this application. In the $TOMCAT_HOME/bin directory, execute the startup script (startup.bat on Windows, startup.sh everywhere else). Open a Web browser and enter http:// localhost:8080/hello into the address bar. In seconds, you should be presented with a standard MessageBox with a greeting to the whole world.