================================================================================
 employee  -  JSP / JavaBeans Web Application
================================================================================

A small practice project that demonstrates JavaBeans + JSP in a servlet
container. An "Add Employee" form posts to a JSP, which uses <jsp:useBean> to
populate a JavaBean (Employee), stores it in the session, and renders the
resulting list as an HTML table. Two annotated servlets are included to show
request/response handling.


--------------------------------------------------------------------------------
1. APPLICATION URL
--------------------------------------------------------------------------------

    http://localhost:9090/employee/index.html

    (Requires the Tomcat server to be running - see section 5.)


--------------------------------------------------------------------------------
2. TECHNOLOGIES USED
--------------------------------------------------------------------------------

    Project type     Dynamic Web Project (WTP)
    Java             JDK 1.8 (source / target 1.8)
    Web standard     Jakarta EE / Java EE Web 4.0 (jst.web facet)
    Server runtime   Apache Tomcat 9.0.x
    Servlet API      javax.servlet (servlet-api.jar shipped with Tomcat 9)
    IDE              Eclipse IDE for Enterprise Java and Web Developers
    Front end        Plain HTML + Bootstrap 5 (local copy in webapp/css)
    Build tool       None (Eclipse only - no Maven / Gradle in this project)


--------------------------------------------------------------------------------
3. PREREQUISITES
--------------------------------------------------------------------------------

    a) JDK 8 installed (JAVA_HOME set). Java 11+ will NOT work with the
       servlet-api.jar / jst.web facet combination used here.

    b) Eclipse IDE for Enterprise Java and Web Developers (not the plain
       "JavaSE" package). The package that ships "Eclipse Web Developer Tools"
       is required, because the project uses the JST facets and the Servers
       view.

    c) Apache Tomcat 9.0.x extracted to a folder of your choice.
       This machine uses: D:\sandeep\javaBasics-workspace\apache-tomcat-9.0.122

    d) This project folder, imported as an existing project (see section 4).
       Do NOT create a new project - the .project / .classpath / .settings
       files already carry the correct configuration.


--------------------------------------------------------------------------------
4. PROJECT STRUCTURE
--------------------------------------------------------------------------------

    employee/
     |
     +-- readme.txt                     This file
     +-- requirement-jsp.txt            Original task description / notes
     +-- .classpath                     JRE + servlet-api.jar + web containers
     +-- .project                       Eclipse project descriptor
     +-- build/classes/                 Compiled .class output folder
     |
     +-- .settings/                     Facets, JDT compiler, JSDT settings
     |
     +-- src/main/java/com/vs/
     |       GreetingServlet.java      @WebServlet("/GreetingServlet")
     |       ServerInfoServlet.java    @WebServlet("/server-info")
     |       bean/Employee.java        JavaBean: id (int), name (String)
     |       bean/BeanTest.java        Plain main() test for the bean
     |
     +-- src/main/webapp/
             index.html                 Add Employee form  (START HERE)
             process.jsp                Handles the form POST, shows the table
             second.jsp                 "View All" page, reads from session
             hello.jsp                  Minimal JSP hello-world sample
             info.jsp                   Prints Tomcat / JVM environment info
             css/bootstrap.min.css      Bootstrap 5
             css/styles.css             Extra custom styles
             WEB-INF/web.xml            Minimal descriptor (4.0) - servlets
                                       are declared with @WebServlet annotations
             WEB-INF/lib/               Extra jars go here (currently empty)
             META-INF/MANIFEST.MF

    Context path when deployed by Eclipse: /employee
    (it comes from the project name, so keep the project named "employee")


--------------------------------------------------------------------------------
5. SETUP AND RUNNING IN ECLIPSE  (step by step)
--------------------------------------------------------------------------------

STEP 1 - Import the project
    1. Start Eclipse.
    2. File > Import...
    3. General > Existing Projects into Workspace > Next.
    4. Select the root directory "D:\sandeep\javaBasics-workspace\employee"
       (or "Select root directory" and browse to the employee folder).
    5. Make sure the "employee" project is ticked in the Projects list.
    6. Click Finish.

    If Eclipse shows the project with a red X on the JRE line, continue to
    step 2 - it is the missing JDK, not a broken project.


STEP 2 - Point the project at a JDK 8
    1. Right-click the "employee" project > Properties > Java Build Path >
       Libraries tab.
    2. Select "JavaSE-1.8" (or the JRE System Library showing a red cross)
       and click "Edit...".
    3. Choose "Alternate JRE" > "Workspace default JRE", or browse to your
       JDK 1.8 folder (for example C:\Program Files\Java\jdk1.8.0_xxx).
    4. Apply and Close.

    Tip: you can register JDK 8 once under
         Window > Preferences > Java > Installed JREs > Add... and select it
         as the Workspace default, so step 2 only has to be done once.


