Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## php.java.servlet
Class CGIServlet

    java.lang.Object
      javax.servlet.GenericServlet
          javax.servlet.http.HttpServlet
              php.java.servlet.CGIServlet

All Implemented Interfaces:
  java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

Direct Known Subclasses:
  FastCGIServlet

    public 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.

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 Jakarta Tomcat group [tomcat-dev@jakarta.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.

Since:
  Tomcat 4, PHP/JavaBridge 2.0.8
Author:
  Martin T Dengler (original author), Amy Roh (for Tomcat), Jost Boekemeier (for the PHP/JavaBridge)
See Also:
  Serialized Form

Field Summary
`static int` | `BUF_SIZE`
`java.lang.String` | `cgiPathPrefix` The CGI search path will start at webAppRootDir + File.separator + cgiPathPrefix (or webAppRootDir alone if cgiPathPrefix is null)
`javax.servlet.ServletContext` | `context` the Context container associated with our web context.
`java.util.HashMap` | `processEnvironment`

Constructor Summary
`CGIServlet()`

Method Summary
`static int` | `getLocalPort(javax.servlet.ServletRequest req)` Only for internal use.
`static java.lang.String` | `getRealPath(javax.servlet.ServletContext context2, java.lang.String pathInfoCGI)` Identical to context2.getRealPath(pathInfoCGI).
`void` | `init(javax.servlet.ServletConfig config)` Sets instance variables.

Methods inherited from class javax.servlet.http.HttpServlet
`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
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### BUF_SIZE

    public static final int BUF_SIZE

See Also:
  Constant Field Values

### context

    public javax.servlet.ServletContext context

  the Context container associated with our web context.

### cgiPathPrefix

    public java.lang.String cgiPathPrefix

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

### processEnvironment

    public java.util.HashMap processEnvironment

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

  Specified by:
    `init` in interface `javax.servlet.Servlet`
  Overrides:
    `init` in class `javax.servlet.GenericServlet`
  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
  See Also:
    `UnavailableException`

### getLocalPort

    public static int getLocalPort(javax.servlet.ServletRequest req)

  Only for internal use. Returns the port# of the local port

  Parameters:
    `req` - The servlet request
  Returns:
    The local port or the value from the server port variable.

### getRealPath

    public static java.lang.String getRealPath(javax.servlet.ServletContext context2,
                                               java.lang.String pathInfoCGI)

  Identical to context2.getRealPath(pathInfoCGI). On BEA WebLogic, which has a broken getRealPath() implementation, we use context2.getResource(pathInfoCGI)) instead.

  Parameters:
    `context2` - The servlet context.
    `pathInfoCGI` - may be "" or "/" for example.
  Returns:
    a valid path or null
  Throws:
    `java.net.MalformedURLException`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD