diff --git a/README.md b/README.md index a3ad011..27d6190 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,90 @@ -# pokemong +# PoKeMoNg -This project uses Quarkus, the Supersonic Subatomic Java Framework. +This is a [Quarkus](https://quarkus.io/) / [MongoDB](https://mongodb.com/) app for educational purposes. -If you want to learn more about Quarkus, please visit its website: https://quarkus.io/ . +Instructions are [here](https://clientserveur-courses.clubinfo-clermont.fr/Notation.html) for reference. -## Running the application in dev mode +## About -You can run your application in dev mode that enables live coding using: -```shell script -./gradlew quarkusDev -``` +A "Pokemong" is a playful term for a `MongoDB` pocket monster. -> **_NOTE:_** Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/. +The application is developed using the Quarkus framework and uses `MongoDB` as its database. -## Packaging and running the application +This application is a RESTful service designed to emulate a basic Pokemong management system. It allows users to perform +CRUD operations on Pokemongs, trainers, moves, and types. -The application can be packaged using: -```shell script -./gradlew build -``` -It produces the `quarkus-run.jar` file in the `build/quarkus-app/` directory. -Be aware that it’s not an _über-jar_ as the dependencies are copied into the `build/quarkus-app/lib/` directory. +
🗂️ See the DCM +Data Concept Model -The application is now runnable using `java -jar build/quarkus-app/quarkus-run.jar`. +
-If you want to build an _über-jar_, execute the following command: -```shell script -./gradlew build -Dquarkus.package.type=uber-jar -``` +
🧬 See the UML Class diagram +UML Class Diagram -The application, packaged as an _über-jar_, is now runnable using `java -jar build/*-runner.jar`. +
-## Creating a native executable +## Prep steps -You can create a native executable using: -```shell script -./gradlew build -Dquarkus.package.type=native -``` +### ♨️ Java version + +This project is set up to use `Java 17`. + +Your build will fail if the version of `Java` that your build tools are using does not match that. + +
💻 Run from command line + +You should have `JDK 17` installed locally, and accessible to `Gradle`. + +That may involve updating your `JAVA_HOME` and `Path` environment variables. + +
+ +
🛠️ Run from an IDE + +If you're planning to run this app directly from an IDE like IntelliJ, make sure to update any `Gradle JVM` (or similar) +settings to use `JDK 17` for `Gradle` tasks + +
+ +### 🔐 Database connection + +Note that the DB connection properties are not included -- your `src/main/resources/application.properties` should look +like this : -Or, if you don't have GraalVM installed, you can run the native executable build in a container using: ```shell script -./gradlew build -Dquarkus.package.type=native -Dquarkus.native.container-build=true +quarkus.mongodb.connection-string=mongodb+srv://:@..mongodb.net +quarkus.mongodb.database= ``` -You can then execute your native executable with: `./build/pokemong-1.0-SNAPSHOT-runner` +
🏫 If you are the corrector + +To be able to use this app, update `application.properties` with the provided database secrets. + +If none were provided, that was a mistake. Sorry. Please request them to the owner of this repo. -If you want to learn more about building native executables, please consult https://quarkus.io/guides/gradle-tooling. +
-## Related Guides +
👥 If you are another user or developer -- MongoDB client ([guide](https://quarkus.io/guides/mongodb)): Connect to MongoDB in either imperative or reactive style +To be able to use this app, first create a MongoDB database, either locally or on +their [Atlas Cloud](https://cloud.mongodb.com/), then update `application.properties` with your database secrets. -## Provided Code +You may want to look up the nice [MongoDB official documentation](https://www.mongodb.com/docs/) if you get stuck. -### RESTEasy Reactive +
-Easily start your Reactive RESTful Web Services +### 🩺 API testing tool -[Related guide section...](https://quarkus.io/guides/getting-started-reactive#reactive-jax-rs-resources) +It is recommended to use an API testing tool such as [Postman](https://www.postman.com/) +or [Insomnia](https://insomnia.rest/), while playing around with this app. + +Moving forward, the front end part of this app -- a different project -- might also come into play for trying out this +API. + +## Running the application in dev mode + +You can run the application in dev mode using: + +```shell script +./gradlew quarkusDev +``` \ No newline at end of file diff --git a/docs/DB.md b/docs/DB.md new file mode 100644 index 0000000..ce5bce5 --- /dev/null +++ b/docs/DB.md @@ -0,0 +1,75 @@ +# About the database schema + +## Collections + +### trainers collection + +* _id: ObjectId +* name: string + * (_indexed_: would be queried often in a dashboard situation) +* dob: date +* wins: int +* losses: int +* past_opponents: array of ObjectId (references to other trainers) + * (_indexed_: reflexivity would make deep queries quite slow, so it seems worthwhile) +* pokemongs: array of ObjectId (references to owned pokemongs) + denormalizing on "nickname" and "species" + * (_indexed_: to improve speed when querying non-denormalized fields) + +### pokemongs collection + +* _id: ObjectId +* nickname: string +* dob: date +* level: int +* pokedex_id: int +* evo_stage: int + * (_indexed_: "species" is calculated as evo_track[evo_stage], and would be queried often) +* evo_track: array of strings (therefore "species" is evo_track[evo_stage], and "evo_base" is evo_track[0]) + * (_indexed_: "species" is calculated as evo_track[evo_stage], and xould be queried often) +* is_mega_evolved: boolean + * **polymorphic**: this field is only here for mature_pokemongs, i.e. pokemongs who have reached their last evo_stage +* trainer: ObjectId? (reference to a trainer) (but can be "wild" instead, if ref is null) + * (_indexed_: could be queried often in a dashboard situation) +* types: embedded type, or array of embedded types + * (_indexed_: would be queried often in a dashboard situation) +* move_set: array of ObjectId (references to known moves) + denormalizing on "name" + +### moves collection + +* _id: ObjectId +* name: string + * (_indexed_: would be queried often in a dashboard situation) +* category: string (can be "physical", "special", or "status") +* pp: int +* power: int + * (_indexed_: would be used often in sorts, in a dashboard situation) +* accuracy: int +* type: embedded type + * (_indexed_: would be queried often in a dashboard situation) + + +### types collection + +* _id: ObjectId +* name: string + * (_indexed_: would be queried often in a dashboard situation) +* weak_against: array of strings (denormalized type names) +* effective_against: array of strings (denormalized type names) + +## Relationships + +* trainers.past_opponents: one-to-many and reflexive + * => referencing +* trainers.pokemongs: one-to-many + * => referencing + denormalizing on "nickname" and "species" +* pokemongs.trainer: many-to-one + * => referencing +* pokemongs.types: one-to-few [1;2] but will also need to be queried independently + * => denormalizing on all fields +* pokemongs.move_set: one-to-few [1;4] but will also need to be queried independently + * => referencing + denormalizing on "name" +* moves.type: one-to-one [1;1] but will also need to be queried independently + * => denormalizing on all fields +* types.weak_against & types.effective_against: one-to-few but reflexive + * => denormalizing on "name" + \ No newline at end of file diff --git a/docs/mcd.png b/docs/mcd.png new file mode 100644 index 0000000..a8ef40a Binary files /dev/null and b/docs/mcd.png differ diff --git a/docs/nosql_uml.png b/docs/nosql_uml.png new file mode 100644 index 0000000..0979200 Binary files /dev/null and b/docs/nosql_uml.png differ