Use cookies

The web view keeps cookies for the sites that a window shows, and Java can read and change all of them. That lets the application sign a user in without a login page: Java sets the session cookie, and the site finds the user signed in. In this guide, Java sets four cookies, the page reads the ones that it may, and Java signs the user out by clearing them.

Set a cookie from Java

application.cookies() returns the cookies of the engine, which every window of the application shares. Build a Cookie and set it:

public class SessionCookies {
  public static void main(String[] args) throws Exception {
    try (Application application = Application.create()) {
      // The window exists, hidden, before the cookies do: Windows keeps them in its profile.
      Window window =
          application.open(
              WindowParameters.builder().title("Cookies").size(new WindowSize(560, 230)).build());
      Cookies cookies = application.cookies();
      cookies
          .set(
              Cookie.builder()
                  .name("session")
                  .value(SessionCookies.token())
                  .domain("example.com")
                  .secure(true)
                  .httpOnly(true)
                  .build())
          .get(10, TimeUnit.SECONDS);
      cookies
          .set(Cookie.builder().name("theme").value("dark").domain("example.com").build())
          .get(10, TimeUnit.SECONDS);
      cookies
          .set(
              Cookie.builder()
                  .name("lang")
                  .value("en")
                  .domain("example.com")
                  .expires(Instant.now().plus(Duration.ofDays(30)))
                  .build())
          .get(10, TimeUnit.SECONDS);
      // The page loads after the cookies are set, so its first request carries them.
      window.navigate("https://example.com/");
      window.show();
      application.run();
    }
  }
}

The engine keeps its cookies in a process of its own, so every method of Cookies returns a CompletableFuture. A cookie that you set goes with the next request of the page. The pictures use a local page at 127.0.0.1 in place of example.com, with the same calls.

Component	What it does
name, domain	Required. domain is the host of the site; one that starts with a dot, such as .example.com, belongs to its subdomains too
value	The value. Default: empty
path	The path under which the browser sends the cookie. Default: /
expires	When the cookie goes. null, the default, makes a session cookie, which goes when the application ends
secure	Whether the browser sends it over HTTPS only
httpOnly	Whether the page can't read it through document.cookie
sameSite	NONE, LAX, or STRICT: when the browser sends it with a request that another site started. null leaves the choice to the engine

A SameSite.NONE cookie works only when it's secure, which is a rule of the browsers, not of lwjwae.

Read the cookies

List<Cookie> sent = cookies.get("https://example.com/account").get(10, TimeUnit.SECONDS);
List<Cookie> all = cookies.getAll().get(10, TimeUnit.SECONDS);

get(url) returns the cookies that the engine would send with a request to that URL, which depends on the domain, the path, and secure. getAll() returns every cookie of every site. A cookie that a site set is in the list once its response has come, so Java sees what a login of the site left behind.

See what the page sees

The page has document.cookie, and it sees the cookies that Java set, apart from the ones that Java marked httpOnly:

document.cookie; // "theme=dark; lang=en"
document.cookie = "visits=1; path=/";

In the picture, Java prints four cookies, and the page lists three: session is httpOnly, so only requests carry it. The page set visits itself, and Java sees that cookie too. Keep the token of a sign-in httpOnly: a script of the page then can't read it, whatever the page loads.

Sign the user out

delete removes the cookie of the name, the domain, and the path of the one that you pass, and clear removes every cookie:

cookies.delete(Cookie.builder().name("session").domain("example.com").build()).get(10, TimeUnit.SECONDS);
cookies.clear().get(10, TimeUnit.SECONDS);

Java sees the change at once. The page keeps a cache of its cookies, which the engine updates when its network process tells it, so document.cookie shows the old list for a moment longer.

Good to know

• Wait for the future before you load a page that needs the cookie: get(10, TimeUnit.SECONDS) above, or thenRun for a page that doesn't block.
• On Windows, the cookies belong to the profile of the web view, which a window creates. Open a window before you call application.cookies().
• Cookies are not the place for data that the application owns. For that, use the store.