[WIP] Update session code

[WIP] Add CRUD and trainers

[WIP] Update OpenAPI

Practical session 3

README.md

@@ -12,7 +12,14 @@ and to submit their own contributions.
 
 ![](./design/models/Class%20Diagram.png)
 
-## External resources
+**NOTE: this diagram has been simplified in the implementation and several fields have been omitted.**
+
+## Support files
+
+- `/design`: this folder different files to support the design of the PokeApp including an [OpenAPI specification](./design/open-api.yaml) containing all routes and various [HTTP request files](./design/requests) to be executed directly from IntelliJ's HTTP client.
+- `./meetings/practical-session-3.md`: [this file](./meetings/practical-session-3.md) contains different guides and tips to help you work on the practical session (e.g., how to checkout a new remote branch, or how to run HTTP requests).
+
+## Credits
 
 The following datasets and resources have been used in the development this project.
 

design/open-api.yaml

@@ -20,8 +20,8 @@ tags:
     description: Routes for managing data about trainers.
   - name: Pokémon
     description: Routes for managing data about pokémon.
-#  - name: Pokémon Type
-#    description: Routes for managing data about pokémon types.
+  - name: Pokémon Type
+    description: Routes for managing data about pokémon types.
 paths:
   /trainers:
     get:
@@ -42,6 +42,26 @@ paths:
       responses:
         200:
           description: OK
+          content:
+            application/json:
+              example:
+                {
+                  "meta": {
+                    "total": 1,
+                    "pageNumber": 1,
+                    "pageSize": 1
+                  },
+                  "data": [
+                    {
+                      "id": "1",
+                      "name": "Red",
+                      "created": "24/04/2024",
+                      "lastUpDate": "2024-05-12T23:12:01.660866Z",
+                      "profileUrl": "https://archives.bulbagarden.net/media/upload/thumb/d/d3/Lets_Go_Pikachu_Eevee_Red.png/500px-Lets_Go_Pikachu_Eevee_Red.png"
+                    }
+                  ]
+                }
+
     post:
       description: Creates a resource on the route's collection.
       tags:
@@ -50,10 +70,30 @@ paths:
         content:
           'application/json':
             schema:
-              type: object
+              $ref: '#/components/schemas/Trainer'
+            examples:
+              full:
+                description: Complete POST example
+                value: {
+                  "name": "Red",
+                  "profileUrl": "https://archives.bulbagarden.net/media/upload/thumb/d/d3/Lets_Go_Pikachu_Eevee_Red.png/500px-Lets_Go_Pikachu_Eevee_Red.png"
+                }
+              min:
+                description: Minimum POST example
+                value: { }
       responses:
         200:
           description: OK
+          content:
+            'application/json':
+              example:
+                {
+                  "id": "1",
+                  "name": "Red",
+                  "created": "24/04/2024",
+                  "lastUpDate": "2024-05-12T23:12:01.660866Z",
+                  "profileUrl": "https://archives.bulbagarden.net/media/upload/thumb/d/d3/Lets_Go_Pikachu_Eevee_Red.png/500px-Lets_Go_Pikachu_Eevee_Red.png"
+                }
         400:
           description: Bad request
         405:
@@ -74,6 +114,16 @@ paths:
       responses:
         200:
           description: OK
+          content:
+            'application/json':
+              example:
+                {
+                  "id": "1",
+                  "name": "Red",
+                  "created": "24/04/2024",
+                  "lastUpDate": "2024-05-12T23:12:01.660866Z",
+                  "profileUrl": "https://archives.bulbagarden.net/media/upload/thumb/d/d3/Lets_Go_Pikachu_Eevee_Red.png/500px-Lets_Go_Pikachu_Eevee_Red.png"
+                }
         404:
           description: Not found
     put:
@@ -93,10 +143,31 @@ paths:
         content:
           'application/json':
             schema:
