Architecture Overview - struct-by-lightning/wpi-suite GitHub Wiki
The WPI Suite system follows the basic client-server architecture:
- Client
- used to access projects
- display module GUIs
- Server (Core)
- provides user and project management functionality
- coordinates storage and retrieval of project and module data
- implements the public REST API
The diagram above shows the main components of the WPI Suite system. These components consist of the following:
The following items represent data passed around WPI Suite:
The desktop client is implemented in Java. It consists of a library that is used to generate, send, and manage HTTP requests/responses and sessions as well as a Swing-based application that dynamically loads and displays the client-side GUIs for each WPI Suite module.
The swing application that displays module GUIs is known as Janeway. Each WPI Suite module provides a .jar file containing a class that implements the IJanewayModule interface. The Janeway client loads all necessary modules from their .jar files dynamically when the client is run. Each module can make use of the network library to make requests to the server.
The network library simplifies the process of creating HTTP requests to send and receive model entities from the core. The library provides a Network factory that can be used to easily create requests. Clients using the library can simply create a request, add an observer to be notified when the response is received, and then send the request. The network library takes care of spawning a new thread to send the request, allowing all HTTP requests to be asynchronous without clients needing to manage threads. More detailed information on the network library can be found on the Networking with janeway page.
The core consists of all the components that manage users and projects, implement the public REST API, handle retrieving and storing models, and persist model data.
The public REST API is used by client applications to communicate with the core. It is accessed using HTTP, so it is accessible by almost any type of client implementation. The primary functions of the API are storing and retrieving models. It also manages login and authentication and project selection. Data is passed back and forth by the API using JSON. This necessitates that models be serialized into JSON before being transferred, and then be deserialized upon being received. This article explains the concept of a REST API very well. For more specific details on the functionality of the WPI Suite API, visit the REST API page.
The Core Servlet is located in the core and is responsible for handling incoming HTTP requests. See Networking with janeway for an explanation of those HTTP requests. In handling requests, this servlet will parse message addresses and pass them to the Manager Layer, which will return any data that the Core Servlet ultimately uses as a response to the HTTP request. The code for the Core Servlet can be seen here. There are other servlets, like the Advanced API Servlet that handle other features of the Core.
The Manager Layer works for the Core Servlet by performing requested operations on the database through Entity Managers. Each Entity Manager is addressed by a two part string containing first the module name and second the model name as described here. The Manager Layer simply gets the appropriate entity manager, calls that manager's methods to interact with the database, then finally returns the result back up to the Core Servlet.
A Session object contains important information about a particular query. The most useful things are references to the User whose Session it is and what Project is being worked on. This information is maintained by the WPI Suite Core and made available only to the Entity Managers every time they have to handle a request.
Entity Managers are located on the server side of WPI Suite and handle interactions with the database. Entity Managers are the only level of the Core that have to be implemented for any new modules. The Core automatically routes network requests to the appropriate methods in the Entity Manager and sends the values returned back to the client. See Networking with janeway for a mapping of network requests to Entity Manager methods.
The method headers are located in the EntityManager interface, most of which must be implemented by all Entity Managers. Basic examples of Entity Managers include: [Defect Manager] (https://github.com/WPI-Suite/wpi-suite/blob/dev/DefectTracker/src/edu/wpi/cs/wpisuitetng/modules/defecttracker/entitymanagers/DefectManager.java) and PostBoardEntityManager
For implementing new Entity Managers, there is an AbstractEntityManager to start with. The Advanced-API page explains the usage of the available advanced methods from the Entity Manager interface.
There is a database framework designed specifically for WPI Suite. The interface that outlines the methods for expected use of the database can be seen here. DataStore is a fully implemented database using db4o and will be passed into Entity Managers upon initialization of the Core. The Database offers an in depth explanation of each of the method types and some db4o specific characteristics.
Models are special objects that have been prepared for storage in the the WPI Suite Database. Their purpose is to hold real data and represent singular things. For example, a Note Model would be made so that every Note object would hold only one note. The Model interface describes all of the methods necessary for a Model to work with the WPI Suite Core. AbstractModel has a few methods required to be able to be saved to the database already implemented. Example Models include the Project class or the PostBoardModel. Adding a Model (Data Entity) provides a tutorial on adding Models to your module.
The following two methods are not currently used by the WPI Suite Core. One use could be to have the save method use a SaveModelController to send a message to the database to make the save.
public void save(); public void delete();
All of the available exceptions can be seen here and are listed below:
- AuthenticationException: Thrown for Authentication errors in the login system
- BadRequestException: Thrown when json is malformed.
- ConflictException: Thrown when attempting to store an object already in the database
- DatabaseException: Thrown for database errors.
- ForbiddenException: Thrown when a forbidden action is attempted.
- NotFoundException: Thrown when an item is not found in the database.
- NotImplementedException: Thrown when an unimplemented method is called.
- SerializationException: Thrown for serialization errors in Models and EntityManagers.
- SessionException: Thrown for issues in the Sessions system.
- UnauthorizedException: Thrown when attempting an action not allowed for that user's permission level
- WPISuiteException: Base WPI Suite Exception class.