Enterprise Java Development@TOPIC@

Chapter 22. Project 2 Technical Details

22.1. Data Tier and Business Logic Support
22.2. Module Layout
22.2.1. eLeague Modules
22.2.2. eClub Module(s)
22.3. EJB Tier
22.3.1. EJB Base Tier
22.3.2. EJB Business
22.3.3. eClub EJB Tier
22.3.4. Remote Interfaces
22.3.5. eClub/eLeague Integration
22.4. Transactions
22.5. Web UI
22.5.1. eLeague Web UI
22.5.2. eClub WEB UI Tier

Tip

It may be helpful to browse the grading criteria at the end of this assignment before reading through the specifications. This will give you a better idea of what has to be completed to achieve a passing grade. A perfect score for the assignment will require that the entire specification be implemented. A passing score will require the demonstration of understanding of specific concepts covered. You can conceivably do well in the grading if you tackle each of the technical areas at least once. Example: Don't focus so much on completing the steps of the end-to-end that you ignore the transaction and Web UI aspects of the assignment. Of course, the opposite is true. Don't ignore the end-to-end scenario and demonstrate functionality in a vacuum. The end-to-end scenario should provide plenty of chances to demonstrate required technical parts of this assignment.

22.1. Data Tier and Business Logic Support

Continue to provide all functionality from Project 1; especially the unit tests as you revise your earlier implementations For example, you should continue to have the ability to run the unit and end-to-end tests implemented in project 1. Make sure you design your project 2 testing such that it does not depend on database residue from project 1 tests.

22.2. Module Layout

Create a Maven module layout that will support the additional architecture layers of the assignment. It is intended that eLeague be implemented with a multi-module approach (to mimic a complex application) and eClub be implemented with very few (possibly one) modules (to mimic a simplistic application).

To implement the full project 2 assignment, you will eventually need your existing implementation module(s) and new modules to implement a remote client, EJB, WEB, EAR, and test concepts.

Figure 22.1. eLeague Candidate Modules

eLeague Candidate Modules

League Implementation Module(s)

These are your existing implementation module(s) from project 1. They are intended to remain mostly unchanged when working on project 2. They represent your core data and business logic and business decisions in getting this far. We want to keep project 2 focused on the technical aspects of deploying this capabilty to the server-side and leave the detailed business decisions behind.

LeagueClient Module

This new module is going to make available to external clients of eLeague. This will contain data transfer objects (DTOs) and JAX-RS client code to make implementing the client calls easier.

LeagueEJB Module

This new module will host the EJB components and define a META-INF/persistence.xml that is appropriate for use on the server-side. Most of the implementation of these components will be based on the project 1 implementation.

LeagueWAR Module

This new module will host the JAX-RS interface for eLeague and any Web UI that is developed.

LeagueEAR Module

This new module will package the EJB(s), WAR(s), and necessary JAR(s) in a single deployment to the server. It will define identity information for the EJB and WAR that will impact base JNDI and URI name paths generated to access the hosted components. It will also be a location where we exclude unecessary dependency JARs to trim the EAR of unecessary artifacts.

League Remote Test Module

This new module will deploy the EAR to the server and execute integration tests that use remote interfaces to verify eLeague functionality.

To implement the project 2 assignment, you will need a WAR module. You can create a WAR module that is a sibling to your existing implementation module or change your existing implementation module into a WAR. Since there are no clients of eClub (other than the eClub and end-to-end eSport tests that can be hosted within the WAR module) there will be no need to expose a client interface.

Figure 22.2. eClub Candidate Modules

eClub Candidate Modules

Club Implementation Module

This is your existing implementation module from project 1. It is anticipated that you will enhance your existing business logic to become EJBs and host the existing code in a module that supports EJB. That module can be the WAR.

ClubWAR Module

This new module will host the JAX-RS interface and Web UI for eClub and any supporting components and artifacts necessary to support them. It is anticipated that you will convert your existing module from project 1 into a WAR. However, the only core requirement is that you deploy eClub as a WAR -- whether you choose to add separate EJB modules or not.

22.3. EJB Tier

Create an EJB tier for both applications to host your server-side, transactional, and persistence logic. Security will be added in the next project.

The EJB tiers must host your persistence unit and supply a set of EJB components that will provide access to your server-side logic.

The eLeague EJB tier must be hosted in a separate EJB module and deployed to the server in an EAR. A remote Test module must deploy the EAR as part of its integration testing (IT).

Figure 22.3. eLeague Candidate Base EJB Tier

eLeague Candidate Base EJB Tier

LeagueTestUtilEJB

This candidate support EJB will primarily host the LeagueTestUtilImpl business logic to support remote testing requirements. Its biggest role is to perform database initialization and ingest. It can be the target of early "hello world" test calls without poluting your primary application classes.

ClubMgmtEJB

This candidate EJB will primarily host the ClubMgmtImpl business logic where clubs can define their Teams and Venues in eLeague.

LeagueMgmtEJB

This candidate EJB will primarily host the LeagueMgmtImpl business logic where the seasons and divisions are managed.

ContestMgmtEJB

This candidate EJB will primarily host the ContestMgmtImpl business logic where day-to-day contests are managed.

