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

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, the method at lines 151-158 returns a new PokerSession instance:

@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) 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 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:

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) 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, 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

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 lines 69-74, the application exposes:

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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}