Server Overview

RyanBard edited this page Dec 5, 2016 · 5 revisions

Design

Server Code Design

Organization

Folder structure

The back-end Java code is located under the src/main/java directory in the root of the repository. The unit tests are located in a mirrored folder hierarchy under src/test/java.

Module structure

Each group of domain objects, controllers, services, and DAOs are in a Java package. Each group of unit tests associated with a class is located in the same package under the same class name suffixed with Test in src/test/java.

By convention, Java class names should be TitleCamelCased, methods and properties should be camelCased, and getters/setters should follow the JavaBeans spec: https://en.wikipedia.org/wiki/JavaBeans

The domain objects are using Java convention (JavaBeans) to satisfy JPA without need for explicit JPA annotations on every field.

The Controller classes represent an interface to the client. They are supporting either a JSON REST endpoint, a KML endpoint, or the serving of static or dynamic html/jsp/js/etc.

The Service classes contain all of the business logic in the server. This includes all server input validation, data manipulation, and authorization/privilege checking.

The DAO interfaces are the interface to the database. The implementation of them is provided by convention by Spring Data and JPA: http://docs.spring.io/spring-data/jpa/docs/1.4.0.RELEASE/reference/html/jpa.repositories.html#jpa.query-methods.query-creation

A subset of KML (https://en.wikipedia.org/wiki/Keyhole_Markup_Language) was implemented in JAXB to support the map features we needed in org.hmhb.kml.jaxb. We chose to make these objects immutable in the hope that they could be cached because we never read in XML, but only send it out to the caller. JAXB requires getters, setters, and a no-arg constructor. We implemented empty setters and empty no-arg constructors to satisfy it. We didn't end up caching the results, so looking back, we probably just should have used simple getters and setters.

There are a few Servlet Filters and Spring Configuration classes tying together a few complicated things like authentication and JAXB. You can see Spring Boot docs for details on how Spring config works: http://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-configuration-classes.html

Quality

Documentation

All public methods should have javadocs. Any complicated non-obvious code should either be simplified or have a comment explaining it.

Correctness and maintainability

Our unit tests are implemented with JUnit and Mockito. All significant code should be unit tested if feasible. Non-significant code like getters & setters is usually not worth it. Some code exists that isn't feasible to unit test (eg. code that is forced to use static methods like GeocodingApi.geocode). The un-testable code should be minimized as much as possible.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.