Objective

The objective of this article is to demonstrate how to use the mimik Client Library interfaces when working with edge microservices in an Android project.

Intended Readers

The intended readers of this document are Android software developers, who want to familiarize themselves with the basics of mimik Client Library interfaces, specifically methods for interfacing with edge microservices.

What You'll Be Doing

In this tutorial, you will learn about key topics related to working with the mimik Client Library edge microservice interfaces. These topics include:

• Deploying
• Referencing
• Calling
• Updating
• Undeploying

Prerequisites

• Understanding the mimik Client Library initialization process as laid out in this article.

• Understanding how to work with the mim OE Runtime in an Android application.

Technical Prerequisites

This tutorial has the following technical prerequisites:

• A working Android Studio environment. You can download Android Studio here.
• An ARM-based Android device. The mim OE Runtime for Android does not support virtual or x86-based devices.

Deploying an edge microservice

Developers can use the mimik Client Library to deploy an edge microservice that's encapsulated in a pre-existing .tar file.

Sometimes the edge microservice .tar file will be stored in a source code repository for immediate download. Other times that .tar file will need to be built from scratch using the source code for the edge microservice. It all depends on the build and deployment policies of the given organization. To learn the details of building an edge microservice into a deployable edge Image .tar file, read Understanding the Strategies for Deploying an edge Microservice here.

The segment below shows the code a developer can use to deploy a microservice that is encapsulated in the .tar file fictitiously named microservice.tar and stored as a raw resource in the module. Notice the use of the mimik Client Library API method, mimOEClient.deployMimOEMicroservice() at Line 6.

1: String accessToken = <ACCESS_TOKEN>;
2: InputStream microserviceResource = getResources().openRawResource(R.raw.microservice);
3: 
4: // Create microservice deployment configuration, dependent
5: // on microservice implementation
6: MicroserviceDeploymentConfig config = new MicroserviceDeploymentConfig();
7: 
8: // Set the name that will represent the microservice
9: config.setName("microservice");
10: 
11: // Set the InputStream of the edge microservice
12: config.setResourceStream(microserviceResource);
13: 
14: // Set the filename that by which the edge client will identify
15: // the microservice internally. This filename is associated internally
16: // with the resource stream initialized above
17: config.setFilename("microservice.tar");
18: 
19: // Declare the URI by  which the application code will access
20: // the microservice
21: config.setApiRootUri(Uri.parse("/microservice/v1"));
22: 
23: // Deploy edge microservice using the client library instance variable
24: MicroserviceDeploymentStatus status =
25:         mimOEClient.deployMimOEMicroservice(accessToken, config);
26: if (status.error != null) {
27:     // Display microservice deployment error
28:     Log.d("mim OE", "Failed to deploy microservice! " + status.error.getMessage());
29: } else {
30:     // Store the microservice API root URI
31:     String microserviceRoot = status.response.getContainer().getApiRootUri().toString();
32:     // Display a message indicating a successful microservice deployment
33:     Log.d("mim OE", "Successfully deployed microservice!");
34: }

WHERE:

• <ACCESS_TOKEN> is the Access Token the developer generated previously using the mimik Client Library

Notice that the microservice API root URI is stored as microserviceRoot, set at Line 31 in the code above.

Uninstalling an edge microservice deployment

The segment below shows the code a developer can use to undeploy (uninstall) an edge microservice from the mim OE Runtime running on an Android device. Add the following code to your Android project.

1: String accessToken = <ACCESS_TOKEN>;
2: 
3: MicroserviceDeploymentConfig config = new MicroserviceDeploymentConfig();
4: // Declare the name of the microservice to be uninstalled
5: config.setName("microservice");
6: MicroserviceDeploymentStatus status =
7:         mimOEClient.removeMimOEMicroservice(accessToken, config);
8: if (status.error != null) {
9:     // Display microservice uninstall error
10:     Log.d("mim OE", "Failed to uninstall microservice! " + status.error.getMessage());
11: } else {
12:     // Display microservice uninstall success
13:     Log.d("mim OE", "Successfully uninstalled microservice!");
14: }
15: }

WHERE:

• <ACCESS_TOKEN> is the Access Token the developer generated previously using the mimik Client Library

Calling an edge microservice

Once an edge microservice is deployed with the Android application, a developer can work with it using the mimik Client Library.

The code segment below shows an example of how to access and use an edge microservice programmatically using the mimik Client Library. HTTP requests are performed using OkHttpClient.

1: String randomNumberRoot = "<MICROSERVICE_ROOT_URI>";
2: String microserviceApiEndpoint = "<MICROSERVICE_API_ENDPOINT>";
3: 
4: // Construct an API request for the edge microservice
5: OkHttpClient client = new OkHttpClient();
6: Request request = new Request.Builder()
7:         .url(String.format(
8:                 "http://127.0.0.1:%d%s/" + microserviceApiEndpoint,
9:                 // use the client to get the default localhost port
10:                 mimOEClient.getMimOEPort(),
11:                 randomNumberRoot)) // root URI determined by microservice deployment
12:         .build();
13: client.newCall(request).enqueue(new Callback() {
14:     @Override
15:     public void onFailure(
16:             @NotNull Call call,
17:             @NotNull IOException e) {
18:         // Display microservice request error
19:         e.printStackTrace();
20:         Log.d("mim OE", "Failed to communicate with microservice! " + e.getMessage());
21:     }
22: 
23:     @Override
24:     public void onResponse(
25:             @NotNull Call call,
26:             @NotNull final Response response) throws IOException {
27:         if (!response.isSuccessful()) {
28:             // Display microservice unknown error
29:             Log.d("mim OE", "Microservice returned unexpected code! " + response);
30:         } else {
31:             // Display microservice response
32:             Log.d("mim OE", "Microservice returned " + response.body().string());
33:         }
34:     }
35: });

WHERE

• <MICROSERVICE_ROOT_URI> is the microservice API root URI acquired previously
• <MICROSERVICE_API_ENDPOINT> is microservice API endpoint defined by the microservice

Example Android project

You can download a fully functional example of an Android application, showing all the functions discussed in the three Android tutorials here. Clone the project and build the code_completed branch, run it on your Android device, and see all functions in action right away!

Additional reading

In order to get more out of this article, the reader could further familiarize themselves with the following concepts and techniques:

• Understanding the mimik Client Library for Android.
• Creating a Simple Android Application that Uses an edge microservice.
• Integrating the mimik Client Library into an Android project.
• Working with mim OE in an Android project.