Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
   /*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    * 
    *      http://www.apache.org/licenses/LICENSE-2.0
   * 
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  
  package org.apache.catalina.servlets;
  
  import static org.jboss.web.CatalinaMessages.MESSAGES;
  
  import java.io.File;
  import java.util.Date;
  import java.util.Locale;
  import java.util.Vector;
  
  
CGI-invoking servlet for web applications, used to execute scripts which comply to the Common Gateway Interface (CGI) specification and are named in the path-info used to invoke this servlet.

Note: This code compiles and even works for simple CGI cases. Exhaustive testing has not been done. Please consider it beta quality. Feedback is appreciated to the author (see below).

Example:
If an instance of this servlet was mapped (using <web-app>/WEB-INF/web.xml) to:

<web-app>/cgi-bin/*

then the following request:

http://localhost:8080/<web-app>/cgi-bin/dir1/script/pathinfo1

would result in the execution of the script

<web-app-root>/WEB-INF/cgi/dir1/script

with the script's PATH_INFO set to /pathinfo1.

Recommendation: House all your CGI scripts under <webapp>/WEB-INF/cgi. This will ensure that you do not accidentally expose your cgi scripts' code to the outside world and that your cgis will be cleanly ensconced underneath the WEB-INF (i.e., non-content) area.

The default CGI location is mentioned above. You have the flexibility to put CGIs wherever you want, however:

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

CGI Specification:
derived from http://cgi-spec.golux.com. A work-in-progress & expired Internet Draft. Note no actual RFC describing the CGI specification exists. Where the behavior of this servlet differs from the specification cited above, it is either documented here, a bug, or an instance where the specification cited differs from Best Community Practice (BCP). Such instances should be well-documented here. Please email the Tomcat group [dev@tomcat.apache.org] with amendments.

Canonical metavariables:
The CGI specification defines the following canonical metavariables:
[excerpt from CGI specification]

  AUTH_TYPE
  CONTENT_LENGTH
  CONTENT_TYPE
  GATEWAY_INTERFACE
  PATH_INFO
  PATH_TRANSLATED
  QUERY_STRING
  REMOTE_ADDR
  REMOTE_HOST
  REMOTE_IDENT
  REMOTE_USER
  REQUEST_METHOD
  SCRIPT_NAME
  SERVER_NAME
  SERVER_PORT
  SERVER_PROTOCOL
  SERVER_SOFTWARE
 

Metavariables with names beginning with the protocol name (e.g., "HTTP_ACCEPT") are also canonical in their description of request header fields. The number and meaning of these fields may change independently of this specification. (See also section 6.1.5 [of the CGI specification].)

[end excerpt]

Implementation notes

standard input handling: If your script accepts standard input, then the client must start sending input within a certain timeout period, otherwise the servlet will assume no input is coming and carry on running the script. The script's the standard input will be closed and handling of any further input from the client is undefined. Most likely it will be ignored. If this behavior becomes undesirable, then this servlet needs to be enhanced to handle threading of the spawned process' stdin, stdout, and stderr (which should not be too hard).
If you find your cgi scripts are timing out receiving input, you can set the init parameter of your webapps' cgi-handling servlet to be

Metavariable Values: According to the CGI specification, implementations may choose to represent both null or missing values in an implementation-specific manner, but must define that manner. This implementation chooses to always define all required metavariables, but set the value to "" for all metavariables whose value is either null or undefined. PATH_TRANSLATED is the sole exception to this rule, as per the CGI Specification.

NPH -- Non-parsed-header implementation: This implementation does not support the CGI NPH concept, whereby server ensures that the data supplied to the script are precisely as supplied by the client and unaltered by the server.

The function of a servlet container (including Tomcat) is specifically designed to parse and possible alter CGI-specific variables, and as such makes NPH functionality difficult to support.

The CGI specification states that compliant servers MAY support NPH output. It does not state servers MUST support NPH output to be unconditionally compliant. Thus, this implementation maintains unconditional compliance with the specification though NPH support is not present.

The CGI specification is located at http://cgi-spec.golux.com.

TODO:

  • Support for setting headers (for example, Location headers don't work)
  • Support for collapsing multiple header lines (per RFC 2616)
  • Ensure handling of POST method does not interfere with 2.3 Filters
  • Refactor some debug code out of core
  • Ensure header handling preserves encoding
  • Possibly rewrite CGIRunner.run()?
  • Possibly refactor CGIRunner and CGIEnvironment as non-inner classes?
  • Document handling of cgi stdin when there is no stdin
  • Revisit IOException handling in CGIRunner.run()
  • Better documentation
  • Confirm use of ServletInputStream.available() in CGIRunner.run() is not needed
  • [add more to this TODO list]

Author(s):
Martin T Dengler [root@martindengler.com]
Amy Roh
Version:
$Id: CGIServlet.java 1584 2010-11-23 10:18:39Z remy.maucherat@jboss.com $
Since:
Tomcat 4.0
 
 
 
 public final class CGIServlet extends HttpServlet {
 
     /* some vars below copied from Craig R. McClanahan's InvokerServlet */
 
     private static final long serialVersionUID = 1L;

    
