Support for GraphQL with Open Liberty 20.0.0.6

The Open Liberty 20.0.0.6 release brings new features, updates, and bug fixes. This article introduces the new features in Open Liberty 20.0.0.6, including support for developing "code-first" GraphQL applications, provisioning features from a Maven repository, and using a server configuration to control application startup.

What's new in Open Liberty 20.0.0.6

Open Liberty 20.0.0.6 includes the following feature updates, which I discuss in the next sections:

• Using GraphQL with Open Liberty
• Provisioning features from a Maven repository
• Administrators control the application start order
• New REST visualizations in Open Liberty Grafana dashboards
• Web application startup changes

Note: Visit Open Liberty's GitHub repository to learn about bug fixes in Open Liberty 20.0.0.6.

Run your apps using Open Liberty 20.0.0.6

Use the following command to get or update to Open Liberty 20.0.0.6 using Maven:

  <dependency>
      <groupId>io.openliberty</groupId>
      <artifactId>openliberty-runtime</artifactId>
      <version>20.0.0.6</version>
      <type>zip</type>
  </dependency>

If you're using Gradle, simply enter:

dependencies {
    libertyRuntime group: 'io.openliberty', name: 'openliberty-runtime', version: '[20.0.0.6,)'
}

Here's the command for Docker:

FROM open-liberty

See the Open Liberty downloads page to get the latest release for Jakarta EE 8, Web Profile 8, and MicroProfile 3.

Using GraphQL with Open Liberty

Open Liberty's support for MicroProfile GraphQL lets developers write "code-first" GraphQL applications that put clients in control of the data they receive. You can use annotations like @Query and @Mutation to turn Plain Old Java Objects (POJOs) into HTTP-based GraphQL endpoints. When the query or mutation method returns an existing entity object, the client can specify the fields it is interested in—which reduces network bandwidth and client-side processing.

Here’s an example:

@GraphQLApi
public class MovieService {
    AtomicInteger nextId = new AtomicInteger();
    Map<Integer, Movie> movieDB = new HashMap();

    @Query("movieById")
    public Movie getMovieByID(int id) throws UnknownMovieException {
        return Optional.ofNullable(movieDB.get(id)).orElseThrow(UnknownMovieException::new);
    }

    @Query("allMoviesDirectedBy")
    public List<Movie> getAllMoviesWithDirector(String directorName) {
        return movieDB.values().stream()
                               .filter(m -> m.getDirector().equals(directorName))
                               .collect(Collectors.toList());
    }

    @Mutation("newMovie")
    public int createNewMovie(@Name("movie") Movie movie) {
        int id = nextId.incrementAndGet();
        movie.setId(id);
        movieDB.put(id, movie);
        return id;
    }
}

This code creates a GraphQL application with two queries (movieById and allMoviesDirectedBy) and a mutation (newMovie). If the client executes the following query:

query {
  allMoviesDirectedBy(directorName: "Roland Emmerich") {
    id, title, actors
  }
}

The result will be:

{
  "data": {
    "allMoviesDirectedBy": [
      {
        "id": 1,
        "title": "Independence Day",
        "actors": [
          "Will Smith",
          "Bill Pullman",
          "Jeff Goldblum",
          ...
        ]
      },
      ...
    ]
  }
}

Open Liberty’s GraphQL APIs were developed within the MicroProfile community and have broad industry support. The implementation is based on SmallRye GraphQL. Liberty’s GraphQL feature goes beyond the MicroProfile specification and adds support for collecting metrics, checking authorizations, and logging requests and responses to query and mutation methods.

For more details and a sample application, see this simple demo of the MicroProfile GraphQL capabilities in Open Liberty. Join the growing landscape of GraphQL adopters and write your first GraphQL application today!

Provisioning features from a Maven repository

Developers can now use a convenient command-line tool to install features from the Maven Central repository or an on-premises Maven repository (such as one served on Artifactory or Nexus) directly onto an Open Liberty runtime. Table 1 details using the wlp/bin/featureUtility commands to find, install, and get information about assets in a Maven repository.

Table 1. Open Liberty commands to install features from a Maven repository

Administrators control the application start order

By default, applications start in parallel and can finish starting in random order. With the 20.0.0.6 release, Open Liberty empowers administrators to prevent an application from starting until one or more other applications have started.

Being able to define the order of application startup is critical because applications are often dependent on each other. For example, a single Open Liberty server might contain a front-end application that provides a user interface and a back-end application that accesses a database. Having the front-end application available before the back end started could result in errors. With this feature, you could prevent the front-end application from starting until the back end was ready.

You only need to define the application dependencies in the configuration, using the startAfter attribute on the application element. In this example, you would add a comma-separated list of ID values for the back-end applications that must start before the front-end application can run:

 <webApplication id="frontend" location="myFrontend.war" startAfter="backend1, backend2"/>
 <enterpriseApplication id="backend1" location="myBackend.ear"/>
 <enterpriseApplication id="backend2" location="myUtilities.ear"/>

REST visualizations in Open Liberty Grafana dashboards

Grafana dashboards provide a wide range of time-series visualizations of MicroProfile Metrics data such as CPU, REST, servlet, connection pool, and garbage collection metrics. Grafana dashboards are powered by a Prometheus data source, which is configured to ingest data from the /metrics endpoint of one or more Open Liberty servers. As a result, users can view the metrics on Grafana dashboards in near real-time.

With the release of mpMetrics-2.3 and its addition of JAX-RS metrics, we've introduced a new set of visualizations to our Open Liberty Grafana dashboards. You can find these under a new tab labeled REST. We've also added hover-over descriptions that provide a brief summary of each visualization and its function. These updates apply to OKD 3.11 (the upstream distribution of Red Hat OpenShift), Red Hat OpenShift Container Platform (OCP), and standalone Open Liberty instances.

If you do not already have Grafana and Prometheus set up in your development environment, see the Kabanero guide for Red Hat OpenShift Container Platform 4.3. To get started using the Grafana dashboard with Open Liberty, see my blog post introducing Open Liberty's support for MicroProfile 3.3.

Note: You can find the Grafana dashboards for Open Liberty on OKD or OCP in the open-liberty-operator repository.

Web application startup changes

Starting with Open Liberty 20.0.0.6, web applications are considered started only after calls to ServletContainerInitializers and ServletContextListeners have completed. This update effectively moves more of the application initialization process into the server-startup route. As a result, it might appear that applications and the server take longer to start. The change doesn't affect how long it takes for applications to begin processing requests; it just moves it to run prior to the opening of the ports. In addition, you can now configure the server.xml so that a failure in a ServletContextListener will cause application startup to fail. Just add the following:

<webContainer stopAppStartUponListenerException="true"/>

Note: Find out more about application properties here.

Conclusion

Open Liberty 20.0.0.6 is available through Maven, Gradle, Docker, and as a downloadable archive. Get it today to begin using the new features I've described in this article.