Duke’s Tutoring Case Study Example

The Duke’s Tutoring example application is a tracking system for a tutoring center for students. Students can be checked in and out and can visit the park. The tutoring center can track attendance and status updates and can store contact information for guardians and students. Administrators can maintain the tutoring center system.

Design and Architecture of Duke’s Tutoring

Duke’s Tutoring is a web application that incorporates several Jakarta EE technologies. It exposes both a main interface (for students, guardians, and tutoring center staff) and an administration interface (for staff to maintain the system). The business logic for both interfaces is provided by enterprise beans. The enterprise beans use the Jakarta Persistence to create and store the application’s data in the database. Figure 1, “Architecture of the Duke’s Tutoring Example Application” illustrates the architecture of the application.

Architecture diagram of the Duke’s Tutoring example application. Two clients access the main interface and the admin interface deployed in the web container. These interfaces communicate with enterprise beans deployed in the Jakarta Enterprise Beans container. The enterprise beans communicate with the database.

Figure 1. Architecture of the Duke’s Tutoring Example Application

The Duke’s Tutoring application is organized into two main projects: the dukes-tutoring-common library and the dukes-tutoring-war web application. The dukes-tutoring-common library project contains the entity classes and helper classes used by the dukes-tutoring-war web application, and dukes-tutoring-common is packaged and deployed with dukes-tutoring-war. The library JAR file is useful for allowing the entity classes and helper classes to be reused by other applications, such as a JavaFX client application.

Duke’s Tutoring uses the following Jakarta EE platform features:

Jakarta Persistence entities
- A custom Jakarta Bean Validation annotation, @Email, for validating email addresses
- A standard jta-data-source definition that will create the JDBC resource on deployment
- A standard property in the persistence.xml deployment descriptor to automatically and portably create and delete the tables in the jta-data-source
Enterprise beans
- Local, no-interface view session and singleton beans
- Jakarta RESTful Web Services resources in a session bean
- Jakarta EE security constraints on the administrative interface business methods
- All enterprise beans packaged within the WAR
WebSocket
- A WebSocket server endpoint that automatically publishes the status of students to client endpoints
Jakarta Contexts and Dependency Injection
- A CDI event that is fired when the status of a student changes
- Handler methods for updating the application once the status event is fired
- CDI managed beans for Facelets pages
- Bean Validation annotations in the CDI managed beans
Jakarta Faces technology, using Facelets for the web front end
- Templating
- Composite components
- A custom formatter, PhoneNumberFormatter
- Security constraints on the administrative interface
- Ajax-enabled Facelets components

The Duke’s Tutoring application has two main user interfaces, both packaged within a single WAR file:

The main interface, for students, guardians, and staff
The administrative interface used by the staff to manage the students and guardians, and to generate attendance reports

Main Interface

The main interface allows students and staff to check students in and out, and record when students are outside at the playground.

Jakarta Persistence Entities Used in the Main Interface

The following entities used in the main interface encapsulate data stored and manipulated by Duke’s Tutoring, and are located in the dukestutoring.entity package in the dukes-tutoring-common project.

Person: The Person entity defines attributes common to students and guardians tracked by the application. These attributes are the person’s name and contact information, including phone numbers and email address. This entity has two subclasses, Student and Guardian.
PersonDetails: The PersonDetails entity is used to store additional data common to all people, such as attributes like pictures and the person’s birthday, which aren’t included in the Person entity for performance reasons.
Student and Guardian: The Student entity stores attributes specific to the students who come to tutoring. This includes information like the student’s grade level and school. The Guardian entity’s attributes are specific to the parents or guardians of a Student. Students and guardians have a many-to-many relationship. That is, a student may have one or more guardians, and a guardian may have one or more students.
Address: The Address entity represents a mailing address and is associated with Person entities. Addresses and people have a many-to-one relationship. That is, one person may have many addresses.
TutoringSession: The TutoringSession entity represents a particular day at the tutoring center. A particular tutoring session tracks which students attended that day, and which students went to the park.
StatusEntry: The StatusEntry entity, which logs when a student’s status changes, is associated with the TutoringSession entity. Students' statuses change when they check in to a tutoring session, when they go to the park, and when they check out. The status entry allows the tutoring center staff to track exactly which students attended a tutoring session, when they checked in and out, which students went to the park while they were at the tutoring center, and when they went to and came back from the park.

