2 Writing the App

The previous command createas a micronaut app with the default package example.micronaut in a folder named complete.

Due to the --features kotlin flag, it generates a Kotlin Micronaut app and it uses Gradle build system. However, you could use
other build tool such as Maven or other programming languages such as Java or Groovy.

If you are using Java or Kotlin and IntelliJ IDEA make sure you have enabled annotation processing.

Kotlin, Kapt and IntelliJ

As of this writing IntelliJ’s built-in compiler does not directly support Kapt and annotation processing. You must instead configure Intellij to run Gradle (or Maven) compilation as a build step before running your tests or application class.

First edit the run configuration for tests or for the application and select "Run Gradle task" as a build step:

Then add the classes task as task to execute for the application or for tests the testClasses task:

Now whenever you run tests or the application Micronaut classes will be generated at compilation time.

Use retrieve to perform an HTTP request for the given request object and convert the full HTTP response’s body into the specified type. e.g. List<BintrayPackage>.

6

The retrieve method returns a Flowable which has a firstElement method that returns the first emitted item or nothing

Instead of retrieve we could have used jsonStream. You can use jsonStream() to stream arrays of type application/json or
JSON streams of type application/x-json-stream. If we use retrieve, such as in the previous code listing, the operation will not block.
However, it will not return until all the data has been received from the server. In the case of a JSON array that would be the whole array.
However, if you are interested in just the first element of the array, jsonStream provides a better alternative since it starts streaming data from the server without needing the whole response.
For example, jsonStream().firstElement() will only parse the first item in a JSON array. Hence it is more efficient.

5 Declarative Client

It is time to take a look at Micronaut’s support for declarative clients via the Client annotation.

Create BintrayClient which clearly illustrates how a declarative Micronaut HTTP Client, which is generated at compile-time, simplifies our code.

You can use configuration parameter interpolation when you define the path of the GET endpoint.

3

You can return reactive types, such as an RxJava Flowable.

6 Controller

Create a Controller. It uses both (low-level and declarative clients). It showcases several Micronaut’s capabilities.

Micronaut supports any framework that implements Reactive Streams, including RxJava, and Reactor. Thus, you can easily and efficiently
compose multiple HTTP client calls without blocking (which will limit the throughput and scalability of your application).

To run the application from a unit test you can use the EmbeddedServer interface

2

Micronaut’s HTTP client includes support for streaming data over HTTP via the RxStreamingHttpClient. Register a RxStreamingHttpClient bean in the application context and point it to the embedded server URL. The EmbeddedServer interface provides the URL of the server under test which runs on a random port.

3

Sometimes, receiving just the object is not enough and you need information about the response. In this case, instead of retrieve you should use the exchange method.

4

Micronaut makes it easy to parse JSON into Kotlin objects.

5

Use status to check the HTTP status code.

6

Use .body() to retrieve the parsed payload.

7

Use the jsonStream method, which returns a Flowable, to consume the endpoint which generates a JSON Stream.

8 Testing the Application

To run the tests:

$ ./gradlew test
$ open build/reports/tests/test/index.html

9 Http Client Filter

Often, you need to include the same HTTP headers or URL parameters in a set of requests against a third-party API or when calling another Microservice.

To simplify this, Micronaut includes the ability to define HttpClientFilter classes that are applied to all matching HTTP clients.

For real world example, let us provide Bintray Authentication via a HttpClientFilter:

The Bintray REST API requires an applicative API key. An API key can be obtained from the user profile page. Authentication is achieved using HTTP Basic Authentication with the user’s name as username and the API key as the password. Authenticated REST calls should only be used via HTTPs.

Supply the pattern you want to match to the @Filter annotation. Note the required escaping (backslash) on "/api/\${bintray.apiversion}/repos/**" which is required due to Kotlin string interpolation.

2

Bean will not loaded unless condition is met

3

Constructor injection of the configuration parameters.

4

Enhance every request sent to Bintray API providing Basic Authentication.

We want to load the BintrayFilter bean if both configuration parameters bintray.username and bintray.token are present.
In the Java or Groovy versions of this guide, multiple Requires annotations are used. Multiple @Requires annotations are not possible with Kotlin.
Instead, we use a condition class.