File serving

Static files, scripts, templates, and directory listings can be invoked and served directly out of the public folder. Files that implement REST conventions should instead be placed in the app/resources folder.

Files and directories in the public folder can be accessed by a client directly. For example, the file <appRoot>/public/world/hello.groovy is accessible via http://host/world/hello.groovy. The following sections of this article provide information about file serving:

Types of files that can be served

There are two types of files relative to file serving:

Executable file

A file associated with a Zero Interpreter. File suffix/Interpreter associations are registered in the GlobalContext under /config/interpreters. By default, .groovy and .gt files are executable.

Static file

Any other file.

Executable files are interpreted and the output of that interpretation is returned; for static files, the content of the file is returned.

Executable files can be accessed using the HTTP methods GET, HEAD, PUT, POST and DELETE. Static files and directory listings can only be accessed using the GET and HEAD methods; any other method results in a 405 Method Not Allowed error.

Groovy scripts

Groovy scripts (.groovy) can be either free-form scripts or organized around specific HTTP-method handlers.

The following example shows a complete free-form script:

println "Response from a " + request.method + " request"

The following example shows a complete script with HTTP-method handlers:

def onGET() {
        println "Response from a GET request"
}

// For example, fail the request for unsupported methods
request.status = 405

Zero first attempts to invoke an HTTP-method handler (for example, onGET() for an HTTP GET request). If no such method is found, then the entire script is run.

PHP scripts

PHP scripts (.php) can be either free-form scripts or organized as classes around specific HTTP-method handlers.

The following example shows a complete free-form script:

<?php
echo "Response from a ".get('/request/method'). " request";
?>

The following example shows a complete script with HTTP-method handlers:

<?php
include "zero.php";

class EmployeeCollection {
        function onGET() {
                echo "Response from a GET request";
        }
}
?>

Zero loads the script matching the restful resource uri and invokes an HTTP-method handler (for example, EmployeeCollection::onGET() for an HTTP GET request for /employees). If no such method is found or class is found it will send a 404.

Path information and search order

Path information is not allowed for static files, so the path the client tries to access must exactly match the file location or it will not be found.

Directory listing and Default files

When a client tries to access a directory, if there is an index.groovy file or index.gt file inside that directory, it is run and its output is returned. If neither of these files exists, but index.html file exists, then its content is returned. If neither of these files exist, a 403 Forbidden error message is returned, unless directory browsing has been allowed. To allow directory browsing, add the following lines to your zero.config file:

[/config/fileserver]
directoryBrowsing=true

Default search order summary for basic Zero applications:

For PHP Zero applications, the search order is:

Directory listings are rendered by the app/views/listing.gt template in zero.core. In order to override the template, you can either add listing.gt into views in your application, or set /config/fileserving/directoryView to your template name.

The virtual directory name is available in /request/directory and the children are in a List in /request/dirContents.

Serving files from dependencies

If any of the libraries your application depends on contain files in their public folders these files can be served from their virtualized directories. These files are all accessible as though they physically resided in the public directory, unless there are conflicts. When a file is requested by a client the application's public directory is searched first. If the file cannot be located there, the dependency list is searched in a breadth-first manner.

For a complete description of the search order used for finding files in dependencies, see the virtualized directories section.

Caching

By default, files are served with an Etag header that can be used to validate the next request on the server. If you want to turn this behavior off set /config/fileserver/setEtag to false.

Files are also served by default with a Cache-Control header with a max-age of 0. This behavior can be overridden by file extension. For example, to cache all .js files for 300 seconds, set /config/fileserver/expires/.js to 300. This will result in a Cache-Control header being served with a max-age of 300 for all .js files.