10. Resources

AWS support embedded resources. It means that it is possible to build a fully self dependent executable. This is useful when distributing a server. The server program contains the code but also the images (PNG, JPEG, GIF), the templates, the HTML pages… more generally any file the Web Server must serve to clients.

10.1. Building resources

To embbed the files into the executable you must build a resource tree. This task is greatly simplified using AWSRes tool. For example let’s say that you want to build a simple server with a single page containing some text and one PNG image. The text is handled directly in the callback procedure and contain a reference to the image logo.png. To build the resource tree:

$ awsres logo.png

This will create a set of packages whose root is the unit res by default. The resource tree is created. See awsres tool for the complete AWS’s usage description.

awsres can also compress the resource files. This can be done by using awsres’s -z option. Compressed resources are handled transparently. If the Web client supports compression the resource is sent as-is otherwise a decompression stream will be created for the resource to be decompressed on-the-fly while sending it.

10.2. Using resources

This is really the simplest step. The resource tree must be linked with your executable, to do so you just have to ‘with’ the resource tree root into one of your program unit. This will ensure that the resource tree will be compiled and linked into the executable. AWS and Templates_Parser know about resource files and will pick them up if available.

Note that this is transparent to users. It is possible to build the very same server based on standard files or resources files. The only change in the code is to ‘with’ or not the resource tree.

Note that AWS supports only a single resource tree. If more than one resource tree is included into a program only one will be seen.

10.3. Stream resources

Users can build a response directly from a stream. In this case the callback answer is built using AWS.Response.Stream. It creates a resource object whose operations have been inherited from AWS.Resource.Stream.Stream_Type and redefined by the user. So the Read operation can dynamically create the result stream data, the End_Of_File operation must returns True when the stream data is out and so on. This feature is useful to let users completely create and control dynamically AWS’s response content.

See AWS.Resources.Streams.

10.4. awsres tool

AWSRes is a tool to build resource files. It creates a root package named res by default and a child package for each resource file:

Usage: awsres [-hopqrRuz] file1/dir1 [-uz] [file2/dir2...]

-a

packages are named after the actual filenames

-h

Display help message.

-o

Specify the output directory, by default it is the current directory.

-p name

Append the specified prefix to the resource names.

-q

Quiet mode.

-R

Activate recursive behavior. In this mode awsres will parse recursively all subdirectories. If a directory is specified on the command line then all files in this directory and sub-directories will be added. If a file (possibly a pattern) is specificed on the command line then only files matching in directroy and sub-directories will be added.

-r name

Set the root unit name. Default is res.

-u

Add following files as uncompressed resources.

-z

Add following files as compressed resources.