GlassFish - World's first Java EE 7 Application Server


Dukes Tutoring Case Study Example

The Duke's Tutoring example application is a tracking system for a tutoring center for students. Students can check in and out, and the center can log attendance and status updates, as well as have contact information for guardians and students.

Design & Architecture

Duke's Tutoring is a web application using the following Java EE 6 platform technologies:

  • Java Persistence API entities
    • JavaBeans Validation API annotations on the entities for verifying data
    • Custom JavaBeans Validation annotation @Email for validating email addresses
  • Enterprise beans
    • All enterprise beans packaged withing the WAR for business logic
    • local, no-interface view session and singleton beans
    • Some session beans are JAX-RS resources
    • Java EE security constraints on the admin business methods
  • JavaServer Faces using Facelets for the web front-end
    • templating
    • composite components
    • custom formatter PhoneNumberFormatter
    • security constraints on the admin interface

There are two parts of the Duke's Tutoring application: the main interface, for students, guardians, and staff; and the admin interface used by the staff to manage the students and guardians, and to generate attendance reports. Both parts are packaged within a single WAR file.

Apart from the main and admin interface, there is a JUnit test that demonstrates how to use the embedded EJB container.

Main Interface

Entities (dukestutoring.entity package)

  • Person: Defines common attributes for people tracked by Duke's Tutoring.
  • PersonDetails: Defines additional attributes (pictures, birthday, etc.) that aren't included in Person for performance reasons.
  • Student: Extends Person with attributes specific to the students that come to tutoring.
  • Guardian: Extends Person with attributes specific to the parents or guardians of Student.
  • Address: A mailing address, associated with Person entities.
  • TutoringSession: An entity that represents a particular day at the tutoring center.
  • StatusEntry: An entity for logging student's status changes, with timestamps.

Enterprise Beans (dukestutoring.ejb package)

  • ConfigBean: a singleton session bean used to create the default students and create EJB timers that create tutoring session entities for every weekday
  • RequestBean: a stateless session bean containing the business methods for the main interface. Students or staff can check in/out students, and track when they go to and come back from the playground. Also has business methods for retrieving lists of students.

Facelets files (in web directory)

  • template.xhtml: Template file for the main interface.
  • error.xhtml: Error file if something goes wrong (this shouldn't occur).
  • index.xhtml: Landing page for main interface.
  • park.xhtml: Page showing who is currently at the playground.
  • current.xhtml: Page showing who is currently in today's tutoring session.
  • statusEntries.xhtml: Page showing the status entry log for today's session.
  • resources/components/allStudentsTable.xhtml: Composite component for a table displaying all active students.
  • resources/components/currentSessionTable.xhtml: Composite component for a table displaying all students in today's session.
  • resources/components/parkTable.xhtml: Composite component for a table displaying all students current at the playground.
  • WEB-INF/includes/navigation.xhtml: XHTML fragment for the main interface's navigation bar.
  • WEB-INF/includes/footer.xhtml: XHTML fragment for the main interface's footer.

Helper Classes (dukestutoring.util package)

  • CalendarUtil: strips the unnecessary time data from java.util.Calendar instances.
  • Email: Custom JavaBeans Validation annotation for validating email addresses.
  • StatusType: An enumerated type defining the different statuses that a student can be.

Properties files

  • ValidationMessages.properties: Strings for default locale used by JavaBeans Validation runtime to display validation messages. This file must be named ValidationMessages.properties and located in the default package as required by JSR 303.
  • dukestutoring/web/messages/Messages.properties: Strings for default locale for the main and admin Facelets interface.

Deployment descriptors

  • src/conf/beans.xml: Empty file used to enable the CDI runtime.
  • web/WEB-INF/faces-config.xml: JavaServer Faces configuration file.
  • src/conf/persistence.xml: Java Persistence API configuration file.
  • web/WEB-INF/sun-web.xml: GlassFish-specific configuration file.
  • web/WEB-INF/web.xml: Web application's configuration file.

Admin Interface

Enterprise beans (dukestutoring.ejb package)

  • AdminBean: Stateless session bean for all admin business logic

Facelets files (in web directory)

  • admin directory:
    • adminTemplate.xhtml: Template for admin interface.
    • index.xhtml: Landing page for admin interface.
    • login.xhtml: Login page for security-constrained admin interface.
    • loginError.xhtml: Page displayed if there are errors authenticating the admin user.
    • address directory: Create, edit, delete XHTML files for Address entities.
    • guardian directory: Create, edit, delete XHTML files for Guardian entities.
    • student directory: Create, edit, delete XHTML files for Student entities.
  • resources/components/formLogin.xhtml: Composite component for a login form using Java EE security.
  • WEB-INF/includes/adminNav.xhtml: XHTML fragment for the admin interface's navigation bar.

Tests

JUnit test classes (in test directory)

  • dukestutoring.ejb.RequestBeanTest: JUnit test class for exercising the dukestutoring.ejb.RequestBean stateless session bean. Uses the embeddable EJB container.

Status

  • Partially localized.
  • Delete functionality in admin interface not complete.
  • Need to figure out localization in web/resources/components/loginForm.xhtml, since using the Messages.properties via #{bundle.propertyname results in runtime errors.
  • Need to add a JAX-RS interface.
  • Need to resolve the issue where adding Bean Validation annotations to persistent attributes in the entities causes input fields in the Facelets files to fail validation by the JSF runtime if those attributes aren't required. For example, a mobile phone number isn't required, but leaving the input form blank causes the JSF runtime to show validation errors. I emailed Ed Burns about this issue, but he had a higher priority project he had to work on. If this is a bug, it needs to be filed and fixed before I get back.