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.

Since:
  Tomcat 4.0

### Constructor Summary

Constructors
`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
`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 void` `setupFromRequest(HttpServletRequest req)` Uses the HttpServletRequest to set most CGI variables
`String` `toString()` Print important CGI environment information in a easy-to-read HTML table

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

### 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 void setupFromRequest(HttpServletRequest req)
                             throws UnsupportedEncodingException

Uses the HttpServletRequest to set most CGI variables

Parameters:
  `req` - HttpServletRequest for information provided by the Servlet API
Throws:
  `UnsupportedEncodingException`

#### 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
Since:
  Tomcat 4.0

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

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

Print important CGI environment information in a easy-to-read HTML table

Overrides:
  `toString` in class `Object`
Returns:
  HTML string containing 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 ("")