For information on creating Jakarta Persistence entities, see Introduction to Jakarta Persistence. For information on validating entity data, see Validating Persistent Fields and Properties and Bean Validation: Advanced Topics.

Enterprise Beans Used in the Main Interface

The following enterprise beans used in the main interface provide the business logic for Duke’s Tutoring, and are located in the dukestutoring.ejb package in the dukes-tutoring-war project:

ConfigBean is a singleton session bean used to create the default students when the application is initially deployed, and to create an automatic enterprise bean timer that creates tutoring session entities every weekday.
RequestBean is a stateless session bean containing the business methods for the main interface. The bean also has business methods for retrieving lists of students. These business methods use strongly typed Criteria API queries to retrieve data from the database. RequestBean also injects a CDI event instance, StatusEvent. This event is fired from the business methods when the status of a student changes.

For information on creating and using enterprise beans, see Enterprise Beans. For information on creating strongly typed Criteria API queries, see Using the Criteria API to Create Queries. For information on CDI events, see Using Events in CDI Applications.

WebSocket Endpoint Used in the Main Interface

The ee.jakarta.tutorial.dukestutoring.web.websocket.StatusEndpoint class is a WebSocket server endpoint that returns students and their status to client endpoints. The StatusEndpoint.updateStatus method is a CDI observer method for the StatusEvent event. When a student’s status changes in the main interface, a StatusEvent is fired. The updateStatus observer method is called by the container, and pushes out the status change to all the client endpoints registered with StatusEndpoint.

The index.xhtml Jakarta Faces page contains JavaScript code to connect to the WebSocket endpoint. The onMessage method on this page clicks a Jakarta Faces button, which makes an Ajax request to refresh the table that shows the current status of the students.

For more information on WebSocket endpoints, see Jakarta WebSocket. For information on CDI events, see Using Events in CDI Applications.

Facelets Files Used in the Main Interface

The Duke’s Tutoring application uses Facelets to display the user interface, making extensive use of the templating features of Facelets. Facelets, the default display technology for Jakarta Faces technology, consists of XHTML files located in the jakartaee-examples/tutorial/case-studies/dukes-tutoring/dukes-tutoring-war/src/main/webapp/ directory.

The following Facelets files are used in the main interface:

template.xhtml: Template file for the main interface
error.xhtml: Error file if something goes wrong
index.xhtml: Landing page for the main interface
park.xhtml: Page showing who is currently at the park
current.xhtml: Page showing who is currently in today’s tutoring session
statusEntries.xhtml: Page showing the detailed status entry log for today’s session
resources/components/allStudentsTable.xhtml: A composite component for a table displaying all active students
resources/components/allInactiveStudentsTable.xhtml: A composite component for a table displaying all inactive students
resources/components/currentSessionTable.xhtml: A composite component for a table displaying all students in today’s session
resources/components/parkTable.xhtml: A composite component for a table displaying all students currently at the park
WEB-INF/includes/mainNav.xhtml: XHTML fragment for the main interface’s navigation bar

For information on using Facelets, see Introduction to Facelets.

Helper Classes Used in the Main Interface

The following helper classes, found in the dukes-tutoring-common project’s dukestutoring.util package, are used in the main interface.

CalendarUtil: A class that provides a method to strip the unnecessary time data from java.util.Calendar instances.
Email: A custom Bean Validation annotation class for validating email addresses in the Person entity.
StatusType: An enumerated type defining the different statuses that a student can have. Possible values are IN, OUT, and PARK. StatusType is used throughout the application, including in the StatusEntry entity, and throughout the main interface. StatusType also defines a toString method that returns a localized translation of the status based on the locale.

Properties Files

The strings used in the main interface are encapsulated into resource bundles to allow the display of localized strings in multiple locales. Each of the properties files has locale-specific files appended with locale codes, containing the translated strings for each locale. For example, Messages_es.properties contains the localized strings for Spanish locales.

The dukes-tutoring-common project has the following resource bundle under src/main/resources/.

ee.jakarta.tutorial/dukestutoring/util/StatusMessages.properties: Strings for each of the status types defined in the StatusType enumerated type for the default locale. Each supported locale has a property file of the form StatusMessages_locale prefix.properties containing the localized strings. For example, the strings for Spanish-speaking locales are located in StatusMessages_es.properties.

