Epigram

Epigram is a simple Java web app that provides a random epigram to the user and lets users submit their own.

The app is packaged with an embedded Jetty server exposing a Jersey (JAX-RS) REST API alongside a static HTML/CSS/JS frontend, backed by a simple CSV file for persistence of epigrams.

Features

• A browser frontend that fetches and displays a random epigram, with a manual refresh and an auto-refresh toggle, and an add page for submitting new entries.
• A backend service which serves static frontend files and provides an Epigram API with the following endpoints:
  • GET /api/epigram: returns a random epigram as JSON, never repeating the same one twice in a row.
  • POST /api/epigram: adds a new epigram, either as JSON or as an HTML form submission (used by the add page).
• File-based persistence: Backend service loads epigram data from a CSV file on startup and appends new submissions. If the file doesn't exist on startup, it is created with the required header and a default entry.

Project structure

The project is managed with Gradle, with a primary project app:

• core: core model classes, namely Epigram domain object
• repo: repository interfaces and implementations, for query and persistence of Epigram objects
• useCase: logic classes which perform app behaviour, including EpigramRandomiser which draws a random, non-repeating epigram
• ext: frameworks/external services for app, namely the Jetty-based web server EpigramJettyServer and Jersey/JAX-RS endpoint description EpigramResource for the Epigram API
• resources/webapp: static frontend assets (HTML/CSS/JS) for random epigram and add epigram views, served by the web server

Requirements

• JRE 17+

Running the web app

Via Distribution JAR

Pre-built distribution JARs can be found in Releases.

You can run the web app from the distribution JAR:

java -jar epigram.jar [csvRepoFile] [port]

The app can be configured with two positional arguments:

1. csvRepoFile: path to the CSV repository file. If it does not exist, it will be generated in the working directory. Defaults to epigrams.csv if not provided.
2. port: port to bind server to. Defaults to port 8080 if not provided.

Via Gradle

You can also start the server using Gradle wrapper:

./gradlew run

By default this starts the server on port 8080, using epigrams.csv (created in the working directory if it doesn't already exist) as the data file.

Once running, visit:

• http://localhost:8080/ (random epigram view)
• http://localhost:8080/add.html (add epigram view)
• http://localhost:8080/api/epigram (epigram api endpoint)

Stop the server with Ctrl+C.

Arguments can also be passed with --args with the same positional arguments as per above.

./gradlew run --args="epigrams.csv 8080"

Building the web app

The project uses the Shadow plugin to build a "fat" JAR containing the app and all its dependencies:

./gradlew shadowJar

On build, the distribution JAR can be found at app/build/libs/app-all.jar.

CSV Repository File

The repository file is a simple comma-delimited (',') CSV with the following header row:

text,author,original_work,original_year

• text and author are required for each entry
• original_work and original_year are optional, but must be included as empty cells
• For manual entry, ensure fields are enquoted if they contain commas

If the file doesn't exist at startup, it will be generated with this header and a single default entry.

A sample file is included in this repo: epigrams.csv.

Running the tests

./gradlew test