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 and Description
    --- | ---
    `protected` | `CGIServlet.CGIEnvironment(HttpServletRequest req, ServletContext context)` Creates a CGIEnvironment and derives the necessary environment, query parameters, working directory, cgi command, etc.

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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 Hashtable<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

    - #### CGIServlet.CGIEnvironment

          protected CGIServlet.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 Hashtable<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 ("")

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