CGIServlet.CGIEnvironment (Apache Tomcat 9.0.81 API Documentation)

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 java.lang.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 java.lang.String` | `blanksToString​(java.lang.String couldBeBlank, java.lang.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 java.lang.String[]` | `findCGI​(java.lang.String pathInfo, java.lang.String webAppRootDir, java.lang.String contextPath, java.lang.String servletPath, java.lang.String cgiPathPrefix)` | Resolves core information about the cgi script.
    `protected java.lang.String` | `getCommand()` | Gets derived command string
    `protected java.util.Hashtable<java.lang.String,​java.lang.String>` | `getEnvironment()` | Gets derived CGI environment
    `protected java.util.ArrayList<java.lang.String>` | `getParameters()` | Gets derived CGI query parameters
    `protected java.io.File` | `getWorkingDirectory()` | Gets derived CGI working directory
    `protected boolean` | `isValid()` | Gets validity status
    `protected java.lang.String` | `nullsToBlanks​(java.lang.String s)` | Converts null strings to blank strings ("")
    `protected java.lang.String` | `nullsToString​(java.lang.String couldBeNull, java.lang.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
    `java.lang.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 java.io.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:
        `java.io.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 java.io.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:
        `java.io.UnsupportedEncodingException` - Unknown encoding

    - #### findCGI

          protected java.lang.String[] findCGI​(java.lang.String pathInfo,
                                               java.lang.String webAppRootDir,
                                               java.lang.String contextPath,
                                               java.lang.String servletPath,
                                               java.lang.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 java.io.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:
        `java.io.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 java.lang.String toString()

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

    - #### getCommand

          protected java.lang.String getCommand()

      Gets derived command string
      Returns:
        command string

    - #### getWorkingDirectory

          protected java.io.File getWorkingDirectory()

      Gets derived CGI working directory
      Returns:
        working directory

    - #### getEnvironment

          protected java.util.Hashtable<java.lang.String,​java.lang.String> getEnvironment()

      Gets derived CGI environment
      Returns:
        CGI environment

    - #### getParameters

          protected java.util.ArrayList<java.lang.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 java.lang.String nullsToBlanks​(java.lang.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 java.lang.String nullsToString​(java.lang.String couldBeNull,
                                                   java.lang.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 java.lang.String blanksToString​(java.lang.String couldBeBlank,
                                                    java.lang.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 ("")