-              type: object
+              $ref: '#/components/schemas/Trainer'
+            examples:
+              full:
+                description: Complete PUT example
+                value: {
+                  "id": "1",
+                  "name": "New Red Name",
+                  "profileUrl": null
+                }
+              min:
+                description: Minimum PUT example
+                value: { "id": "1" }
       responses:
         200:
           description: OK
+          content:
+            'application/json':
+              example:
+                {
+                  "id": "1",
+                  "name": "New Red Name",
+                  "created": "24/04/2024",
+                  "lastUpDate": "2024-05-12T23:12:01.660866Z",
+                  "profileUrl": null
+                }
         400:
           description: Bad request
         404:
@@ -125,96 +196,174 @@ paths:
         405:
           description: Server error
 
-#  /pokemon:
-#    get:
-#      description: Retrieves a collection of resources.
-#      tags:
-#        - Pokémon
-#      responses:
-#        200:
-#          description: OK
-#    post:
-#      description: Creates a resource on the route's collection.
-#      tags:
-#        - Pokémon
-#      requestBody:
-#        content:
-#          'application/json':
-#            schema:
-#              type: object
-#      responses:
-#        200:
-#          description: OK
-#        400:
-#          description: Bad request
-#        405:
-#          description: Server error
-#  /pokemon/{id}:
-#    get:
-#      description: Retrieves a resource with matching a {id}.
-#      tags:
-#        - Pokémon
-#      parameters:
-#        - name: id
-#          description: The {id} of the desired resource.
-#          in: path
-#          schema:
-#            type: string
-#            minLength: 1
-#          required: true
-#      responses:
-#        200:
-#          description: OK
-#        404:
-#          description: Not found
-#    put:
-#      description: Replaces the resource {id} with the provided one.
-#      tags:
-#        - Pokémon
-#      parameters:
-#        - name: id
-#          description: The {id} of the desired resource.
-#          in: path
-#          schema:
-#            type: string
-#            minLength: 1
-#          required: true
-#
-#      requestBody:
-#        content:
-#          'application/json':
-#            schema:
-#              type: object
-#      responses:
-#        200:
-#          description: OK
-#        400:
-#          description: Bad request
-#        404:
-#          description: Not found
-#        405:
-#          description: Server error
-#    delete:
-#      description: Deletes the resource identified as {id}.
-#      tags:
-#        - Pokémon
-#      parameters:
-#        - name: id
-#          description: The {id} of the desired resource.
-#          in: path
-#          schema:
-#            type: string
-#            minLength: 1
-#          required: true
-#      responses:
-#        204:
-#          description: No content
-#        400:
-#          description: Bad request
-#        404:
-#          description: Not found
-#        405:
-#          description: Server error
+  /pokemon:
+    get:
+      description: Retrieves a collection of resources.
+      tags:
+        - Pokémon
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              example:
+                {
+                  "meta": {
+                    "total": 1,
+                    "pageNumber": 1,
+                    "pageSize": 1
+                  },
+                  "data": [
+                    {
+                      "id": "1",
+                      "created": "24/04/2024",
+                      "lastUpDate": "2024-05-12T23:12:01.660866Z",
+                      "name": "My Pikachu",
+                      "pokemonType": "513",
+                      "trainerId": "1"
+                    }
+                  ]
+                }
+    post:
+      description: Creates a resource on the route's collection.
+      tags:
+        - Pokémon
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/Pokemon'
+            examples:
+              full:
+                value: {
+                  "name": "My Pikachu",
+                  "pokemonType": "513",
+                  "trainerId": "1"
+                }
+                description: Complete POST example
+              min:
+                value: { }
+                description: Minimum POST example
+      responses:
+        200:
+          description: OK
+          content:
+            'application/json':
+              example:
+                {
+                  "id": "1",
+                  "created": "24/04/2024",
+                  "lastUpDate": "2024-05-12T23:12:01.660866Z",
+                  "name": "My Pikachu",
+                  "pokemonType": "513",
+                  "trainerId": "1"
+                }
+        400:
+          description: Bad request
+        405:
+          description: Server error
+  /pokemon/{id}:
+    get:
+      description: Retrieves a resource with matching a {id}.
+      tags:
+        - Pokémon
+      parameters:
+        - name: id
+          description: The {id} of the desired resource.
+          in: path
+          schema:
+            type: string
+            minLength: 1
+          required: true
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              example:
+                {
+                  "id": "1",
+                  "name": "My Pikachu",
+                  "created": "24/04/2024",
+                  "lastUpDate": "2024-05-12T23:12:01.660866Z",
+                  "pokemonType": "513",
+                  "trainerId": "1"
+                }
+        404:
+          description: Not found
+    put:
+      description: Replaces the resource {id} with the provided one.
+      tags:
+        - Pokémon
+      parameters:
+        - name: id
+          description: The {id} of the desired resource.
+          in: path
+          schema:
+            type: string
+            minLength: 1
+          required: true
+
+      requestBody:
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/Pokemon'
+            examples:
+              full:
+                value: {
+                  "id": "1",
+                  "name": "It's Blue's charmander",
+                  "pokemonType": "4",
+                  "trainerId": "2"
+                }
+                description: Complete PUT example
+              min:
+                value: {
+                  "id": "1"
+                }
+                description: Minimum PUT example
+      responses:
+        200:
+          description: OK
+          content:
+            'application/json':
+              example:
+                {
+                  "id": "1",
+                  "created": "24/04/2024",
+                  "lastUpDate": "2024-05-12T23:12:01.660866Z",
+                  "name": "It's Blue's charmander",
+                  "pokemonType": "4",
+                  "trainerId": "2"
+                }
+        400:
+          description: Bad request
+        404:
+          description: Not found
+        405:
+          description: Server error
+    delete:
+      description: Deletes the resource identified as {id}.
+      tags:
+        - Pokémon
+      parameters:
+        - name: id
+          description: The {id} of the desired resource.
+          in: path
+          schema:
+            type: string
+            minLength: 1
+          required: true
+      responses:
+        204:
+          description: No content
+        400:
+          description: Bad request
+        404:
+          description: Not found
+        405:
+          description: Server error
 
   /pokemonTypes:
     get:
