ikrs.httpd.filehandler
Class CGIHandler

java.lang.Object
  extended by ikrs.httpd.AbstractFileHandler
      extended by ikrs.httpd.filehandler.CGIHandler
All Implemented Interfaces:
FileHandler
Direct Known Subclasses:
PHPHandler

public abstract class CGIHandler
extends AbstractFileHandler

The CGI handler is an abstract class implementing some basic methods for the Common Gateway Interface.

Subclasses must implement these methods:
- List buildCGISystemCommand( ... )
- void buildAdditionalCGIEnvironmentVars( ... )
- Resource handleCGIOutput( ... )


Field Summary
static java.lang.String CGI_ENV_AUTH_TYPE
           
static java.lang.String CGI_ENV_CONTENT_LENGTH
           
static java.lang.String CGI_ENV_CONTENT_TYPE
           
static java.lang.String CGI_ENV_DOCUMENT_ROOT
           
static java.lang.String CGI_ENV_GATEWAY_INTERFACE
           
static java.lang.String CGI_ENV_HTTP_
           
static java.lang.String CGI_ENV_PATH_INFO
           
static java.lang.String CGI_ENV_PATH_TRANSLATED
           
static java.lang.String CGI_ENV_QUERY_STRING
           
static java.lang.String CGI_ENV_REMOTE_ADDR
           
static java.lang.String CGI_ENV_REMOTE_HOST
           
static java.lang.String CGI_ENV_REMOTE_IDENT
           
static java.lang.String CGI_ENV_REMOTE_USER
           
static java.lang.String CGI_ENV_REQUEST_METHOD
           
static java.lang.String CGI_ENV_REQUEST_URI
           
static java.lang.String CGI_ENV_SCRIPT_FILENAME
           
static java.lang.String CGI_ENV_SCRIPT_NAME
           
static java.lang.String CGI_ENV_SERVER_NAME
           
static java.lang.String CGI_ENV_SERVER_PORT
           
static java.lang.String CGI_ENV_SERVER_PROTOCOL
           
static java.lang.String CGI_ENV_SERVER_SOFTWARE
           
 
Constructor Summary
CGIHandler()
           
 
Method Summary
abstract  void buildAdditionalCGIEnvironmentVars(HTTPHeaders headers, java.io.File file, java.net.URI requestURI, java.util.Map<java.lang.String,java.lang.String> environment)
          Subclasses implementing the method may define additional/optional CGI environment settings.
abstract  java.util.List<java.lang.String> buildCGISystemCommand(HTTPHeaders headers, PostDataWrapper postData, java.io.File file, java.net.URI requestURI)
          Subclasses implementing this method must return a valid system command that can be executed directly using Java's ProcessBuilder.
protected  java.util.Set<java.lang.String> getDefaultIncludeHeadersSet()
          There is a default set of HTTP headers that should be included into the CGI environment.
abstract  Resource handleCGIOutput(HTTPHeaders headers, java.io.File file, java.net.URI requestURI, PostDataWrapper postData, ProcessableResource cgiOutput)
          After the CGI handler performed the system command the resulting resource must be handled.
 Resource process(java.util.UUID sessionID, HTTPHeaders headers, PostDataWrapper postData, java.io.File file, java.net.URI requestURI)
          The 'process' method is very generic.
 boolean requiresExistingFile()
          Most file handlers operate on existing files that are located inside the local file system (such as the default handler does for simple file delivery).
 
Methods inherited from class ikrs.httpd.AbstractFileHandler
getHTTPHandler, getLogger, setHTTPHandler, setLogger
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CGI_ENV_AUTH_TYPE

public static final java.lang.String CGI_ENV_AUTH_TYPE
See Also:
Constant Field Values

CGI_ENV_CONTENT_LENGTH

public static final java.lang.String CGI_ENV_CONTENT_LENGTH
See Also:
Constant Field Values

CGI_ENV_CONTENT_TYPE

