Package org.apache.catalina.servlets

## Class CGIServlet.CGIEnvironment

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

- Enclosing class:
    CGIServlet

      protected class CGIServlet.CGIEnvironment
      extends Object

  Encapsulates the CGI environment and rules to derive that environment from the servlet container and request information.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `CGIEnvironment​(HttpServletRequest req, ServletContext context)` | Creates a CGIEnvironment and derives the necessary environment, query parameters, working directory, cgi command, etc.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected String` | `blanksToString​(String couldBeBlank, String subForBlanks)` | Converts blank strings to another string
    `protected void` | `expandCGIScript()` | Extracts requested resource from web app archive to context work directory to enable CGI script to be executed.
    `protected String[]` | `findCGI​(String pathInfo, String webAppRootDir, String contextPath, String servletPath, String cgiPathPrefix)` | Resolves core information about the cgi script.
    `protected String` | `getCommand()` | Gets derived command string
    `protected Map<String,​String>` | `getEnvironment()` | Gets derived CGI environment
    `protected ArrayList<String>` | `getParameters()` | Gets derived CGI query parameters
    `protected File` | `getWorkingDirectory()` | Gets derived CGI working directory
    `protected boolean` | `isValid()` | Gets validity status
    `protected String` | `nullsToBlanks​(String s)` | Converts null strings to blank strings ("")
    `protected String` | `nullsToString​(String couldBeNull, String subForNulls)` | Converts null strings to another string
    `protected boolean` | `setCGIEnvironment​(HttpServletRequest req)` | Constructs the CGI environment to be supplied to the invoked CGI script; relies heavily on Servlet API methods and findCGI
    `protected void` | `setupFromContext​(ServletContext context)` | Uses the ServletContext to set some CGI variables
    `protected boolean` | `setupFromRequest​(HttpServletRequest req)` | Uses the HttpServletRequest to set most CGI variables
    `String` | `toString()` | Returns important CGI environment information in a multi-line text format.

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

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

- - ### Constructor Detail

    - #### CGIEnvironment

          protected CGIEnvironment​(HttpServletRequest req,
                                   ServletContext context)
                            throws IOException

      Creates a CGIEnvironment and derives the necessary environment, query parameters, working directory, cgi command, etc.
      Parameters:
        `req` - HttpServletRequest for information provided by the Servlet API
        `context` - ServletContext for information provided by the Servlet API
      Throws:
        `IOException` - an IO error occurred

  - ### Method Detail

    - #### setupFromContext

          protected void setupFromContext​(ServletContext context)

      Uses the ServletContext to set some CGI variables
      Parameters:
        `context` - ServletContext for information provided by the Servlet API

    - #### setupFromRequest

          protected boolean setupFromRequest​(HttpServletRequest req)
                                      throws UnsupportedEncodingException

      Uses the HttpServletRequest to set most CGI variables
      Parameters:
        `req` - HttpServletRequest for information provided by the Servlet API
      Returns:
        true if the request was parsed without error, false if there was a problem
      Throws:
        `UnsupportedEncodingException` - Unknown encoding

    - #### findCGI

          protected String[] findCGI​(String pathInfo,
                                     String webAppRootDir,
                                     String contextPath,
                                     String servletPath,
                                     String cgiPathPrefix)

      Resolves core information about the cgi script.

      Example URI:

           /servlet/cgigateway/dir1/realCGIscript/pathinfo1

      - path = $CATALINA_HOME/mywebapp/dir1/realCGIscript
      - scriptName = /servlet/cgigateway/dir1/realCGIscript
      - cgiName = /dir1/realCGIscript
      - name = realCGIscript

      CGI search algorithm: search the real path below <my-webapp-root> and find the first non-directory in the getPathTranslated("/"), reading/searching from left-to-right.

      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

      Parameters:
        `pathInfo` - String from HttpServletRequest.getPathInfo()
        `webAppRootDir` - String from context.getRealPath("/")
        `contextPath` - String as from HttpServletRequest.getContextPath()
        `servletPath` - String as from HttpServletRequest.getServletPath()
        `cgiPathPrefix` - subdirectory of webAppRootDir below which the web app's CGIs may be stored; can be null. The CGI search path will start at webAppRootDir + File.separator + cgiPathPrefix (or webAppRootDir alone if cgiPathPrefix is null). cgiPathPrefix is defined by setting the servlet's cgiPathPrefix init parameter.
      Returns:
        - `path` - full file-system path to valid cgi script, or null if no cgi was found
        - `scriptName` - CGI variable SCRIPT_NAME; the full URL path to valid cgi script or null if no cgi was found
        - `cgiName` - servlet pathInfo fragment corresponding to the cgi script itself, or null if not found
        - `name` - simple name (no directories) of the cgi script, or null if no cgi was found

    - #### setCGIEnvironment

          protected boolean setCGIEnvironment​(HttpServletRequest req)
                                       throws IOException

      Constructs the CGI environment to be supplied to the invoked CGI script; relies heavily on Servlet API methods and findCGI
      Parameters:
        `req` - request associated with the CGI Invocation
      Returns:
        true if environment was set OK, false if there was a problem and no environment was set
      Throws:
        `IOException` - an IO error occurred

    - #### expandCGIScript

          protected void expandCGIScript()

      Extracts requested resource from web app archive to context work directory to enable CGI script to be executed.

    - #### toString

          public String toString()

      Returns important CGI environment information in a multi-line text format.
      Overrides:
        `toString` in class `Object`
      Returns:
        CGI environment info

    - #### getCommand

          protected String getCommand()

      Gets derived command string
      Returns:
        command string

    - #### getWorkingDirectory

          protected File getWorkingDirectory()

      Gets derived CGI working directory
      Returns:
        working directory

    - #### getEnvironment

          protected Map<String,​String> getEnvironment()

      Gets derived CGI environment
      Returns:
        CGI environment

    - #### getParameters

          protected ArrayList<String> getParameters()

      Gets derived CGI query parameters
      Returns:
        CGI query parameters

    - #### isValid

          protected boolean isValid()

      Gets validity status
      Returns:
        true if this environment is valid, false otherwise

    - #### nullsToBlanks

          protected String nullsToBlanks​(String s)

      Converts null strings to blank strings ("")
      Parameters:
        `s` - string to be converted if necessary
      Returns:
        a non-null string, either the original or the empty string ("") if the original was `null`

    - #### nullsToString

          protected String nullsToString​(String couldBeNull,
                                         String subForNulls)

      Converts null strings to another string
      Parameters:
        `couldBeNull` - string to be converted if necessary
        `subForNulls` - string to return instead of a null string
      Returns:
        a non-null string, either the original or the substitute string if the original was `null`

    - #### blanksToString

          protected String blanksToString​(String couldBeBlank,
                                          String subForBlanks)

      Converts blank strings to another string
      Parameters:
        `couldBeBlank` - string to be converted if necessary
        `subForBlanks` - string to return instead of a blank string
      Returns:
        a non-null string, either the original or the substitute string if the original was `null` or empty ("")