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