Package org.apache.catalina.servlets

## Class CGIServlet.CGIRunner

- java.lang.Object
- - org.apache.catalina.servlets.CGIServlet.CGIRunner

- Enclosing class:
    CGIServlet

      protected class CGIServlet.CGIRunner
      extends Object

  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.

  The CGI environment and settings are derived from the information passed to the constructor.

  The input and output streams can be set by the `setInput` and `setResponse` methods, respectively.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `CGIRunner​(String command, Map<String,​String> env, File wd, ArrayList<String> params)` | Creates a CGIRunner and initializes its environment, working directory, and query parameters.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected boolean` | `isReady()` | Gets ready status
    `protected String[]` | `mapToStringArray​(Map<String,​?> map)` | Converts a Map to a String array by converting each key/value pair in the Map to a String in the form "key=value" (key + "=" + map.get(key).toString())
    `protected void` | `run()` | Executes a CGI script with the desired environment, current working directory, and input/output streams
    `protected void` | `setInput​(InputStream stdin)` | Sets standard input to be passed on to the invoked cgi script
    `protected void` | `setResponse​(HttpServletResponse response)` | Sets HttpServletResponse object used to set headers and send output to
    `protected void` | `updateReadyStatus()` | Checks and sets ready status

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CGIRunner

          protected CGIRunner​(String command,
                              Map<String,​String> env,
                              File wd,
                              ArrayList<String> params)

      Creates a CGIRunner and initializes its environment, working directory, and query parameters.
      Input/output streams (optional) are set using the `setInput` and `setResponse` methods, respectively.
      Parameters:
        `command` - string full path to command to be executed
        `env` - Map with the desired script environment
        `wd` - File with the script's desired working directory
        `params` - ArrayList with the script's query command line parameters as strings

  - ### Method Detail

    - #### updateReadyStatus

          protected void updateReadyStatus()

      Checks and sets ready status

    - #### isReady

          protected boolean isReady()

      Gets ready status
      Returns:
        false if not ready (`run` will throw an exception), true if ready

    - #### setResponse

          protected void setResponse​(HttpServletResponse response)

      Sets HttpServletResponse object used to set headers and send output to
      Parameters:
        `response` - HttpServletResponse to be used

    - #### setInput

          protected void setInput​(InputStream stdin)

      Sets standard input to be passed on to the invoked cgi script
      Parameters:
        `stdin` - InputStream to be used

    - #### mapToStringArray

          protected String[] mapToStringArray​(Map<String,​?> map)
                                       throws NullPointerException

      Converts a Map to a String array by converting each key/value pair in the Map to a String in the form "key=value" (key + "=" + map.get(key).toString())
      Parameters:
        `map` - Map to convert
      Returns:
        converted string array
      Throws:
        `NullPointerException` - if a hash key has a null value

    - #### run

          protected void run()
                      throws IOException

      Executes a CGI script with the desired environment, current working directory, and input/output streams

      This implements the following CGI specification recommendations:

      - Servers SHOULD provide the "`query`" component of the script-URI as command-line arguments to scripts if it does not contain any unencoded "=" characters and the command-line arguments can be generated in an unambiguous manner.
      - Servers SHOULD set the AUTH_TYPE metavariable to the value of the "`auth-scheme`" token of the "`Authorization`" if it was supplied as part of the request header. See `getCGIEnvironment` method.
      - Where applicable, servers SHOULD set the current working directory to the directory in which the script is located before invoking it.
      - Server implementations SHOULD define their behavior for the following cases:
        - Allowed characters in pathInfo: This implementation does not allow ASCII NUL nor any character which cannot be URL-encoded according to internet standards;
        - Allowed characters in path segments: This implementation does not allow non-terminal NULL segments in the the path -- IOExceptions may be thrown;
        - "`.`" and "`..`" path segments: This implementation does not allow "`.`" and "`..`" in the the path, and such characters will result in an IOException being thrown (this should never happen since Tomcat normalises the requestURI before determining the contextPath, servletPath and pathInfo);
        - Implementation limitations: This implementation does not impose any limitations except as documented above. This implementation may be limited by the servlet container used to house this implementation. In particular, all the primary CGI variable values are derived either directly or indirectly from the container's implementation of the Servlet API methods.
      Throws:
        `IOException` - if problems during reading/writing occur
      See Also:
        `Runtime.exec(String command, String[] envp, File dir)`