STEP 3 - Fix the servlet-api.jar path  (IMPORTANT on a new machine)
    The project compiles against Tomcat's own servlet-api.jar, and
    .classpath stores an ABSOLUTE path to it:

        <classpathentry kind="lib"
            path="D:/sandeep/javaBasics-workspace/apache-tomcat-9.0.122/lib/servlet-api.jar"/>

    If your Tomcat is somewhere else (or you moved the workspace), the JAR
    will show up as a red / missing entry and the servlets will not compile.

    Fix it one of these ways:

    Option A (recommended) - let Eclipse manage it:
        1. Project > Properties > Java Build Path > Libraries.
        2. Select the broken "servlet-api.jar" entry > Remove.
        3. Click "Add Library..." > "Server Runtime" > Next.
        4. Pick "Apache Tomcat v9.0" > Finish.
        5. Move it below the JRE entry so the JRE stays first (Build Order tab
           lets you move entries up/down), then Apply and Close.

    Option B - browse to your own copy:
        1. Project > Properties > Java Build Path > Libraries > Add JARs...
        2. Select <your-tomcat>\lib\servlet-api.jar.
        3. Apply and Close.

    Do NOT add servlet-api.jar from the project's WEB-INF/lib, and do NOT copy
    Tomcat's servlet jars into the workspace - the Server Runtime option above
    is the supported way.


STEP 4 - Verify the facets
    1. Right-click "employee" > Properties > Facets.
    2. You should see these installed facets:
           - Dynamic Web Module : 4.0
           - Java               : 1.8
           - JavaScript / wst.jsdt.web : 1.0
    3. If "Dynamic Web Module" is not ticked, tick it, select version 4.0 and
       click Apply and Close.


STEP 5 - Create / configure the Tomcat server
    1. Open the Servers view:
           Window > Show View > Servers   (or Window > Show View > Other...
           > Server > Servers)
    2. In the Servers view click the "No servers are available. Click this link
       to create a new server..." link.
    3. Expand "Apache Tomcat" and select "Tomcat v9.0 Server" > Next.
    4. "Tomcat installation directory" -> Browse to your Tomcat 9 folder,
       e.g. D:\sandeep\javaBasics-workspace\apache-tomcat-9.0.122
       (the folder that contains bin\ and conf\) > Next > Finish.
    5. Open "Server Locations" (double-click the server entry, or right-click >
       Open).
       - Select "Use Tomcat installation (base directory)".
       - IMPORTANT: the Application name / path field must read:
             /employee
         If it reads something else (e.g. /employee_war), edit it so the
         context path is exactly /employee. This is what makes
         http://localhost:9090/employee/index.html resolve.
    6. Open the "Ports" tab and set the HTTP port to 9090 (already configured on
       this machine):
           (HTTP) = 9090
       Click Next > Finish.
       Port 9090 is what every URL in this file assumes.


STEP 6 - Add the project to the server
    1. In the Servers view, right-click the Tomcat server > "Add and Remove
       Projects...".
    2. Select "employee" in the Projects list, click "Add", then Finish.
    3. The project now appears under the server as "employee (employee)".


STEP 7 - Run
    1. Right-click the Tomcat server in the Servers view > "Start".
       Wait until the Console shows "Server startup in ... ms".
    2. Right-click the "employee" project > "Run As" > "Run on Server".
       (Or double-click index.html > Open in Browser, and Eclipse will start
       the server and open the page for you.)
    3. The browser opens automatically. If it does not, go to the URL yourself:

            http://localhost:9090/employee/index.html


--------------------------------------------------------------------------------
6. HOW TO USE THE APPLICATION
--------------------------------------------------------------------------------

    1. Open      http://localhost:9090/employee/index.html
    2. Type a Name and an Employee Id into the form.
    3. Press "Add". The browser posts to process.jsp.
    4. process.jsp creates an Employee bean, copies the request parameters into
       it with <jsp:setProperty property="*"/>, appends it to a List held in
       the HTTP session, and renders the whole list as a table.
    5. Press "Add" again to add more rows - the table grows.
    6. Press "View All" to open second.jsp, which lists the employees that are
       currently in the session.

    Notes on behaviour:
    - The employee list lives in the session (in memory). Restarting Tomcat,
      or opening the app in a different browser / private window, starts a
      fresh empty list.
    - process.jsp only appends when the request is a real POST with a non-empty
      "name" parameter, so refreshing the results page does not add a blank
      row.
    - There is no database and no persistence layer in this project - that is
      intentional, it is a JSP/JavaBeans exercise.