The eClub EJB tier may be part of a separate module but must be deployed within a WAR. The WAR module must deploy the WAR as part of its integration testing (IT). Note that the candidate EJBs in this case are shown to be the Impls from project 1 turned into EJBs. This is to highlight that EJBs are just annotated POJOs (plain old Java objects) and this approach is a simplification of implementation over the eLeague approach.

Figure 22.4. eClub Candidate Base EJB Tier

eClub Candidate Base EJB Tier

ClubTestUtil

This candidate support EJB will primarily host the ClubTestUtilImpl business logic to support remote testing requirements. Its biggest role is to perform database initialization. It can be the target of early "hello world" test calls without poluting your primary application classes.

MemberMgmtEJB

This candidate EJB will primarily host the MemberMgmtImpl business logic where people assiciated with the Club can sign up and provide their identity information.

OrgMgmtEJB

This candidate EJB will primarily host the OrgMgmtImpl business logic where the seasons and divisions are managed.

Note

Note the difference in how the two approaches addressed the EJB hosting the BLImpl business logic. In the first/more complex case -- the EJB and BLImpl were separate classes with the EJB delegating to the BLImpl class. This allowed us to highlight what the EJB is adding to the solution. In the later/simpler case, the BLImpl became an EJB. This allows us to highlight how the EJB can contain our business logic can be subject to normal POJO unit tests if desired.

The EJB tier must host your business logic and data access tiers. The EJBs must define injections and initialize implementation objects and provide a remote interface. Configuration and initialization can be via deployment descriptors, brute force/manual code in @PostConstructs, or indirectly using CDI. It is your choice. Transaction scope will be added as a part of a separate requirement.

The candidate EJBs are shown with possible dependencies between them. @Local interfaces are meant to identify interfaces that can easily support pass by reference and lazily loaded entities. @Remote interfaces are meant to identify interfaces where calls are likely coming from an external context (i.e., pass-by-id or pass-by-value serialization) and the responses must be complete. Each @Local interface could be the interface defined by the Impls.

Figure 22.5. eLeague Candidate EJB Tier

eLeague Candidate EJB Tier

  • Each of the EJB components will need to expose targeted behavior required to complete the end-to-end scenario.

  • The candidate ClubMgmtEJB may need to support calls from LeagueMgmt to form seasons for its teams.

  • The candidate LeagueMgmtEJB may need to support calls from ContestMgmt to manage season contests.

Figure 22.6. eClub Candidate EJB Tier

eClub Candidate EJB Tier

  • Each of the EJB components will need to expose targeted behavior required to complete the end-to-end scenario.

  • The candidate OrgMgmtEJB may need to make remote calls to eLeague and eLeague has been depicted as providing a client module for such use.

Remote interface to the two applications will be demonstrated using two technologies: Java Remote Method Invocation (RMI) and HTTP/REST-like (using JAX-RS). Any data transferred using either will be part of the Data Transfer Objects (DTOs). DTOs used with RMI will need to be Java Serializable. DTOs used with JAX-RS will need to be marshaled as XML or JSON.

DTOs and and any classes written to support the remote interface will be placed in a JAR module that can be easily used by clients. Since eClub does not have any clients and we want to limit its complexity -- only eLeague will require a separate client module to host these classes.

We will limit our required use of RMI to eLeague and only to the eLeagueTestUtilEJB. This interface will be made accessible to remote clients of the application server using JNDI.

Figure 22.7. eLeague RMI Interface

eLeague RMI Interface

  1. The commands to reset and populate the eLeague database must be accessible to a remote client using RMI.

The primary focus for implementing remote interfaces will be HTTP/REST-like interfaces using JAX-RS (server and client APIs). The EJBs already provide an injectable component to complete the desired functionality. It is intended that you add a set of one or more classes that expose access to this functionality using JAX-RS.

A candidate set of resource collection URIs is shown below. Add a {resourceId} to address a specific resource from the collection. Add an additional property name or query parameter to address a specific property of the resource. Use the appropriate verb (GET, POST, PUT, DELETE), query parameters, and payloads to make the intended requests. Make use of appropriate status codes (e.g, 200, 201, 400, 404, and 500) to communicate the results.

There is no requirement that you specifically make use of the specific URIs listed or break root level resources into separate JAX-RS classes. It is your choice. It is suggested that all URIs be exposed under the "/api" root URI for the targeted application context. The details here are provided as concrete suggestions. In the end, the primary requirement for remote interfaces is:

  1. All server-side methods methods invoked remotely by the end-to-end scenario (excluding reset() and populate() for eLeague) must be accessed through HTTP/REST-like interfaces implemented with JAX-RS.

The diagram below shows an abstract JAX-RS layer that should be deployed as one or more classes in the WAR. Since eLeague is required to have separate DTO classes from BO classes -- you will need to create a mapping capability from DTOs to BOs for request payloads and BOs to DTOs for response payloads.

Figure 22.8. eLeague JAX-RS Resources

eLeague JAX-RS Resources

