bookmarkit

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 11 Open GitHub ↗

A Quarkus dojo with JAX-RS, Hibernate with Panache and some Cloud Ready features (OpenAPI, mertrics, health).

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# bookmarkit - Quarkus coding dojo

You can use the `docker-compose.yml` file located on the root of this repository to launch all dependencies.

So going inside the root directory and launching the following command will get you up and running :)

```
docker-compose up
```

There is a Postman collection that can help to test your application during you developement, it is located [here](Bookmarkit.postman_collection.json).

## Step 1 - Quarkus basics

Goal: implements a bookmark service that pass the test from `fr.loicmathieu.bookmarkit.BookmarkResourceTest`.

Steps:

- Open `bookmark-service` inside your favorite IDE
- Implements the `fr.loicmathieu.bookmarkit.BookmarkResource` service, it's a classical CRUD service to allow to create/read/update/delete a bookmark. 
  You must implement the service as a JAX-RS resource ([WRITING JSON REST SERVICES](https://quarkus.io/guides/rest-json-guide)).
  You must use Hibernate ORM with Panache to access the database ([SIMPLIFIED HIBERNATE ORM WITH PANACHE](https://quarkus.io/guides/hibernate-orm-panache-guide)).
- Run the service with `mvn compile quarkus:dev` it has live reload !
- Test that everything works with `mvn test -Dtest=BookmarkResourceTest`.

NOTE: Hibernate is configured to drop and recreate the schema each time you restart your application. You can change this behavior inside your `application.properties`.

## Step 2 - Observability: OpenAPI, OpenMetrics and Health

Goal: implements Observability principles: metrology, health and discoverability

Steps:

- Add [OpenAPI annotations](https://github.com/eclipse/microprofile-open-api/blob/master/spec/src/main/asciidoc/microprofile-openapi-spec.adoc#annotations) to document your API, it will be available at http://localhost:8080/openapi and there is an embedded swagger UI at http://localhost:8080/swagger-ui
  - Use `@Operation` to document each operation.
- Add OpenMetrics annotations to create metrics for each method of your endpoints, you should provide counted and timed metrics via `@Counted` and `@Timed`, 
be careful that the name of the metric must be unique. You can access your metrics at http://localhost:8080/metrics.
- See that an health check is available at http://localhost:8080/health.
- Create a custom check
```
@Readiness
public class AppHealthCheck implements HealthCheck {

@Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.builder().name("bookmark").withData("is", "always").up().build();
    }
}
```
- Test that everything works with `mvn test -Dtest=BookmarkObservabilityTest`.

NOTE: OpenAPI and OpenMetrics works as soon as you integrate the extension inside your application as it provides default documentation and metrics. Health provides basic liveness and readiness checks, you can add your own if needed.

## Step 3 - Configuration

Goal: understand how we can configure the application: [Application Configuration](https://quarkus.io/guides/application-configuration-guide).

Steps:

- Add a configuration property inside you `application.properties` file: `greeting=World` 
- Modify `BookmarkResource` to read this configuration property and log it at startup:
  - Use `@ConfigProperty` to inject the property inside a `greeting` variable.
  - Create a `@PostConstruct` method that log it via `LOGGER.infof("Hello %s", greeting)` using [Jboss logging](https://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html).
- Test using `mvn quarkus:dev` you should see `Hello World` in the console.
- Add a new line to `application.properties` file: `%dev.greeting=Dev` this is an override of the same property for the dev profile.
- Test using `mvn quarkus:dev` you should see `Hello Dev` in the console.

NOTE: you must call the endpoint to initialize it so the method annotated by `@PostConstruct`runs.

## Step 4 - Run you app inside a container

Goal: understand how to build your application, package it in a container, configure it and run it.

Steps:

- Package your application with `mvn package -DskipTests`
- Run your application with `java -jar target/bookmark-service-1.0-SNAPSHOT-runner.jar`
- Limit it's Heap memory with `java -Xmx32m -jar target/bookmark-service-1.0-SNAPSHOT-runner.jar` (you can go lower but your apps will be slower)
- Override it's configuration from the command line with `java -Dgreeting=JAR -jar target/bookmark-service-1.0-SNAPSHOT-runner.jar`
- Build a docker image with `docker build -f src/main/docker/Dockerfile.jvm -t bookmarkit .`
- Run it with `docker run -ti -p 8080:8080 -e "QUARKUS_DATASOURCE_URL=jdbc:postgresql://{your_ip}:5432/mydatabase" bookmarkit` (replace {your_ip} by your ip).

## Step 5 - Send a message via AMQP for each created bookmark

Goal: implements asynchronous messaging via AMQP

Steps:

- Uncomment the commented dependency `quarkus-smallrye-reactive-messaging-amqp` inside the pom.xml file.
- Configure AMQP inside your `application.properties`
```
amqp-username=quarkus
amqp-password=quarkus
```
- Configure MicroProfile messaging inside your `application.properties`
```
mp.messaging.outgoing.bookmarks.connector=smallrye-amqp
mp.messaging.outgoing.bookmarks.address=bookmarks
mp.messaging.outgoing.bookmarks.durable=true
```
- Inject an `Emitter` inside your `BookmarkResource` : `@Inject @Stream("bookmarks") Emitter<Bookmark> emitter;` 
- Use this emitter to send the bookmark inside the `create()` method.
- Launch the consumer from [bookmark-message-consumer](bookmark-message-consumer) via `mvn compile quarkus:dev` in an other console
- Create some bookmarks, you should see a line in the console of  bookmark-message-consumer for each creation

## Step 6 - Call an external service reliability

Goal: learn how to call an external REST service via MicroProfile RestClient and use the fault-tolerance capabilities to make it reliable

Steps:

- Uncomment the commented dependencies `quarkus-rest-client` and `quarkus-smallrye-fault-tolerance` inside the pom.xml file.
- Create an interface annotated with Jax-rs annotations to call the webservice TODO
- Inject it inside the `BookmarkResource` with the `@RestClient` annotation 
- Use it to make a call to the ws each time a bookmark is created
- Test it multiple times, you should see that it crash half of the time
- Add fault-tolerance `@Retry` annotation to retry the call
- Test it again multiple times, it should work now :)

bookmarkit

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README