public static final java.lang.String CGI_ENV_CONTENT_TYPE
See Also:
Constant Field Values

CGI_ENV_DOCUMENT_ROOT

public static final java.lang.String CGI_ENV_DOCUMENT_ROOT
See Also:
Constant Field Values

CGI_ENV_GATEWAY_INTERFACE

public static final java.lang.String CGI_ENV_GATEWAY_INTERFACE
See Also:
Constant Field Values

CGI_ENV_PATH_INFO

public static final java.lang.String CGI_ENV_PATH_INFO
See Also:
Constant Field Values

CGI_ENV_PATH_TRANSLATED

public static final java.lang.String CGI_ENV_PATH_TRANSLATED
See Also:
Constant Field Values

CGI_ENV_QUERY_STRING

public static final java.lang.String CGI_ENV_QUERY_STRING
See Also:
Constant Field Values

CGI_ENV_REMOTE_ADDR

public static final java.lang.String CGI_ENV_REMOTE_ADDR
See Also:
Constant Field Values

CGI_ENV_REMOTE_HOST

public static final java.lang.String CGI_ENV_REMOTE_HOST
See Also:
Constant Field Values

CGI_ENV_REMOTE_IDENT

public static final java.lang.String CGI_ENV_REMOTE_IDENT
See Also:
Constant Field Values

CGI_ENV_REMOTE_USER

public static final java.lang.String CGI_ENV_REMOTE_USER
See Also:
Constant Field Values

CGI_ENV_REQUEST_METHOD

public static final java.lang.String CGI_ENV_REQUEST_METHOD
See Also:
Constant Field Values

CGI_ENV_REQUEST_URI

public static final java.lang.String CGI_ENV_REQUEST_URI
See Also:
Constant Field Values

CGI_ENV_SCRIPT_FILENAME

public static final java.lang.String CGI_ENV_SCRIPT_FILENAME
See Also:
Constant Field Values

CGI_ENV_SCRIPT_NAME

public static final java.lang.String CGI_ENV_SCRIPT_NAME
See Also:
Constant Field Values

CGI_ENV_SERVER_NAME

public static final java.lang.String CGI_ENV_SERVER_NAME
See Also:
Constant Field Values

CGI_ENV_SERVER_PORT

public static final java.lang.String CGI_ENV_SERVER_PORT
See Also:
Constant Field Values

CGI_ENV_SERVER_PROTOCOL

public static final java.lang.String CGI_ENV_SERVER_PROTOCOL
See Also:
Constant Field Values

CGI_ENV_SERVER_SOFTWARE

public static final java.lang.String CGI_ENV_SERVER_SOFTWARE
See Also:
Constant Field Values

CGI_ENV_HTTP_

public static final java.lang.String CGI_ENV_HTTP_
See Also:
Constant Field Values
Constructor Detail

CGIHandler

public CGIHandler()
           throws java.lang.NullPointerException
Throws:
java.lang.NullPointerException
Method Detail

getDefaultIncludeHeadersSet

protected java.util.Set<java.lang.String> getDefaultIncludeHeadersSet()
There is a default set of HTTP headers that should be included into the CGI environment. Due to security reasons not all headers should be included! This set contains the headers that are allowed; all others will not be mapped. By default this set contains: - Accept - Accept-Charset - Accept-Encoding - Accept-Language - Connection - Cookie - Host - Referer - User-Agent It's up to your own risk to modify this list. Some application might not be working if some of these essential headers are missing.

Returns:
The HTTP-include-into-CGI set with HTTP headers that should be mapped into the CGI environment. The returned set is never null.

buildCGISystemCommand

public abstract java.util.List<java.lang.String> buildCGISystemCommand(HTTPHeaders headers,
                                                                       PostDataWrapper postData,
                                                                       java.io.File file,
                                                                       java.net.URI requestURI)
