Expression Functions (Sun Java System Web Server 7.0 Update 6 Administrator's Configuration File Reference)

Sun Java System Web Server 7.0 Update 6 Administrator's Configuration File Reference

Expression Functions

Expression functions manipulate data for use in expressions. Expression functions are different from SAFs. While SAFs perform the actual work associated with an HTTP request, expression functions are used to select which SAFs run and what parameters to pass to the SAFs.

Some expression functions require one or more arguments. An expression function's argument list is bracketed by parentheses (()) and the individual arguments are separated by commas (,).

The individual expression functions are listed in the following sections:

atime

The atime function returns the time of the last access for the specified file or directory.

Syntax

atime(path)

Arguments

The following table describes the argument for the expression function.

Table A–4 atime Argument


Argument	Description
`path`	The absolute path to the directory or file name for which you are requesting the last access

choose

The choose function parses pipe-separated values from values and returns one at random.

Syntax

choose(values)

Arguments

The following table describes the argument for the expression function.

Table A–5 choose Argument


Argument	Description
`values`	The list of values to choose from, separated by the pipe character (`\|`)

Example

The following obj.conf code demonstrates the use of choose to randomly select one of three images:

NameTrans fn="rewrite"
          from="/images/random"
          path="/images/$(choose('iwsvi.jpg|0061.jpg|webservervii.jpg'))"

ctime

The ctime function returns the time of the last status change for the specified file or directory.

Syntax

ctime(path)

Arguments

The following table describes the argument for the expression function.

Table A–6 ctime Argument


Argument	Description
`path`	The absolute path to the directory or file name for which you are requesting the last status change

escape

The escape function encodes the URI using util_uri_escape, converting special octets to their %-encoded equivalents, and returns the result.

Syntax

escape(uri)

Arguments

The following table describes the argument for the expression function.

Table A–7 escape Argument


Argument	Description
`uri`	The URI that the expression function converts

external

The external function passes a value to an external rewriting program and returns the result.

Each invocation of external results in a single newline-terminated line being written to the external rewriting program's stdin. For each line of input, the program must produce a single line of output. When developing an external rewriting program, it is important to avoid buffering stdout. In Perl, for example, $| = 1; should be used to disable buffering. Because the server expects the external rewriting program to produce one line of output for each line of input, the server can hang if the external rewriting program buffers its output.

Syntax

external(program, value)

Arguments

The expression function has the following arguments.

Table A–8 external Arguments


Argument	Description
`program`	The `program` argument is the file name of an external rewriting program. Because `program` is executed using the operating system's default shell (`/bin/sh on Unix/Linux`) or the command interpreter (`CMD.EXE` on Windows), `program` should be an absolute path or the name of a program in the operating system's `PATH`. The server starts the external rewriting program on demand. A given server process never executes more than one instance of the program at a time. Note – The server may start multiple instances of a given external rewriting program when the server is running in multiprocess mode.
`value`	The value passed to the rewrite program.

Example

The following is an example of an external rewriting program rewrite.pl, used to change the prefix /home/ to /u/:

#!/usr/bin/perl
$| = 1;
while (<STDIN>) {
    s|^/home/|/u/|;
    print $_;
}

In this example, the external expression function used to invoke rewrite.pl is as follows:

NameTrans fn="rewrite" path="$(external('rewrite.pl', $path))"

httpdate

The httpdate function returns an RFC 1123 date/time stamp for use in HTTP header fields such as Expires.

Syntax

httpdate(time)

Arguments

The following table describes the argument for the expression function.

Table A–9 httpdate Argument


Argument	Description
`time`	The time value

Example

The following obj.conf code could be used to set an Expires header that indicates a response is not cached for more than one day:

ObjectType fn="set-variable"
           insert-srvhdrs="$(httpdate($time + 86400))"

lc

The lc function converts all the US ASCII characters in the string to lowercase and returns the result.

syntax

lc(string)

Arguments

The following table describes the argument for the expression function.

Table A–10 lc Argument


Argument	Description
`string`	The string the expression function converts to lowercase

Example

The following obj.conf code can be used to redirect clients who erroneously used uppercase characters in the request URI to the equivalent lowercase URI:

<If code == 404 and not -e path and -e lc(path)>
Error fn="redirect" uri="$(lc($uri))"
</If>

length

The length function returns the length of its argument, that is, a number representing the length of the string.

Syntax

length(string)

Arguments

The following table describes the argument for the expression function.

Table A–11 length Argument


Argument	Description
`string`	The string for which the expression function computes the length.

Example

The following obj.conf code can be used to send a 404 Not found error to clients that request URIs longer than 255 bytes:

<If length($uri) > 255)>
PathCheck fn="deny-existence"
</If>

lookup

The lookup function inspects a text file for a name-value pair with name name and returns the corresponding value. The name-value pairs in the file are separated by white space.

If the file does not contain a name-value pair with the specified name, this function returns the value of defaultvalue, if specified, or returns an empty string.

Syntax

lookup(filename, name, defaultvalue)

Arguments

The expression function has the following arguments:

Table A–12 lookup Arguments


Argument	Description
`filename`	`filename` is the name of a text file that contains one name-value pair per line. `filename` can be an absolute path or a path relative to the server's `config` directory. Names and values are separated by white space. Lines beginning with `#` are ignored.
`name`	The name of the name-value pair for which the function looks in the text file.
`defaultvalue`	The value returned by the function if `filename` exists but does not contain a name-value pair with a name matching the value of `name`. If `defaultvalue` is not specified, it defaults to an empty string.

Example

The following example shows a text file called urimap.conf that could be used with the lookup function to map shortcut URIs to URIs:

# This file contains URI mappings for Web Server.
# Lines beginning with # are treated as comments.
# All other lines consist of a shortcut URI, whitespace, and canonical URI.
/webserver /software/products/web_srvr/home_web_srvr.html
/solaris   /software/solaris/
/java      /software/java/

Using the sample text file above, you could use the following lookup expression to implement shortcut URIs for commonly accessed resources:

<If lookup('urimap.conf', uri)>
NameTrans fn="redirect" url="$(lookup('urimap.conf', uri))"
</If>

mtime

The mtime function returns the time of the last data modification for the specified file or directory.

Syntax

mtime(path)

Arguments

The following table describes the argument for the expression function.

Table A–13 mtime Argument


Argument	Description
`path`	The absolute path to the directory or file name for which you are requesting the last data modification

owner

The owner function returns the owner of a file.

Syntax

owner(path)

Arguments

The following table describes the argument for the expression function.

Table A–14 owner Argument


Argument	Description
`path`	The absolute path to the directory or file name for which you are requesting the last data modification

uc

The uc function converts all the US ASCII characters in string to uppercase and returns the result.

Syntax

uc(string)

Arguments

The following table describes the argument for the expression function.

Table A–15 uc Argument


Argument	Description
`string`	The string that the expression function converts to uppercase

unescape

The unescape function decodes the URI using util_uri_unescape, converting %-encoded octets to their unencoded form, and returns the result.

Syntax

unescape(uri)

Arguments

The following table describes the argument for the expression function.

Table A–16 unescape Argument


Argument	Description
`uri`	The URI that the function converts

uuid

The uuid function returns a UUID as a string. No two calls to uuid return the same UUID. Because they are guaranteed to be unique, UUIDs are useful for constructing client-specific cookie values.

Syntax

uuid()