Customize

From Groom

Contents 1 Technical documentation 2 FileTypeHandler framework 3 Embedded handlers 4 Custom handlers

Technical documentation

Javadoc for the whole server can be found here: Javadoc Groom version 1.2 Inline documentation and javadoc tagging still needs huge improvement. However, external interfaces are detailled.

FileTypeHandler framework

Groom handlers are, generally speaking, the piece of code that will be called once an incoming query has been received, decoded and validated.

It takes in input basically the decoded request (headers, GET/POST parameters, request resource...) and is in charge of writing the content of the reply (i.e. the payload only, headers are written by the server itself, although handlers can sometimes write some headers too).

In the Configuration file, handlers are assigned too extensions, directories, and a default one is set. The class is then dynamically loaded by the server and instanciated when needed.

Embedded handlers

Here is the list of the embedded handlers provided by Groom (then can be used directly without addind anything):

• groom.handlers.CgiHandler: Handler for Common Gateway Interface (see PHP/CGI Configuration)
• groom.handlers.PhpHandler: Handler dedicated to PHP files (see PHP/CGI Configuration)
• groom.handlers.BinaryHandler: The most common one, used to serve all the files from the disk that do no need any special treatment
• groom.handlers.DirectoryHandler: Prints a listing of the requested directory
• groom.handlers.FancyDirectoryHandler: Same as above but looks better
• groom.handlers.GroomHandler: This handler display a diagnostic page (whatever the requested resource is), printing stats about the request served and the internal server configuration
• groom.handlers.TextHandler: Handler treating the requested resource as a text file that is read line per line. Usage of this one is discouraged, prefer BinaryHandler

Custom handlers

You have the possibility to create and use your how handlers. This can be particularly useful is you want to use Groom not to serve files from a disk, but as a server engine embedded inside a larger application/system.

To do so, your custom handler must depend on Groom jarfile and implement the interface groom.FileTypeHandler (more details here). I will not give much details about writing a handler, considering that looking at the source code should be enough to understand what you need to do (you can still email me if you cannot get through it).

Here is the source code of a dummy handler that just prints "Hello World" on the screen:

/* A very simple sample handler that prints Hello World */

import groom.GroomException;
import groom.HttpQuery;
import groom.LoggerInterface;
import java.io.IOException;
import java.io.OutputStream;

/*
 * @author Mathieu ALLORY
 */
public class HelloHandler implements groom.FileTypeHandler {

    private String _Display;
    private LoggerInterface _Logger;

    public void setResource(HttpQuery iQuery, LoggerInterface iLogger) {
        _Logger = iLogger;
        // Drop a log
        _Logger.log(this, 10, "In the place");
        // Access to the requested resource (real file path on the disk)
        // Just to show you, here we don't care
        _Logger.log(this, 10, "Requested resource: " + iQuery.Resource);
    }

    public long prefetch() throws GroomException {
        // Let's prefetch, just to get the size
        _Display = "Hello World";
        // Return length
        return _Display.length();
    }

    public void writeContent(OutputStream oStream) throws GroomException {
        try {
            // Just write the content of our stream
            oStream.write(_Display.getBytes());
            oStream.flush();
        } catch (IOException ex) {
            _Logger.logErr(this, 10, "Damned, we got an error !");
            // Sent back the error to the client using
            // the beautiful built-in error page
            throw new GroomException(GroomException.IO_ERROR);
        } 
    }

    public String getOverrideMimeType() {
        // In this particular case, we want to override the mime
        // type set in the configuration file
        return "text/plain";
        // You can return null and let the config do
    }

    public boolean mustFinalizeHeaders() {
        // By doing so the server will finalize the header
        // When calling writeContent, we can focus on the payload
        return true;
        // If you return false, you can send back additionnal headers
        // but you must finalise the header before writing payload data
    }

}