org.apache.catalina.servlets
Class CGIServlet

java.lang.Object
  extended byjavax.servlet.GenericServlet
      extended byjavax.servlet.http.HttpServlet
          extended byorg.apache.catalina.servlets.CGIServlet
All Implemented Interfaces:
java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

public final class CGIServlet
extends javax.servlet.http.HttpServlet

CGI-invoking servlet for web applications, used to execute scripts which comply to the Common Gateway Interface (CGI) specification and are named in the path-info used to invoke this servlet.

Note: This code compiles and even works for simple CGI cases. Exhaustive testing has not been done. Please consider it beta quality. Feedback is appreciated to the author (see below).

Example:
If an instance of this servlet was mapped (using <web-app>/WEB-INF/web.xml) to:

<web-app>/cgi-bin/*

then the following request:

http://localhost:8080/<web-app>/cgi-bin/dir1/script/pathinfo1

would result in the execution of the script

<web-app-root>/WEB-INF/cgi/dir1/script

with the script's PATH_INFO set to /pathinfo1.

Recommendation: House all your CGI scripts under <webapp>/WEB-INF/cgi. This will ensure that you do not accidentally expose your cgi scripts' code to the outside world and that your cgis will be cleanly ensconced underneath the WEB-INF (i.e., non-content) area.

The default CGI location is mentioned above. You have the flexibility to put CGIs wherever you want, however:

The CGI search path will start at webAppRootDir + File.separator + cgiPathPrefix (or webAppRootDir alone if cgiPathPrefix is null).

cgiPathPrefix is defined by setting this servlet's cgiPathPrefix init parameter

CGI Specification:
derived from http://cgi-spec.golux.com. A work-in-progress & expired Internet Draft. Note no actual RFC describing the CGI specification exists. Where the behavior of this servlet differs from the specification cited above, it is either documented here, a bug, or an instance where the specification cited differs from Best Community Practice (BCP). Such instances should be well-documented here. Please email the Tomcat group [dev@tomcat.apache.org] with amendments.

Canonical metavariables:
The CGI specification defines the following canonical metavariables:
[excerpt from CGI specification]

  AUTH_TYPE
  CONTENT_LENGTH
  CONTENT_TYPE
  GATEWAY_INTERFACE
  PATH_INFO
  PATH_TRANSLATED
  QUERY_STRING
  REMOTE_ADDR
  REMOTE_HOST
  REMOTE_IDENT
  REMOTE_USER
  REQUEST_METHOD
  SCRIPT_NAME
  SERVER_NAME
  SERVER_PORT
  SERVER_PROTOCOL
  SERVER_SOFTWARE
 

Metavariables with names beginning with the protocol name (e.g., "HTTP_ACCEPT") are also canonical in their description of request header fields. The number and meaning of these fields may change independently of this specification. (See also section 6.1.5 [of the CGI specification].)

[end excerpt]

Implementation notes

standard input handling: If your script accepts standard input, then the client must start sending input within a certain timeout period, otherwise the servlet will assume no input is coming and carry on running the script. The script's the standard input will be closed and handling of any further input from the client is undefined. Most likely it will be ignored. If this behavior becomes undesirable, then this servlet needs to be enhanced to handle threading of the spawned process' stdin, stdout, and stderr (which should not be too hard).
If you find your cgi scripts are timing out receiving input, you can set the init parameter of your webapps' cgi-handling servlet to be

Metavariable Values: According to the CGI specificion, implementations may choose to represent both null or missing values in an implementation-specific manner, but must define that manner. This implementation chooses to always define all required metavariables, but set the value to "" for all metavariables whose value is either null or undefined. PATH_TRANSLATED is the sole exception to this rule, as per the CGI Specification.

NPH -- Non-parsed-header implementation: This implementation does not support the CGI NPH concept, whereby server ensures that the data supplied to the script are preceisely as supplied by the client and unaltered by the server.

The function of a servlet container (including Tomcat) is specifically designed to parse and possible alter CGI-specific variables, and as such makes NPH functionality difficult to support.

The CGI specification states that compliant servers MAY support NPH output. It does not state servers MUST support NPH output to be unconditionally compliant. Thus, this implementation maintains unconditional compliance with the specification though NPH support is not present.

The CGI specification is located at http://cgi-spec.golux.com.

TODO:

Since:
Tomcat 4.0
Version:
$Id: CGIServlet.java 939529 2010-04-30 00:51:34Z kkolinko $
Author:
Martin T Dengler [root@martindengler.com], Amy Roh
See Also:
Serialized Form

Nested Class Summary
protected  class CGIServlet.CGIEnvironment
          Encapsulates the CGI environment and rules to derive that environment from the servlet container and request information.
protected  class CGIServlet.CGIRunner
          Encapsulates the knowledge of how to run a CGI script, given the script's desired environment and (optionally) input/output streams Exposes a run method used to actually invoke the CGI.
protected  class CGIServlet.HTTPHeaderInputStream
          This is an input stream specifically for reading HTTP headers.
 
Constructor Summary
CGIServlet()
           
 
Method Summary
protected  void doGet(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)
          Provides CGI Gateway service
protected  void doPost(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)
          Provides CGI Gateway service -- delegates to doGet
 void init(javax.servlet.ServletConfig config)
          Sets instance variables.
static void main(java.lang.String[] args)
          For future testing use only; does nothing right now
protected  void printServletEnvironment(javax.servlet.ServletOutputStream out, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)
          Prints out important Servlet API and container information Copied from SnoopAllServlet by Craig R.
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CGIServlet

public CGIServlet()
Method Detail

init

public void init(javax.servlet.ServletConfig config)
          throws javax.servlet.ServletException
Sets instance variables.

Modified from Craig R. McClanahan's InvokerServlet

Parameters:
config - a ServletConfig object containing the servlet's configuration and initialization parameters
Throws:
javax.servlet.ServletException - if an exception has occurred that interferes with the servlet's normal operation

printServletEnvironment

protected void printServletEnvironment(javax.servlet.ServletOutputStream out,
                                       javax.servlet.http.HttpServletRequest req,
                                       javax.servlet.http.HttpServletResponse res)
                                throws java.io.IOException
Prints out important Servlet API and container information

Copied from SnoopAllServlet by Craig R. McClanahan

Parameters:
out - ServletOutputStream as target of the information
req - HttpServletRequest object used as source of information
res - HttpServletResponse object currently not used but could provide future information
Throws:
java.io.IOException - if a write operation exception occurs

doPost

protected void doPost(javax.servlet.http.HttpServletRequest req,
                      javax.servlet.http.HttpServletResponse res)
               throws java.io.IOException,
                      javax.servlet.ServletException
Provides CGI Gateway service -- delegates to doGet

Parameters:
req - HttpServletRequest passed in by servlet container
res - HttpServletResponse passed in by servlet container
Throws:
javax.servlet.ServletException - if a servlet-specific exception occurs
java.io.IOException - if a read/write exception occurs
See Also:
HttpServlet

doGet

protected void doGet(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse res)
              throws javax.servlet.ServletException,
                     java.io.IOException
Provides CGI Gateway service

Parameters:
req - HttpServletRequest passed in by servlet container
res - HttpServletResponse passed in by servlet container
Throws:
javax.servlet.ServletException - if a servlet-specific exception occurs
java.io.IOException - if a read/write exception occurs
See Also:
HttpServlet

main

public static void main(java.lang.String[] args)
For future testing use only; does nothing right now



Copyright © 2000-2012 Apache Software Foundation. All Rights Reserved.