Getting Started with Eclipse and Tomcat

This is a short tutorial¹ on how to get you started with Servlet development with Eclipse IDE to develop XML-RPC services that can be a counterpart for your XWT application. It will guide you through installing the necessary tools and building your first XMLRPC Servlet. There is a separate tutorial available here that focuses on developing the client-side XWT application.

Installing the development environment

The first step is to install the development environment. In this example our development environment is based on Eclipse IDE and we use Tomcat servlet container. These tools integrate well and are freely available from their vendors.

1. Install JDK 1.4
2. Install Apache Tomcat 4
3. Install Eclipse IDE
4. Install the Tomcat plugin for Eclipse (read the included readme.html!)
   
5. Download the Apache XML-RPC library
6. Start Eclipse
7. Under Window / Preferences / Tomcat, check Tomcat Version 4.1.x and browse to teh Tomcat installation directory; under Tomcat / JVM Settings select the JDK 1.4 or detected jvm in the JRE - dropdown.
8. If you are proficient with Tomcat, we recommend that you clean up all the extra stuff from TOMCAT_HOME/conf/server.xml as this will greatly decrease the startup time.

Creating a new Web-application project

To create a new web application, we must first set up a new project in Eclipse.

1. Start by creating a new Java Tomcat project from Eclipse: open File / New / Project and select Java / Tomcat project
2. Name the project, check "can update server.xml" and click Finish.
3. Right click the newly created project, select Properties / Tomcat, set the Context name to /xmlrpc
4. Copy xmlrpc-1.2-b1.jar (from the xmlrpc-1.2-b1.zip archive) and place it under Eclipse/workspace/<your project name>/WEB-INF/lib
5. In Eclipse, right click your project and choose Properties, under Java Build Path, on the Libraries-tab, and add the above mentioned file as an external JAR. In the adjoining Order and Export tab, check  xmlrpc-1.2-b1.jar.
6. In the Eclipse resource view, browse to the WEB-INF/lib directory, right click and select Refresh

Writing the application

Now you are ready to write your first XmlRPC Servlet. Here we use a fortune server that will serve us useless witticisms.

1. Right click the new project and select New->Other->Class, name the class "XwtXmlRpcServlet" and set it's superclass to HttpServlet.
2. Insert the following code in XwtXmlRpcServlet.java:
   

   import javax.servlet.*;
   import javax.servlet.http.*;
   import java.io.*;
   import org.apache.xmlrpc.XmlRpcServer;
   
   public class XwtXmlRpcServlet extends HttpServlet {
      public static XmlRpcServer xmlrpc = new XmlRpcServer();
   
      public void init (ServletConfig config) throws ServletException
      {
         xmlrpc = new XmlRpcServer();
         xmlrpc.addHandler("fortune", new Fortune());
      }
   
      public void doPost(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException
      {
         byte[] result = xmlrpc.execute(req.getInputStream(), null, null);
         res.setContentType("text/xml");
         res.setContentLength(result.length);
         OutputStream output = res.getOutputStream();
         output.write(result);
         output.flush();
      }
   }
   

3. Right click the project and select New->Other->Class, name the class "Fortune" and set it's superclass to Object.
   
4. Insert the following code in Fortune.java:
   

   public class Fortune {
      public String get(int index)
      {
         return fortunes[index];
      }
   
      public String get()
      {
         return fortunes[random.nextInt() % fortunes.length];
      }
   
      private String[] fortunes =
      {
         "This is an ignore, please test...",
         "An unbreakable toy is useful for breaking other toys",
         "What is another word for Thesaurus?",
         "Rule 1: Don't tell people everything you know. Rule 2: ***  intentionally left blank  ***",
         "Don't test for errors you can't handle.",
         "Experience is something you don't get until just after you need it.",
         "I think the best sign of intelligent life in the Universe is that no-one has tried to contact us.",
         "Old MacDonald had an agricultural real estate tax abatement.",
         "It is not possible to both understand and appreciate Intel CPUs.",
         "The generation of random numbers is too important to be left to chance.",
         "Don't you just hate rhetorical questions?"
      };
   
      private java.util.Random random = new java.util.Random();
   }
   

5. Save your new class files.
6. Choose from the Eclipse -menu Window->Preferences and there Tomcat and check our tutorial project to be added to the tomcat classpath.

Deploying the application

The servlet container requires some configuration before you can access the application. The configuration is stored in the web.xml file which is stored in web application's WEB-INF directory.

Here is the configuration file for the example application created above. Right click the WEB-INF icon in your project and select New->File, call the file web.xml and copy & paste the following xml into it:
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>

<servlet>
<servlet-name>xmlrpc</servlet-name>
<servlet-class>XwtXmlRpcServlet</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>xmlrpc</servlet-name>
<url-pattern>/fortune</url-pattern>
</servlet-mapping>

</web-app>



Running the example

To run the example application the servlet container must be running. This is straightforward, if you have the Tomcat-plugin installed in Eclipse. After the servlet container is up and running you can access the application using the specified URL.

1. Run tomcat by clicking the Start Tomcat -icon in the Eclipse toolbar.
2. Point your web browser to http://localhost:8080/xmlrpc/fortune

<xwt>



   <static>

      xwt.theme("xwt.standard", "org.xwt.themes.monopoly");

   </static>



   <import name="xwt.standard.*"/>

   <import name="xwt.standard.widgets.*"/>



   <template height="180" width="400" thisbox="frame" orient="vertical">

      svc = xwt.origin.replace("fortune.xwar", "fortune/fortune");



      refresh = function() {

         try {

            $fortune.text = xwt.xmlrpc(svc).fortune.get();

         } catch(e) {

            $fortune.text = e.faultString;

         }

      }



      xwt.thread = refresh; 



      $refresh._click = function(c) { xwt.thread = refresh; }



      <box id="fortune"/>

      <button id="refresh" text="Refresh"/>

   </template>

</xwt>