Building Block View

The application, packaged as biking2.jar, contains two (the api and the spa) of the three main parts shown in the business context:

From those two, we take a closer look at the api only. For details regarding the structure of an AngularJS 1.2.x application, have a look at their developer’s guide.

To comply with the Java coding style guidelines, the modules “bikingPictures” and “galleryPictures” reside in the Java packages bikingpictures and gallerypictures.

Whitebox biking2::api

The following diagram shows the main building blocks of the system and their interdependencies:

Functional decomposition was used to separate responsibilities. The individual parts of the api are all encapsulated in their own components, represented as Java packages.

All components depend on a standard JPA EntityManager, and some on local file storage — those blackboxes aren’t detailed further here.

Contained blackboxes:

Interfaces:

bikes (Blackbox)

Intent/Responsibility: bikes provides the external API for reading, creating and manipulating bikes and their milages, as well as computing statistics and generating charts.

Interfaces:

Files: the bikes module and all of its dependencies are contained inside the Java package ac.simons.biking2.bikes.

tracks (Blackbox)

Intent/Responsibility: tracks manages file uploads (TCX files), converts them to GPX files and computes their surrounding rectangle (envelope) using GPSBabel. It also provides the oEmbed interface that resolves URLs to embeddable tracks.

Interfaces:

Files: the tracks module and all of its dependencies are contained inside the Java package ac.simons.biking2.tracks.

trips (Blackbox)

Intent/Responsibility: trips manages distances that have been covered on single days without relationships to bikes.

Interfaces:

Files: the trips module and all of its dependencies are contained inside the Java package ac.simons.biking2.trips.

locations (Blackbox)

Intent/Responsibility: locations stores locations with timestamps in near real time and provides access to locations from the last 30 minutes.

Interfaces:

Files: the locations module and all of its dependencies are contained inside the Java package ac.simons.biking2.tracker. The module is configured through ac.simons.biking2.config.TrackerConfig.

bikingPictures (Blackbox)

Intent/Responsibility: bikingPictures is used for regularly checking an RSS feed from Daily Fratze, collecting new images and storing them locally. It also provides an API for getting all collected images.

Interfaces:

Files: the bikingPictures module and all of its dependencies are contained inside the Java package ac.simons.biking2.bikingpictures.

galleryPictures (Blackbox)

Intent/Responsibility: galleryPictures manages file uploads (images). It stores them locally and provides an RSS interface for getting metadata and image data.

Interfaces:

statistics (Blackbox)

Intent/Responsibility: module for computing statistics, generating charts and providing version and summary information.

Interfaces:

Files: the statistics module and all of its dependencies are contained inside the Java package ac.simons.biking2.statistics.

Building Blocks — Level 2

bikes (Whitebox)

The BikeRepository is a Spring Data JPA based repository for BikeEntities. The BikeController and the ChartsController access it to retrieve and store instances of BikeEntity, and provide external interfaces.

Contained blackboxes:

tracks (Whitebox)

The TrackRepository is a Spring Data JPA based repository for TrackEntities. The TracksController and the OembedController access it to retrieve and store instances of TrackEntity, and provide external interfaces.

Contained blackboxes:

trips (Whitebox)

The AssortedTripRepository is a Spring Data JPA based repository for AssortedTripEntities. The TripsController accesses it to retrieve and store instances of AssortedTripEntity, and provide external interfaces.

locations (Whitebox)

Locations are stored and read via a Spring Data JPA based repository named LocationRepository. This repository is only accessed through the LocationService. The LocationService provides real time updates for connected clients through a SimpMessagingTemplate, and the LocationController uses the service to provide access to all locations created within the last 30 minutes.

New locations are created by the service either through a REST interface in the form of the LocationController, or via a MessageListener on an MQTT channel.

bikingPictures (Whitebox)

A Spring Data JPA repository named BikingPicturesRepository is used for all access to BikingPictureEntities; the external REST API for reading pictures is implemented with BikingPicturesController. The RSS feed is read by FetchBikingPicturesJob using a JAXB context “rss”. The URLs to the image files, which may be protected by various means, are provided to the job via a DailyFratzeProvider.

Contained blackboxes:

galleryPictures (Whitebox)

The GalleryPictureRepository is a Spring Data JPA based repository for GalleryPictureEntities. The GalleryController accesses it to retrieve and store instances of GalleryPictureEntity, and provide external interfaces.

statistics (Whitebox)

The StatisticService is a database centric service that uses an instance of jOOQ’s DSLContext for creating SQL. That SQL is not generated SQL, but handcrafted — jOOQ is used only to do this in a type-safe way.

During the build, jOOQ reads a temporary database, created from SQL based migration scripts, and generates several Java classes reassembling a schema. Those classes, along with the DSL, are used to write SQL.

The statements make heavy use of analytic functions. This is necessary because the original decision for storing milages was to not store the amount biked each month, but the accumulated milage on a bike — so the monthly values need to be computed. This is done with queries like the following:

-- Query that provides the statistics for the current year
WITH mm AS (
  SELECT
    bikes.name,
    bikes.color,
    milages.recorded_on,
    (lead(milages.amount) OVER (PARTITION BY bikes.id ORDER BY milages.recorded_on) - milages.amount) value
  FROM bikes
    JOIN milages
      ON milages.bike_id = bikes.id
  ORDER BY milages.recorded_on ASC
)
SELECT
  mm.name,
  mm.color,
  (EXTRACT(MONTH FROM mm.recorded_on) - 1) idx,
  mm.value,
  sum(mm.value) OVER (PARTITION BY mm.recorded_on) total
FROM mm
WHERE (
  mm.value IS NOT NULL
  AND EXTRACT(YEAR FROM mm.recorded_on) >= EXTRACT(YEAR FROM DATE '2019-01-01')
)
ORDER BY mm.name ASC