@@ -244,6 +393,44 @@ paths:
       responses:
         200:
           description: OK
+          content:
+            'application/json':
+              example: {
+                "meta": {
+                  "total": 1,
+                  "pageNumber": 1,
+                  "pageSize": 1
+                },
+                "data": [
+                  {
+                    "id": "1",
+                    "name": "Abomasnow",
+                    "created": "24/04/2024",
+                    "lastUpDate": "24/04/2024",
+                    "pokedexNumber": 460,
+                    "generation": 4,
+                    "japaneseName": "Yukinoohユキノオー",
+                    "classification": "Frosted Tree Pokémon",
+                    "abilities": [
+                      "Snow Warning",
+                      "Soundproof"
+                    ],
+                    "baseHeight": 2.2,
+                    "baseWeight": 135.5,
+                    "baseHp": 90,
+                    "baseAttack": 132,
+                    "baseSpAttack": 132,
+                    "baseDefense": 105,
+                    "baseSpDefense": 105,
+                    "baseSpeed": 30,
+                    "captureRate": 60,
+                    "isLegendary": false,
+                    "imgUrl": "./images/abomasnow.png",
+                    "primaryType": "grass",
+                    "secondaryType": "ice"
+                  }
+                ]
+              }
     post:
       description: Creates a resource on the route's collection.
       tags:
@@ -252,10 +439,48 @@ paths:
         content:
           'application/json':
             schema:
-              $ref: '#/components/schemas/Trainer'
+              $ref: '#/components/schemas/PokemonType'
+            examples:
+              partial:
+                value: {
+                  "id": "804",
+                  "name": "New Pokemon Type",
+                  "pokedexNumber": 999
+                }
+                description: Partial POST example
+              min:
+                value: { }
+                description: Minimum POST example
       responses:
         200:
           description: OK
