diff --git a/img/blog/Liberty-Tools-Example.png b/img/blog/Liberty-Tools-Example.png new file mode 100644 index 0000000000..df05a2b294 Binary files /dev/null and b/img/blog/Liberty-Tools-Example.png differ diff --git a/img/blog/liberty-app-directory-img.png b/img/blog/liberty-app-directory-img.png new file mode 100644 index 0000000000..f3b9298d16 Binary files /dev/null and b/img/blog/liberty-app-directory-img.png differ diff --git a/img/blog/liberty-starter.png b/img/blog/liberty-starter.png new file mode 100644 index 0000000000..3cd0f1c9a2 Binary files /dev/null and b/img/blog/liberty-starter.png differ diff --git a/posts/2024-05-05-liberty-project-starter-guide-IntelliJ.adoc b/posts/2024-05-05-liberty-project-starter-guide-IntelliJ.adoc new file mode 100644 index 0000000000..806d9b985a --- /dev/null +++ b/posts/2024-05-05-liberty-project-starter-guide-IntelliJ.adoc @@ -0,0 +1,217 @@ +--- +layout: post +title: "Developing a cloud-native Java application with the Liberty Starter, Liberty Tools, and IntelliJ IDEA" +# Do NOT change the categories section +categories: blog +author_picture: https://avatars3.githubusercontent.com/Ruilin-Ma +author_github: https://github.com/Ruilin-Ma +seo-title: Developing a cloud-native Java application with the Liberty Starter, Liberty Tools, and IntelliJ IDEA - OpenLiberty.io +seo-description: Learn how to create a Liberty Maven project for a new cloud-native Java application by using the Open Liberty Starter, and to edit your application using the Liberty Tools in IntelliJ IDEA. +blog_description: Learn how to create a Liberty Maven project for a new cloud-native Java application by using the Open Liberty Starter, and to edit your application using the Liberty Tools in IntelliJ IDEA. +open-graph-image: https://openliberty.io/img/blog/liberty-starter.png +open-graph-image-alt: Open Liberty starter +--- += Developing a cloud-native Java application with Liberty Tools in IntelliJ IDEA +Ruilin Ma +:imagesdir: / +:url-prefix: +:url-about: / + +:figure-caption!: +//Blank line here is necessary before starting the body of the post. + +Learn how to create a Liberty Maven project for a new cloud-native Java application by using the Open Liberty Starter, and to edit your application using the Liberty Tools in IntelliJ IDEA. + +* <> +* <> +* <> +* <> +* <> + + +[#prerequisites] +== Before you start + +=== Installing Java + +Install either Java 17 or Java 21. You can link:https://www.ibm.com/support/pages/semeru-runtimes-installation[download IBM Semeru Runtimes for free]. Semeru integrates well with Liberty, but you can find out more about Semeru and other Java distributionslink:https://foojay.io/today/where-do-you-get-your-java/[in this article]. + + + + + +When the Java installation is complete, ensure the `JAVA_HOME` variable is properly configured in your system path. The `JAVA_HOME` variable is essential for Maven Liberty projects because it indicates which JVM to use. Locate the Java installation path on your system, and then export or set the `JAVA_HOME` environment variable using the following command (Linux and Mac): + +[role='command'] +``` +export JAVA_HOME= +``` + +=== Installing Liberty Tools for IntelliJ IDEA +Liberty Tools is a plugin for IntelliJ IDEA that helps you develop, test, debug, and manage Liberty applications in IntelliJ. + +To install Liberty Tools in IntelliJ IDEA: + +1. Start IntelliJ IDEA. +2. Click **Plugins** or open the **Plugins** section of the **Settings** window. +3. Search the Plugins Marketplace for `Liberty Tools`. If nothing is found, check whether you have a link:https://plugins.jetbrains.com/plugin/14856-liberty-tools[supported version of IntelliJ IDEA]. +4. Install Liberty Tools then restart the IDE. + +When the IDE restarts, Liberty Tools is installed and enabled. + +[#libertyStarter] +== Creating a Liberty Maven project with the Open Liberty Starter + +The Open Liberty Starter provides a simple way to create a Liberty Maven project. This Maven project contains all the files and project structure that you need to get started writing your cloud-native Java app. You can easily modify the project configuration in the `pom.xml` and `server.xml` files to add more or different options later, if necessary. + +To create your project: + +1. Visit the link:https://openliberty.io/start/[Open Liberty Starter]. +2. Accept the default values by clicking **Generate Project** and download your project. + +image::img/blog/liberty-starter.png[Maven dependencies example,width=60%,align="center"] + +[#ImportProject] +== Importing your project into IntelliJ IDEA + +When you import a Liberty Maven project into IntelliJ IDEA, Liberty Tools automatically detects the project. + +To import your Liberty Maven project: + +1. Extract the `app-name.zip` file that you downloaded from the Open Liberty Starter. The file extracts to a project folder called `app-name`, which you can optionally move elsewhere on your file system before you continue. +2. In the IDE, click **File > Open...**, select the project folder, then click **Open**. + +Your project is imported into IntelliJ IDEA and detected by Liberty Tools. + +[#AboutProject] +== Overview of the Liberty Maven project + +=== Project structure + +After importing a project into the IDE, the Project view displays the Liberty Maven project structure, as shown in the following image: + +image::img/blog/liberty-app-directory-img.png[Liberty Project directory image,width=40%,align="center"] + +A well-organized file structure is crucial for Maven projects, providing a clear framework for development. This hierarchy includes directories for application code, MicroProfile and Liberty configuration files, and tests: + +- `src/main/java`: Java application code files +- `src/main/liberty/config`: Liberty configuration files +- `src/main/resources/META-INF`: MicroProfile configuration files +- `src/test`: Test files +- `Dockerfile`: Dockerfile for building the Docker image +- `mvnw` or `mvnw.cmd`: Maven Wrapper script for Unix-like or Windows operating systems + + +In the `app-name` directory, the `pom.xml` file contains configuration details for the project, including dependencies, plugins, and other settings. + +=== Declaring dependencies +If you need to add any Liberty features to your app (such as JPA support), update the Maven project configuration in the `pom.xml` file. + +To declare dependencies, edit the `` section of the `pom.xml` file, as shown in the following example: + +[source, xml] +---- + + + jakarta.platform + jakarta.jakartaee-api + 10.0.0 + provided + + +---- + +In this example, the `jakarta.jakartaee-api` API from the `jakarta.platform` project is introduced as a dependency for this project. + +You can add more dependencies to your Maven project from the link:https://mvnrepository.com/open-source/[Maven Library]. + +=== Adding Maven plugins + +In IntelliJ IDEA , like many other development tools, you can enhance the functionality of Maven by adding Maven plugins. Maven plugins are commonly used for compiling code, running tests, and packaging applications. + +The Open Liberty Starter configures the Liberty Maven Plugin in your Maven project by default. The Liberty Maven Plugin provides several goals for managing a Liberty runtime, including tasks such as downloading and installing the Liberty runtime, starting or stopping a Liberty server in development mode, installing features, and deploying applications. + +You can see where the Liberty Maven Plugin is configured in your Liberty Maven project in the `pluginManagement` section of the `pom.xml`: + +[source, xml] +---- + + + + io.openliberty.tools + liberty-maven-plugin + 3.10.2 + + + +---- + +//explain lmp here +In this example, the `liberty-maven-plugin` from `io.openliberty.tools` is added to this project. + +For more information, see the link:https://github.com/OpenLiberty/ci.maven/blob/main/README.md[Liberty Maven Plugin docs]. + + +[#libertyToolsWithDevMode] +== Efficiently edit your application with Liberty dev mode + +Liberty Tools enhances the application development experience with Open Liberty by providing convenient features that are integrated directly into your IDE, including the Liberty Dashboard and Liberty dev mode. + +The Liberty Dashboard effectively manages Maven projects, seamlessly integrating configurations for Open Liberty. It facilitates rapid development of MicroProfile and Jakarta EE applications by offering automatic code blocks, auto-complete functionality, and real-time syntax validation. With just a few clicks, you can start or stop your app, run tests, and check reports. + +Liberty dev mode can swiftly apply code changes to your running app without needing to restart the server, ensuring faster development. + +Click the Open Liberty logo in the IDE window to open the Liberty tool window, which provides a set of actions to help you to manage your app (e.g. starting and stopping the Liberty runtime instance): + +image::img/blog/Liberty-Tools-Example.png[Liberty Tools Example image, title="An example integrating Liberty Dashboard from Liberty Tools into a Maven project with IntelliJ IDEA", width=30%,align="center"] + +Liberty Tools offer three ways to start your Liberty application in dev mode: Start, Start with configuration, or Start in a container. + +For now, click the **Start** action to simply start your application in dev mode. + + + + + + +Dev mode automatically detects, recompiles, and deploys code changes whenever you save a new change in your IDE or text editor. The following example creates a simple REST resource Java file. + +Ensure that Liberty dev mode is running, then create the following Java class file named `HelloWorldResource.java` as the REST resource: + +[source, java] +---- +src/main/java/com/demo/rest/HelloWorldResource.java +---- + +Paste the following code into the file: + +[source,java] +``` +package com.demo.rest; + +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.core.MediaType; + +@Path("/hello") +public class HelloWorldResource { + + @GET + @Produces(MediaType.TEXT_PLAIN) + public String helloWorld() { + return "Hello, World!"; + } +} +``` + +When the console displays `Web application available`, the Liberty server has successfully detected, recompiled, and deployed the changes. You can now view the message drafted in the example by accessing the link: http://localhost:9080/app-name/api/hello + +For more information, see: + +* link:https://openliberty.io/docs/latest/development-mode.html[Open Liberty dev mode docs] +* link:https://developer.ibm.com/articles/awb-effective-cloud-native-development-open-liberty-intellij-idea/[Effective cloud-native Java app development with Open Liberty in IntelliJ IDEA] +* link:https://github.com/OpenLiberty/liberty-tools-intellij/blob/main/docs/user-guide.md#run-your-application-on-liberty-using-dev-mode[Liberty Tools for IntelliJ IDEA user guide] + +== Next steps +Learn more about Open Liberty with our link:https://openliberty.io/guides/getting-started.html[Getting started with Open Liberty guide]