Calipso Hub: DVD Rental
build a DVD Rental Store app within a few hours
Currently v2.0-SNAPSHOT
Overview
Sample project demonstrating how to use Calipso-Hub to build a DVD Rental Store within hours and minimal effort.
Build and Run
Follow the steps bellow to build.
a) Clone the repository:
git clone https://github.com/manosbatsis/calipso-hub-dvdrental.git b) Copy HOWTO.txt to dev.properties:
cp HOWTO.txt dev.properties
c) Build and install (
-U
forces the download of updated snapshot dependencies):
mvn -U clean install d) run embedded Jetty container:
mvn jetty:run e) Browse the app client: http://localhost:8080/calipso/client or the API reference: http://localhost:8080/calipso/apidoc. See also the Swagger API Reference section bellow.
If you are using chrome, ensure you have enabled cookies for localhost.
Maven Profiles
If have [node](https://nodejs.org) installed, you can use the
optimize
profile and
jetty:run-war
to optimize client-side code:
mvn -P optimize clean jetty:run-war
To run integration tests simply activate the
ci
profile:
mvn -P ci clean install See also Tests.
Architecture and Current Status
Front-end
The front end is based on backbone marionette and provided by the calipso overlay WAR. Backbone models are the only code pending to provide an administrative SCRUD UI (thanks to calipso's use-case driven front-end), unless those models become optional first.
Back-end
Most SCRUD endpoints documented bellow use Controller/Service/Repository classes generated automatically by calipso on startup using javassist. The small amounts of business logic and custom methods can be found in the few custom components in the code. The larger part of the code is simple JPA entity models.
The only manually created endpoint is that of Orders
Tests
The
ci
POM profile executes integration tests. It does so by utilising maven-failsafe-plugin and jetty-maven-plugin to start and stop jetty during the
pre-integration-test
and
post-integration-test
phases respectively. The tests, based on the rest-assured API, are performed against the live container, i.e. without using any mocks.
Sample Workflow
Sample workflow of an application client used by clerk on the store counter. The client may have to hold references of objects in memory as indicated in the "notes" since the services API is totally stateless. The workflow has three simple steps:
- Scan Client Card
- Scan DVD boxes
- Submit Payment
The steps are explained in detail within the following sections.
Scan Client Card
Scan the 2D barcode of the client card to retrieve the corresponding user:
| Method | URL |
|---|---|
| GET | http://localhost:8080/calipso/api/rest/filmInventoryEntries/:userId |
Notes
- The API client is able to authenticate each request (required role: staff or admin)
- The API client must store the user until the end of the workflow (either payment or abort).
Scan DVD boxes
Scan the 2D barcode of each physical copy and use the utility "orders" endpoint to get an Order object that includes the appropriate cost for both new and returned rentals
| Method | URL |
|---|---|
| GET | http://localhost:8080/calipso/api/rest/order/orders/:filmInventoryEntryId?days |
The
days
can be used to control the cost for new rentals. The clients state the number of days they intent to rent the inventory entry for and the service calculates the cost according to the pricing
strategy of the film. The days parameter is ignored for returns, in which case the current date is used to calculate any amount due for late returns.
The returned Order JSON has the following properties.
| Name | Type | Description |
|---|---|---|
| inventoryId | string | The UUID of the inventory entry |
| filmTitle | string | The film title |
| filmMpaa | string | The film MPAA rating (unrated, G, PG, PG-13, R, NC-17) |
| rentalId | string | The UUID of the current inventory rental or null if new (i.e. if the inventory entry is available) |
| cost | float | The initial or pending cost for the inventory entry rental |
| days | int | The number of days included in the cost according to the clients intent. |
| pricingStrategy | object | The pricinig strategy, see Film Pricing Strategies |
Notes
- The API client is able to authenticate each request (required role: staff or admin)
- The API client can store the entry for use in the next step, update with a new request to adjust the days or discard it at any time (i.e. if the store client changed his mind)
Submit Payment
p>Once ready, the staff can submit the set of orders for payment by submitting a POST request, using an Orders object as the JSON body.| Method | URL |
|---|---|
| POST | http://localhost:8080/calipso/api/rest/order/orders |
The returning Payments JSON has the following properties:
| Name | Type | Description |
|---|---|---|
| items | collection | The persisted payments (one per inventory rental/return) |
| totalCost | float | he total cost of enclosed payments |
Swagger API Reference
The webapp provides automatically-generated API documentation based on Swagger and created by Springfox. To access the documentation run the app and point your browser to http://localhost:8080/calipso/apidoc.
API Overview
In addition to the complete reference documentation described above, the following sections document a subset of the services API. The application exposes more endpoints for auth and SCRUD; those are "inherited" by the calipso-hub-webapp WAR overlay.
With the exception of Orders, endpoints are based on code tiers (Controller, Service, Repository) calipso generated using javassist during application initialization.
Orders
Orders endpoints use DTOs and manually written code to provide the convenient API used in the Sample Workflow.
| Action | Method | URL | Request JSON body | Response JSON body |
|---|---|---|---|---|
| Calculate order | GET | http://localhost:8080/calipso/api/rest/order/orders/:filmInventoryEntryId?days | none | Order DTO |
| Finalize orders | POST | http://localhost:8080/calipso/api/rest/order/orders | Orders DTO | Payments DTO |
DVD Inventory
The DVD inventory endpoints refer to the actual physical DVD boxes available for rent by the store.
| Action | Method | URL | Request body |
|---|---|---|---|
| Create | POST | http://localhost:8080/calipso/api/rest/filmInventoryEntries | JSON |
| Update | PUT | http://localhost:8080/calipso/api/rest/filmInventoryEntries | JSON |
| Search | GET | http://localhost:8080/calipso/api/rest/filmInventoryEntries?:paramN=valueN | ignored |
Search parameters:
| Name | Type |
|---|---|
| id | UUID string |
| film | UUID string | film.[any field property name] | according to the property name |
| createdDate | timestamp |
| lastModifiedBy | UUID string |
| lastModifiedDate | timestamp |
Films
The film endpoints refer to films in the general sense of audio/visual production titles.
| Action | Method | URL | Request body |
|---|---|---|---|
| Create | POST | http://localhost:8080/calipso/api/rest/films | JSON |
| Update | PUT | http://localhost:8080/calipso/api/rest/films | JSON |
| Search | GET | http://localhost:8080/calipso/api/rest/films?:paramN=valueN | ignored |
Search parameters:
| Name | Type |
|---|---|
| id | UUID string |
| title | string (‘%’ is a “like” wildcard) |
| description | string (‘%’ is a “like” wildcard) |
| mpaaRating | enum, one of: unrated, G, PG, PG-13, R, NC-17 |
| createdBy | UUID string |
| createdDate | timestamp |
| lastModifiedBy | UUID string |
| lastModifiedDate | timestamp |
Film Actors
Information on physical persons with roles in films on record
| Action | Method | URL | Request body |
|---|---|---|---|
| Create | POST | http://localhost:8080/calipso/api/rest/filmActors | JSON |
| Update | PUT | http://localhost:8080/calipso/api/rest/filmActors | JSON |
| Search | GET | http://localhost:8080/calipso/api/rest/filmActors?:paramN=valueN | ignored |
Search parameters:
| Name | Type |
|---|---|
| id | UUID string |
| firstName | string (‘%’ is a “like” wildcard) |
| lastName | string (‘%’ is a “like” wildcard) |
| createdBy | UUID string |
| createdDate | timestamp |
| lastModifiedBy | UUID string |
| lastModifiedDate | timestamp |
Film Categories
Film categories (action, drama etc.).
| Action | Method | URL | Request body |
|---|---|---|---|
| Create | POST | http://localhost:8080/calipso/api/rest/filmCategories | JSON |
| Update | PUT | http://localhost:8080/calipso/api/rest/filmCategories | JSON |
| Search | GET | http://localhost:8080/calipso/api/rest/filmCategories?:paramN=valueN | ignored |
Search parameters:
| Name | Type |
|---|---|
| id | UUID string |
| name | string (‘%’ is a “like” wildcard) |
| parent | UUID string |
| createdBy | UUID string |
| createdDate | timestamp |
| lastModifiedBy | UUID string |
| lastModifiedDate | timestamp |
Film Pricing Strategies
The store has three types of films.
- New releases – Price is times number of days rented.
- Regular films – Price is for the fist 3 days and then times the number of days over 3.
- Old film - Price is for the fist 5 days and then times the number of days over 5
This is modeled in three properties:
-
initialPrice - the price to rent a film
-
daysFree -
the number of days included in the
initialPrice -
dailyPrice -
the price per day (not counting
daysFree)
| Action | Method | URL | Request body |
|---|---|---|---|
| Create | POST | http://localhost:8080/calipso/api/rest/filmPricingStrategies | JSON |
| Update | PUT | http://localhost:8080/calipso/api/rest/filmPricingStrategies | JSON |
| Search | GET | http://localhost:8080/calipso/api/rest/filmPricingStrategies?:paramN=valueN | ignored |
Search parameters:
| Name | Type |
|---|---|
| id | UUID string |
| initialPrice | float |
| daysFree | int |
| dailyPrice | float |
| createdBy | UUID string |
| createdDate | timestamp |
| lastModifiedBy | UUID string |
| lastModifiedDate | timestamp |
Rentals
Inventory rentals
| Action | Method | URL | Request body |
|---|---|---|---|
| Create | POST | http://localhost:8080/calipso/api/rest/rentals | JSON |
| Update | PUT | http://localhost:8080/calipso/api/rest/rentals | JSON |
| Search | GET | http://localhost:8080/calipso/api/rest/rentals?:paramN=valueN | ignored |
Search parameters:
| Name | Type |
|---|---|
| id | UUID string |
| customer | UUID string | customer.[any customer property name] | according to the property name |
| inventory | UUID string | inventory.[any inventory property name] | according to the property name |
| createdBy | UUID string |
| rentalDate | timestamp |
| returnDate | timestamp |
| createdDate | timestamp |
| lastModifiedBy | UUID string |
| lastModifiedDate | timestamp |
License
Calipso Hub DVD Rental is distributed under the GNU Affero General Public License