--------------------------------------------------------------------------------
7. ALL AVAILABLE URLS  (once the server is running on port 9090)
--------------------------------------------------------------------------------

    Home / Add Employee form   http://localhost:9090/employee/index.html
    Form handler               http://localhost:9090/employee/process.jsp
    View all employees         http://localhost:9090/employee/second.jsp
    Hello JSP sample           http://localhost:9090/employee/hello.jsp
    Server info (JSP)          http://localhost:9090/employee/info.jsp
    Greeting servlet           http://localhost:9090/employee/GreetingServlet
    Server info (servlet)      http://localhost:9090/employee/server-info

    Tomcat manager (if enabled) http://localhost:9090/manager/html


--------------------------------------------------------------------------------
8. STOPPING THE SERVER
--------------------------------------------------------------------------------

    In the Servers view: right-click the Tomcat server > "Stop".
    "Terminate" force-kills it, "Restart" picks up changes to JSPs and Java
    classes automatically. You do not need to republish or redeploy manually.


--------------------------------------------------------------------------------
9. RUNNING BEANTEST AS A PLAIN JAVA PROGRAM
--------------------------------------------------------------------------------

    com.vs.bean.BeanTest has a main() method and needs no server.
    Right-click BeanTest.java > "Run As" > "Java Application".
    Console output:

        1  Arjun


--------------------------------------------------------------------------------
10. COMMON PROBLEMS AND FIXES
--------------------------------------------------------------------------------

    "The type javax.servlet.http.HttpServlet cannot be resolved"
    / red X on GreetingServlet.java or ServerInfoServlet.java
        -> The JRE is not Java 8, or the servlet-api.jar entry is broken.
           Repeat section 4 STEP 2 and STEP 3.

    "The project cannot be built until build path errors are resolved"
        -> A .classpath entry points to a file that no longer exists.
           Usually the Tomcat path. Repeat STEP 3 (Option A).

    HTTP 404 at http://localhost:9090/employee/index.html
        -> The project was not added to the server, the server is not started,
           or the context path is not "/employee".
           Check: Servers view > server > Add and Remove Projects, and
           Server Locations > Application name = /employee.

    HTTP 404 but http://localhost:9090/ works
        -> The webapp was deployed under a different context name.
           Fix the Application name in Server Locations to /employee, or use
           the exact context shown under Tomcat > employee in the Servers view.

    Port 9090 already in use
        -> Another process owns the port (another Tomcat, or an IDE-embedded
           server). Either stop that process, or change the HTTP port in the
           server's Ports tab and use that port in the URL instead.

    Changes to a JSP do not show up in the browser
        -> The page is cached, or the server was not restarted.
           Use Ctrl+F5 to hard-reload, then Restart the server if needed.

    "javax.servlet" not found at RUNTIME (500 error, ClassNotFoundException)
        -> The Web App Libraries / server runtime was removed from the classpath.
           Repeat STEP 3 Option A and redeploy (clean + republish).

    Tomcat window closes / "The Tomcat installation directory is not valid"
        -> The Tomcat path in STEP 5 is wrong; it must point at the folder that
           contains bin\ and conf\.


--------------------------------------------------------------------------------
11. MAKING THE servlet-api.jar PATH PORTABLE  (optional but recommended)
--------------------------------------------------------------------------------

    .classpath currently stores an absolute Windows path:

        D:/sandeep/javaBasics-workspace/apache-tomcat-9.0.122/lib/servlet-api.jar

    Anyone who clones this project on a different machine must fix it manually
    (section 4, STEP 3). Two ways to avoid the problem in future:

    Option 1 - Use a Classpath Variable (Eclipse-only, no files changed):
        Preferences > Java > Build Path > Classpath Variables > New...
        Name = TOMCAT_HOME, Path = <your tomcat folder>
        then in the project build path replace the jar with:
            ${env_var:TOMCAT_HOME}/lib/servlet-api.jar

    Option 2 - Convert the project to Maven:
        New > Maven Project, add javax.servlet:javax.servlet-api:4.0.1 with
        scope "provided", and remove the hardcoded jar entry. With Maven the
        build is then reproducible on any machine and in any IDE.

    Until one of these is done, always check STEP 3 after moving the workspace
    or Tomcat to a new folder.


================================================================================
 End of file
================================================================================