================================================================================
 cookie-demo  -  Working with Cookies
================================================================================

Source: "Session 6 - Working with Cookies.pptx"
        STAGE 2 / Topic 1 - Servlet

    The deck declares the servlets in web.xml. This project uses the
    @WebServlet annotation instead, which needs no descriptor.


--------------------------------------------------------------------------------
1. WHAT IT DEMONSTRATES
--------------------------------------------------------------------------------

    1. Creating a cookie and adding it to the response   (response.addCookie)
    2. Reading cookies back from the request             (request.getCookies)
    3. Deleting a cookie                                  (setMaxAge(0))
    4. Non-persistent vs persistent cookies               (setMaxAge)

    Credentials: username "jai", password "1234"


--------------------------------------------------------------------------------
2. PROJECT STRUCTURE
--------------------------------------------------------------------------------

    cookie-demo/
     +-- readme.txt                    This file
     +-- .classpath / .project         Eclipse configuration
     +-- .settings/                    Facets, compiler settings
     |
     +-- src/main/java/com/vs/
     |       CreateCookieServlet.java  Creates the cookies on login
     |       GetCookieServlet.java     Reads and prints the cookies
     |       DeleteCookieServlet.java  Expires the cookies
     |       CookieDemoPage.java       Shared HTML output (not part of the lesson)
     |
     +-- src/main/webapp/
             index.html                Demo overview        (START HERE)
             login.html                Login form
             css/styles.css            Page styling

    The servlets are mapped with @WebServlet annotations, so there is no
    WEB-INF/web.xml. Without a descriptor the default welcome file applies,
    so http://localhost:9090/cookie-demo/ opens index.html.


--------------------------------------------------------------------------------
3. SETUP
--------------------------------------------------------------------------------

    a) Eclipse > File > Import > General > Existing Projects into Workspace
       > select the "cookie-demo" folder > Finish.
       (Import it - do not create a new project.)

    b) Project > Properties > Java Build Path > Libraries
       If servlet-api.jar has a red cross, remove it and add it again:
       Add Library... > Server Runtime > Apache Tomcat v9.0 > Finish.

    c) Servers view > right-click your Tomcat > Add and Remove Projects
       > Add "cookie-demo" > Finish.

    d) Right-click the Tomcat server > Start.


--------------------------------------------------------------------------------
4. RUN
--------------------------------------------------------------------------------

    Open:  http://localhost:9090/cookie-demo/login.html
    (or http://localhost:9090/cookie-demo/ for the overview page)

    1. Enter username "jai" and password "1234".
    2. Leave "Remember me" unchecked, click Login.
       -> Cookies are created (non-persistent).
    3. Click "Get Cookie".
       -> The cookies the browser sent back are printed in a table.
    4. Click "Delete Cookies".
       -> The cookies are expired.
    5. Log in again with "Remember me" CHECKED and click "Get Cookie".
       -> A "rememberMe=yes" cookie now appears.

    Use http://localhost:9090/ if your Tomcat runs on port 8080.


--------------------------------------------------------------------------------
5. HOW TO SEE PERSISTENT COOKIES
--------------------------------------------------------------------------------

    Non-persistent cookies are deleted when the browser closes, so use the
    browser's developer tools instead:

        F12 > Application (Chrome) or Storage (Firefox)
             > Cookies > http://localhost:9090

    A persistent cookie shows an "Expires" date; a non-persistent one shows
    "Session". The same information is in the Set-Cookie response header:

        Response Headers > Set-Cookie: userName=jai; Max-Age=604800; Expires=...

    After deleting the cookies, the Set-Cookie header changes to Max-Age=0.


--------------------------------------------------------------------------------
6. NOTES
--------------------------------------------------------------------------------

    * Deleting a cookie needs TWO calls - setMaxAge(0) AND addCookie(cookie).
      Setting the max age alone changes nothing, because the new expiry never
      reaches the browser.

    * request.getCookies() returns null when there are no cookies, never an
      empty array. Always null-check it.

    * This demo stores a plain-text password in a cookie. That is what the
      session teaches, but it is never acceptable in a real application.

    * Cookies are disabled in some browsers. If nothing works, check that
      cookies are allowed for localhost.


================================================================================