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