ikrs.httpd
Interface FileHandler

All Known Implementing Classes:

AbstractFileHandler, CGIHandler, IkarosExampleHandler, PHPHandler

public interface FileHandler

This FileHandler interface is meant for HTTP resources that represent executable files (in any way) inside the document root (such as CGI scripts, system commands, executables, ...). As configuration files such as .htaccess allow to define file handlers (AddHandler and SetHandler directives) there is the need to summarize those handlers together under one general interface. IMPLEMENTATION NOTE: subclasses should implement an empty-argument-list constructor to make the class instantiable using the Class.newInstance() method!

Method Summary

HTTPHandler	getHTTPHandler() Get get FileHandler's global HTTPHandler.
CustomLogger	getLogger() Get the custom logger to use to write log messages.
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).
void	setHTTPHandler(HTTPHandler handler) Set the global HTTP handler.
void	setLogger(CustomLogger logger) Set the logger to use.

Method Detail

getHTTPHandler

HTTPHandler getHTTPHandler()

Get get FileHandler's global HTTPHandler. Warning: as subclasses might be instantiated using the Class.newInstance() method in some very unusual cases the returned handler might be null. In that case be sure you have the handler set before by the use of setHTTPHandler(...).

Returns:

The global HTTP handler (if available).

setHTTPHandler

void setHTTPHandler(HTTPHandler handler)
                    throws java.lang.NullPointerException

Set the global HTTP handler.

Parameters:

handler - The new handler (must not be null).

Throws:

java.lang.NullPointerException - If handler is null.

getLogger

CustomLogger getLogger()

Get the custom logger to use to write log messages. Warning: as subclasses might be instantiated using the Class.newInstance() method in some very unusual cases the returned logger might be null. In that case be sure you have the logger set before by the use of setLogger(...).

Returns:

The logger to use (if available).

setLogger

void setLogger(CustomLogger logger)
               throws java.lang.NullPointerException

Set the logger to use.

Parameters:

logger - The new logger (must not be null).

Throws:

java.lang.NullPointerException - If logger is null.

requiresExistingFile

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.

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

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.

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