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 an IBM® WebSphere® sMash 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

WebSphere sMash 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 Employees {
        function onGET() {
                
echo
 "Response from a GET request";
        }
}
?>

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

Supported Encoding format

WebSphere sMash currently supports the UTF-8 encoding format only. If the browser is set to any other encoding format other than UTF-8, some of the APIs in WebSphere sMash like retrieving request parameters may not work correctly.

Path information and search order

For executable files the file that will be executed is the first matching file that can be located by walking down the directory structure. Everything after the first matching file is considered to be path information and can be accessed using GlobalContext.zget("/event/pathInfo"). 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 WebSphere sMash applications:

index.groovy

index.gt

index.html

directory listing (if enabled) or 403

For PHP WebSphere sMash applications, the search order is:

index.php

index.html

directory listing (if enabled) or 403

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<File> 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.