| permalink |
|---|
/guides/microprofile-eclipse-codewind/ |
|
Note
|
This repository contains the guide documentation source. To view the guide in published form, view it on the website. |
NOTE: Use this guide only for Kabanero V0.5.0 and earlier releases.
You will use the Kabanero Eclipse MicroProfile Collection in your Eclipse IDE to create and run a simple cloud native microservice Java application.
Kabanero’s Eclipse MicroProfile Collection contains all the components you need to develop your microservice application, including the Eclipse MicroProfile application stack and any necessary container build and deployment artifacts.
-
You must have Docker installed.
-
You must install the Eclipse Codewind Extension from the Eclipse Marketplace, which creates a CODEWIND workspace and downloads Docker images to your Docker registry.
-
(Optional) If you have an enterprise-specific Kabanero Collection Hub, you need the URL to your index file.
Everything is now set up, and you’re ready to create your first project!
Kabanero brings together open source technologies that provide a framework for developing cloud native microservice applications. As a developer, you are likely to have a preferred IDE for writing application code. In this guide, we are going to develop a simple containerized microservice application that is based on the Eclipse MicroProfile Kabanero Collection in the Eclipse IDE.
Kabanero contains Appsody, which is designed to enable applications to be built and tested inside a container. To access Appsody functions from your IDE, you need Eclipse Codewind, a plugin that provides a rich user interface that integrates seamlessly into the Eclipse IDE. Codewind also provides performance and monitoring tools to help you test and debug applications in containers.
When you install Eclipse Codewind, an extension to Appsody is automatically installed as part of your CODEWIND workspace. By default, Codewind is configured to use the latest Appsody stacks that are available in the Appsody GitHub repository. However, those stacks are not integrated with Kabanero. In order to use Appsody with Kabanero you need to configure Codewind to use a Kabanero Collection Hub.
As a developer, your enterprise architect might provide you with the URL of a Kabanero Collection Hub that your organisation has defined for developers to use. If not, you should clone the public Kabanero Collection Hub locally. The public collection is updated on a regular basis, so by making a copy, you avoid adopting unplanned changes.
To keep things simple in this guide, you will add the latest public Kabanero Collection Hub repository instead of a clone of a Kabanero Collection Hub repository.
With Codewind installed, make sure you have it showing in one of the Eclipse side panels. If you cannot see Codewind Explorer, go to the Menu Bar and select Window > Show View > Other > Codewind Explorer and press OK.
Now we can edit the template sources where Codewind expects to find the Kabanero Collections. Right-click Projects (Local) and select Manage Template Sources. A new box appears with a list of template sources, including Standard Codewind Templates and Appsody Stacks.
Kabanero Collections might already be showing in this list. If so, enable it with the tick box.
If Kabanero Collections are not in the list, select Add and enter Kabanero Collections as a description. In the URL field,
enter https://github.com/kabanero-io/collections/releases/latest/download/kabanero-index.json.
Note: If you’ve been provided with a Kabanero Collection Hub URL for your organisation you can repeat the last step to add it.
Uncheck all the other template sources except Kabanero Collections because those sources are not supported by the Kabanero application cluster.
Codewind is now configured to use the public Kabanero Collection Hub.
In the Explorer view, right-click on Projects and select Create New Project to get a list of available Kabanero Collections.
From the Create a new project window, choose the Kabanero Eclipse MicroProfile Template, as shown in the following diagram:
Choose a suitable name for your project and select Finish to save it.
Your new project is created, built, and compiled inside a container. To see the status of the build, right-click the project in Codewind Explorer, select Show Log Files and chose Appsody.log. The log files for the container are shown in a Console Window.
When the application is compiled and running on localhost, the status changes from [Stopped] [Build Successful] to [Running] [Build Successful]. Right-click the project in Codewind Explorer and select Open Application to view the app running on your local machine.
Note: This process takes longer the first time it runs because dependencies are downloaded and installed.
Projects are created with a default set of files, which you can find in a Project Explorer in your CODEWIND-WORKSPACE.
Show the Application by right-clicking the Project from the Codewind Explorer and selecting Open Application.
The Eclipse browser opens to display "Welcome to your Appsody Microservice" on http://127.0.0.1:<local_port_number>/. Make a note
of the <local_port_number> for your next task.
You are now going to create a new route that listens on http://127.0.0.1:<local_port_number>/starter/hello.
In Project Explorer, right click on the dev.appsody.starter package located inside the Java Resources > src/main/java folder and create a new file called HelloResource.
Add the following code to this new file:
package dev.appsody.starter;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
@Path("/")
public class HelloResource {
@GET
@Path("hello")
@Produces(MediaType.TEXT_PLAIN)
public String helloWorld() {
return "Hello World!";
}
}Save the changes.
Codewind watches for file changes and automatically recompiles your application. Point your browser to
http://127.0.0.1:<local_port_number>/starter/hello to see your new route, which displays Hello World!.
This code is creating a new path on /hello to return a String to the browser saying Hello World!. The starter part of the full URL comes from the StarterApplication.java file, which specifies that all routes should begin with /starter.
You can perform a number of operations through the Eclipse Explorer interface that help you develop, test, and debug your application locally. Right-click on your project to see a list of available tasks:
-
you can disable the automated build of your project and build it on demand
-
you can restart your application in run mode or debug mode
-
you can view the available logs to troubleshoot issues
-
you can find information about the running app in Open Project Overview. Eclipse displays information about your project, including the location, status, and any ports in use. The output is similar to the following screenshot:
-
you can stop the application, by clicking the Disable project button.
At some stage in development, you might want to do some local performance testing. As well as checking whether your code runs cleanly, Codewind provides application metrics and performance monitoring. For more information about developing applications with Eclipse Codewind, see the Codewind documentation.
When you’ve finished unit testing your microservice application on your local system, the next stage in the process is to test the microservice in the context of the overall system. To test the application as part of the system, you must deploy the system and then the new application, which requires access to a Kubernetes or Knative environment.
If your responsibilities include deploying your microservice application on Kubernetes or Knative, additional pre-requisites apply. For example, you must install the Appsody CLI and configure Kubernetes on your local system. The steps required to deploy an application to Kubernetes or Knative are covered in Developing cloud native microservices with the Eclipse MicroProfile Collection and Appsody CLI.
If deploying your microservice application as part of the overall system is handled by another team in your organisation, your role in the deployment process ends by delivering your changes to a GitHub repository. Here, your operations team can automate the deployment of your microservice application to a kubernetes or Knative test environment by implementing Tekton webhooks that trigger Tekton pipelines.
Want to learn about Tekton? Using Tekton pipelines to deploy microservice applications is covered in a different guide.