Skip to content

Various documentation fixes #666

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Jan 30, 2019
Merged

Various documentation fixes #666

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
f61e983
fix variable injection and uber-jar explanation in the getting starte…
cescoffier Jan 29, 2019
91ac664
add a note about having a working docker environment before building …
cescoffier Jan 29, 2019
b808c82
extend a bit the application configuration guide
cescoffier Jan 29, 2019
00036ba
use admonitions
cescoffier Jan 29, 2019
ead2453
move the extension list to a filtered resource directory - otherwise …
cescoffier Jan 29, 2019
6bb3aa8
Various fixes in the input validation guides
cescoffier Jan 29, 2019
cebb3b6
Extend the list of items generated by the create project mojo
cescoffier Jan 29, 2019
9be53bc
Fix typos in the scheduled tasks guide
cescoffier Jan 29, 2019
47ec614
Replace reference to the old repository
cescoffier Jan 29, 2019
fc19f4b
Modify the getting started guide to use the project generation capabi…
cescoffier Jan 29, 2019
58c2279
apply the comment made by Guillaume
cescoffier Jan 30, 2019
29882ac
Some more reviews:
cescoffier Jan 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
0 ...common/src/main/resources/extensions.json → cli/common/src/main/filtered/extensions.json
View file
Open in desktop
File renamed without changes.
2 changes: 1 addition & 1 deletion docs/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
<shamrock-version>${project.version}</shamrock-version>
<surefire-version>${version.surefire.plugin}</surefire-version>
<graal-version>${graal-sdk.version-for-documentation}</graal-version>
<restassured-version>3.3.0</restassured-version>
<restassured-version>${rest-assured.version}</restassured-version>
<project-name>Protean</project-name>
</attributes>
</configuration>
Expand Down
24 changes: 19 additions & 5 deletions docs/src/main/asciidoc/application-configuration-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,17 +19,17 @@ Remember, you need to configure Maven as indicated in the link:maven-config.html
We recommend you to follow the instructions in the next sections and create the application step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone https://github.com/protean-project/quickstarts.git`, or download an https://github.com/protean-project/quickstarts/archive/master.zip[archive].
Clone the Git repository: `git clone https://github.com/jbossas/protean-quickstarts.git`, or download an https://github.com/jbossas/protean-quickstarts/archive/master.zip[archive].

The solution is located in the `application-configuration` directory.

== Creating the Maven project

First, we need a new project. Create a new project with the following command:

[source]
[source, subs=attributes+]
----
mvn org.jboss.shamrock:shamrock-maven-plugin:1.0.0.Alpha1-SNAPSHOT:create \
mvn org.jboss.shamrock:shamrock-maven-plugin:{shamrock-version}:create \
-DprojectGroupId=org.acme \
-DprojectArtifactId=application-configuration \
-DclassName="org.acme.config.GreetingResource" \
Expand All @@ -39,6 +39,9 @@ mvn org.jboss.shamrock:shamrock-maven-plugin:1.0.0.Alpha1-SNAPSHOT:create \
It generates:

* the Maven structure
* a landing page accessible on `http://localhost:8080`
* an example of `Dockerfile`
* the application configuration file
* an `org.acme.config.GreetingResource` resource
* an associated test

