mirror of
https://github.com/jlengrand/quarkus-workshop.git
synced 2026-03-10 08:41:21 +00:00
202 lines
8.7 KiB
Plaintext
202 lines
8.7 KiB
Plaintext
= The Basics
|
||
:experimental:
|
||
|
||
In this step, you will create a straightforward application serving a `hello` endpoint. To demonstrate dependency injection this endpoint uses a `greeting` bean.
|
||
|
||
image::arch.png[arch,800]
|
||
|
||
## Import new project
|
||
|
||
In Che, click on **Import Project...**. In the dialog box, select **GITHUB** as the type of import, and then enter the following URL into the URL field and click **Import**.
|
||
|
||
[source,none,role="copypaste"]
|
||
----
|
||
https://github.com/RedHatWorkshops/quarkus-workshop-labs
|
||
----
|
||
|
||
image::import.png[import,800]
|
||
|
||
[NOTE]
|
||
====
|
||
You may see errors in the _dev machine_ teminal like `Java Model Exception: Java Model Status [people does not exist]`. **These can be safely ignored**.
|
||
====
|
||
|
||
After a few seconds, you'll get a _Project Configuration_ Dialog. Select **Maven** as the project type, and click **Save**.
|
||
|
||
image::importmaven.png[maven,800]
|
||
|
||
This will tell Che that the project is a Maven-based project, and be able to resolve dependencies and do error checking on the `pom.xml` file.
|
||
|
||
The structure of the project can be seen in the project browser to the left of the code editor:
|
||
|
||
image::structure.png[structure,600]
|
||
|
||
The project has
|
||
|
||
* The Maven structure
|
||
* An `org.acme.people.rest.GreetingResource` resource exposed on `/hello`, along with a simple test
|
||
* A landing page that is accessible on `http://localhost:8080` after starting the application
|
||
* The application configuration file
|
||
|
||
To save screen space, you can hide the Git Repository window on the right:
|
||
|
||
image::che-realestate2.png[githide,800]
|
||
|
||
Next, double-click on `pom.xml` in the project browser to open it in the editor. You will find the import of the Quarkus BOM, allowing to omit the version on the different Quarkus dependencies. In addition, you can see the `quarkus-maven-plugin` responsible of the packaging of the application and also providing the development mode.
|
||
|
||
[source,xml]
|
||
----
|
||
<dependencyManagement>
|
||
<dependencies>
|
||
<dependency>
|
||
<groupId>io.quarkus</groupId>
|
||
<artifactId>quarkus-bom</artifactId>
|
||
<version>${quarkus.version}</version>
|
||
<type>pom</type>
|
||
<scope>import</scope>
|
||
</dependency>
|
||
</dependencies>
|
||
</dependencyManagement>
|
||
----
|
||
|
||
And a few more `<dependency>` imports and other ancillary sections. We will be adding things to our `pom.xml` in future sections.
|
||
|
||
Navigate to `src -> main -> java -> org.acme.people.rest` in the project tree and double click on `GreetingResource.java`. This class has a very simple RESTful endpoint definition:
|
||
|
||
[source, java]
|
||
----
|
||
@Path("/hello")
|
||
public class GreetingResource {
|
||
|
||
@GET
|
||
@Produces(MediaType.TEXT_PLAIN)
|
||
public String hello() {
|
||
return "hello";
|
||
}
|
||
}
|
||
----
|
||
|
||
It’s a very simple REST endpoint, returning "hello" to requests on `/hello`.
|
||
|
||
[NOTE]
|
||
====
|
||
Compared to vanilla JAX-RS, with Quarkus there is no need to create an `Application` class. It’s supported but not required. In addition, only one instance of the resource is created and not one per request. You can configure this using the different `*Scoped` annotations (`ApplicationScoped`, `RequestScoped`, etc).
|
||
====
|
||
|
||
## Running the Application in Live Coding Mode
|
||
|
||
**Live Coding** (also referred to as _dev mode_) allows us to run the app and make changes on the fly. Quarkus will automatically re-compile and reload the app when changes are made. This is a powerful and effecient style of developing that you will use throughout the lab.
|
||
|
||
In Che, select the _Command Palette_ by clicking on its icon in the upper right, and double-click on **Start Live Coding**:
|
||
|
||
image::runlocally.png[runlocal,800]
|
||
|
||
This will compile and run the app using `mvn compile quarkus:dev` in a Terminal window. Leave this terminal window open throughout the lab! You can complete the entire lab without shutting down Quarkus Live Coding mode. This is very useful for quick expermentation.
|
||
|
||
[NOTE]
|
||
====
|
||
The first time you build the app, new dependencies may be downloaded via maven. This should only happen once, after that things will go even faster
|
||
====
|
||
|
||
[NOTE]
|
||
====
|
||
You may see WARNINGs like `Unrecognized configuration key` or `Duplicate entry`. These are configuration values that will take effect later on and can be safely ignored for now.
|
||
====
|
||
|
||
You should see:
|
||
|
||
[source,none]
|
||
----
|
||
2019-02-28 17:05:22,347 INFO [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation
|
||
2019-02-28 17:05:22,635 INFO [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 288ms
|
||
2019-02-28 17:05:22,770 INFO [io.quarkus] (main) Quarkus started in 0.668s. Listening on: http://localhost:8080
|
||
2019-02-28 17:05:22,771 INFO [io.quarkus] (main) Installed features: [cdi, resteasy]
|
||
----
|
||
|
||
Note the amazingly fast startup time! The app is now running "locally" (within the Che container in which the workspace is also running). `localhost` refers to the Kubernetes pod, not "your" laptop (so therefore opening localhost:8080 in your browser will not do anything). To access applications from your laptop browser, Che creates an Ingress (referred to as a _Route_ in OpenShift) that is displayed at the top of the Terminal window. Look for _Preview URL_:
|
||
|
||
image::previewurl.png[preview,900]
|
||
|
||
Click on this Preview link to open the link in a new tab, which will access the default Quarkus HTML page included in this app:
|
||
|
||
image::defaultpage.png[default,800]
|
||
|
||
Since our RESTful endpoint listens on the `/hello` endpoint, add `/hello` to the end of the URL in your browser tab to access it.
|
||
|
||
You should see `hello` in your browser tab, which means its working!
|
||
|
||
image::hellopage.png[hello,800]
|
||
|
||
Now, let's exercise the **live reload** capabilities of Quarkus. In Che, open the `GreetingResource.java` file (in `src/main/java/org/acme/people/rest`) and change `return "hello";` to `return "hola";` in the editor. After making this change, reload the same brower tab that was showing `hello`. It should now show `hola`.
|
||
|
||
Wow, how cool is that? Supersonic Subatomic live reload! Go ahead and change it a few more times and access the endpoint again. And we're just getting started. Leave the app running so we can continue to change it on the fly in the next section.
|
||
|
||
[NOTE]
|
||
====
|
||
`quarkus:dev` runs Quarkus in development mode. This enables live reload with background compilation, which means that when you modify your Java files your resource files and refresh your browser these changes will automatically take effect.
|
||
====
|
||
|
||
[NOTE]
|
||
====
|
||
This will also listen for a debugger on port `5005`. If you want to wait for the debugger to attach before running you can pass `-Ddebug` on the command line. If you don’t want the debugger at all you can use `-Ddebug=false`. We'll use this later.
|
||
====
|
||
|
||
### Package the app
|
||
|
||
Quarkus apps can be packaged as an executable JAR file or a native binary. We'll cover native binaries later, so for now, let's package as an executable JAR.
|
||
|
||
Using the command palette, select **Create Executable JAR**.
|
||
|
||
image:createexec.png[create,700]
|
||
|
||
This runs `mvn package` under the hood, and when done produces an executable jar file in the `target/` directory:
|
||
|
||
image::jar.png[jar,800]
|
||
|
||
* `people-1.0-SNAPSHOT-runner.jar` - being an executable jar. Be aware that it’s not an über-jar as the dependencies are copied into the `target/lib` directory.
|
||
|
||
## Opening new Terminals
|
||
|
||
Several steps in this workshop require you to execute commands in a Terminal. To open a new Terminal window, simply right-click on the project name `quarkus-workshop-labs` in the project browser on the left and select **Open In Terminal**:
|
||
|
||
image::term.png[term,800]
|
||
|
||
This will open a new Terminal window and set the current directory to the project directory. You could also use the `+` button on the Terminal tabs area, but you would need to change the directory using `cd quarkus-workshop-labs` before executing commands.
|
||
|
||
## Run the executable JAR
|
||
|
||
Run the packaged application. In a Terminal, run the following command:
|
||
|
||
[source, sh, role="copypaste"]
|
||
----
|
||
java -Dquarkus.http.port=8081 -jar target/*-runner.jar
|
||
----
|
||
|
||
[NOTE]
|
||
====
|
||
We use `-Dquarkus.http.port=8081` to avoid conflicting with port `8080` used for Live Coding mode
|
||
====
|
||
|
||
With the app running, open a separate terminal window, and ensure the app _is_ running by executing a `curl` command:
|
||
|
||
[source, sh, role="copypaste"]
|
||
----
|
||
curl http://localhost:8081/hello
|
||
----
|
||
|
||
You should see:
|
||
|
||
```console
|
||
hola
|
||
```
|
||
|
||
## Cleanup
|
||
|
||
Go back to the terminal in which you ran the app with `java -jar` and stop the app by pressing kbd:[CTRL+C] (or close the Terminal). Be sure not to close the "Live Coding" terminal!
|
||
|
||
## Congratulations!
|
||
|
||
You've seen how to build a basic app, package it as an executable JAR and start it up very quickly. The JAR file can be used like any other executable JAR file (e.g. running it as-is, packaging as a Linux container, etc.)
|
||
|
||
In the next step we'll inject a custom bean to showcase Quarkus' CDI capabilities.
|