.\" This man page is automatically generated using
.\" kayadoc2man from the Kaya development tools and the -xmldocs compile 
.\" option. Editing it directly is not encouraged.
.\" It is under the same license as the source .k file that it was
.\" generated from.
.TH "Webapp.retrieveFunction" "3kaya" "August 2014" "Kaya" "Kaya module reference"
.SH "NAME"
Webapp::retrieveFunction \- Retrieve saved state
.SH "SYNOPSIS"
.B b retrieveFunction(
\fIb() defn, String(String) retriever, String key\fP
.B ")"
.SH "ARGUMENTS"
.PP
.B "defn"
The default function to call if the state key does not exist.
.PP
.B "retriever"
A function that returns the encoded state when given the key
.PP
.B "key"
The key to find the state
.SH "DESCRIPTION"
.PP
In some circumstances you may need to store application state in an external source, so that a user may save their session and return to it later.
This function lets you retrieve a saved state from an external source based on a key.
The function represented by the saved state is then executed. The retrieval function should throw an Exception if it can't find the key, which will cause the default function
\fBdefn \fP
to be executed instead. Otherwise, it should, given the key, return the state string that was stored using
.B "Webapp.storeFunction"(3kaya)

.PP
One use of this is to generate links to be sent via email, where the links generated by Kaya containing the state data itself are too long to be practical.
.PP
You should consider when writing the retrieval function whether the action of retrieving the state should delete it from the persistent storage.
.SH "AUTHORS"
Kaya standard library by Edwin Brady, Chris Morris and others (kaya@kayalang.org). For further information see http://kayalang.org/
.SH LICENSE
The Kaya standard library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License (version 2.1 or any later version) as published by the Free Software Foundation.
.SH "RELATED"
.PD 0
.PP
.B "Webapp.runHandler"(3kaya)
.PP
.B "Webapp.storeFunction"(3kaya)
.PD 0.4v