The dukes-tutoring-war project has the following resource bundles under src/main/resources/.

ValidationMessages.properties: Strings for the default locale used by the Bean Validation runtime to display validation messages. This file must be named ValidationMessages.properties and located in the default package as required by the Bean Validation specification. Each supported locale has a property file of the form ValidationMessages_locale prefix.properties containing the localized strings. For example, the strings for German-speaking locales are located in ValidationMessages_de.properties.
ee.jakarta.tutorial/dukestutoring/web/messages/Messages.properties: Strings for the default locale for the main and administration Facelets interface. Each supported locale has a property file of the form Messages_locale prefix.properties containing the localized strings. For example, the strings for simplified Chinese-speaking locales are located in Messages_zh.properties.

For information on localizing web applications, see Registering Application Messages.

Deployment Descriptors Used in Duke’s Tutoring

Duke’s Tutoring uses these deployment descriptors in the src/main/webapp/WEB-INF directory of the dukes-tutoring-war project:

faces-config.xml: The Jakarta Faces configuration file
glassfish-web.xml: The configuration file specific to GlassFish Server, which defines security role mapping
web.xml: The web application configuration file

Duke’s Tutoring also uses the following deployment descriptor in the src/main/resources/META-INF directory of the dukes-tutoring-common project:

persistence.xml: The Jakarta Persistence configuration file

No enterprise bean deployment descriptor is used in Duke’s Tutoring. Annotations in the enterprise bean class files are used for the configuration of enterprise beans in this application.

Administration Interface

The administration interface of Duke’s Tutoring is used by the tutoring center staff to manage the data employed by the main interface: the students, the students' guardians, and the addresses. The administration interface uses many of the same components as the main interface. Additional components that are only used in the administration interface are described here.

Enterprise Beans Used in the Administration Interface

The following enterprise bean, in the dukestutoring.ejb package of the dukes-tutoring-war project, is used in the administration interface.

AdminBean: A stateless session bean for all the business logic used in the administration interface. Calls security methods to allow invocation of the business methods only by authorized users.

Facelets Files Used in the Administration Interface

The following Facelets files, under src/main/webapp/, are used in the administration interface:

admin/adminTemplate.xhtml: Template for the administration interface
admin/index.xhtml: Landing page for the administration interface
login.xhtml: Login page for the security-constrained administration interface
loginError.xhtml: Page displayed if there are errors authenticating the administration user
admin/address directory: Pages that allow you to create, edit, and delete Address entities
admin/guardian directory: Pages that allow you to create, edit, and delete Guardian entities
admin/student directory: Pages that allow you to create, edit, and delete Student entities
resources/components/formLogin.xhtml: Composite component for a login form using Jakarta Security
WEB-INF/includes/adminNav.xhtml: XHTML fragment for the administration interface’s navigation bar

CDI Managed Beans Used in the Administration Interface

The CDI managed beans used in the administration interface are located in the dukestutoring.web package in the dukes-tutoring-war project.

StudentBean.java: A managed bean for the Facelets pages used to create and edit students. The first and last names have Bean Validation annotations that require the fields to be filled in. The phone numbers have Bean Validation annotations to ensure that the submitted data is well-formed.
GuardianBean.java: A managed bean for the Facelets pages used to create guardians for and assign guardians to students. The first and last names have Bean Validation annotations that require the fields to be filled in. The phone numbers have Bean Validation annotations to ensure that the submitted data is well-formed.
AddressBean.java: A managed bean for the Facelets pages used to create addresses for students. The street, city, province, and postal code attributes have Bean Validation annotations that require the fields to be filled in, and the postal code attribute has an additional annotation to ensure that the data is properly formed.

Helper Classes Used in the Administration Interface

The following helper classes, found in the dukes-tutoring-war project’s dukestutoring.web.util package, are used in the administration interface.

EntityConverter: A parent class to StudentConverter and GuardianConverter that defines a cache to store the entity classes when converting the entities for use in Jakarta Faces user interface components. The cache helps increase performance. The cache is stored in the Jakarta Faces context.
StudentConverter: A Jakarta Faces converter for the Student entity class. This class contains methods to convert Student instances to strings and back again, so they can be used in the user interface components of the application.
GuardianConverter: Similar to StudentConverter, this class is a converter for the Guardian entity class.

