CGIServlet.CGIEnvironment (Apache Tomcat 11.0.8 API Documentation)
Description: declaration: package: org.apache.catalina.servlets, class: CGIServlet, class: CGIEnvironment

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

Author:
  Martin T Dengler [root@martindengler.com], Amy Roh

- ## 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

  Modifier and Type
  Method
  Description
  `protected String`
  `blanksToString(String couldBeBlank, String subForBlanks)`
  Converts blank strings to another string
  `protected String[]`
  `findCGI(String contextPath, String servletPath, String pathInfo, 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 Details

  - ### 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 Details

  - ### 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 contextPath, String servletPath, String pathInfo, 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:
      `contextPath` - String as from HttpServletRequest.getContextPath()
      `servletPath` - String as from HttpServletRequest.getServletPath()
      `pathInfo` - String from HttpServletRequest.getPathInfo()
      `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

  - ### 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 ("")