Subclasses implementing this method must return a valid system command that can be executed directly using Java's ProcessBuilder. The first list element must be the command name itself, all following elements are the command line arguments.

Parameters:
headers - The current request's HTTP headers.
postData - The current request's post data (a data wrapper holding the input stream).
file - The requested file (in the local file system).
requestURI - The request's URI (from headers.getRequestURI()).
Returns:
A list representing the system command.

buildAdditionalCGIEnvironmentVars

public abstract void buildAdditionalCGIEnvironmentVars(HTTPHeaders headers,
                                                       java.io.File file,
                                                       java.net.URI requestURI,
                                                       java.util.Map<java.lang.String,java.lang.String> environment)
Subclasses implementing the method may define additional/optional CGI environment settings. Note: there is no need to define the standard CGI environment as it is already contained in the handler's default mapping. The default vars are: - AUTH_TYPE - CONTENT_LENGTH - CONTENT_TYPE - GATEWAY_INTERFACE - HTTP_* - 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 See CGI specs or http://graphcomp.com/info/specs/cgi11.html for details. If the handler requires to overwrite pre-defined environment vars the method may change/remove the value in the given mapping. Handle with care. If the implementing handler has no additional environment vars the method may just do nothing.

Parameters:
headers - The current request's HTTP headers.
file - The requested file (in the local file system).
requestURI - The request's URI (from headers.getRequestURI()).
environment - The current environment settings and the target map.

handleCGIOutput

public abstract Resource handleCGIOutput(HTTPHeaders headers,
                                         java.io.File file,
                                         java.net.URI requestURI,
                                         PostDataWrapper postData,
                                         ProcessableResource cgiOutput)
                                  throws java.io.IOException
After the CGI handler performed the system command the resulting resource must be handled. The way the CGI output is handled differs from handler to handler as the underlying ran command produces different types of output. So it's up the the handler to process the generated data.

Parameters:
headers - The current request's HTTP headers.
file - The requested file (in the local file system).
requestURI - The request's URI (from headers.getRequestURI()).
cgiOutput - The actual CGI output; use cgiOutput.getEcitValue() to determine the return code of the CGI program.
postDataWrapper - The sent post data (a wrapper object containing the input stream).
Returns:
After the output was processed the returned resource should contain (optional) header replacements and returned script data.
Throws:
java.io.IOException

requiresExistingFile

public boolean requiresExistingFile()
Most file handlers operate on existing files that are located inside the local file system (such as the default handler does for simple file delivery). Some file handlers operate on virtual file systems, which means that the request URI does not necessarily address an existing file but a symbol only the handler may know. The global HTTP handler needs to know if to throw a MissingResourceException (resulting in a 404) if a requested file does not exists --- or if to ignore that fact and simply continue. This method tells how to proceed. If your implementation returns true this handler will not be called at all; the request processing will directly stop raising an HTTP status 404.

Specified by:
requiresExistingFile in interface FileHandler
Specified by:
requiresExistingFile in class AbstractFileHandler
Returns:
true if this file handler definitely requires existing files. The process(...) method will never be called if the requested file does not exist in that case.

process

public Resource process(java.util.UUID sessionID,
                        HTTPHeaders headers,
                        PostDataWrapper postData,
                        java.io.File file,
                        java.net.URI requestURI)
                 throws java.io.IOException,
                        HeaderFormatException,
                        DataFormatException,
                        UnsupportedFormatException
The 'process' method is very generic. It depends on the underlying implementation how the passed file should be processed.

Specified by:
process in interface FileHandler
Specified by:
process in class AbstractFileHandler
Parameters:
sessionID - The current session's ID.
headers - The HTTP request headers.
postData - The HTTP post data; if the method is not HTTP POST the 'postData' should be null (or empty).
file - The requested file itself (inside the local file system).
requestURI - The requested URI (relative to DOCUMENT_ROOT).
Throws:
java.io.IOException
HeaderFormatException
DataFormatException
UnsupportedFormatException