Embedthis Appweb 4.3.4
Home >ESP Guide > Embedded Server Pages

# Quick Nav

# See Also

# Session and Flash Storage

Session storage is a limited, semi-permanent store for keeping state information across web requests. The HTTP protocol by design, encourages stateless implementations and so Session state storage provides an essential context for a series of requests.

Appweb provides a high performance, in-process session state store. The store is managed in that Appweb imposes a session timeout on information and will automatically prune stale information. It uses the Appweb memory limit configured by the LimitMemory directive to restrict the amount of memory that is devoted to session state.

## Sample Code

    if (!(id = getSessionVar("user-id")) != 0) {
        redirect("/login");
    }

This example (above) tests if a "user-id" is defined in the session store. If not, the user must login and is redirect to the login page.

    destroySession();
    createSession();

This forces the creation of a new session.

    setSessionVar("Name", "John");

This defines the "Name" variable to the value "John".

## ESP APIs

The ESP session state API is comprised of four key APIs:

- createSession
- destroySession
- getSessionVar
- setSessionVar

## Flash Storage

ESP provides a traditional get/set key/value store. But it also provides a "flash" storage for passing information to the next web request (only). Thereafter, the flash information is automatically removed. Flash storage is useful to easily pass and manage feedback or notification messages for the next web page. Using session state for this is problematic as the message can easily display on web pages other than the immediate next web page. Flash storage will automatically remove the message after the next web page.

### Flash Types

Flash messages are divided into different types:

- Errors — An error occurred and the operation failed.
- Warnings — A warning has been issued, but the operation succeeded.
- Informational — The operation succeeded and this is just for feedback.
- Other — Any other kind of message.

When ESP generates flash messages in a web page, it emits a CSS style corresponding to the message type. This permits all errors to be flagged to the user using an "error" style. Similarly, for warnings and informational errors.

### Defining Flash Messages

To issue a flash message for the next web page, use one of the APIs: "error", "inform", "warn", "setFlash",

    inform("Document saved");
    warn("Session is about to expire in %d seconds", seconds);
    error("Could not save document");
    setFlash("custom", "Could not save document %s", myDocument);

You can use "setFlash" to define a custom type flash message using a type of your choosing.

### Displaying Flash Messages

To display flash messages in a web page, use the flash() API.

    <% flash("all", NULL); %>

This will display all flash messages and then erase them from the flash store.

## Configuring Session

Session data has a lifespan defined by the SessionTimeout configuration file directive. When this timeout expires, Appweb will prune the data from the session store.

If there is a low memory condition, Appweb may prune session data prematurely to free up memory. The maximum memory limit may be configured by the LimitMemory configuration directive.

## Performance Considerations

### Minimize Session Data Size

To maximize the performance of your application, try to minimize the size of data stored in the session state store. Session data is copied to and from the store. Unnecessary copies will slow your application.

### Minimize Session Data Reads and Writes

It is important not to read from the session store repeatedly. During one request, try to read session data once and keep a reference to the data for the duration of that request.

© Embedthis Software LLC, 2003-2013. All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.