Building a Microservice with Apache Meecrowave

1. Overview

In this tutorial, we’ll explore the basic functionality of the Apache Meecrowave framework.

Meecrowave is a lightweight microservices framework from Apache, which works very well with CDI, JAX-RS, and JSON API’s. It’s very simple to setup and deploy. It also eliminates the hassle of deploying heavy application servers like Tomcat, Glassfish, Wildfly, etc.

2. Maven Dependency

To use Meecrowave, let’s define the dependency in pom.xml:

<dependency>
    <groupId>org.apache.meecrowave</groupId>
    <artifactId>meecrowave-core</artifactId>
    <version>1.2.1</version>
</dependency>

Check for the latest version on Maven Central.

3. Starting a Simple Server

I order to start a Meecrowave server all we need to do is write the main method, create a Meecrowave instance and invoke the main bake() method:

public static void main(String[] args) {
    try (Meecrowave meecrowave = new Meecrowave()) {
        meecrowave.bake().await();
    }
}

We don’t need this main method if we package the application as a distribution package; we’ll look into that in the later sections. The main class is useful while testing the application from an IDE.

As an advantage, while developing in an IDE, once we run the application using the main class, it reloads automatically with code changes, thus saving the hassle of restarting the server again and again to test.

Note that, if we are using Java 9, don’t forget to add javax.xml.bind modules to the VM:

--add-module javax.xml.bind

Creating the server this way will start it with default configuration. We can programmatically update the default configurations using the Meecrowave.Builder class:

Meecrowave.Builder builder = new Meecrowave.Builder();
builder.setHttpPort(8080);
builder.setScanningPackageIncludes("com.baeldung.meecrowave");
builder.setJaxrsMapping("/api/*");
builder.setJsonpPrettify(true);

And use this builder instance while baking the server:

try (Meecrowave meecrowave = new Meecrowave(builder)) { 
    meecrowave.bake().await();
}

There are more configurable properties here.

4. REST Endpoints

Now, once the server is ready, let’s create some REST endpoints:

@RequestScoped
@Path("article")
public class ArticleEndpoints {
    
    @GET
    public Response getArticle() {
        return Response.ok().entity(new Article("name", "author")).build();      
    }
    
    @POST 
    public Response createArticle(Article article) { 
        return Response.status(Status.CREATED).entity(article).build(); 
    }
}

Notice that, we’re mostly using JAX-RS annotations to create the REST endpoints. Read more about JAX-RS here.

In the next section, we’ll see how to test these endpoints.

5. Unit Testing

Writing unit test cases with for REST API’s written with Meecrowave is simple as writing annotated JUnit test cases.

Let’s add the test dependencies to our pom.xml first:

<dependency>
    <groupId>org.apache.meecrowave</groupId>
    <artifactId>meecrowave-junit</artifactId>
    <version>1.2.1</version>
    <scope>test</scope>
</dependency>

To see the latest version, check out Maven Central.

Also, let’s add OkHttp as HTTP client for our tests:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>3.10.0</version>
</dependency>

Check out the latest version here.

Now with the dependencies in place lets go ahead and write the tests:

@RunWith(MonoMeecrowave.Runner.class)
public class ArticleEndpointsTest {
    
    @ConfigurationInject
    private Meecrowave.Builder config;
    private static OkHttpClient client;
    
    @BeforeClass
    public static void setup() {
        client = new OkHttpClient();
    }
    
    @Test
    public void whenRetunedArticle_thenCorrect() {
        String base = "http://localhost:" + config.getHttpPort();
        
        Request request = new Request.Builder()
          .url(base + "/article")
          .build();
        Response response = client.newCall(request).execute();
        assertEquals(200, response.code());
    }
}

While writing the test cases, make to annotate the test class with MonoMeecrowave.Runner class, also inject the configuration, to get access to the random port used by Meecrowave for the test server

6. Dependency Injection

To inject dependencies into a class, we need to annotate those classes within a particular scope.

Let’s take the example of an ArticleService class:

@ApplicationScoped
public class ArticleService {
    public Article createArticle(Article article) {
        return article;
    }
}

Now let’s inject this into our ArticleEndpoints instance using the javax.inject.Inject annotation:

@Inject
ArticleService articleService;

7. Packaging the Application

Creating a distribution package becomes very simple, with the Meecrowave Maven plugin:

<build>
    ...
    <plugins>
        <plugin>
            <groupId>org.apache.meecrowave</groupId>
            <artifactId>meecrowave-maven-plugin</artifactId>
            <version>1.2.1</version>
        </plugin>
    </plugins>
</build>

Once we have the plugin in place let’s use the Maven goal meecrowave:bundle to package the application.

Once packaged it will create a zip inside the target directory:

meecrowave-meecrowave-distribution.zip

This zip contains the required artifacts to deploy the application:

|____meecrowave-distribution
| |____bin
| | |____meecrowave.sh
| |____logs
| | |____you_can_safely_delete.txt
| |____lib
| |____conf
| | |____log4j2.xml
| | |____meecrowave.properties

Let’s navigate to the bin directory and start the application:

./meecrowave.sh start

To stop the application:

./meecrowave.sh stop

8. Conclusion

In this article, we learned about using Apache Meecrowave to create a microservice. Also, we looked into some basic configuration about the application and to prepare a distribution package.

As always the code snippets could be found in the Github Project.