According to the programmers' guide provided with EAS (5.x), a Web application is a unit of deployment for interrelated Web content, JavaServer Pages (JSPs), and Java servlets. Generally, a Web application developer under EAS must create JSP files and/or Java servlets. Sometimes, however, it would be better to use some other techniques to save development time. It is possible that there is already a similar open source Web page, or there might be a demand to run a complete Web application not written in Java/JSP code under EAS.

The majority of these open source pages/applications are made of CGI scripts. CGI is not an abbreviation of another programming language; it is a standard interface between Web server software and other "programs" running on the same machine. The communication is mutual, the output of the "program" is pure HTML code, and the Web server directs it into the browser, but the values of the edit fields of a form can also be returned to the "program" to be processed. A CGI script can use a variety of languages, for instance Perl, which is one of the most popular ones. Usually Web servers in the market support running CGI scripts via embedded handlers easily, but unfortunately EAS does not have this feature.

Solution
At my firm there was an urgent need to implement a bug-tracking application. Finally, Bugzilla was chosen (written completely in Perl) because it's a famous one; it's an open source program with great support and, apart from the missing dateline usage, it seemed to be suitable for bug tracking of their projects. I started to find some solution to install and run it under EAS, because installing a rival Web server just for the sake of Bugzilla is unattractive. Somehow the handler, which is responsible for communication between the program and the Web server, must be emulated. A Java servlet seemed to be perfect for this aim. A servlet, in short, is a Java program that processes the client request; it dynamically creates some content as a response that is finally sent back to the client.

In our example we are talking about an HTTP servlet. The request from the client comes in the form of Perl script and the generated content is HTML code displayed in the client's browser. Apart from writing a new servlet, there is another issue: how that servlet is started. It depends on the URL initiated by the client. If the URL contains a filename with a cgi extension, our servlet must be launched. Our efforts to find out how it can be done globally in EAS failed, but it is easily possible under a Web application. The servlet must be attached to a Web application, a new mapping between the URL and the servlet must be created based on the cgi extension and it is ready. The one disadvantage of this method is that the servlet is launched just under the Web application and not globally from any URL.

Implementation
Before involving the development of the servlet, let's see how the aforementioned steps look in EAS. All steps must be executed in Jaguar Manager with a connected Jaguar server.

• A new Web application must be created, so starting with a Web application node in the left panel, use the new Web application menu item (or use the pop-up menu with a right-click). Enter Bugzilla for its name.
• Among the properties of the new Web application, two things must be set:
  - File Refs: Add index.cgi file as a welcome file. This will be the start page of Bugzilla.
  - Servlet/JSP Mapping: Add the cgi, *.cgi pair into the list. This property ensures that the servlet is launched for each request for a cgi file (see Figure 1).

So far it's easy. Now let's see the servlet. At the time this article was written, the latest stable Bugzilla version was 2.22. It includes more useful features; the greatest one is the native UTF-8 support (at least for a Hungarian author). Therefore one important requirement is to handle the UTF-8 character set in the servlet. Another demand is that the servlet could be easily expanded to process other CGI scripts in addition to Perl ones. It must be noted that the servlet is to be compiled under JDK v1.4. Due to the length of the complete Java code, some not so important parts were removed. The original source can be downloaded from the URLs provided in the Resources section.

public class CgiProviderServlet extends HttpServlet {
    //Process the HTTP Post request
    public void doPost( HttpServletRequest request, HttpServletResponse response )
       throws ServletException, IOException {
       doGet(request, response);
}

    //Process the HTTP Get request
    public void doGet( HttpServletRequest request, HttpServletResponse response )
       throws ServletException, IOException {

The name of our servlet is CgiProviderServlet inherited from HttpServlet. There are two important methods of the class: doPost and doGet.The former simply calls the latter. If the type of the request must be known, request.getMethod() returns with POST or GET. From this information the originally called method can be determined.

     final boolean utf_8 = true; // set false if no utf-8 support is needed

     if (utf_8) request.setCharacterEncoding("UTF-8");
     HttpSession session = request.getSession(false);

     ServletContext sc = this.getServletConfig().getServletContext();
     String shortFilename = request.getServletPath().substring(request.getServletPath().startsWith("/") ||
request.getServletPath().startsWith("\\") ? 1 : 0);
     String fullPath = sc.getRealPath(request.getServletPath());
     String perl_params = "";

If UTF-8 usage is unnecessary, it can be switched off by setting utf_8 to false. From the URL both the CGI filename and the path are retrieved.

     //Get list of HTTP Arguments
     Enumeration requestArgumentNames = request.getParameterNames();
     String selfLinkArguments = "";
     StringBuffer tempselfLinkArguments = new StringBuffer("");

     while( requestArgumentNames.hasMoreElements() ){
       String argName = (String)requestArgumentNames.nextElement();
       String[] argValue = request.getParameterValues( argName );

       for (int i=0; i<argValue.length; i++){
       tempselfLinkArguments.append((tempselfLinkArguments.length()>0?"&":"")+argName+"="+argValue[i]);
}

     }
     selfLinkArguments = tempselfLinkArguments.toString();

Parameter names and their values from the HTTP request are collected into a string named selfLinkArguments separated by an & character.

     //Get cookies from HTTP request
     Cookie[] cookies = {};
     String cookies_str = "";
     if (request.getCookies()!=null) cookies = request.getCookies();
     for (int i=0; i<cookies.length; i++){
       if (i>0) cookies_str += "; ";
       cookies_str += (cookies[i].getName() + "=" + cookies[i].getValue());
     }

Cookies store data on the client (e.g., last logged-in user and her password). If there are some cookies in the HTTP request, another string is concatenated from the found cookie names and their values (see Listing 1).

So that Perl and the Web server could communicate via CGI, some environment variables must be passed to the Perl compiler. Some of them come from the operation system environment variables, the others spring from the HTTP request. For example, in the case of the GET request method, the earlier assembled request parameter list must be placed into QUERY_STRING.

   //Let see the CGI script
   try {
     //Get the cgi template, in case of perl script, first line must be looked like this:
     #!/usr/local/bin/perl
     FileInputStream fis = new FileInputStream( new File( fullPath ) );
     InputStreamReader isr = utf_8 ? new InputStreamReader
     (fis, "UTF-8") : new InputStreamReader( fis );
     BufferedReader in = new BufferedReader( isr );
     line = in.readLine();
     in.close();
     isr.close();
     fis.close();
     if( line == null || !line.startsWith( "#!" ) || line.indexOf( "perl " ) == -1 ) {
return; // it is not a perl script
     } else {
perl_params = line.substring(line.indexOf("perl ")+"perl ".length());
     }