+          content:
+            'application/json':
+              example:
+                {
+                  "id": "804",
+                  "name": "New Pokemon Type",
+                  "created": null,
+                  "lastUpDate": "2024-05-13T08:07:50.212596Z",
+                  "pokedexNumber": 999,
+                  "generation": 0,
+                  "japaneseName": null,
+                  "classification": null,
+                  "abilities": null,
+                  "baseHeight": 0.0,
+                  "baseWeight": 0.0,
+                  "baseHp": 0,
+                  "baseAttack": 0,
+                  "baseSpAttack": 0,
+                  "baseDefense": 0,
+                  "baseSpDefense": 0,
+                  "baseSpeed": 0,
+                  "captureRate": 0,
+                  "isLegendary": false,
+                  "imgUrl": null,
+                  "primaryType": null,
+                  "secondaryType": null
+                }
         400:
           description: Bad request
         405:
@@ -276,6 +501,33 @@ paths:
       responses:
         200:
           description: OK
+          content:
+            'application/json':
+              example:
+                {
+                  "id": "804",
+                  "name": "Modified Pokemon Type",
+                  "created": "2024-05-13T08:04:03.186221Z",
+                  "lastUpDate": "2024-05-13T08:04:03.186308Z",
+                  "pokedexNumber": 1000,
+                  "generation": 0,
+                  "japaneseName": null,
+                  "classification": "The most powerful pokemon",
+                  "abilities": null,
+                  "baseHeight": 0.0,
+                  "baseWeight": 0.0,
+                  "baseHp": 0,
+                  "baseAttack": 0,
+                  "baseSpAttack": 0,
+                  "baseDefense": 0,
+                  "baseSpDefense": 0,
+                  "baseSpeed": 0,
+                  "captureRate": 0,
+                  "isLegendary": false,
+                  "imgUrl": null,
+                  "primaryType": null,
+                  "secondaryType": null
+                }
         404:
           description: Not found
     put:
@@ -295,7 +547,17 @@ paths:
         content:
           'application/json':
             schema:
-              type: object
+              $ref: '#/components/schemas/PokemonType'
+            examples:
+              partial:
+                value: {
+                  "name": "Modified Pokemon Type",
+                  "pokedexNumber": 1000
+                }
+                description: Partial PUT example
+              min:
+                value: { }
+                description: Minimum PUT example
       responses:
         200:
           description: OK
@@ -359,41 +621,28 @@ components:
             type: string
             minLength: 1
 
-#    Pokemon:
-#      description: Schema describing the overall shape of pokemon resources.
-#      type: object
-#      properties:
-#        id:
-#          type: string
-#          minLength: 1
-#        created:
-#          type: string
-#          format: date-time
-#        lastUpdate:
-#          type: string
-#          format: date-time
-#        name:
-#          type: string
-#          minLength: 1
-#        height:
-#          type: number
-#        weight:
-#          type: number
-#        hp:
-#          type: number
-#        attack:
-#          type: number
-#        spAttack:
-#          type: number
-#        defense:
-#          type: number
-#        spDefense:
-#          type: number
-#        speed:
-#          type: number
-#        pokemonType:
-#          type: string
-#          minLength: 1
+    Pokemon:
+      description: Schema describing the overall shape of pokemon resources.
+      type: object
+      properties:
+        id:
+          type: string
+          minLength: 1
+        created:
+          type: string
+          format: date-time
+        lastUpdate:
+          type: string
+          format: date-time
+        name:
+          type: string
+          minLength: 1
+        pokemonType:
+          type: string
+          minLength: 1
+        trainerId:
+          type: string
+          minLength: 1
 
     PokemonType:
       description: Schema describing the overall shape of pokemon type resources.

design/requests/requests-pokemon-types.http

