Session Management

Secure session handling with configurable timeouts, secure cookies, and per-page overrides.

OorianSession

A clean wrapper around the servlet session with a simplified API, secure defaults, and full integration with Oorian's page lifecycle.

Idle Timeout

Configurable idle timeout that automatically invalidates sessions after a period of inactivity. Set globally or override per page.

Absolute Timeout

Set a maximum session lifetime regardless of activity. Ensures sessions expire after a fixed duration for compliance and security.

Secure Cookies

Session cookies are configured with HttpOnly, Secure, and SameSite attributes by default. No manual configuration required.

Per-Page Overrides

Sensitive pages like admin panels or financial transactions can define shorter timeouts without affecting the rest of your application.

Session Events

Listen for session lifecycle events such as creation, expiration, and invalidation. Perform cleanup or logging when sessions end.

Accessing the Session

OorianSession is Oorian's wrapper around the servlet session. It provides a cleaner API with built-in security features, typed attribute access, and static access from anywhere in your application. Use OorianSession instead of HttpSession directly.

From Anywhere

Java

// Static access from any class
OorianSession session = OorianSession.get();

session.setAttribute("theme", "dark");
String theme = session.getAttributeAsString("theme");

The static get() method returns the OorianSession bound to the current thread. This works from pages, event handlers, worker threads, and any code running within an Oorian request.

From a Page

Java

public class DashboardPage extends HtmlPage
{
    @Override
    protected void createBody(Body body)
    {
        OorianSession session = getSession();

        String userId = session.getUserId();
        User user = (User) session.getAttribute("user");

        // Build page using session data
        body.addElement(new H1("Welcome, " + user.getName()));
    }
}

Inside an HtmlPage, call getSession() for a convenient shorthand. Both approaches return the same OorianSession instance.

Storing and Retrieving Attributes

OorianSession provides typed getters for common data types, eliminating manual casting and null checks. Each typed getter has an overload that accepts a default value, so you can safely read attributes without extra null-handling code.

Java

OorianSession session = getSession();

// Store any object
session.setAttribute("currentUser", user);
session.setAttribute("cartTotal", 149.99);
session.setAttribute("isAdmin", true);
session.setAttribute("loginCount", 42);

// Retrieve with type-safe getters
User user = (User) session.getAttribute("currentUser");
double total = session.getAttributeAsDouble("cartTotal", 0.0);
boolean admin = session.getAttributeAsBoolean("isAdmin", false);
int count = session.getAttributeAsInt("loginCount", 0);
String theme = session.getAttributeAsString("theme", "light");

// Remove an attribute
session.removeAttribute("cartTotal");

Available Typed Getters

getAttributeAsString(name)

Returns the attribute as a String, or null if not set. An overload accepts a default value.

getAttributeAsInt(name)

Returns the attribute as an Integer, or null. Overload with default value available.

getAttributeAsLong(name)

Returns the attribute as a Long, or null. Overload with default value available.

getAttributeAsDouble(name)

Returns the attribute as a Double, or null. Overload with default value available.

getAttributeAsBoolean(name)

Returns the attribute as a Boolean, or null. Overload with default value available.

getAttributeAsFloat(name)

Returns the attribute as a Float, or null. Overload with default value available.

Session Info

OorianSession exposes session metadata for monitoring, debugging, and implementing custom timeout or security logic. You can inspect the session ID, creation time, last access time, and authentication state.

Java

OorianSession session = getSession();

// Session identity
String id = session.getId();
boolean isNew = session.isNew();

// Timestamps (milliseconds since epoch)
long created = session.getCreationTime();
long lastAccess = session.getLastAccessedTime();

// Authentication
boolean loggedIn = session.isAuthenticated();
UserPrincipal principal = session.getPrincipal();
String userId = session.getUserId();

// Timeout management
session.setMaxInactiveInterval(1800); // 30 minutes
boolean expired = session.isExpired();

// End the session
session.invalidateSession();

Configuring Timeouts

Set idle and absolute timeouts in your Application class. Idle timeout invalidates sessions after a period of inactivity. Absolute timeout caps total session duration regardless of activity. Sensitive pages can override with shorter timeouts.

Java

// In Application.initialize()
@Override
protected void initialize(ServletContext context)
{
    registerPackage("com.myapp");

    // Idle timeout: 30 minutes
    setSessionIdleTimeout(Duration.ofMinutes(30));

    // Absolute timeout: 8 hours
    setSessionAbsoluteTimeout(Duration.ofHours(8));
}

// Per-page override for sensitive pages
@Page("/admin/settings")
public class AdminSettingsPage extends HtmlPage
{
    @Override
    protected Duration getPageIdleTimeout()
    {
        return Duration.ofMinutes(10);
    }
}

Cookies

Oorian provides OorianCookie, a framework-level cookie class decoupled from the servlet API. When secure cookie defaults are configured, every new cookie automatically inherits HttpOnly, Secure, and SameSite attributes—no manual configuration required.

Reading and Writing Cookies

Java

// Add a cookie from any page
OorianCookie cookie = addCookie("preference", "dark-mode");
cookie.setMaxAge(60 * 60 * 24 * 30); // 30 days
cookie.setPath("/");

// Read a cookie by name
OorianCookie pref = getCookie("preference");

if (pref != null)
{
    String value = pref.getValue();
}

// Read with a default value (creates cookie if missing)
OorianCookie lang = getCookie("language", "en");

Secure Cookie Defaults

Configure global cookie security in your Application class. Once set, every OorianCookie created anywhere in your application automatically inherits these defaults.

Java

@Override
protected void initialize(ServletContext context)
{
    registerPackage("com.myapp");

    // All cookies inherit these security attributes
    setSecureCookieDefaults(new CookieDefaults()
        .setHttpOnly(true)
        .setSecure(true)
        .setSameSite(SameSite.LAX));
}

HttpOnly

Prevents client-side JavaScript from accessing the cookie, protecting against XSS attacks that attempt to steal session tokens.

Secure

Ensures the cookie is only sent over HTTPS connections, preventing transmission over unencrypted channels.

SameSite

Controls whether the cookie is sent with cross-site requests. Lax is the recommended default, providing CSRF protection while allowing top-level navigations.

Benefits

Secure Defaults

Session cookies are configured with HttpOnly, Secure, and SameSite attributes out of the box. Your application is protected without any manual security configuration.

Typed Attribute Access

Read session attributes as String, int, long, double, float, or boolean without manual casting. Default-value overloads eliminate null checks and simplify your code.

Configurable Timeouts

Set idle and absolute timeouts at the application level to match your security requirements. Idle timeouts invalidate inactive sessions, while absolute timeouts cap total session duration.

Per-Page Overrides

Sensitive pages can define stricter timeout policies without changing global settings. An admin panel might use a 10-minute idle timeout while the rest of the app uses 30 minutes.

Static Access

Access the current session from anywhere in your code with OorianSession.get(). No need to pass session references through method parameters or store them in fields.

Next FeatureLightweight Configuration System

→