Expand Down Expand Up @@ -91,7 +94,7 @@ public String hello() {

We need to create the file providing the values.
By default, Shamrock reads `META-INF/microprofile-config.properties`.
Create the `src/main/resources/META-INF/microprofile-config.properties` with the following content:
Edit the `src/main/resources/META-INF/microprofile-config.properties` with the following content:

[source]
----
Expand All @@ -100,6 +103,17 @@ greeting.message = hello
greeting.name = shamrock
----

Once set, check the application with:

[source]
----
$ curl http://localhost:8080/greeting
hello shamrock!
----

TIP: If the application requires configuration values and these values are not set, an error is thrown.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A TIP admonition would make sense?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's already an admonition (single line admonition).

Admonition blocks are supported too and allows adding title and paragraph as content. However, for short notes like this one I've found single-line more readable.

So you can quickly now when your configuration is complete.

== Update the test

We also need to update the functional test to reflect the changes made to endpoint.
Expand Down Expand Up @@ -140,4 +154,4 @@ Changing the configuration file is immediately reflected.
You can add the `greeting.suffix`, remove the other properties, change the values, etc.

As usual, the application can be packaged using `mvn clean package` and executed using the `-runner.jar` file.
You can also generate the native executable.
You can also generate the native executable with `mvn clean package -Pnative`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not related to this patch but maybe we should be consistent with what we do in Shamrock proper and use -Dnative. We would need the profile to be activated on the property.

Not sure it's worth the work though. In any case, if we decide to do it, let's do it in a follow-up PR (and update all the guides).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to prefer specifying profiles explicitly, at least for the users. Now, if the user is a Maven user, he can definitely change that.

But we can change the behavior (it would require changing the template, doc, and quickstarts).

17 changes: 7 additions & 10 deletions docs/src/main/asciidoc/application-lifecycle-events-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Remember, you need to configure Maven as indicated in the link:maven-config.html
We recommend you to follow the instructions in the next sections and create the application step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone https://github.com/protean-project/quickstarts.git`, or download an https://github.com/protean-project/quickstarts/archive/master.zip[archive].
Clone the Git repository: `git clone https://github.com/jbossas/protean-quickstarts.git`, or download an https://github.com/jbossas/protean-quickstarts/archive/master.zip[archive].

The solution is located in the `application-lifecycle-events` directory.

Expand All @@ -42,6 +42,9 @@ mvn org.jboss.shamrock:shamrock-maven-plugin:{shamrock-version}:create \
It generates:

* the Maven structure
* a landing page accessible on `http://localhost:8080`
* an example of `Dockerfile`
* the application configuration file
* an `org.acme.events.GreetingResource` resource
* an associated test

Expand Down Expand Up @@ -80,20 +83,14 @@ public class AppLifecycleBean {
1. Method called when the application is starting
2. Method called when the application is terminating

[INFO]
====
The events are also called in _dev mode_ between each redeployment.
====
TIP: The events are also called in _dev mode_ between each redeployment.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, one line admonitions are supported this way?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. See https://asciidoctor.org/docs/user-manual/#admonition.


[INFO]
====
The methods can access injected beans. Check the https://github.com/protean-project/quickstarts/blob/master/application-lifecycle-events/src/main/java/org/acme/events/AppLifecycleBean.java[AppLifecycleBean.java] class for details.
====
NOTE: The methods can access injected beans. Check the https://github.com/jbossas/protean-quickstarts/blob/master/application-lifecycle-events/src/main/java/org/acme/events/AppLifecycleBean.java[AppLifecycleBean.java] class for details.

== Package and run the application

Run the application with: `mvn compile shamrock:dev`, the logged message is printed.
When the application is stopped, the second log message is printed.

As usual, the application can be packaged using `mvn clean package` and executed using the `-runner.jar` file.
You can also generate the native executable.
You can also generate the native executable using `mvn clean package -Pnative`.
10 changes: 6 additions & 4 deletions docs/src/main/asciidoc/building-native-image-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Remember, you need to configure Maven as indicated in the link:maven-config.html
We recommend you to follow the instructions in the next sections and package the application step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone https://github.com/protean-project/quickstarts.git`, or download an https://github.com/protean-project/quickstarts/archive/master.zip[archive].
Clone the Git repository: `git clone https://github.com/jbossas/protean-quickstarts.git`, or download an https://github.com/jbossas/protean-quickstarts/archive/master.zip[archive].

The solution is located in the `getting-started-native` directory.

Expand All @@ -54,7 +54,7 @@ image:native-image-process.png[Creating a native executable, width=640]

Before going further, be sure that the `GRAALVM_HOME` environment variable is configured appropriately.

Edit the `pom.xml` to add the following _profile_.
If you generated the application from the previous tutorial, you can find in the `pom.xml` the following _profile_:

[source,xml]
----
Expand Down Expand Up @@ -86,7 +86,7 @@ Edit the `pom.xml` to add the following _profile_.

We use a profile because, you will see very soon, packaging the native image takes a _few_ seconds.

Now run: `mvn package -Pnative`
Create a native executable using: `mvn package -Pnative`.

In addition to the regular files, the build also produces `target/shamrock-quickstart-1.0-SNAPSHOT-runner`.
You can run it using: `target/shamrock-quickstart-native-1.0-SNAPSHOT-runner`.
Expand Down Expand Up @@ -176,6 +176,8 @@ Executing /Users/starksm/Dev/JBoss/Protean/get-started/target/shamrock-quickstar

== Producing a Docker container

IMPORTANT: Before going further, be sure to have a working Docker environment.

You can run the application in a Docker container using the JAR produced by the Shamrock Maven Plugin.
However, in this guide we focus on creating a Docker image using the produced native executable.
Because the Docker container may not use the same _executable_ format as the one produced by default, we must instruct the Maven build to produce an
Expand All @@ -188,7 +190,7 @@ mvn package -Pnative -Dnative-image.docker-build=true

The produced executable will be a 64 bit Linux executable, so depending on your operating system it may no longer be runnable.
However, it's not an issue as we are going to copy it to a Docker container.
Create the following `Dockerfile` in the `src/main/docker` (or wherever you want):
The project generation has provided a `Dockerfile` in the `src/main/docker` with the following content:

[source]
----
Expand Down
72 changes: 37 additions & 35 deletions docs/src/main/asciidoc/getting-started-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,33 +49,34 @@ Clone the Git repository: `git clone [email protected]:jbossas/protean-quickstarts.

The solution is located in the `getting-started` directory.

== Creating the pom file
== Bootstrapping the project

In your favorite IDE, create a new Maven project.
It should generate a `pom.xml` file with a content similar to:
The easiest way to create a new Protean project is to open a terminal and run the following command:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, missed that on the first review, but Protean should be {project-name}. We use that consistently in the docs.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Damn! Yes, thanks!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

replaced everywhere.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have you pushed your changes? It still appears as "Protean" on GitHub?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well... pushed on the wrong remote. Will cleanup once merged.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be better now.


[source,xml]
[source, subs=attributes+]
----
mvn org.jboss.shamrock:shamrock-maven-plugin:{shamrock-version}:create \
-DprojectGroupId=org.acme \
-DprojectArtifactId=getting-started \
-DclassName="org.acme.quickstart.GreetingResource" \
-Dpath="/hello"
----
<?xml version="1.0" encoding="UTF-8"?>
<project>
<modelVersion>4.0.0</modelVersion>

<groupId>org.acme</groupId>
<artifactId>shamrock-quickstart</artifactId>
<version>1.0-SNAPSHOT</version>
It generates:

</project>
----
* the Maven structure
* an `org.acme.quickstart.GreetingResource` resource exposed on `/hello`
* an associated unit test
* a landing page accessible on `http://localhost:8080`
* an example of `Dockerfile`
* the application configuration file

Add the Shamrock Maven plugin to the `pom.xml` file:
Once generated, look at the `pom.xml`.
You will find the import of the Shamrock BOM, allowing to omit the version on the different Protean dependencies.
In addition, you can see the `shamrock-maven-plugin` responsible of the packaging of the application and also providing the development mode.

[source,xml,subs=attributes+]
----
<properties>
<shamrock.version>{shamrock-version}</shamrock.version>
<surefire.version>{surefire-version}</surefire.version>
</properties>

<dependencyManagement>
<dependencies>
<dependency>
Expand Down Expand Up @@ -112,11 +113,10 @@ Add the Shamrock Maven plugin to the `pom.xml` file:
Shamrock can be seen as {project-name} core.
====

As we are going to create a JAX-RS endpoint, you also need to add the following dependencies:
If we focus on the dependencies section, you can see 2 extensions allowing the development of REST applications:

[source,xml]
----
<dependencies>
<dependency>
<groupId>org.jboss.shamrock</groupId>
<artifactId>shamrock-jaxrs-deployment</artifactId>
Expand All @@ -125,7 +125,6 @@ As we are going to create a JAX-RS endpoint, you also need to add the following
<groupId>org.jboss.shamrock</groupId>
<artifactId>shamrock-arc-deployment</artifactId>
</dependency>
</dependencies>
----

[NOTE]
Expand All @@ -134,9 +133,9 @@ As we are going to create a JAX-RS endpoint, you also need to add the following
ArC is a CDI-based dependency injection solution - see also link:cdi-reference.html[Contexts and Dependency Injection].
====

=== Creating the JAX-RS resource
=== The JAX-RS resources

Create the `src/main/java/org/acme/quickstart/GreetingResource.java` file with the following content:
During the project creation, the `src/main/java/org/acme/quickstart/GreetingResource.java` file as been created with the following content:

[source,java]
----
Expand All @@ -158,6 +157,8 @@ public class GreetingResource {
}
----

It's a very simple REST endpoint, returning "hello" to request on "/hello".

[TIP]
.Differences with vanilla Jax-RS
====
Expand Down Expand Up @@ -201,11 +202,11 @@ $ curl http://localhost:8080/hello
hello
```

Hit `CTRL+C` to stop the application.
Hit `CTRL+C` to stop the application, but you can also keep it running and enjoy the blasting fast hot-reload.

== Using injection

Let's add a companion bean.
Let's modify the application and add a companion bean.
Create the `src/main/java/org/acme/quickstart/GreetingService.java` file with the following content:

[source, java]
Expand Down Expand Up @@ -258,15 +259,14 @@ public class GreetingResource {
}
----

Start the application and check that http://localhost:8080/hello/greeting/shamrock returns `hello shamrock`.


If you stopped the application, restart the application with `mvn compile shamrock:dev`.
Then check that http://localhost:8080/hello/greeting/shamrock returns `hello shamrock`.

== Testing

All right, so far so good, but wouldn't it be better with a few tests, just in case.

Edit the `pom.xml` file to add the 2 following dependencies:
In the generated `pom.xml` file, you can see 2 test dependencies:

[source,xml,subs=attributes+]
----
Expand All @@ -285,17 +285,18 @@ Edit the `pom.xml` file to add the 2 following dependencies:
----

Note that Shamrock uses JUnit 5 by default, which means that you may need to upgrade the version of surefire
that is in use. Do this by adding the following to the `<build><plugins>` section of `pom.xml`:
that is in use. This is done in `<build><plugins>` section of `pom.xml`:

[source,xml,subs=attributes+]
----
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>{surefire-version}</version>
<version>${surefire.version}</version>
</plugin>
----

Then, create the `src/test/java/org/acme/quickstart/GreetingResourceTest.java` with the following content:
The project generation contains a simple test.
Edit the `src/test/java/org/acme/quickstart/GreetingResourceTest.java` to match the following content:

[source,java]
----
Expand Down Expand Up @@ -348,8 +349,9 @@ It produces 2 jar files:

* `shamrock-quickstart-1.0-SNAPSHOT.jar` - containing just the classes and resources of the projects, it's the regular
artifact produced by the Maven build;
* `shamrock-quickstart-1.0-SNAPSHOT-runner.jar` - being an executable _über-jar_.
It embeds all the dependencies required to run the application.
* `shamrock-quickstart-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. Refer to the Maven plugin documentation to generate an
_über-jar_ embedding the dependencies.

You can run the application using: `java -jar target/shamrock-quickstart-1.0-SNAPSHOT-runner.jar`

Expand All @@ -368,7 +370,7 @@ public CompletionStage<String> hello() {
}
----

The async version of the code is available in the https://github.com/protean-project/quickstarts[Github] repository, in the `getting-started-async` directory.
The async version of the code is available in the https://github.com/jbossas/protean-quickstarts[Github] repository, in the `getting-started-async` directory.

== What's next?

Expand Down
14 changes: 11 additions & 3 deletions docs/src/main/asciidoc/json-and-validation-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@ image:validation-guide-architecture.png[alt=Architecture,width=640,height=480]
We recommend you to follow the instructions in the next sections and create the application step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone https://github.com/protean-project/quickstarts.git`, or download an https://github.com/protean-project/quickstarts/archive/master.zip[archive].
Clone the Git repository: `git clone https://github.com/jbossas/protean-quickstarts.git`, or download an https://github.com/jbossas/protean-quickstarts/archive/master.zip[archive].

The solution is located in the `input-validation` https://github.com/protean-project/quickstarts/tree/master/input-validation[directory].
The solution is located in the `input-validation` https://github.com/jbossas/protean-quickstarts/tree/master/input-validation[directory].

== Creating the Maven project

Expand All @@ -40,6 +40,7 @@ mvn org.jboss.shamrock:shamrock-maven-plugin:{shamrock-version}:create \
-DprojectGroupId=org.acme \
-DprojectArtifactId=input-validation \
-DclassName="org.acme.validation.BookResource" \
-Dpath="/books" \
-Dextensions="json, validation"
----

Expand Down Expand Up @@ -207,6 +208,11 @@ The best option is then to annotate a method of your business service with your

[source, java]
----
package org.acme.validation;

import javax.enterprise.context.ApplicationScoped;
import javax.validation.Valid;

@ApplicationScoped
public class BookService {

Expand All @@ -220,6 +226,8 @@ Calling the service in your rest end point triggers the `Book` validation automa

[source, java]
----
@Inject BookService bookService;

@Path("/service-method-validation")
@POST
@Produces(MediaType.APPLICATION_JSON)
Expand All @@ -244,7 +252,7 @@ Keep in mind that you usually don't want to expose to the public the internals o

Now let's add the simple web page to interact with our `BookResource`.
Shamrock automatically serves static resources contained in the `META-INF/resources` directory.
Creates the `src/main/resources/META-INF/resources` directory and copy this https://github.com/protean-project/quickstarts/blob/master/input-validation/src/main/resources/META-INF/resources/index.html[index.html] file in it.
In the `src/main/resources/META-INF/resources` directory, replace the `index.html` file with the content from this https://raw.githubusercontent.com/jbossas/protean-quickstarts/master/input-validation/src/main/resources/META-INF/resources/index.html[index.html] file in it.

== Run the application

Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/kubernetes-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Remember, you need to configure Maven as indicated in the link:maven-config.html
We recommend to follow the instructions in the next sections and build the application step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone https://github.com/protean-project/quickstarts.git`, or download an https://github.com/protean-project/quickstarts/archive/master.zip[archive].
Clone the Git repository: `git clone https://github.com/jbossas/protean-quickstarts.git`, or download an https://github.com/jbossas/protean-quickstarts/archive/master.zip[archive].

The solution is located in the `getting-started-kubernetes` directory.

Expand Down
Loading