The following is a list of candidate URIs for eLeague that could be exposed below "/api".

  • clubs - clubs in league

  • clubs/{clubId}/venues -- venues for club

  • clubs/{clubId}/teams -- teams for club

  • contests - contests in league

  • divisions - divisions in league uniquely identifiable outside of season

  • divisions/{divisionId}/teams - team seasons within division

  • seasons - seasons in league

  • teams - teams within league uniquely identifiable outside of club

  • tests - open-ended base resource to support testing

The diagram below shows an abstract JAX-RS layer that should be deployed as one or more classes in the WAR. Since eClub is required to reuse BOs as DTOs, you will not need to perform different class mapping. However, to cleans the BO of persistence parasites and to reduce information expressed, you may need to create POJO copies of the BOs when going from the BO to DTO role.

Figure 22.9. eLeague JAX-RS Resources

eLeague JAX-RS Resources

The following is a list of candidate URIs for eClub that could be exposed below "/api".

  • members/parents - parents in org

  • members/players -- players in org

  • members/coaches -- coaches in org

  • teams -- teams in org

  • teams/{teamId}/players -- players on team

  • teams/{teamId}/coaches -- coaches for team

  • teams/{teamId}/managers - managers for team

  • tests - open-ended base resource to support testing

Create or identify classes that will express information passed between client and server within the remote interfaces.

  1. DTO classes passed between client and server using RMI interfaces must be Java Serializable.

  2. DTO class state passed between client and server using the JAX-RS interfaces must be either marshaled using XML or JSON.

XML marshaling should be implemented with JAXB. JSON marshalling can be implemented with JSONB, but it is recommended to use jackson2 since JSONB is not supported in Wildfly until we reach JavaEE 8 compliance. Client-side JSONB and server-side jackson will work 95% of the time -- but there are some differences. 

<!-- JSON wiring for RESTEasy JAX-RS provider (javaee7)-->
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-jackson2-provider</artifactId>
</dependency>

eLeague will be implemented using separate DTO and BO classes to maintain separation between client interface and implementation.

  1. eLeague DTO classes must be a distinct set of classes specifically designed to pass data between client and server.

  2. eLeague BO/entity classes may not be used as DTOs.

The following is a list of candidate DTOs including an ErrorDTO that can be used to express server-side error responses. Requests likely have most of the same BO data filled in. Responses likely are redacted down to only what is necessary to express an ID and possibly its name. e.g., when listing the location for a Contest the ID and name of the related Venue should be sufficient. If they want more information about the Venue -- that can be a request of the venues resource and not the related contest.

eClub will be implemented with dual use of BO classes as DTO and entity purposes to demonstrate a more simplistic approach.

  1. eClub BO/entity classes must be re-used as DTOs.

For ease of client access (including IT tests), you will write a JAX-RS Client helper class that encapsulates the URI paths, methods, query parameters and payloads of all HTTP/REST-like requests and also encapsulates determining the status and extracting any result payload.

Most of our external client calls to eLeague will be accomplished through JAX-RS and will use DTO classes. For that reason, we will need to package the client classes in a separate module for use in eClub and in any IT tests within eLeague.

Figure 22.10. eLeague Client

eLeague Client

  1. eLeague shall provide a class that uses the JAX-RS Client API to make HTTP/REST-like calls to eLeague.

  2. eLeague shall provide a separate client module that contains the JAX-RS Client class and interface DTOs.

There is no explicit requirement for an eClub Remote client since this application has no external application clients within the scope of the project. However, you may find it helpful to still write a JAX-RS client class for use with IT tests like the end-to-end scenario.

A placeholder step was included in project 1 that we could not yet complete because eLeague did not have a remote interface at that time. Now that eLeague has a remote interface to use (for eClub development and testing as well), we can implement getting the team season for a member of eClub.

eClub and eLeague manage independent concepts of a team and their IDs are different. eClub must maintain not only its internal ID but also the ID used by eLeague so that users of eClub can easily locate information for their team.

Figure 22.11. eClub/eLeague Integration

eClub/eLeague Integration

22.4. Transactions

Add transaction properties to the EJBs.

  1. Transaction Scope - all session bean methods in these two applications should require a transaction unless otherwise justified.

  2. Transaction Integrity - Create a demonstration of transactions integrity and the capability of rollback by implementing a scenario that adds something to the database and then a *follow-on* rollback causes the changes to be undone. The state of the database must remain consistent once complete.

Note

To satisfy the transaction demonstration requirement, you must actually store something in the database and then later in the transaction roll it back based on some decision. If you make the decision before you store the information -- you are not satisfying the requirement. It is common for students to implement a wrapper around an existing method that takes a collection and populate the collection with good data up front and bad data at the end. The good data that got successfully processed should get rolled back once the bad data is processed. Create remote methods that can tell your remote test client that this actually occured.

22.5. Web UI

Add separate server-side Web UI(s) to demonstrate integration between the Web UI and EJB Tiers. To meet this requirement -- you only have to implement *ONE* of the following in either eLeague or eClub.

Web UI does not replace remote interface/IT test requirement

The requirement for the Web UI is a single action (display a page, make a request, and display results). You can implement more actions, but all the steps in the end-to-end must still be implemented using remote interfaces and automatically tested with JUnit.