Running the Duke’s Tutoring Case Study Application

This section describes how to build, package, deploy, and run the Duke’s Tutoring application.

Running Duke’s Tutoring

You can use either NetBeans IDE or Maven to build, package, deploy, and run Duke’s Tutoring.

To Build and Deploy Duke’s Tutoring Using NetBeans IDE

Before You Begin

You must have already configured GlassFish Server as a Jakarta EE server in NetBeans IDE, as described in To Add GlassFish Server as a Server Using NetBeans IDE.

Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).
If the database server is not already running, start it as described in Starting and Stopping Apache Derby.
From the File menu, choose Open Project.
In the Open Project dialog box, navigate to:
```
jakartaee-examples/tutorial/case-studies
```
Select the dukes-tutoring folder.

Select the Open Required Projects check box and click Open Project.

The first time you open Duke’s Tutoring in NetBeans, you will see error glyphs in the Projects tab. This is expected, as the metamodel files used by the enterprise beans for Criteria API queries have not yet been generated.

In the Projects tab, right-click the dukes-tutoring project and select Build.

This command creates a JDBC security realm named tutoringRealm, builds and packages the dukes-tutoring-common and dukes-tutoring-war projects, and deploys dukes-tutoring-war to GlassFish Server, starting Derby and GlassFish Server if they have not already been started.

To Build and Deploy Duke’s Tutoring Using Maven

Make sure that GlassFish Server has started (see Starting and Stopping GlassFish Server).
If the database server is not already running, start it as described in Starting and Stopping Apache Derby.

In a terminal window, go to:

jakartaee-examples/tutorial/case-studies/dukes-tutoring/

Enter the following command:
```
mvn install
```
This command creates a JDBC security realm named tutoringRealm, builds and packages the dukes-tutoring-common and dukes-tutoring-war projects, and deploys dukes-tutoring-war to GlassFish Server.

Using Duke’s Tutoring

Once Duke’s Tutoring is running on GlassFish Server, use the main interface to experiment with checking students in and out or sending them to the park.

To Use the Main Interface of Duke’s Tutoring

In a web browser, open the main interface at the following URL:
```
http://localhost:8080/dukes-tutoring-war/
```
Use the main interface to check students in and out, and to log when the students go to the park.

To Use the Administration Interface of Duke’s Tutoring

Follow these instructions to log in to the administration interface of Duke’s Tutoring and add new students, guardians, and addresses.

From the main interface, open the administration interface by clicking Administration main page in the left menu.

This redirects you to the login page at the following URL:
```
http://localhost:8080/dukes-tutoring-war/admin/index.xhtml
```
On the login page, enter admin@example.com in the User name field, and enter jakartaee in the Password field.
Use the administration interface to add or modify students, add guardians, or add addresses.
- To add a new student, click Create new student in the left menu, fill in the fields (two are required) in the form that opens, and click Submit. The Email, Home phone, and Mobile phone fields have formatting requirements enforced by HTML5 pass-through or by Bean Validation constraints.
- To modify a student, click Edit next to the student’s name, modify the fields in the form that opens, and click Submit. To edit another student, choose the student from the drop-down menu at the top of the page and click Change student.
- To remove a student, click Remove next to the student’s name, then click Confirm in the page that appears. This action removes the student from the tutoring session but does not remove the student from the database. To add the student to the tutoring session again, click Activate student in the left menu, then click Activate next to the student’s name in the page that appears.
- To add a guardian for a student, click Add guardian next to the student’s name. The page that appears shows the student’s name, the available guardians, and the current guardians for the student, if any. To add an existing guardian for that student, select the guardian from the list and click Add guardian. To create a new guardian for the student, fill in the fields and click Submit. To remove a guardian from a student, select one of the student’s current guardians from the list and click Remove guardian.
- To add an address for a student, click Add address next to the student’s name. In the page that appears, fill in the appropriate fields in the form that appears, and click Submit. Four fields are required.

The administration interface is not fully implemented. It is not possible to edit a guardian or to view or edit an address, although Facelets pages exist for these features. The application also makes no use of the properties in the PersonDetails entity. Feel free to modify the application to add these features.