The microprofile-rest-client quickstart demonstrates the use of the MicroProfile REST Client specification in WildFly.
MicroProfile REST Client provides a type-safe approach to invoke RESTful services over HTTP. It relies on Jakarta REST APIs for consistency and easier reuse.
In this quickstart we have a country server and a country client used in the test. The server provides a simple REST interface providing information about some countries. The test creates a client that consumes this API through the MicroProfile REST Client specification.
The application this project produces is designed to be run on WildFly Application Server 31 or later.
All you need to build this project is Java 11.0 (Java SDK 11) or later and Maven 3.6.0 or later. See Configure Maven to Build and Deploy the Quickstarts to make sure you are configured correctly for testing the quickstarts.
In the following instructions, replace WILDFLY_HOME with the actual path to your WildFly installation. The installation path is described in detail here: Use of WILDFLY_HOME and JBOSS_HOME Variables.
When you see the replaceable variable QUICKSTART_HOME, replace it with the path to the root directory of all of the quickstarts.
-
Open a terminal and navigate to the root of the WildFly directory.
-
Start the WildFly server with the MicroProfile profile by typing the following command.
$ WILDFLY_HOME/bin/standalone.sh -c standalone-microprofile.xmlNoteFor Windows, use the WILDFLY_HOME\bin\standalone.batscript.
-
Make sure you start the WildFly server as described above.
-
Open a terminal and navigate to the root directory of this quickstart.
-
Type the following command to build the quickstart.
$ mvn clean install -
Type the following command to deploy the quickstart.
$ mvn wildfly:deploy
This builds and deploys the country-server and country-client to the running instance of the server.
You should see a message in the server log indicating that the archives deployed successfully.
The application will be running at the following URL: http://localhost:8080/microprofile-rest-client/.
You can verify that the server is responding by accessing
http://localhost:8080/microprofile-rest-client/name/France
endpoint using your browser or
curl http://localhost:8080/microprofile-rest-client/name/France
to get some information about France.
Using the MicroProfile REST Client is as simple as creating an interface which uses the
proper Jakarta REST and MicroProfile annotations. In this case, the org.wildfly.quickstarts.microprofile.rest.client.CountriesServiceClient
interface may be found in src/test/java:
package org.wildfly.quickstarts.microprofile.rest.client;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import org.wildfly.quickstarts.microprofile.rest.client.model.Country;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
@Path("/")
public interface CountriesServiceClient {
@GET
@Path("/name/{name}")
@Produces("application/json")
Country getByName(@PathParam("name") String name);
@GET
@Path("/name/{name}")
@Produces("application/json")
CompletionStage<Country> getByNameAsync(@PathParam("name") String name);
}The getByName method gives our code the ability to query a country by name
from the REST Countries API, while the getByNameAsync method is an asynchronous alternative. The client will handle all the networking and
marshalling leaving our code clean of such technical details.
As you can see, all that our REST client interface uses for now are standard Jakarta REST annotations.
Regarding integrating the REST Client in your application, there are two options, the CDI lookup and the programmatic lookup, and both may be found in the org.wildfly.quickstarts.microprofile.rest.client.CountriesResource
class, respectively in use by cdiName(String) and programmaticName(String) methods.
package org.wildfly.quickstarts.microprofile.rest.client;
import jakarta.ws.rs.WebApplicationException;
import org.eclipse.microprofile.config.inject.ConfigProperty;
import org.eclipse.microprofile.rest.client.RestClientBuilder;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import org.wildfly.quickstarts.microprofile.Country;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.TimeUnit;
@Path("/country")
@ApplicationScoped
public class CountriesResource {
@Inject
@RestClient
private CountriesServiceClient countriesServiceClient;
@Inject
@ConfigProperty(name = "server.host")
private String serverHost;
@GET
@Path("/cdi/{name}")
@Produces(MediaType.APPLICATION_JSON)
public Country cdiName(@PathParam("name") String name) {
try {
return countriesServiceClient.getByName(name);
} catch (NotFoundException e) {
return null;
}
}
@GET
@Path("/programmatic/{name}")
@Produces(MediaType.APPLICATION_JSON)
public Country programmaticName(@PathParam("name") String name) throws MalformedURLException {
CountriesServiceClient client = RestClientBuilder.newBuilder()
.baseUrl(new URL(serverHost))
.build(CountriesServiceClient.class);
return client.getByName(name);
}
@GET
@Path("/name-async/{name}")
@Produces(MediaType.APPLICATION_JSON)
public CompletionStage<Country> nameAsync(@PathParam("name") String name) {
CompletionStage<Country> completionStage = countriesServiceClient.getByNameAsync(name);
try {
TimeUnit.SECONDS.sleep(1L);
} catch (InterruptedException e) {
throw new WebApplicationException(e);
}
return completionStage;
}
}This quickstart includes integration tests, which are located under the src/test/ directory. The integration tests verify that the quickstart runs correctly when deployed on the server.
Follow these steps to run the integration tests.
-
Make sure you start the WildFly server, as previously described.
-
Make sure you build and deploy the quickstart, as previously described.
-
Type the following command to run the
verifygoal with theintegration-testingprofile activated.$ mvn verify -Pintegration-testing
|
Note
|
You may also use the environment variable |
When you are finished testing the quickstart, follow these steps to undeploy the archive.
-
Make sure you start the WildFly server as described above.
-
Open a terminal and navigate to the root directory of this quickstart.
-
Type this command to undeploy the archive:
$ mvn wildfly:undeploy
You can use the WildFly JAR Maven plug-in to build a WildFly bootable JAR to run this quickstart.
The quickstart pom.xml file contains a Maven profile named bootable-jar which configures the bootable JAR building:
<profile>
<id>bootable-jar</id>
<build>
<plugins>
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-jar-maven-plugin</artifactId>
<configuration>
<feature-pack-location>wildfly@maven(org.jboss.universe:community-universe)#${version.server}</feature-pack-location>
<layers>
<layer>jaxrs-server</layer>
<layer>microprofile-config</layer>
</layers>
<plugin-options>
<jboss-fork-embedded>true</jboss-fork-embedded>
</plugin-options>
</configuration>
<executions>
<execution>
<goals>
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>-
Build the quickstart bootable JAR with the following command:
$ mvn clean package -Pbootable-jar -
Run the quickstart application contained in the bootable JAR:
$ java -jar target/microprofile-rest-client-bootable.jar -
You can now interact with the quickstart application.
|
Note
|
After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the |
The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar.
Follow these steps to run the integration tests.
-
Make sure the bootable jar is provisioned.
$ mvn clean package -Pbootable-jar -
Start the WildFly bootable jar, this time using the WildFly Maven Jar Plugin, which is recommend for testing due to simpler automation.
$ mvn wildfly-jar:start -Djar-file-name=target/microprofile-rest-client-bootable.jar -
Type the following command to run the
verifygoal with theintegration-testingprofile activated, and specifying the quickstart’s URL using theserver.hostsystem property, which for a bootable jar by default ishttp://localhost:8080.$ mvn verify -Pintegration-testing -Dserver.host=http://localhost:8080 -
Shutdown the WildFly bootable jar, this time using the WildFly Maven Jar Plugin too.
$ mvn wildfly-jar:shutdown
On OpenShift, the S2I build with Apache Maven uses an openshift Maven profile to provision a WildFly server, deploy and run the quickstart in OpenShift environment.
The server provisioning functionality is provided by the WildFly Maven Plugin, and you may find its configuration in the quickstart pom.xml:
<profile>
<id>openshift</id>
<build>
<plugins>
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-maven-plugin</artifactId>
<configuration>
<feature-packs>
<feature-pack>
<location>org.wildfly:wildfly-galleon-pack:${version.server}</location>
</feature-pack>
<feature-pack>
<location>org.wildfly.cloud:wildfly-cloud-galleon-pack:${version.pack.cloud}</location>
</feature-pack>
</feature-packs>
<layers>...</layers>
<name>ROOT.war</name>
</configuration>
<executions>
<execution>
<goals>
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
</profile>You may note that unlike the provisioned-server profile it uses the cloud feature pack which enables a configuration tuned for OpenShift environment.
This section contains the basic instructions to build and deploy this quickstart to WildFly for OpenShift or WildFly for OpenShift Online using Helm Charts.
-
You must be logged in OpenShift and have an
occlient to connect to OpenShift -
Helm must be installed to deploy the backend on OpenShift.
Once you have installed Helm, you need to add the repository that provides Helm Charts for WildFly.
$ helm repo add wildfly https://docs.wildfly.org/wildfly-charts/
"wildfly" has been added to your repositories
$ helm search repo wildfly
NAME CHART VERSION APP VERSION DESCRIPTION
wildfly/wildfly ... ... Build and Deploy WildFly applications on OpenShift
wildfly/wildfly-common ... ... A library chart for WildFly-based applicationsLog in to your OpenShift instance using the oc login command.
The backend will be built and deployed on OpenShift with a Helm Chart for WildFly.
Navigate to the root directory of this quickstart and run the following command:
$ helm install microprofile-rest-client -f charts/helm.yaml wildfly/wildfly --wait --timeout=10m0s
NAME: microprofile-rest-client
...
STATUS: deployed
REVISION: 1This command will return once the application has successfully deployed. In case of a timeout, you can check the status of the application with the following command in another terminal:
oc get deployment microprofile-rest-clientThe Helm Chart for this quickstart contains all the information to build an image from the source code using S2I on Java 17:
build:
uri: https://github.com/wildfly/quickstart.git
ref: main
contextDir: microprofile-rest-client
deploy:
replicas: 1This will create a new deployment on OpenShift and deploy the application.
If you want to see all the configuration elements to customize your deployment you can use the following command:
$ helm show readme wildfly/wildflyGet the URL of the route to the deployment.
$ oc get route microprofile-rest-client -o jsonpath="{.spec.host}"Access the application in your web browser using the displayed URL.
|
Note
|
The Maven profile named |
The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with the quickstart running on OpenShift.
|
Note
|
The integration tests expect a deployed application, so make sure you have deployed the quickstart on OpenShift before you begin. |
Run the integration tests using the following command to run the verify goal with the integration-testing profile activated and the proper URL:
$ mvn verify -Pintegration-testing -Dserver.host=https://$(oc get route microprofile-rest-client --template='{{ .spec.host }}') |
Note
|
The tests are using SSL to connect to the quickstart running on OpenShift. So you need the certificates to be trusted by the machine the tests are run from. |
MicroProfile REST Client provides you with an option to define REST clients in a clear, declarative, and intuitive way using the same annotations as for your Jakarta REST resources. It also allows you to make the HTTP communication on the background transparent for your services with the direct data conversions and exception mappers. You can find more information about the MicroProfile REST Client specification at https://github.com/eclipse/microprofile-rest-client.