+###
+GET http://localhost:8080/pokemon/api/pokemonTypes
+
+###
+GET http://localhost:8080/pokemon/api/pokemonTypes?pageSize=1&pageNumber=1
+
+###
+GET http://localhost:8080/pokemon/api/pokemonTypes/1
+
+###
+POST http://localhost:8080/pokemon/api/pokemonTypes
+Content-Type: application/json
+
+{}
+
+###
+# Run this after creating a new pokemon type
+PUT http://localhost:8080/pokemon/api/pokemonTypes/802
+Content-Type: application/json
+
+{
+  "id": "802",
+  "name": "Modified Pokemon Type"
+}
+
+###
+# Run this after creating a new pokemon type
+DELETE http://localhost:8080/pokemon/api/pokemonTypes/802

design/requests/requests-pokemon.http

+###
+GET http://localhost:8080/pokemon/api/pokemon
+
+###
+# Run rhis after implementing pagination
+GET http://localhost:8080/pokemon/api/pokemon?pageSize=1&pageNumber=1
+
+###
+# Run rhis after implementing sorting
+GET http://localhost:8080/pokemon/api/pokemon?sortBy=name
+
+###
+# If you run this before creating a pokemon, it should return a 404 error
+GET http://localhost:8080/pokemon/api/pokemon/1
+
+###
+POST http://localhost:8080/pokemon/api/pokemon
+Content-Type: application/json
+
+{
+  "name": "My new pokemon",
+  "pokemonType": "1",
+  "trainerId": "1"
+}
+
+###
+# Run this after creating a new pokemon
+PUT http://localhost:8080/pokemon/api/pokemon/1
+Content-Type: application/json
+
+{
+  "id": "1",
+  "name": "My modified pokemon",
+  "pokemonType": "1",
+  "trainerId": "2"
+}
+
+###
+# Run this after creating a new pokemon
+DELETE http://localhost:8080/pokemon/api/pokemon/1

design/requests/requests-trainers.http

+###
+GET http://localhost:8080/pokemon/api/trainers
+
+###
+GET http://localhost:8080/pokemon/api/trainers?pageSize=1&pageNumber=1
+
+###
+GET http://localhost:8080/pokemon/api/trainers/1
+
+###
+POST http://localhost:8080/pokemon/api/trainers
+Content-Type: application/json
+
+{}
+
+###
+# Run this after creating a new trainer
+PUT http://localhost:8080/pokemon/api/trainers/5
+Content-Type: application/json
+
+{
+  "id": "5",
+  "name": "Ash Ketchum"
+}
+
+###
+# Run this after creating a new trainer
+DELETE http://localhost:8080/pokemon/api/trainers/5

design/system-design.md

 ## Class Diagram
 
-![](/design/models/Class%20Diagram.png)
+NOTE: this diagram has been simplified in the implementation and several fields have been omitted.
+
+![](./models/Class%20Diagram.png)

meetings/practical-session-3.md

+# Practical Session 3 - Guides and Tips
+
+## Changing the application name on Tomcat
+
+As we are using IntelliJ to build and send our application to the Tomcat server, we need to change the _Running Configurations_ in order to set the base route this application. For example, when using `/pokemon` as the base route, all other routes will be affected like `/pokemon/pokemonTypes.html` and `/pokemon/api/pokemonTypes`. To change this, please set the field _Application context_ under the tab _Deployment_ to `/pokemon`.
+
+![](./running-configurations.png)
+
+## Checkout new branch
+
+In order to retrieve the code for the exercises of the practical session, perform the step below on your git client. Here we'll be using IntelliJ's git client:
+
+1. Find or list the remote list of your git client
+
+    ![](./intellij-git-remote.png)
+
+2. Fetch from the remote repository containing the original project all updates
+
+    ![](./intellij-git-fetch-remote.png)
+
+3. Checkout the branch `practical-session-3` and start working on it
+
+    ![](./intellij-git-checkout-branch.png)
+
+4. After committing your changes, push the branch to the upstream (i.e., to your fork on GitLab)
+
+    ![](./intellij-git-push.png)
+
+5. On GitLab, open a new Merge Request
+
+Work on implementing the issues tagged as both `feature-request` and `practical-session-3`
+
+## Running HTTP request on IntelliJ
+
+With IntelliJ, you can create files ending with `.http` to write and run requests directly from the IDE. You can find sample files [here](./../design/requests) and the full documentation [here](https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html).
+
+![](./http-client.animated.gif)
+
+
+## REST API documentations with OpenAPI
+
+OpenAPI is a standard for documenting REST APIs in JSON (or YAML). On IntelliJ, you can open the [our OpenAPI specification](./../design/open-api.yaml) and check all routes implemented or to be implemented, including examples.
+
+![](./open-api.png)

