diff --git a/blog_tags.json b/blog_tags.json index 69203f492..bca27f004 100644 --- a/blog_tags.json +++ b/blog_tags.json @@ -2,7 +2,8 @@ "blog_tags": [ { "name": "announcements", - "posts": ["24.0.0.5", "24.0.0.5-beta", + "posts": ["24.0.0.6-beta", + "24.0.0.5", "24.0.0.5-beta", "24.0.0.4", "24.0.0.4-beta", "24.0.0.3", "24.0.0.2", "24.0.0.2-beta", "24.0.0.1", @@ -78,7 +79,8 @@ "featured": "true" },{ "name": "microprofile", - "posts": ["24.0.0.4", "open-liberty-with-langchain4j-example", + "posts": ["24.0.0.6-beta", + "24.0.0.4", "open-liberty-with-langchain4j-example", "DevNexus24", "24.0.0.2", "23.0.0.12", "23.0.0.11", "23.0.0.11-beta", "23.0.0.10-beta", @@ -158,7 +160,8 @@ }, { "name": "release", - "posts": ["24.0.0.5", "24.0.0.5-beta", + "posts": ["24.0.0.6-beta", + "24.0.0.5", "24.0.0.5-beta", "24.0.0.4", "24.0.0.4-beta", "24.0.0.3", "24.0.0.2", "24.0.0.2-beta", "24.0.0.1", @@ -216,7 +219,7 @@ }, { "name": "beta", - "posts": ["24.0.0.5-beta", + "posts": ["24.0.0.6-beta", "24.0.0.5-beta", "24.0.0.4-beta", "24.0.0.2-beta", "24.0.0.1-beta", "23.0.0.12-beta", "23.0.0.11-beta", "23.0.0.10-beta", @@ -246,7 +249,8 @@ }, { "name": "maven", - "posts": ["23.0.0.12", "liberty-ide-tools-maven-gradle-plugins-for-java-developers", + "posts": ["liberty-project-starter-guide-IntelliJ", + "23.0.0.12", "liberty-ide-tools-maven-gradle-plugins-for-java-developers", "23.0.0.6", "liberty-tools-eclipse-deep-dive", "microprofile-serverless-ibm-code-engine", "develop-user-feature", "liberty-tools-eclipse", @@ -326,7 +330,7 @@ }, { "name": "metrics", - "posts": ["23.0.0.12", + "posts": ["24.0.0.6-beta", "23.0.0.12", "23.0.0.11", "23.0.0.11-beta", "23.0.0.10-beta","23.0.0.3", "22.0.0.12-beta", "logrecordcontext-22007", @@ -344,7 +348,7 @@ }, { "name": "jakarta-ee", - "posts": ["simplifying-nosql-database-integration-with-jakarta-nosql", + "posts": ["24.0.0.6-beta", "simplifying-nosql-database-integration-with-jakarta-nosql", "jakarta-nosql-in-action-meet-jnopo-game", "jakarta-nosql-challenge-switching-nosql-easily","24.0.0.5-beta", "24.0.0.4", "24.0.0.4-beta", @@ -444,7 +448,7 @@ }, { "name": "developer-experience", - "posts": ["simplifying-nosql-database-integration-with-jakarta-nosql", + "posts": ["liberty-project-starter-guide-IntelliJ", "simplifying-nosql-database-integration-with-jakarta-nosql", "jakarta-nosql-in-action-meet-jnopo-game", "jakarta-nosql-challenge-switching-nosql-easily", "spring-boot-3", "open-liberty-with-langchain4j-example", @@ -540,7 +544,7 @@ }, { "name": "data-sources", - "posts": ["simplifying-nosql-database-integration-with-jakarta-nosql", + "posts": ["24.0.0.6-beta", "simplifying-nosql-database-integration-with-jakarta-nosql", "jakarta-nosql-in-action-meet-jnopo-game", "jakarta-nosql-challenge-switching-nosql-easily", "24.0.0.5-beta", "24.0.0.4-beta", "24.0.0.1-beta", "23.0.0.12-beta", @@ -585,7 +589,8 @@ }, { "name": "devops", - "posts": ["ArgoCD-Configuration-Drift", "argocd-drift-pt1", + "posts": ["liberty-project-starter-guide-IntelliJ", + "ArgoCD-Configuration-Drift", "argocd-drift-pt1", "testcontainers-guide", "23.0.0.6", "rapid-startup-instanton", "tracing-with-microprofile-telemetry","23.0.0.2-beta", diff --git a/img/blog/Liberty-Tools-Example.png b/img/blog/Liberty-Tools-Example.png new file mode 100644 index 000000000..df05a2b29 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 000000000..f3b9298d1 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 000000000..3cd0f1c9a Binary files /dev/null and b/img/blog/liberty-starter.png differ diff --git a/posts/2024-05-31-liberty-project-starter-guide-IntelliJ.adoc b/posts/2024-05-31-liberty-project-starter-guide-IntelliJ.adoc new file mode 100644 index 000000000..a1411dda5 --- /dev/null +++ b/posts/2024-05-31-liberty-project-starter-guide-IntelliJ.adoc @@ -0,0 +1,215 @@ +--- +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. + +Given the rapid rate of technological change, the array of tools available, and the rising complexity of cloud-native applications, it can be difficult to know how to start creating a cloud-native Java application. This short post leads you through creating a simple cloud-native Java application and editing it within an IDE, all within just 10 minutes! Read on to learn how to easily 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 distributions link: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 following 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 + +In just 10 minutes, if you followed along with the instructions in this post, you successfully created a cloud-native Java application, deployed it, and edited it in an agile manner, with rapid feedback. Take your learning to the next level and further develop your application by exploring more of Open Liberty's features or exploring the APIs supported by open source, industry standard projects like MicroProfile and Jakarta EE through our link:https://openliberty.io/guides/[interactive guides]. diff --git a/posts/2024-06-04-24.0.0.6-beta.adoc b/posts/2024-06-04-24.0.0.6-beta.adoc new file mode 100644 index 000000000..ef7bd25b6 --- /dev/null +++ b/posts/2024-06-04-24.0.0.6-beta.adoc @@ -0,0 +1,460 @@ +--- +layout: post +title: "Jakarta EE11 previews and more in 24.0.0.6-beta" +# Do NOT change the categories section +categories: blog +author_picture: https://avatars3.githubusercontent.com/dmuelle +author_github: https://github.com/dmuelle +seo-title: Jakarta EE11 previews and more in 24.0.0.6-beta - OpenLiberty.io +seo-description: The 24.0.0.6-beta release includes previews of the Jakarta Validation and Jakarta Data implementations, both of which are part of Jakarta EE 11. The release also includes enhancements for histogram and timer metrics in MicroProfile 3.0 and 4.0 and InstantOn support for distributed HTTP session caching. +blog_description: The 24.0.0.6-beta release includes previews of the Jakarta Validation and Jakarta Data implementations, both of which are part of Jakarta EE 11. The release also includes enhancements for histogram and timer metrics in MicroProfile 3.0 and 4.0 and InstantOn support for distributed HTTP session caching. +open-graph-image: https://openliberty.io/img/twitter_card.jpg +open-graph-image-alt: Open Liberty Logo +--- += Jakarta EE11 previews and more in 24.0.0.6-beta +David Mueller +:imagesdir: / +:url-prefix: +:url-about: / +//Blank line here is necessary before starting the body of the post. + + +The 24.0.0.6-beta release includes previews of the Jakarta Validation and Jakarta Data implementations, both of which are part of Jakarta EE 11. The release also includes enhancements for histogram and timer metrics in MicroProfile 3.0 and 4.0 and InstantOn support for distributed HTTP session caching. + +The link:{url-about}[Open Liberty] 24.0.0.6-beta includes the following beta features (along with link:{url-prefix}/docs/latest/reference/feature/feature-overview.html[all GA features]): + +* <> +* <> +* <> +* <> + + +// // // // // // // // +// In the preceding section: +// Change SUB_FEATURE_TITLE to the feature that is included in this release and +// change the SUB_TAG_1/2/3 to the heading tags +// +// However if there's only 1 new feature, delete the previous section and change it to the following sentence: +// "The link:{url-about}[Open Liberty] 24.0.0.6-beta includes SUB_FEATURE_TITLE" +// // // // // // // // + +See also link:{url-prefix}/blog/?search=beta&key=tag[previous Open Liberty beta blog posts]. + +// // // // DO NOT MODIFY THIS COMMENT BLOCK // // // // +// Blog issue: https://github.com/OpenLiberty/open-liberty/issues/28397 +// Contact/Reviewer: mswatosh +// // // // // // // // +[#validate] +== Validate Java constraints and records with Jakarta Validation 3.1 + +Jakarta Validation provides a mechanism to validate constraints that are imposed on Java objects by using annotations. The most noticeable change in version 3.1 is the name change, from Jakarta Bean Validation to Jakarta Validation. This version also includes explicit support for validating Java record classes, which were added in Java 16. Records reduce much of the boilerplate code in simple data classes, and pair nicely with Jakarta Validation. + +The following examples demonstrate the simplicity of defining a Java record with Jakarta Validation annotations, as well as performing validation. + +In this example, an `Employee` record is defined with two fields, `empid` and `email`. + +[source,java] +---- +public record Employee(@NotEmpty String empid, @Email String email) {} +---- + +The `@NotEmpty` annotation specifies that `empid` cannot be an empty string, while the `@Email` annotation specifies that the value for `email` must be a properly formatted email address. + +In this example, a validator is created to check the specified `Employee` values against the constraints that were set in the previous example. + +[source,java] +---- +Employee employee = new Employee("12432", "mark@example.com"); +Set> violations = validator.validate(employee); +---- + + +// DO NOT MODIFY THIS LINE. + +// // // // DO NOT MODIFY THIS COMMENT BLOCK // // // // +// Blog issue: https://github.com/OpenLiberty/open-liberty/issues/28293 +// Contact/Reviewer: njr-11 +// // // // // // // // +[#data] +== Preview of Jakarta Data (Release Candidate 1) + +Jakarta Data is a new Jakarta EE specification being developed in the open that aims to standardize the popular Data Repository pattern across various providers. Open Liberty 24.0.0.6-beta includes the Jakarta Data 1.0 release candidate 1, which decouples sorting from pagination, improves the static metamodel, and completes the initial definition of Jakarta Data Query Language (JDQL). + +The Open Liberty beta includes a test implementation of Jakarta Data that we are using to experiment with proposed specification features. You can try out these features and provide feedback to influence the Jakarta Data 1.0 specification as it continues to be developed. The test implementation currently works with relational databases and operates by redirecting repository operations to the built-in Jakarta Persistence provider. + +Jakarta Data 1.0 Release Candidate 1 completes the definition of Jakarta Data Query Language (JDQL) as a subset of Jakarta Persistence Query Language (JPQL). JDQL allows basic comparison and update operations on a single type of entity (an entity identifier variable is not used), as well as the ability to perform deletion and count operations. Find operations in JDQL consist of SELECT, FROM, WHERE, and ORDER BY clauses, all of which are optional. + +Jakarta Data 1.0 Release Candidate 1 decouples sorting from pagination, allowing you to request pages of results without needing to duplicate the specification of the entity type that is queried. + +The static metamodel, which allows for more type-safe usage, is streamlined in Release Candidate 1 to allow the use of interface classes with constant fields to define the metamodel. + +To use these capabilities, you need an Entity and a Repository. + +Start by defining an entity class that corresponds to your data. With relational databases, the entity class corresponds to a database table and the entity properties (public methods and fields of the entity class) generally correspond to the columns of the table. An entity class can be: + +- Annotated with `jakarta.persistence.Entity` and related annotations from Jakarta Persistence +- A Java class without entity annotations, in which case the primary key is inferred from an entity property that is named `id` or ends with `Id` and an entity property that is named `version` designates an automatically incremented version column. + +You define one or more repository interfaces for an entity, annotate those interfaces as `@Repository`, and inject them into components by using `@Inject`. The Jakarta Data provider supplies the implementation of the repository interface for you. + +The following example shows a simple entity: + +[source,java] +---- +@Entity +public class Product { + @Id + public long id; + + public boolean isDiscounted; + + public String name; + + public float price; + + @Version + public long version; +} +---- + +Here is a repository that defines operations relating to the entity. Your repository interface can inherit from built-in interfaces, such as `BasicRepository` and `CrudRepository`, to gain various general-purpose repository methods for inserting, updating, deleting, and querying for entities. You can add methods to further customize it. + +[source,java] +---- +@Repository(dataStore = "java:app/jdbc/my-example-data") +public interface Products extends BasicRepository { + @Insert + Product add(Product newProduct); + + // query-by-method name pattern: + List findByNameIgnoreCaseContains(String searchFor, Order orderBy); + + // parameter based query that does not require -parameters because it explicitly specifies the name + @Find + Page find(@By("isDiscounted") boolean onSale, + PageRequest pageRequest, + Order orderBy); + + // find query in JDQL that requires compilation with -parameters to preserve parameter names + @Query("SELECT price FROM Product WHERE id=:productId") + Optional getPrice(long productId); + + // update query in JDQL: + @Query("UPDATE Product SET price = price - (?2 * price), isDiscounted = true WHERE id = ?1") + boolean discount(long productId, float discountRate); + + // delete query in JDQL: + @Query("DELETE FROM Product WHERE name = ?1") + int discontinue(String name); +} +---- + +Observe that the repository interface includes type parameters in `PageRequest` and `Order`. These parameters help ensure that the page request and sort criteria are for a `Product` entity rather than some other entity. To accomplish this, you can optionally define a static metamodel class for the entity (or various IDEs might generate one for you after the 1.0 specification is released). Here is one that can be used with the `Product` entity: + +[source,java] +---- +@StaticMetamodel(Product.class) +public interface _Product { + String ID = "id"; + String IS_DISCOUNTED = "isDiscounted"; + String NAME = "name"; + String PRICE = "price"; + String VERSION = "version"; + + SortableAttribute id = new SortableAttributeRecord(ID); + SortableAttribute isDiscounted = new SortableAttributeRecord(IS_DISCOUNTED); + TextAttribute name = new TextAttributeRecord(NAME); + SortableAttribute price = new SortableAttributeRecord(PRICE); + SortableAttribute version = new SortableAttributeRecord(VERSION); +} +---- + +The following example shows the repository and static metamodel being used: + +[source,java] +---- +@DataSourceDefinition(name = "java:app/jdbc/my-example-data", + className = "org.postgresql.xa.PGXADataSource", + databaseName = "ExampleDB", + serverName = "localhost", + portNumber = 5432, + user = "${example.database.user}", + password = "${example.database.password}") +public class MyServlet extends HttpServlet { + @Inject + Products products; + + protected void doGet(HttpServletRequest req, HttpServletResponse resp) + throws ServletException, IOException { + // Insert: + Product prod = ... + prod = products.add(prod); + + // Find the price of one product: + price = products.getPrice(productId).orElseThrow(); + + // Find all, sorted: + List all = products.findByNameIgnoreCaseContains(searchFor, Order.by( + _Product.price.desc(), + _Product.name.asc(), + _Product.id.asc())); + + // Find the first 20 most expensive products on sale: + Page page1 = products.find(onSale, PageRequest.ofSize(20), Order.by( + _Product.price.desc(), + _Product.name.asc(), + _Product.id.asc())); + ... + } +} +---- + +// DO NOT MODIFY THIS LINE. + +// // // // DO NOT MODIFY THIS COMMENT BLOCK // // // // +// Blog issue: https://github.com/OpenLiberty/open-liberty/issues/28355 +// Contact/Reviewer: tonyreigns +// // // // // // // // +[#mpm] +== Enhanced histogram and timer metrics in MicroProfile 3.0 and 4.0 + +This release introduces MicroProfile Config properties for MicroProfile 3.0 and 4.0 that are used for configuring the statistics that are tracked and outputted by the histogram and timer metrics. These changes are already available in MicroProfile Metrics 5.1. + +In previous MicroProfile Metrics 3.0 and 4.0 releases, histogram and timer metrics tracked only the following values: + +* Min/max recorded values +* The sum of all values +* The count of the recorded values +* A static set of percentiles for the 50th, 75th, 95th, 98th, 99th and 99.9th percentile. + +These values are output to the `/metrics` endpoint in Prometheus format. + +The new properties can define a custom set of percentiles as well as custom set of histogram buckets for the histogram and timer metrics. Other new configuration properties can enable a default set of histogram buckets, including properties that define an upper and lower bound for the bucket set. + +With these properties, you can define a semicolon-separated list of value definitions that use the following syntax: + +---- +=[,…] +---- + +Some properties can accept multiple values for a given metric name, while others can accept only a single value. + +You can use an asterisk ( *) as a wildcard at the end of the metric name. + +[cols="2*"] +|=== +| Property | Description +| mp.metrics.distribution.percentiles | Defines a custom set of percentiles for matching Histogram and Timer metrics to track and output. Accepts a set of integer and decimal values for a metric name pairing. Can be used to disable percentile output if no value is provided with a metric name pairing. +| mp.metrics.distribution.histogram.buckets| Defines a custom set of (cumulative) histogram buckets for matching Histogram metrics to track and output. Accepts a set of integer and decimal values for a metric name pairing. +| mp.metrics.distribution.timer.buckets| Defines a custom set of (cumulative) histogram buckets for matching Timer metrics to track and output. Accepts a set of decimal values with a time unit appended (that is, ms, s, m, h) for a metric name pairing. +|mp.metrics.distribution.percentiles-histogram.enabled | Configures any matching Histogram or Timer metric to provide a large set of default histogram buckets to allow for percentile configuration with a monitoring tool. Accepts a true/false value for a metric name pairing. +| mp.metrics.distribution.histogram.max-value| When percentile-histogram is enabled for a Timer, this property defines an upper bound for the buckets reported. Accepts a single integer or decimal value for a metric name pairing. +| mp.metrics.distribution.histogram.min-value| When percentile-histogram is enabled for a Timer, this property defines a lower bound for the buckets reported. Accepts a single integer or decimal value for a metric name pairing. +|mp.metrics.distribution.timer.max-value | When percentile-histogram is enabled for a Histogram, this property defines an upper bound for the buckets reported. Accepts a single decimal value with a time unit appended (that is, ms, s, m, h) for a metric name pairing. Accepts a single decimal value with a time unit appended (that is, ms, s, m, h) for a metric name pairing. +|mp.metrics.distribution.timer.min-value | When percentile-histogram is enabled for a Histogram, this property defines a lower bound for the buckets reported. Accepts a single decimal value with a time unit appended (that is, ms, s, m, h) for a metric name pairing. + +|=== + +You can define the `mp.metrics.distribution.percentiles` property similar to the following example. + +---- +mp.metrics.distribution.percentiles=alpha.timer=0.5,0.7,0.75,0.8;alpha.histogram=0.8,0.85,0.9,0.99;delta.*= +---- + +This property creates the `alpha.timer` timer metric to track and output the 50th, 70th, 75th, and 80th percentile values. The `alpha.histogram` histogram metric outputs the 80th, 85th, 90th, and 99th percentile values. Percentiles for any histogram or timer metric that matches with `delta.*` are disabled. + +We'll expand on this example and define histogram buckets for the `alpha.timer` timer metric by using the `mp.metrics.distribution.timer.buckets` property. + +---- +mp.metrics.distribution.timer.buckets=alpha.timer=100ms,200ms,1s +---- + +This configuration tells the metrics runtime to track and output the count of durations that fall within 0-100ms, 0-200ms and 0-1 seconds. This output is due to the histogram buckets working in a _cumulative_ fashion. + +The corresponding prometheus output for the `alpha.timer` metric at the `/metrics` REST endpoint is similar to the following example: + +---- +# TYPE application_alpha_timer_mean_seconds gauge +application_alpha_timer_mean_seconds 2.9700022497975187 +# TYPE application_alpha_timer_max_seconds gauge +application_alpha_timer_max_seconds 5.0 +# TYPE application_alpha_timer_min_seconds gauge +application_alpha_timer_min_seconds 1.0 +# TYPE application_alpha_timer_stddev_seconds gauge +application_alpha_timer_stddev_seconds 1.9997750210918204 +# TYPE alpha_timer_seconds histogram <1> +application_alpha_timer_seconds_bucket{le="0.1"} 0.0 <2> +application_alpha_timer_seconds_bucket{le="0.2"} 0.0 <2> +application_alpha_timer_seconds_bucket{le="1.0"} 1.0 <2> +application_alpha_timer_seconds_bucket{le="+Inf"} 2.0 <2> <3> +application_alpha_timer_seconds_count 2 +application_alpha_timer_seconds_sum 6.0 +application_alpha_timer_seconds{quantile="0.5"} 1.0 +application_alpha_timer_seconds{quantile="0.7"} 5.0 +application_alpha_timer_seconds{quantile="0.75"} 5.0 +application_alpha_timer_seconds{quantile="0.8"} 5.0 +---- + +<1> The Prometheus metric type is `histogram`. Both the quantiles/percentile and buckets are represented under this type. +<2> The `le` tag represents _less than_ and is for the defined buckets, which are converted to seconds. +<3> Prometheus requires that a `+Inf` bucket counts all hits. + + +// DO NOT MODIFY THIS LINE. + +// // // // DO NOT MODIFY THIS COMMENT BLOCK // // // // +// Blog issue: https://github.com/OpenLiberty/open-liberty/issues/28337 +// Contact/Reviewer: anjumfatima90 +// // // // // // // // +[#jcache] +== InstantOn support for distributed HTTP session caching + +Open Liberty link:https://openliberty.io/docs/latest/instanton.html[InstantOn] provides fast startup times for MicroProfile and Jakarta EE applications. With InstantOn, your applications can start in milliseconds, without compromising on throughput, memory, development-production parity, or Java language features. InstantOn uses the Checkpoint/Restore In Userspace (link:https://criu.org/[CRIU]) feature of the Linux kernel to take a checkpoint of the JVM that can be restored later. + +The 24.0.0.6-beta release provides InstantOn support for the link:{url-prefix}/docs/latest/reference/feature/sessionCache-1.0.html[JCache Session Persistence] feature. This feature uses a JCache provider to create a distributed in-memory cache. Distributed session caching is achieved when the server is connected to at least one other server to form a cluster. Open Liberty servers can behave in the following ways in a cluster. + +- Client-server model: An Open Liberty server can act as the JCache client and connect to a dedicated JCache server. +- Peer-to-Peer model: An Open Liberty server can connect with other Open Liberty servers that are also running with the JCache Session Persistence feature and configured to be part of the same cluster. + +To enable JCache Session Persistence, the `sessionCache-1.0` feature must be enabled in your `server.xml` file: + +[source,xml] +---- +sessionCache-1.0 +---- + +You can configure the client/server model in the `server.xml` file, similar to the following example. + +[source,xml] +---- + + + + + + + + +---- + +You can configure the peer-to-peer model in the `server.xml` file, similar to the following example. + +[source,xml] +---- + + + + + + + + + +---- + +**Note:** +To provide InstantOn support for the peer-to-peer model by using Infinispan as a JCache Provider, you must use Infinispan 12 or later. You must also enable link:{url-prefiux}/docs/latest/reference/feature/mpReactiveStreams-3.0.html[MicroProfile Reactive Streams 3.0] or later and link:{url-prefix}docs/latest/reference/feature/mpMetrics-4.0.html[MicroProfile Metrics 4.0] or later in the `server.xml` file, in addition to the JCache Session Persistence feature. + +The environment can provide vendor-specific JCache configuration properties when the server is restored from the checkpoint. The following configuration uses server list, username, and password values as variables defined in the restore environment. + +[source,xml] +---- + + + + + + + +---- + +// DO NOT MODIFY THIS LINE. + +[#run] +=== Try it now + +To try out these features, update your build tools to pull the Open Liberty All Beta Features package instead of the main release. The beta works with Java SE 22, Java SE 21, Java SE 17, Java SE 11, and Java SE 8. + + +If you're using link:{url-prefix}/guides/maven-intro.html[Maven], you can install the All Beta Features package by using: + +[source,xml] +---- + + io.openliberty.tools + liberty-maven-plugin + 3.10.3 + + + io.openliberty.beta + openliberty-runtime + 24.0.0.6-beta + zip + + + +---- + +You must also add dependencies to your pom.xml file for the beta version of the APIs that are associated with the beta features that you want to try. For example, the following block adds dependencies for two example beta APIs: + +[source,xml] +---- + + org.example.spec + exampleApi + 7.0 + pom + provided + + + example.platform + example.example-api + 11.0.0 + provided + +---- + +Or for link:{url-prefix}/guides/gradle-intro.html[Gradle]: + +[source,gradle] +---- +buildscript { + repositories { + mavenCentral() + } + dependencies { + classpath 'io.openliberty.tools:liberty-gradle-plugin:3.8.3' + } +} +apply plugin: 'liberty' +dependencies { + libertyRuntime group: 'io.openliberty.beta', name: 'openliberty-runtime', version: '[24.0.0.6-beta,)' +} +---- + + +Or if you're using link:{url-prefix}/docs/latest/container-images.html[container images]: + +[source] +---- +FROM icr.io/appcafe/open-liberty:beta +---- + +Or take a look at our link:{url-prefix}/downloads/#runtime_betas[Downloads page]. + +If you're using link:https://plugins.jetbrains.com/plugin/14856-liberty-tools[IntelliJ IDEA], link:https://marketplace.visualstudio.com/items?itemName=Open-Liberty.liberty-dev-vscode-ext[Visual Studio Code] or link:https://marketplace.eclipse.org/content/liberty-tools[Eclipse IDE], you can also take advantage of our open source link:https://openliberty.io/docs/latest/develop-liberty-tools.html[Liberty developer tools] to enable effective development, testing, debugging, and application management all from within your IDE. + +For more information on using a beta release, refer to the link:{url-prefix}docs/latest/installing-open-liberty-betas.html[Installing Open Liberty beta releases] documentation. + +[#feedback] +== We welcome your feedback + +Let us know what you think on link:https://groups.io/g/openliberty[our mailing list]. If you hit a problem, link:https://stackoverflow.com/questions/tagged/open-liberty[post a question on StackOverflow]. If you hit a bug, link:https://github.com/OpenLiberty/open-liberty/issues[please raise an issue].