the debugging detail level for this servlet.
 
     private int debug = 0;

    
The CGI search path will start at webAppRootDir + File.separator + cgiPathPrefix (or webAppRootDir alone if cgiPathPrefix is null)
 
     private String cgiPathPrefix = null;

    
the executable to use with the script
 
     private String cgiExecutable = "perl";
    
    
the encoding to use for parameters
 
     private String parameterEncoding =
         System.getProperty("file.encoding""UTF-8");

    
The time (in milliseconds) to wait for the reading of stderr to complete before terminating the CGI process.
 
     private long stderrTimeout = 2000;

    
object used to ensure multiple threads don't try to expand same file
 
     static Object expandFileLock = new Object();

    
the shell environment variables to be passed to the CGI script
 
     static Hashtable<String,StringshellEnv = new Hashtable<String,String>();

    
Sets instance variables.

Modified from Craig R. McClanahan's InvokerServlet

Parameters:
config a ServletConfig object containing the servlet's configuration and initialization parameters
Throws:
javax.servlet.ServletException if an exception has occurred that interferes with the servlet's normal operation
 
     @Override
     public void init(ServletConfig configthrows ServletException {
 
         super.init(config);
 
         // Set our properties from the initialization parameters
         if (getServletConfig().getInitParameter("debug") != null)
              = Integer.parseInt(getServletConfig().getInitParameter("debug"));
          = getServletConfig().getInitParameter("cgiPathPrefix");
         boolean passShellEnvironment = 
             Boolean.valueOf(getServletConfig().getInitParameter("passShellEnvironment")).booleanValue();
 
         if (passShellEnvironment) {
             .putAll(System.getenv());
         }
 
         if (getServletConfig().getInitParameter("executable") != null) {
              = getServletConfig().getInitParameter("executable");
         }
 
         if (getServletConfig().getInitParameter("parameterEncoding") != null) {
              = getServletConfig().getInitParameter("parameterEncoding");
         }
 
         if (getServletConfig().getInitParameter("stderrTimeout") != null) {
              = Long.parseLong(getServletConfig().getInitParameter(
                     "stderrTimeout"));
         }
 
     }


    
Prints out important Servlet API and container information

Copied from SnoopAllServlet by Craig R. McClanahan

Parameters:
out ServletOutputStream as target of the information
req HttpServletRequest object used as source of information
res HttpServletResponse object currently not used but could provide future information
Throws:
java.io.IOException if a write operation exception occurs
 
     protected void printServletEnvironment(ServletOutputStream out,
         HttpServletRequest req,
         @SuppressWarnings("unused"HttpServletResponse res)
     throws IOException {
 
         // Document the properties from ServletRequest
         out.println("<h1>ServletRequest Properties</h1>");
         out.println("<ul>");
         Enumeration<Stringattrs = req.getAttributeNames();
         while (attrs.hasMoreElements()) {
             String attr = attrs.nextElement();
             out.println("<li><b>attribute</b> " + attr + " = " +
                            req.getAttribute(attr));
         }
         out.println("<li><b>characterEncoding</b> = " +
                        req.getCharacterEncoding());
         out.println("<li><b>contentLength</b> = " +
                        req.getContentLength());
         out.println("<li><b>contentType</b> = " +
                        req.getContentType());
         Enumeration<Localelocales = req.getLocales();
         while (locales.hasMoreElements()) {
             Locale locale = locales.nextElement();
             out.println("<li><b>locale</b> = " + locale);
         }
         Enumeration<Stringparams = req.getParameterNames();
         while (params.hasMoreElements()) {
             String param = params.nextElement();
             String values[] = req.getParameterValues(param);
             for (int i = 0; i < values.lengthi++)
                 out.println("<li><b>parameter</b> " + param + " = " +
                                values[i]);
         }
         out.println("<li><b>protocol</b> = " + req.getProtocol());
         out.println("<li><b>remoteAddr</b> = " + req.getRemoteAddr());
         out.println("<li><b>remoteHost</b> = " + req.getRemoteHost());
         out.println("<li><b>scheme</b> = " + req.getScheme());
         out.println("<li><b>secure</b> = " + req.isSecure());
         out.println("<li><b>serverName</b> = " + req.getServerName());
         out.println("<li><b>serverPort</b> = " + req.getServerPort());
         out.println("</ul>");
         out.println("<hr>");
 
         // Document the properties from HttpServletRequest
         out.println("<h1>HttpServletRequest Properties</h1>");
         out.println("<ul>");
         out.println("<li><b>authType</b> = " + req.getAuthType());
         out.println("<li><b>contextPath</b> = " +
                        req.getContextPath());
         Cookie cookies[] = req.getCookies();
         if (cookies!=null) {
             for (int i = 0; i < cookies.lengthi++)
                 out.println("<li><b>cookie</b> " + cookies[i].getName() +" = " +cookies[i].getValue());
         }
         Enumeration<Stringheaders = req.getHeaderNames();
         while (headers.hasMoreElements()) {
             String header = headers.nextElement();
             out.println("<li><b>header</b> " + header + " = " +
                            req.getHeader(header));
         }
         out.println("<li><b>method</b> = " + req.getMethod());
         out.println("<li><a name=\"pathInfo\"><b>pathInfo</b></a> = "
                     + req.getPathInfo());
         out.println("<li><b>pathTranslated</b> = " +
                        req.getPathTranslated());
         out.println("<li><b>queryString</b> = " +
                        req.getQueryString());
         out.println("<li><b>remoteUser</b> = " +
                        req.getRemoteUser());
         out.println("<li><b>requestedSessionId</b> = " +
                        req.getRequestedSessionId());
         out.println("<li><b>requestedSessionIdFromCookie</b> = " +
                        req.isRequestedSessionIdFromCookie());
         out.println("<li><b>requestedSessionIdFromURL</b> = " +
                        req.isRequestedSessionIdFromURL());
         out.println("<li><b>requestedSessionIdValid</b> = " +
                        req.isRequestedSessionIdValid());
         out.println("<li><b>requestURI</b> = " +
                        req.getRequestURI());
         out.println("<li><b>servletPath</b> = " +
                        req.getServletPath());
         out.println("<li><b>userPrincipal</b> = " +
                        req.getUserPrincipal());
         out.println("</ul>");
         out.println("<hr>");
 
         // Document the servlet request attributes
         out.println("<h1>ServletRequest Attributes</h1>");
         out.println("<ul>");
         attrs = req.getAttributeNames();
         while (attrs.hasMoreElements()) {
             String attr = attrs.nextElement();
             out.println("<li><b>" + attr + "</b> = " +
                            req.getAttribute(attr));
         }
         out.println("</ul>");
         out.println("<hr>");
 
         // Process the current session (if there is one)
         HttpSession session = req.getSession(false);
         if (session != null) {
 
             // Document the session properties
             out.println("<h1>HttpSession Properties</h1>");
             out.println("<ul>");
             out.println("<li><b>id</b> = " +
                            session.getId());
             out.println("<li><b>creationTime</b> = " +
                            new Date(session.getCreationTime()));
             out.println("<li><b>lastAccessedTime</b> = " +
                            new Date(session.getLastAccessedTime()));
             out.println("<li><b>maxInactiveInterval</b> = " +
                            session.getMaxInactiveInterval());
             out.println("</ul>");
             out.println("<hr>");
 
             // Document the session attributes
             out.println("<h1>HttpSession Attributes</h1>");
             out.println("<ul>");
             attrs = session.getAttributeNames();
             while (attrs.hasMoreElements()) {
                 String attr = attrs.nextElement();
                 out.println("<li><b>" + attr + "</b> = " +
                                session.getAttribute(attr));
             }
             out.println("</ul>");
             out.println("<hr>");
 
         }
 
         // Document the servlet configuration properties
         out.println("<h1>ServletConfig Properties</h1>");
         out.println("<ul>");
         out.println("<li><b>servletName</b> = " +
                        getServletConfig().getServletName());
         out.println("</ul>");
         out.println("<hr>");
 
         // Document the servlet configuration initialization parameters
         out.println("<h1>ServletConfig Initialization Parameters</h1>");
         out.println("<ul>");
         params = getServletConfig().getInitParameterNames();
         while (params.hasMoreElements()) {
             String param = params.nextElement();
             String value = getServletConfig().getInitParameter(param);
             out.println("<li><b>" + param + "</b> = " + value);
         }
         out.println("</ul>");
         out.println("<hr>");
 
         // Document the servlet context properties
         out.println("<h1>ServletContext Properties</h1>");
         out.println("<ul>");
         out.println("<li><b>majorVersion</b> = " +
                        getServletContext().getMajorVersion());
         out.println("<li><b>minorVersion</b> = " +
                        getServletContext().getMinorVersion());
         out.println("<li><b>realPath('/')</b> = " +
                        getServletContext().getRealPath("/"));
         out.println("<li><b>serverInfo</b> = " +
                        getServletContext().getServerInfo());
         out.println("</ul>");
         out.println("<hr>");
 
         // Document the servlet context initialization parameters
         out.println("<h1>ServletContext Initialization Parameters</h1>");
         out.println("<ul>");
         params = getServletContext().getInitParameterNames();
         while (params.hasMoreElements()) {
             String param = params.nextElement();
             String value = getServletContext().getInitParameter(param);
             out.println("<li><b>" + param + "</b> = " + value);
         }
         out.println("</ul>");
         out.println("<hr>");
 
         // Document the servlet context attributes
         out.println("<h1>ServletContext Attributes</h1>");
         out.println("<ul>");
         attrs = getServletContext().getAttributeNames();
         while (attrs.hasMoreElements()) {
             String attr = attrs.nextElement();
             out.println("<li><b>" + attr + "</b> = " +
                            getServletContext().getAttribute(attr));
         }
         out.println("</ul>");
         out.println("<hr>");
 
 
     }


    
Provides CGI Gateway service -- delegates to doGet

Parameters:
req HttpServletRequest passed in by servlet container
res HttpServletResponse passed in by servlet container
Throws:
javax.servlet.ServletException if a servlet-specific exception occurs
java.io.IOException if a read/write exception occurs
See also:
javax.servlet.http.HttpServlet
 
     @Override
     protected void doPost(HttpServletRequest reqHttpServletResponse res)
         throws IOExceptionServletException {
         doGet(reqres);
     }


    
Provides CGI Gateway service

Parameters:
req HttpServletRequest passed in by servlet container
res HttpServletResponse passed in by servlet container
Throws:
javax.servlet.ServletException if a servlet-specific exception occurs
java.io.IOException if a read/write exception occurs
See also:
javax.servlet.http.HttpServlet
 
     @Override
     protected void doGet(HttpServletRequest reqHttpServletResponse res)
         throws ServletExceptionIOException {
 
         CGIEnvironment cgiEnv = new CGIEnvironment(reqgetServletContext());
 
         if (cgiEnv.isValid()) {
             CGIRunner cgi = new CGIRunner(cgiEnv.getCommand(),
                                           cgiEnv.getEnvironment(),
                                           cgiEnv.getWorkingDirectory(),
                                           cgiEnv.getParameters());
             //if POST, we need to cgi.setInput
             //REMIND: how does this interact with Servlet API 2.3's Filters?!
             if ("POST".equals(req.getMethod())) {
                 cgi.setInput(req.getInputStream());
             }
             cgi.setResponse(res);
             cgi.run();
         }
 
         if (!cgiEnv.isValid()) {
             res.setStatus(404);
         }
  
         if ( >= 10) {
 
             ServletOutputStream out = res.getOutputStream();
             out.println("<HTML><HEAD><TITLE>$Name$</TITLE></HEAD>");
             out.println("<BODY>$Header$<p>");
 
             if (cgiEnv.isValid()) {
                 out.println(cgiEnv.toString());
             } else {
                 out.println("<H3>");
                 out.println("CGI script not found or not specified.");
                 out.println("</H3>");
                 out.println("<H4>");
                 out.println("Check the <b>HttpServletRequest ");
                 out.println("<a href=\"#pathInfo\">pathInfo</a></b> ");
                 out.println("property to see if it is what you meant ");
                 out.println("it to be.  You must specify an existant ");
                 out.println("and executable file as part of the ");
                 out.println("path-info.");
                 out.println("</H4>");
                 out.println("<H4>");
                 out.println("For a good discussion of how CGI scripts ");
                 out.println("work and what their environment variables ");
                 out.println("mean, please visit the <a ");
                 out.println("href=\"http://cgi-spec.golux.com\">CGI ");
                 out.println("Specification page</a>.");
                 out.println("</H4>");
 
             }
 
             printServletEnvironment(outreqres);
 
             out.println("</BODY></HTML>");
 
         }
 
 
     } //doGet
 

    
Encapsulates the CGI environment and rules to derive that environment from the servlet container and request information.

Version:
$Id: CGIServlet.java 1584 2010-11-23 10:18:39Z remy.maucherat@jboss.com $
Since:
Tomcat 4.0
 
     protected class CGIEnvironment {


        
context of the enclosing servlet
 
         private ServletContext context = null;

        
context path of enclosing servlet
 
         private String contextPath = null;

        
servlet URI of the enclosing servlet
 
         private String servletPath = null;

        
pathInfo for the current request
 
         private String pathInfo = null;

        
real file system directory of the enclosing servlet's web app
 
         private String webAppRootDir = null;

        
tempdir for context - used to expand scripts in unexpanded wars
 
         private File tmpDir = null;

        
derived cgi environment
 
         private Hashtable<StringStringenv = null;

        
cgi command to be invoked
 
         private String command = null;

        
cgi command's desired working directory
 
         private File workingDirectory = null;

        
cgi command's command line parameters
 
         private ArrayList<StringcmdLineParameters = new ArrayList<String>();

        
whether or not this object is valid or not
 
         private boolean valid = false;


        
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
 
         protected CGIEnvironment(HttpServletRequest req,
                                  ServletContext contextthrows IOException {
             setupFromContext(context);
             setupFromRequest(req);
 
             this. = setCGIEnvironment(req);
 
             if (this.) {
                  = new File(.substring(0,
                       .lastIndexOf(.)));
             }
 
         }


        
Uses the ServletContext to set some CGI variables

Parameters:
context ServletContext for information provided by the Servlet API
 
         protected void setupFromContext(ServletContext context) {
             this. = context;
             this. = context.getRealPath("/");
             this. = (Filecontext.getAttribute(.);
         }


        
Uses the HttpServletRequest to set most CGI variables

Parameters:
req HttpServletRequest for information provided by the Servlet API
Throws:
java.io.UnsupportedEncodingException
 
         protected void setupFromRequest(HttpServletRequest req)
                 throws UnsupportedEncodingException {
 
             boolean isIncluded = false;
 
             // Look to see if this request is an include
             if (req.getAttribute(.) != null) {
                 isIncluded = true;
             }
             if (isIncluded) {
                 this. = (Stringreq.getAttribute(
                         .);
                 this. = (Stringreq.getAttribute(
                         .);
                 this. = (Stringreq.getAttribute(
                         .);
             } else {
                 this. = req.getContextPath();
                 this. = req.getServletPath();
                 this. = req.getPathInfo();
             }
             // If getPathInfo() returns null, must be using extension mapping
             // In this case, pathInfo should be same as servletPath
             if (this. == null) {
                 this. = this.;
             }
 
             // If the request method is GET, POST or HEAD and the query string
             // does not contain an unencoded "=" this is an indexed query.
             // The parsed query string becomes the command line parameters
             // for the cgi command.
             if (req.getMethod().equals("GET")
                 || req.getMethod().equals("POST")
                 || req.getMethod().equals("HEAD")) {
                 String qs;
                 if (isIncluded) {
                     qs = (Stringreq.getAttribute(
                             .);
                 } else {
                     qs = req.getQueryString();
                 }
                 if (qs != null && qs.indexOf("=") == -1) {
                     StringTokenizer qsTokens = new StringTokenizer(qs"+");
                     while ( qsTokens.hasMoreTokens() ) {
                         .add(URLDecoder.decode(qsTokens.nextToken(),
                                               ));
                     }
                 }
             }
         }


        
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
 
         protected String[] findCGI(String pathInfoString webAppRootDir,
                                    String contextPathString servletPath,
                                    String cgiPathPrefix) {
             String path = null;
             String name = null;
             String scriptname = null;
             String cginame = "";
 
             if ((webAppRootDir != null)
                 && (webAppRootDir.lastIndexOf(.) ==
                     (webAppRootDir.length() - 1))) {
                     //strip the trailing "/" from the webAppRootDir
                     webAppRootDir =
                     webAppRootDir.substring(0, (webAppRootDir.length() - 1));
             }
 
             if (cgiPathPrefix != null) {
                 webAppRootDir = webAppRootDir + .
                     + cgiPathPrefix;
             }
 
             if ( >= 2) {
                 log("findCGI: path=" + pathInfo + ", " + webAppRootDir);
             }
 
             File currentLocation = new File(webAppRootDir);
             StringTokenizer dirWalker =
             new StringTokenizer(pathInfo"/");
             if ( >= 3) {
                 log("findCGI: currentLoc=" + currentLocation);
             }
             while (!currentLocation.isFile() && dirWalker.hasMoreElements()) {
                 if ( >= 3) {
                     log("findCGI: currentLoc=" + currentLocation);
                 }
                 String nextElement = (StringdirWalker.nextElement();
                 currentLocation = new File(currentLocationnextElement);
                 cginame = cginame + "/" + nextElement;
             }
             if (!currentLocation.isFile()) {
                 return new String[] { nullnullnullnull };
             }
 
             if ( >= 2) {
                 log("findCGI: FOUND cgi at " + currentLocation);
             }
             path = currentLocation.getAbsolutePath();
             name = currentLocation.getName();
 
             if (".".equals(contextPath)) {
                 scriptname = servletPath;
             } else {
                 scriptname = contextPath + servletPath;
             }
             if (!servletPath.equals(cginame)) {
                 scriptname = scriptname + cginame;
             }
 
             if ( >= 1) {
                 log("findCGI calc: name=" + name + ", path=" + path
                     + ", scriptname=" + scriptname + ", cginame=" + cginame);
             }
             return new String[] { pathscriptnamecginamename };
         }

        
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
 
         protected boolean setCGIEnvironment(HttpServletRequest reqthrows IOException {
 
             /*
              * This method is slightly ugly; c'est la vie.
              * "You cannot stop [ugliness], you can only hope to contain [it]"
              * (apologies to Marv Albert regarding MJ)
              */
 
             Hashtable<String,Stringenvp = new Hashtable<String,String>();
 
             // Add the shell environment variables (if any)
             envp.putAll();
 
             // Add the CGI environment variables
             String sPathInfoOrig = null;
             String sPathInfoCGI = null;
             String sPathTranslatedCGI = null;
             String sCGIFullPath = null;
             String sCGIScriptName = null;
             String sCGIFullName = null;
             String sCGIName = null;
             String[] sCGINames;
 
 
             sPathInfoOrig = this.;
             sPathInfoOrig = sPathInfoOrig == null ? "" : sPathInfoOrig;
 
             if ( == null ) {
                 // The app has not been deployed in exploded form
                  = .toString();
                 expandCGIScript();
             } 
             
             sCGINames = findCGI(sPathInfoOrig,
                                 ,
                                 ,
                                 ,
                                 );
 
             sCGIFullPath = sCGINames[0];
             sCGIScriptName = sCGINames[1];
             sCGIFullName = sCGINames[2];
             sCGIName = sCGINames[3];
 
             if (sCGIFullPath == null
                 || sCGIScriptName == null
                 || sCGIFullName == null
                 || sCGIName == null) {
                 return false;
             }
 
             envp.put("SERVER_SOFTWARE""TOMCAT");
 
             envp.put("SERVER_NAME"nullsToBlanks(req.getServerName()));
 
             envp.put("GATEWAY_INTERFACE""CGI/1.1");
 
             envp.put("SERVER_PROTOCOL"nullsToBlanks(req.getProtocol()));
 
             int port = req.getServerPort();
             Integer iPort =
                 (port == 0 ? Integer.valueOf(-1) : Integer.valueOf(port));
             envp.put("SERVER_PORT"iPort.toString());
 
             envp.put("REQUEST_METHOD"nullsToBlanks(req.getMethod()));
 
             envp.put("REQUEST_URI"nullsToBlanks(req.getRequestURI()));
 
 
             /*-
              * PATH_INFO should be determined by using sCGIFullName:
              * 1) Let sCGIFullName not end in a "/" (see method findCGI)
              * 2) Let sCGIFullName equal the pathInfo fragment which
              *    corresponds to the actual cgi script.
              * 3) Thus, PATH_INFO = request.getPathInfo().substring(
              *                      sCGIFullName.length())
              *
              * (see method findCGI, where the real work is done)
              *
              */
             if ( == null
                 || (.substring(sCGIFullName.length()).length() <= 0)) {
                 sPathInfoCGI = "";
             } else {
                 sPathInfoCGI = .substring(sCGIFullName.length());
             }
             envp.put("PATH_INFO"sPathInfoCGI);
            /*-
             * PATH_TRANSLATED must be determined after PATH_INFO (and the
             * implied real cgi-script) has been taken into account.
             *
             * The following example demonstrates:
             *
             * servlet info   = /servlet/cgigw/dir1/dir2/cgi1/trans1/trans2
             * cgifullpath    = /servlet/cgigw/dir1/dir2/cgi1
             * path_info      = /trans1/trans2
             * webAppRootDir  = servletContext.getRealPath("/")
             *
             * path_translated = servletContext.getRealPath("/trans1/trans2")
             *
             * That is, PATH_TRANSLATED = webAppRootDir + sPathInfoCGI
             * (unless sPathInfoCGI is null or blank, then the CGI
             * specification dictates that the PATH_TRANSLATED metavariable
             * SHOULD NOT be defined.
             *
             */
            if (sPathInfoCGI != null && !("".equals(sPathInfoCGI))) {
                sPathTranslatedCGI = .getRealPath(sPathInfoCGI);
            }
            if (sPathTranslatedCGI == null || "".equals(sPathTranslatedCGI)) {
                //NOOP
            } else {
                envp.put("PATH_TRANSLATED"nullsToBlanks(sPathTranslatedCGI));
            }
            envp.put("SCRIPT_NAME"nullsToBlanks(sCGIScriptName));
            envp.put("QUERY_STRING"nullsToBlanks(req.getQueryString()));
            envp.put("REMOTE_HOST"nullsToBlanks(req.getRemoteHost()));
            envp.put("REMOTE_ADDR"nullsToBlanks(req.getRemoteAddr()));
            envp.put("AUTH_TYPE"nullsToBlanks(req.getAuthType()));
            envp.put("REMOTE_USER"nullsToBlanks(req.getRemoteUser()));
            envp.put("REMOTE_IDENT"""); //not necessary for full compliance
            envp.put("CONTENT_TYPE"nullsToBlanks(req.getContentType()));
            /* Note CGI spec says CONTENT_LENGTH must be NULL ("") or undefined
             * if there is no content, so we cannot put 0 or -1 in as per the
             * Servlet API spec.
             */
            int contentLength = req.getContentLength();
            String sContentLength = (contentLength <= 0 ? "" :
                (Integer.valueOf(contentLength)).toString());
            envp.put("CONTENT_LENGTH"sContentLength);
            Enumeration<Stringheaders = req.getHeaderNames();
            String header = null;
            while (headers.hasMoreElements()) {
                header = null;
                header = headers.nextElement().toUpperCase(.);
                //REMIND: rewrite multiple headers as if received as single
                //REMIND: change character set
                //REMIND: I forgot what the previous REMIND means
                if ("AUTHORIZATION".equalsIgnoreCase(header) ||
                    "PROXY_AUTHORIZATION".equalsIgnoreCase(header)) {
                    //NOOP per CGI specification section 11.2
                } else {
                    envp.put("HTTP_" + header.replace('-''_'),
                             req.getHeader(header));
                }
            }
            File fCGIFullPath = new File(sCGIFullPath);
             = fCGIFullPath.getCanonicalPath();
            envp.put("X_TOMCAT_SCRIPT_PATH");  //for kicks
            envp.put("SCRIPT_FILENAME");  //for PHP
            this. = envp;
            return true;
        }

        
Extracts requested resource from web app archive to context work directory to enable CGI script to be executed.
        protected void expandCGIScript() {
            StringBuilder srcPath = new StringBuilder();
            StringBuilder destPath = new StringBuilder();
            InputStream is = null;
            // paths depend on mapping
            if ( == null ) {
                srcPath.append();
                is = .getResourceAsStream(srcPath.toString());
                destPath.append();
                destPath.append();
            } else {
                // essentially same search algorithm as findCGI()
                srcPath.append();
                StringTokenizer pathWalker =
                        new StringTokenizer ("/");
                // start with first element
                while (pathWalker.hasMoreElements() && (is == null)) {
                    srcPath.append("/");
                    srcPath.append(pathWalker.nextElement());
                    is = .getResourceAsStream(srcPath.toString());
                }
                destPath.append();
                destPath.append("/");
                destPath.append(srcPath);
            }
            if (is == null) {
                // didn't find anything, give up now
                if ( >= 2) {
                    log("expandCGIScript: source '" + srcPath + "' not found");
                }
                 return;
            }
            File f = new File(destPath.toString());
            if (f.exists()) {
                // Don't need to expand if it already exists
                return;
            } 
            // create directories
            String dirPath = destPath.toString().substring(
                    0,destPath.toString().lastIndexOf("/"));
            File dir = new File(dirPath);
            if (!dir.mkdirs() &&  >= 2) {
                log("expandCGIScript: failed to create directories for '" +
                        dir.getAbsolutePath() + "'");
                return;
            }
            try {
                synchronized () {
                    // make sure file doesn't exist
                    if (f.exists()) {
                        return;
                    }
                    // create file
                    if (!f.createNewFile()) {
                        return;
                    }
                    FileOutputStream fos = new FileOutputStream(f);
                    // copy data
                    IOTools.flow(isfos);
                    is.close();
                    fos.close();
                    if ( >= 2) {
                        log("expandCGIScript: expanded '" + srcPath + "' to '" + destPath + "'");
                    }
                }
            } catch (IOException ioe) {
                // delete in case file is corrupted 
                if (f.exists()) {
                    if (!f.delete() &&  >= 2) {
                        log("expandCGIScript: failed to delete '" +
                                f.getAbsolutePath() + "'");
                    }
                }
            }
        }


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

Returns:
HTML string containing CGI environment info
        @Override
        public String toString() {
            StringBuilder sb = new StringBuilder();
            sb.append("<TABLE border=2>");
            sb.append("<tr><th colspan=2 bgcolor=grey>");
            sb.append("CGIEnvironment Info</th></tr>");
            sb.append("<tr><td>Debug Level</td><td>");
            sb.append();
            sb.append("</td></tr>");
            sb.append("<tr><td>Validity:</td><td>");
            sb.append(isValid());
            sb.append("</td></tr>");
            if (isValid()) {
                Enumeration<Stringenvk = .keys();
                while (envk.hasMoreElements()) {
                    String s = envk.nextElement();
                    sb.append("<tr><td>");
                    sb.append(s);
                    sb.append("</td><td>");
                    sb.append(blanksToString(.get(s),
                                             "[will be set to blank]"));
                    sb.append("</td></tr>");
                }
            }
            sb.append("<tr><td colspan=2><HR></td></tr>");
            sb.append("<tr><td>Derived Command</td><td>");
            sb.append(nullsToBlanks());
            sb.append("</td></tr>");
            sb.append("<tr><td>Working Directory</td><td>");
            if ( != null) {
                sb.append(.toString());
            }
            sb.append("</td></tr>");
            sb.append("<tr><td>Command Line Params</td><td>");
            for (int i=0; i < .size(); i++) {
                String param = .get(i);
                sb.append("<p>");
                sb.append(param);
                sb.append("</p>");
            }
            sb.append("</td></tr>");
            sb.append("</TABLE><p>end.");
            return sb.toString();
        }


        
Gets derived command string

Returns:
command string
        protected String getCommand() {
            return ;
        }


        
Gets derived CGI working directory

Returns:
working directory
        protected File getWorkingDirectory() {
            return ;
        }


        
Gets derived CGI environment

Returns:
CGI environment
        protected Hashtable<String,StringgetEnvironment() {
            return ;
        }


        
Gets derived CGI query parameters

Returns:
CGI query parameters
        protected ArrayList<StringgetParameters() {
            return ;
        }


        
Gets validity status

Returns:
true if this environment is valid, false otherwise
        protected boolean isValid() {
            return ;
        }


        
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
        protected String nullsToBlanks(String s) {
            return nullsToString(s"");
        }


        
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
        protected String nullsToString(String couldBeNull,
                                       String subForNulls) {
            return (couldBeNull == null ? subForNulls : couldBeNull);
        }


        
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 ("")
        protected String blanksToString(String couldBeBlank,
                                      String subForBlanks) {
            return (("".equals(couldBeBlank) || couldBeBlank == null)
                    ? subForBlanks
                    : couldBeBlank);
        }
    } //class CGIEnvironment


    
Encapsulates the knowledge of how to run a CGI script, given the script's desired environment and (optionally) input/output streams

Exposes a run method used to actually invoke the CGI.

The CGI environment and settings are derived from the information passed to the constructor.

The input and output streams can be set by the setInput and setResponse methods, respectively.

Version:
$Id: CGIServlet.java 1584 2010-11-23 10:18:39Z remy.maucherat@jboss.com $
    protected class CGIRunner {

        
script/command to be executed
        private String command = null;

        
environment used when invoking the cgi script
        private Hashtable<String,Stringenv = null;

        
working directory used when invoking the cgi script
        private File wd = null;

        
command line parameters to be passed to the invoked script
        private ArrayList<Stringparams = null;

        
stdin to be passed to cgi script
        private InputStream stdin = null;

        
response object used to set headers & get output stream
        private HttpServletResponse response = null;

        
boolean tracking whether this object has enough info to run()
        private boolean readyToRun = false;


        
Creates a CGIRunner and initializes its environment, working directory, and query parameters.
Input/output streams (optional) are set using the setInput and setResponse methods, respectively.

Parameters:
command string full path to command to be executed
env Hashtable with the desired script environment
wd File with the script's desired working directory
params ArrayList with the script's query command line parameters as strings
        protected CGIRunner(String commandHashtable<String,Stringenv,
                            File wdArrayList<Stringparams) {
            this. = command;
            this. = env;
            this. = wd;
            this. = params;
            updateReadyStatus();
        }


        
Checks & sets ready status
        protected void updateReadyStatus() {
            if ( != null
                &&  != null
                &&  != null
                &&  != null
                &&  != null) {
                 = true;
            } else {
                 = false;
            }
        }


        
Gets ready status

Returns:
false if not ready (run will throw an exception), true if ready
        protected boolean isReady() {
            return ;
        }


        
Sets HttpServletResponse object used to set headers and send output to

Parameters:
response HttpServletResponse to be used
        protected void setResponse(HttpServletResponse response) {
            this. = response;
            updateReadyStatus();
        }


        
Sets standard input to be passed on to the invoked cgi script

Parameters:
stdin InputStream to be used
        protected void setInput(InputStream stdin) {
            this. = stdin;
            updateReadyStatus();
        }


        
Converts a Hashtable to a String array by converting each key/value pair in the Hashtable to a String in the form "key=value" (hashkey + "=" + hash.get(hashkey).toString())

Parameters:
h Hashtable to convert
Returns:
converted string array
Throws:
java.lang.NullPointerException if a hash key has a null value
        protected String[] hashToStringArray(Hashtable<String,?> h)
            throws NullPointerException {
            Vector<Stringv = new Vector<String>();
            Enumeration<Stringe = h.keys();
            while (e.hasMoreElements()) {
                String k = e.nextElement();
                v.add(k + "=" + h.get(k).toString());
            }
            String[] strArr = new String[v.size()];
            v.copyInto(strArr);
            return strArr;
        }


        
Executes a CGI script with the desired environment, current working directory, and input/output streams

This implements the following CGI specification recommedations:

  • Servers SHOULD provide the "query" component of the script-URI as command-line arguments to scripts if it does not contain any unencoded "=" characters and the command-line arguments can be generated in an unambiguous manner.
  • Servers SHOULD set the AUTH_TYPE metavariable to the value of the "auth-scheme" token of the "Authorization" if it was supplied as part of the request header. See getCGIEnvironment method.
  • Where applicable, servers SHOULD set the current working directory to the directory in which the script is located before invoking it.
  • Server implementations SHOULD define their behavior for the following cases:
    • Allowed characters in pathInfo: This implementation does not allow ASCII NUL nor any character which cannot be URL-encoded according to internet standards;
    • Allowed characters in path segments: This implementation does not allow non-terminal NULL segments in the the path -- IOExceptions may be thrown;
    • "." and ".." path segments: This implementation does not allow "." and ".." in the the path, and such characters will result in an IOException being thrown (this should never happen since Tomcat normalises the requestURI before determining the contextPath, servletPath and pathInfo);
    • Implementation limitations: This implementation does not impose any limitations except as documented above. This implementation may be limited by the servlet container used to house this implementation. In particular, all the primary CGI variable values are derived either directly or indirectly from the container's implementation of the Servlet API methods.

        protected void run() throws IOException {
            /*
             * REMIND:  this method feels too big; should it be re-written?
             */
            if (!isReady()) {
                throw new IOException(this.getClass().getName()
                                      + ": not ready to run.");
            }
            if ( >= 1 ) {
                log("runCGI(envp=[" +  + "], command=" +  + ")");
            }
            if ((.indexOf(. + "." + .) >= 0)
                || (.indexOf(. + "..") >= 0)
                || (.indexOf(".." + .) >= 0)) {
                throw new IOException(this.getClass().getName()
                                &