src/main/java/nl/utwente/mod4/pokemon/InitializationListener.java

@@ -35,4 +35,5 @@ public class InitializationListener implements ServletContextListener {
         }
         System.out.println("PokeApp shutdown.");
     }
+
 }

src/main/java/nl/utwente/mod4/pokemon/RequestFilter.java

+package nl.utwente.mod4.pokemon;
+
+import jakarta.ws.rs.container.ContainerRequestContext;
+import jakarta.ws.rs.container.ContainerRequestFilter;
+import jakarta.ws.rs.ext.Provider;
+
+@Provider
+public class RequestFilter implements ContainerRequestFilter {
+
+    @Override
+    public void filter(ContainerRequestContext requestContext) {
+        System.out.println("Incoming Request:");
+        System.out.println("Method: " + requestContext.getMethod());
+        System.out.println("URI: " + requestContext.getUriInfo().getRequestUri());
+        System.out.println("Headers: " + requestContext.getHeaders());
+    }
+
+}

src/main/java/nl/utwente/mod4/pokemon/Utils.java

 package nl.utwente.mod4.pokemon;
 
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Path;
 import java.util.List;
 
 public class Utils {
 
     public static String getAbsolutePathToResources() {
-        return Utils.class.getClassLoader().getResource("").getPath();
+        var path = Utils.class.getClassLoader().getResource("").getPath();
+        return URLDecoder.decode(path, StandardCharsets.UTF_8);
     }
 
     public static <T extends Comparable<T>> int compare(T o1, T o2) {

src/main/java/nl/utwente/mod4/pokemon/dao/PokemonTypeDao.java

@@ -98,8 +98,8 @@ public enum PokemonTypeDao {
                 .get();
     }
 
-    public PokemonType update(PokemonType updated) {
-        if(!updated.isValid())
+    public PokemonType replace(PokemonType updated) {
+        if(!updated.checkIsValid())
             throw new BadRequestException("Invalid pokemon type.");
         if(pokemonTypes.get(updated.id) == null)
             throw new NotFoundException("Pokemon type id '" + updated.id + "' not found.");

src/main/java/nl/utwente/mod4/pokemon/dao/TrainerDao.java

@@ -88,8 +88,8 @@ public enum TrainerDao {
         return newTrainer;
     }
 
-    public Trainer update(Trainer updated) {
-        if(!updated.isValid())
+    public Trainer replace(Trainer updated) {
+        if(!updated.checkIsValid())
             throw new BadRequestException("Invalid trainer.");
         if(trainers.get(updated.id) == null)
             throw new NotFoundException("Trainer id '" + updated.id + "' not found.");

src/main/java/nl/utwente/mod4/pokemon/model/NamedEntity.java

 package nl.utwente.mod4.pokemon.model;
 
-import java.time.Instant;
-
 public class NamedEntity {
 
     public String id;
@@ -16,7 +14,7 @@ public class NamedEntity {
         lastUpDate = null;
     }
 
-    public boolean isValid() {
+    public boolean checkIsValid() {
         return id != null && !id.isEmpty();
     }