# How the DD Poker Wicket Web Application Handles User Sessions and Profiles

> Discover how the DD Poker Wicket web app manages user sessions and profiles with custom sessions, cookie auto-login, and Spring-integrated validation. Learn about their session handling.

- Repository: [Doug Donohoe/ddpoker](https://github.com/dougdonohoe/ddpoker)
- Tags: internals
- Published: 2026-02-28

---

**The DD Poker Wicket web application handles user sessions and profiles by overriding `newSession()` in `PokerWicketApplication` to instantiate a custom `PokerSession` that stores a `PokerUser` wrapper, while `LoginUtils` manages authentication through cookie-based auto-login and form-based validation against Spring-managed profile services.**

The DD Poker web site is built on Apache Wicket and implements a clear, layered approach to tracking visitor identity and permissions. This architecture demonstrates how to extend Wicket's standard `WebSession` to maintain authenticated state across HTTP requests while integrating with database-backed user profiles. Understanding this implementation provides a complete blueprint for customizing session management in Wicket-based web applications.

## Customizing the Wicket Application Entry Point

The session lifecycle begins in `PokerWicketApplication`, which extends `BaseWicketApplication` (itself extending `WebApplication`). During initialization, the application overrides the `newSession()` method to ensure every HTTP request receives the custom session type rather than the default Wicket implementation.

In [`code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerWicketApplication.java`](https://github.com/dougdonohoe/ddpoker/blob/main/code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerWicketApplication.java), the method at lines 151-158 returns a new `PokerSession` instance:

```java
@Override
public Session newSession(Request request, Response response) {
    return new PokerSession(request);
}

```

The base class `BaseWicketApplication` (located in [`code/wicket/src/main/java/com/donohoedigital/wicket/BaseWicketApplication.java`](https://github.com/dougdonohoe/ddpoker/blob/main/code/wicket/src/main/java/com/donohoedigital/wicket/BaseWicketApplication.java)) handles Spring injection, request-cycle listeners, and markup settings, providing the foundation that allows `PokerSession` to operate within a Spring-managed environment.

## Storing User State in PokerSession

The `PokerSession` class serves as the concrete `WebSession` implementation that persists for the duration of a user's HTTP session. Its primary responsibility is maintaining a **single `PokerUser` instance** that represents either an authenticated or anonymous profile.

Key methods in [`code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerSession.java`](https://github.com/dougdonohoe/ddpoker/blob/main/code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerSession.java) include:

- **`getLoggedInUser()`** – Returns the stored `PokerUser` or null if unauthenticated
- **`setLoggedInUser(PokerUser u)`** – Stores the user and calls `bind()` to persist the session to the servlet container
- **`isLoggedIn()`** – Performs a simple null check on the stored user
- **`isLoggedInUserAdmin()`** – Convenience method checking if the user's name indicates administrative privileges

The session binding occurs explicitly when setting the user:

```java
private PokerUser loggedInUser;

public void setLoggedInUser(PokerUser loggedInUser) {
    this.loggedInUser = loggedInUser;
    this.bind();          // persists the session
}

```

The `PokerUser` class (in [`code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerUser.java`](https://github.com/dougdonohoe/ddpoker/blob/main/code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerUser.java)) acts as a **lightweight wrapper** around the persistent `OnlineProfile` entity. It carries UI-relevant fields including name, email, license key, and retirement status, plus an `authenticated` boolean indicating whether the user has verified their password in the current session.

## Authenticating Users via LoginUtils

All authentication logic resides in `LoginUtils`, which supports two entry points: cookie-based auto-login for returning visitors and form-based login for explicit authentication. Both paths converge on a private `login()` method that validates credentials and populates the session.

In [`code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/util/LoginUtils.java`](https://github.com/dougdonohoe/ddpoker/blob/main/code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/util/LoginUtils.java), the typical authentication sequence involves:

1. **Retrieving the profile** – Calling `profileService.getOnlineProfileByName(name)` to fetch the `OnlineProfile` entity
2. **Validation** – Checking activation status, ban records, and password correctness (for form-based logins)
3. **Session population** – Creating a `PokerUser` wrapper and storing it in the session

```java
OnlineProfile profile = profileService.getOnlineProfileByName(name);
...
// validate activation, bans, password (if page login)
PokerUser user = new PokerUser(profile);
user.setAuthenticated(authenticated);
PokerSession.get().setLoggedInUser(user);

```

When the *remember-me* flag is set during form login, `LoginUtils` creates a persistent cookie via `WicketUtils.createCookie(LOGIN, name)`, allowing subsequent sessions to re-authenticate automatically without password entry.

## Integrating Spring-Managed Profile Services

The authentication layer connects to persistent storage through Spring-managed services exposed by the application class. `PokerWicketApplication` provides accessor methods for `OnlineProfileService` and `BanService`, which `LoginUtils` accesses statically.

From [`code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerWicketApplication.java`](https://github.com/dougdonohoe/ddpoker/blob/main/code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerWicketApplication.java) lines 69-74, the application exposes:

```java
public OnlineProfileService getProfileService() {
    return profileService;
}

public BanService getBanService() {
    return banService;
}

```

`LoginUtils` retrieves these services via `PokerWicketApplication.get().getProfileService()` to perform database lookups during the authentication process. This architecture decouples the web layer from direct data access while maintaining type-safe service injection through the Wicket-Spring integration.

## Summary

- **Custom Session Creation** – `PokerWicketApplication.newSession()` returns `PokerSession` instances to replace default Wicket session handling
- **Session State Storage** – `PokerSession` maintains a `PokerUser` wrapper and calls `bind()` to persist HTTP session state
- **Dual Authentication Paths** – `LoginUtils` supports both cookie-based auto-login and form-based password validation
- **Profile Wrapping Pattern** – `PokerUser` decouples the UI session from the persistent `OnlineProfile` entity while carrying authentication status
- **Service Integration** – Spring-managed `OnlineProfileService` and `BanService` are accessed through the application singleton for database operations

## Frequently Asked Questions

### How does PokerSession differ from standard Wicket WebSession?

`PokerSession` extends Wicket's `WebSession` to add a typed `loggedInUser` field specifically for storing `PokerUser` instances. Unlike the generic session, it provides semantic methods like `isLoggedIn()` and `isLoggedInUserAdmin()`, and explicitly calls `bind()` during `setLoggedInUser()` to ensure the servlet container persists the session.

### What is the relationship between PokerUser and OnlineProfile?

`PokerUser` is a lightweight, session-scoped wrapper that carries a subset of `OnlineProfile` data needed for UI decisions, including display name, email, and license status. While `OnlineProfile` represents the persistent database entity managed by `OnlineProfileService`, `PokerUser` adds an `authenticated` flag that indicates whether the current session has verified the user's password.

### How does the remember-me cookie authentication work?

When a user selects "remember me" during form login, `LoginUtils` creates a cookie named "login" containing the username. On subsequent visits, `LoginUtils.loginFromCookie()` reads this cookie, retrieves the corresponding `OnlineProfile` through the service layer, validates that the account is active and not banned, then reconstructs the `PokerUser` in the new session without requiring password re-entry.

### Where is the session binding logic implemented?

The explicit session binding occurs in `PokerSession.setLoggedInUser()` at [`code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerSession.java`](https://github.com/dougdonohoe/ddpoker/blob/main/code/pokerwicket/src/main/java/com/donohoedigital/games/poker/wicket/PokerSession.java). This method calls `this.bind()`, which triggers Wicket's mechanism for marking the HTTP session as dirty and requiring persistence by the servlet container, ensuring the `PokerUser` survives across requests.