タグ別アーカイブ: Microprofile

MicroProfile 3.0 Support Comes to Helidon

このエントリは以下のエントリをベースにしています。
This entry is based on the following one written by Dmitry Kornilov (Eclipse EE4J PMC member, Jakarta EE contributor, JCP star spec lead, Helidon Project lead, Oracle).
https://dmitrykornilov.net/2019/09/14/microprofile-3-0-support-comes-to-helidon/
https://medium.com/oracledevs/microprofile-3-0-support-comes-to-helidon-f72ba752b42f

Helidonの新しいバージョン、1.3が出ました。このリリースの主要機能は、MicroProfile 3.0のサポートですが、その他にも機能追加や不具合の修正、パフォーマンス改善などが含まれています。詳しく見ていきましょう。

MicroProfile 3.0

約1ヵ月前にMicroProfile 2.2をサポートしたHelidon 1.2をリリースしました。その後さらに作業を進めて、Helidon 1.3でMicroProfile 3.0のサポートをするようにいたしました。

ご存じない方のために、MicroProfileとはクラウドネイティブJavaのためのAPI群です。

Eclipse MicroProfile
https://microprofile.io/

多くのモダンなJavaベンダー(Oracle、IBM、Red Hat、Payara、Tomitribeなど)がMicroProfileをサポートしており、この領域におけるデファクトスタンダードになっています。Helidon MicroProfile実装はHelidon MPと呼ばれ、リアクティブやノンブロッキングフレームワークのHelidon SEと共にHelidonのコアをなしています。

MicroProfile 3.0はメジャーリリースで、これには以下のアップデートが含まれています。

  • 後方互換性を担保しない変更あり
    • Metrics 2.0
  • 小規模なアップデート
    • HealthCheck 2.0
    • Rest Client 1.3

MicroProfile 3.0はMicroProfile 2.2に対する後方互換性がありませんが、Helidonには後方非互換性を持ち込みたくありませんでした。Helidon 1.3ではMicroProfile 2.2とMicroprofile 3.0の両方をサポートします。Helidon MPアプリケーションは以下のバンドルによってMicroProfileのバージョンを選択できます。

MicroProfile 2.2互換にしたい場合

<dependency>
    <groupId>io.helidon.microprofile.bundles</groupId>    
    <artifactId>helidon-microprofile-2.2</artifactId>
</dependency>

MicroProfile 3.0互換にしたい場合

<dependency>
    <groupId>io.helidon.microprofile.bundles</groupId
    <artifactId>helidon-microprofile-3.0</artifactId>
</dependency>

MicroProfile 2.2への後方互換性はhelidon-microprofile-2.2に依存する既存の全てのHelidonアプリケーションが変更せずに継続して動作することを意図しています。Helidon 1.3の最新のarchetypeを使って作成した新規アプリケーションはhelidon-microprofile-3.0に依存します。

Metrics 2.0 Support

前述の通り、MicroProfile Metrics 2.0では後方非互換の変更だけでなく、数多くの新機能も導入されています。以下はその変更をまとめたものです。

  • 既存のカウンタを常にモノトニック(monotonic)なものに制限
  • concurrent gaugeと呼ばれる新たなメトリックをサポート
  • タグはMetadataではなくMetricIDTagsの一部になった
  • Metadataはイミュータブル
  • JSONフォーマットに小規模な変更
  • PrometheusフォーマットはOpenMetricsフォーマットに(いくつかの小規模なアップデートを含む)

詳細は以下のURLをご覧ください。

MicroProfile Metrics 2.0.1
https://github.com/eclipse/microprofile-metrics/releases/tag/2.0.1

Note: MetricRegistryクラスには、破壊的なシグネチャの変更が入っており、getterメソッドの中には、キーがStringではなくMetricID型であるマップを返すようになったものがあります。MicroProfile Metrics 2.0の最新バージョンにアップグレードするアプリケーションは、これらの使用法を確認して正しいタイプが渡されることを確認し、メトリック検索の失敗を防ぐ必要があります。

Helidon SEアプリケーションでメトリクスを使っている場合も、Helidon 1.3の新機能を活用できます。例えば、MicroProfile 2.0で導入されたconcurrent gaugeの概念はHelidon SEでも利用できます。これらの新機能を使うためには、Helidon SEアプリケーションは以下の依存関係を設定しておく必要があります。

<dependency>
    <groupId>io.helidon.metrics</groupId>
    <artifactId>helidon-metrics2</artifactId>
</dependency>

既存のHelidon SEアプリケーションは引き続き旧来のhelidon-metricsを依存関係として利用できます。

HealthCheck 2.0 Support

HealthCheck 2.0には重要な変更が含まれています。Health checkレスポンスのメッセージ本体が変更され、outcomestatestatusに置き換えられました。 また、readiness (/health/ready) と liveness (/health/live) の両エンドポイントがKubernetesとのスムーズな統合のために導入されました。

これまでの /health エンドポイントは削除されていませんので、既存のアプリケーションは変更しなくてもそのまま動作します。

新たな仕様により、2個の注釈(@Liveness@Readiness)が導入されています。Helidon SEで、2個の対応するメソッド(addReadinessaddReadiness)が導入され、これまでのメソッドaddは廃止されました。

JPA and JTA are Production Ready

Helidonの初期バージョンでJPAとJTAとの統合の早期アクセスバージョンを導入しました。ユーザーからのフィードバックを受けて、問題を修正してパフォーマンスを改善しました。Helidon 1.3ではJPAとJTAのサポートを早期アクセスからProduction Readyに移行しました。

この機能を理解するのに有用なガイドも作成しました。

Guides — Using JPA in Helidon MP
https://helidon.io/docs/latest/index.html#/guides/24_jpa

Hibernate Support

Helidon 1.3ではJPAプロバイダとしてHiberneteを利用できるようになりました。引き続きEclipseLinkを利用することもできます。どちらを選択するかはあなた次第です。依存関係の違いは以下の通りです。

EclipseLinkの場合

<dependency>
    <groupId>io.helidon.integrations.cdi</groupId
    <artifactId>helidon-integrations-cdi-eclipselink</artifactId
    <scope>runtime</scope>
</dependency>

Hibernateの場合

<dependency>
    <groupId>io.helidon.integrations.cdi</groupId
    <artifactId>helidon-integrations-cdi-hibernate</artifactId
    <scope>runtime</scope>
</dependency>

EclipseLinkのサポートと同様に、HelidonのHibernate JPA統合は、EJBを使わない拡張された永続コンテキスト、JTAトランザクション、Bean Validationのサポートを含む、Java EEモードとの完全な互換性を備えています。これは、慣れ親しんだアプリケーションサーバーと同じように機能しますが、Helidonの軽量なMicroProfile環境内で機能します。

GraalVM Improvements

GraalVMのサポートは目的の一つです。各リリースでHelidon SEにおけるGraalVMのサポートを継続的に改善しています。このバージョンではGraalVM 19.2.0をサポートしています。また、JerseyクライアントをHelidon SEアプリケーションで利用でき、ネイティブイメージにすることもできます。

以下はサンプルコードです。

private void outbound(ServerRequest request, ServerResponse response) {
    // and reactive jersey client call
    webTarget.request()
        .rx()
        .get(String.class)
        .thenAccept(response::send)
        .exceptionally(throwable -> {
            // process exception
            response.status(Http.Status.INTERNAL_SERVER_ERROR_500);
            response.send("Failed with: " + throwable);
            return null;
    });
}

Helidon SE applicationからGraalVMネイティブイメージを生成する方法を説明するガイドを追加しましたので、是非チェックしてください。

Guides — GraalVM Native Images
https://helidon.io/docs/latest/#/guides/36_graalnative

New Guides

Helidonを使う上で有用な、さまざまなHelidon機能の使用方法を説明する新しいガイドを多数追加しました。

Guides — Overview
https://helidon.io/docs/latest/index.html#/guides/01_overview

Getting Started

Basics

Persistence

Build and Deploy

Tutorial

Other features

このリリースには多数の不具合修正、パフォーマンス改善やマイナーアップデートが含まれています。変更内容の詳細情報はリリースノートをご覧ください。

Release notes
https://github.com/oracle/helidon/releases/tag/1.3.0

Helidon on OOW/CodeOne 2019

来週(2019年9月16日)、Oracle Open World と CodeOne が開催されますが、Helidonもそこでご紹介します。ユーザーからHelidonの様々なユースケースを紹介してもらうだけでなく、まもなく登場するHelidon DBのような新機能をHelidonチームからご紹介するセッションがあります。以下はそのリストです。

  • Non-blocking Database Access in Helidon SE [DEV5365]
    Monday, September 16, 09:00 AM — 09:45 AM
  • Migrating a Single Monolithic Application to Microservices [DEV5112]
    Thursday, September 19, 12:15 PM — 01:00 PM
  • Hands on Lab: Building Microservices with Helidon
    Monday, September 16, 05:00 PM — 07:00 PM
  • Building Cloud Native Applications with Helidon [CON5124]
    Wednesday, September 18, 09:00 AM — 09:45 AM
  • Helidon Flies Faster on GraalVM [DEV5356]
    September 16, 01:30 PM — 02:15 PM
  • Helidon MicroProfile: Managing Persistence with JPA [DEV5376]
    Thursday, September 19, 09:00 AM — 09:45 AM

CodeOneでお会いしましょう。

Announcing Visual Studio Code Extension for MicroProfile Starter

このエントリは以下のエントリをベースにしています。
This entry is based on the following one written by YK Chang.
https://microprofile.io/2019/09/17/announcing-visual-studio-code-extension-for-microprofile-starter/

MicroProfileコミュニティから、MicroProfile StarterのVisual Studio Code extension(拡張機能)が利用可能になったことを発表します。 VS Code extension for Eclipse MicroProfile Starterバージョン0.1が、Visual Studio CodeのMarketplaceからダウンロードして使用できるようになりました。

MicroProfile Starter
https://marketplace.visualstudio.com/items?itemName=MicroShed.mp-starter-vscode-ext

MicroProfile Starterは、MicroProfileを実装するランタイムのコード例を伴うMavenプロジェクトを開発者向けに生成します。開発者は、必要なものを使ってマイクロサービスのコーディングをすばやく開始できます。このたび、VS Code extensionが登場したことで、開発者はエディターを離れずに、VS Code内でMavenスタータープロジェクトを直接生成できるようになりました。

MicroProfile Starter
https://start.microprofile.io/

VS Codeにインストールしたら、コマンドパレットからMicroProfile Starterを選択して実行し、プロンプトに従って必要なものを選択すれば、指定したフォルダーにスタータープロジェクトが生成されます。VS Code extensionは、MicroProfile Starter Webサイトと同じオプションを提供し、プロジェクト生成にあたっては同じAPIを使用します。

MicroProfile Starterと同様に、この拡張機能はMicroProfileコミュニティによる協同作業の成果です。このソースコードはオープンであり、MicroShed(Javaマイクロサービスの開発者ツールに関するコミュニティ・コラボレーション)の下、GitHubに格納されています。

MicroShed — Developer tools for creating Java microservices
https://github.com/MicroShed

Visual Studio Code extension for Eclipse MicroProfile Starter をお試しいただき、フィードバックを頂けると幸甚です、Gitterのmicroprofile-starterやmp-starter-vscode-extリポジトリのIssueでお寄せください。

Gitter — microprofile-starter
https://gitter.im/eclipse/microprofile-starter
Issues — mp-starter-vscode-ext
https://github.com/MicroShed/mp-starter-vscode-ext/issues

VS Code extensionのロードマップには、オフラインモードなどがあがっています。また、これがMicroProfileコミュニティが作成した最初のIDE extensionであり、MicroProfile Starterプロジェクトは、さまざまなIDE向けの拡張機能を近日中に提供する予定です。是非一緒に作り上げましょう。我々はみなさまからのフィードバック、アイデア、貢献を歓迎し、貴重なものとして受け止めます。

Happy coding with MicroProfile!

Helidon brings MicroProfile 2.2+ support

このエントリは以下のエントリをベースにしています。
This entry is based on the following one, written by Dmitry Kornilov (Eclipse EE4J PMC member, Jakarta EE contributor, JCP star spec lead, Helidon Project lead, Oracle).
https://dmitrykornilov.net/2019/08/08/helidon-brings-microprofile-2-2-support/
https://medium.com/oracledevs/helidon-brings-microprofile-2-2-support-93d85bb4223e

Helidon 1.2.0では、MicroProfile 2.2をサポートし、さらにバグ修正やパフォーマンス上の問題を改善しています。

Helidon 1.2.0 (Release Notes)
https://github.com/oracle/helidon/releases/tag/1.2.0
Eclipse MicroProfile 2.2 is Now Available
https://microprofile.io/2019/02/12/eclipse-microprofile-2-2-is-now-available/

MicroProfile

Project Helidonの主目的の一つは最新のMicroProfile APIのサポートを提供することにあります。HelidonのMicroProfile実装はHelidon MPと呼ばれ、Helidon SEと呼ばれるリアクティブ、ノンブロッキングフレームワークと並んでHelidonの中核を形成しています。

下図はサポートしているMicroProfileとJava EEのAPIのリストです。

1.2.0では、JPA (Persistence) と JTA (Transaction) という2個のJava EE APIのサポートを追加しました。現時点ではEarly accessのため、実装や構成は今後変更の可能性があります。

以下はHelidon 1.2.0で追加された新しいAPIの利用例です。

MicroProfile REST Client sample

RESTクライアントインターフェースを登録します(これはJAX-RSリソースが実装するものと同一であってもかまいません)。URIは構成を使ってオーバーライドできる点にご注意ください。

@RegisterRestClient(baseUri = "http://localhost:8081/greet")
public interface GreetResource {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    JsonObject getDefaultMessage();
     
    @Path("/{name}")
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    JsonObject getMessage(@PathParam("name") String name);
}

(異なるマイクロサービスのJAX-RSリソースなど)利用するクラスでRESTクライアントを宣言します

@Inject
@RestClient
private GreetResource greetService;

あとはフィールドを使ってリモートサービス(この例ではリモートサービスへのリクエストをプロキシしています)を呼び出すだけです。

@GET
@Produces(MediaType.APPLICATION_JSON)
public JsonObject getDefaultMessage() {
    return greetService.getDefaultMessage();
}

Health Check 2.0 sample

Health Check 2.0 にはReadinessとLivenessという2種類のチェック機構があります(以前は1種類だけでした)。

  • Readiness — サービスが起動し利用可能であることを確認するためにクライアントが利用(例えばk8s readiness check)
  • Liveness — サービスが稼働しており実行中であることを確認するためにクライアントが利用(例えば k8s liveness check)

application scopedのbeanに適切な注釈(@Readiness もしくは @Liveness)をつけてヘルスチェックを作成します。

import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Liveness;
 
@Liveness
@ApplicationScoped
public class GreetHealthcheck implements HealthCheck {
    private GreetingProvider provider;
   
    @Inject
    public GreetHealthcheck(GreetingProvider provider) 
        this.provider = provider;
    }
 
    @Override
    public HealthCheckResponse call() {
        String message = provider.getMessage();
        return HealthCheckResponse.named("greeting")
            .state("Hello".equals(message))
            .withData("greeting", message)
            .build();
    }
}

Open Tracing Sample

MicroProfileのOpen Tracing では、CDI beansのトレースを追加する目的で @Tracedという1個のアノテーションを追加しています。

Tracing of JAX-RS リソースのトレースは自動化されています( @Tracedで無効化できます)。以下はHealth checkのサンプルで使ったbeanの例で、getMessageメソッドをトレースしています。

@ApplicationScoped
public class GreetingProvider {
    private final AtomicReference<String&gt; message = new AtomicReference<&gt;();
     
    /**
     * Create a new greeting provider, reading the message 
     * from configuration.
     *
     * @param message greeting to use
     */
    @Inject
    public GreetingProvider(
        @ConfigProperty(name = "app.greeting") String message) {
        this.message.set(message);
    }
     
    @Traced(operationName = "GreetingProvider.getMessage")
    String getMessage() {
        return message.get();
    }
     
    ...
}

Other Enhancements

MicroProfile 2.2に加え、Helidon 1.2.0にはいくつかの機能強化が含まれています。

  • Helidon MP と SEでHTTP Access Logをサポート
  • Oracle Universal Connection Pool のサポート(Early access)
    これを使って、Oracle UCP JDBCドライバをHelidon MPアプリケーションのDataSourceとして構成、注入できる。

More to Come

MicroProfile 2.2 のサポートにより、Helidonは他の主要なMicroProfile実装に追いついてきました。現在HelidonのMicroProfile 3.0対応に向けて作業を進めており、すでに最初の一歩を踏み出しています。これがタイトルの2.2の後に+をつけている理由です。すでにHealth Check 2.0をサポートしています(今後後方互換のある形でサポートする予定です)。残るはMetrics 2.0とREST Client 1.3で、来月リリースできるように鋭意取り組んでいます。

A preview of MicroProfile GraphQL

このエントリは以下のエントリをベースにしています。
This entry is based on the following one, written by Jean-François James (Senior Software Architect, Worldline by Atos Worldline).
https://jefrajames.wordpress.com/2019/07/25/a-preview-of-microprofile-graphql/

このエントリはmpql-previewプロジェクトと関係があります。

A preview of the future MicroProfile GraphQL specification
https://github.com/jefrajames/mpql-preview

Objectives

このプロジェクトは将来のEclipse MicroProfile GraphQL仕様のプレビューを提供することを目的としています。MicroProfile GraphQLをご存知ない場合は、以前のエントリとGitHubをご覧ください。手短に言えば、MicroProfile GraphQLは、モダンなAPIを開発するためにGraphQLをMicroProfileプラットフォームにおける第一級の市民とすることを目的としています。

When GraphQL meets MicroProfile
https://jefrajames.wordpress.com/2019/01/04/when-graphql-meets-microprofile/
https://logico-jp.io/2019/04/22/when-graphql-meets-microprofile/
MicroProfile GraphQL
https://github.com/eclipse/microprofile-graphql

GraphQLはFacebookが作った仕様で2018年11月からLinux Foundationがホストしています。クライアントサイドを非常に柔軟に作成でき、特にデータ指向APIに関連しています。

GraphQL
https://graphql.github.io/graphql-spec/

GraphQLについて知りたい方は、Bojan Tomicのすばらしいチュートリアルを辿ってください。

graphql-java Tutorial – Introduction
https://www.howtographql.com/graphql-java/0-introduction/

Status of Eclipse MicroProfile GraphQL

MicroProfile GraphQLはEclipseプロジェクトで、2018年12月にスタートしました。コードファーストのアプローチに従うGraphQLアプリケーションのための標準APIを定義することを目的としています。「コードファースト」とはGraphQLスキーマを事前に定義せず、アプリケーション起動時にJavaコードから導出することを意味します。

現在のAPIは一連のアノテーションのセットから構成されています。

プロジェクトはまだ開発途中ですが、既にお試し頂ける状態にあります。

  1. プロジェクトはGitHubからご覧頂けます。
    https://github.com/eclipse/microprofile-graphql
  2. APIはMaven Centralにパブリッシュ済みです。
    https://mvnrepository.com/artifact/org.eclipse.microprofile.graphql/microprofile-graphql-api
  3. 最初のプロトタイプ実装はspqrから提供されています。GitHubのmicroprofile-protpブランチでご覧頂けます。
    Java 8+ API for rapid development of GraphQL services
    https://github.com/leangen/graphql-spqr/tree/microprofile-proto

MicroProfile GraphQLの完全な実装がまだ利用できないことを除けば、試して頂ける状態にあります。

What is this preview project about?

このプロジェクトは3パートから構成されています。

  1. SuperHero デモアプリケーション
  2. SuperHeroアプリとspqr実装の間の糊 (glue) を作成するつなぐCDI拡張ベースのrunner。このglueが必要なのは、実際のMicroProfile GraphQL実装が現在開発中ゆえである。IBM、Red Hat、そしてTomitribeが現在開発に取り組んでいる。ServletもまたHTTPトランスポートを確保するためにrunner内で定義されている。
  3. テスト実行のための、基本的なGraphQLクライアント

Payara 5.192を使うJava EE Webアプリケーションとして開発されており、任意のJava EE 8プラットフォームで実行できます。

Building and running the project

Preambles

まず、JDK 8(もしくはそれ以降のJDK)とMaven 3.5がインストールされている必要があります。より細かく言えば、このプロジェクトは以下のコンポーネントを使って開発されました。

  1. Maven 3.6.1,
  2. OpenJDK 11.0.3 with OpenJ9.

Building the project

以下の手順を踏む必要があります。

  1. このプロジェクトを複製する
  2. spqrのmicroprofile-protoブランチをGitHubから複製する
    Java 8+ API for rapid development of GraphQL services
    https://github.com/leangen/graphql-spqr/tree/microprofile-proto
  3. ローカルでビルドしインストール(Maven Centralは利用できない)
  4. Payara 5.192をダウンロード
    https://www.payara.fish/software/downloads/
  5. Payaraを起動するため、 asadmin start-domain domain1 を実行(テスト目的で必要)
  6. Mavenを使ってプロジェクトをビルド
  7. WARファイルができたら、お気に入りのIDEを使って自由にソースコードを変更したり、アプリケーションサーバーを変更したり…

コードの変更時には、少なくとも1個の@GraphQLApiクラスがアプリケーションを起動するものと想定されていることにご注意ください。

Running

SuperHeroアプリケーションを含むWARファイルはJava/Jakarta EE 8に完全準拠しており、任意のアプリケーションサーバーにデプロイできます。現時点でテスト済みの環境は以下の通りです。

  1. GlassFish 5.1
  2. OpenLiberty 19.0.5
  3. TomEE plus 8.0.0-M2
  4. Wildfly 16.0.0.Final

Playing around with GraphQL

アプリを開始して、Indexページに移動してください。この中に2個の選択肢があります。

  1. GraphQL スキーマのイントロスペクト
    これはGraphQLの重要なコンセプトで、サーバーとクライアント間の契約(Contract)として機能します。ところで、GraphQLはネイティブのイントロスペクションを提供します。
  2. GraphQLを使う
    SuperHeroアプリケーションと対話するためにGraphQLを使います。GraphiQLは対話的なJavaScriptベースのツールで、Webブラウザからクエリやmutationの送信を実現します。
    An in-browser IDE for exploring GraphQL.
    https://github.com/graphql/graphiql

GraphQL の構文に不慣れな場合、graphql-config.propertiesファイルに定義済みのテストで使うクエリをCopy & Pasteしてもかまいません。

全てのヒーローを取り出すには

query allHeroes {
  allHeroes {
    name
    primaryLocation
    superPowers
    realName
  }
}

Avengers チームに属するヒーローを取り出すには

query allAvengers {
  allHeroesInTeam(team: "Avengers") {
    name
    primaryLocation
    superPowers
  }
}

指定されたスーパーパワーを持つAvengersチームの新しいヒーローを作成するには

mutation createNewHero {
  createNewHero(
    hero: {
           name: "Captain America", 
           realName: "Steven Rogers", 
           superPowers: ["Super strength", "Vibranium Shield"], 
           primaryLocation: "New York, NY", 
           teamAffiliations: [{name: "Avengers"}]
           }
         ) 
  {
  name
  primaryLocation
  superPowers
  realName
  }
}

是非、GitHub mpql-previewプロジェクトを是非ご覧ください。MicroProfile GraphQLで遊んでいただき、MicroProfile GraphQLにご期待ください。

A preview of the future MicroProfile GraphQL specification
https://github.com/jefrajames/mpql-preview

Command line interface for MicroProfile Starter is now available

このエントリは以下のエントリをベースにしています。
This entry is based on the following one written by Michal Karm Babacek (Red Hat).
https://microprofile.io/2019/07/08/command-line-interface-for-microprofile-starter-is-available-now/

2019年2月から利用可能のMicroProfile Starterサービスですが、REST APIとCLIからも利用できるようになりました。

Eclipse MicroProfile Starter (Beta) Available
https://microprofile.io/2019/02/06/eclipse-microprofile-starter-beta-available/
https://logico-jp.io/2019/02/10/eclipse-microprofile-starter-beta-available/

これはMicroProfile Starterの開始以来、Starterにコマンドラインでアクセスできるように、MicroProfile開発者から要求されてきた機能です。このAPIは、今後予定されているVisual Studio Codeの拡張や、Eclipse Che、IntelliJ IDEA、Netbeansの拡張でも使用される予定です。

Why do you need this API?

  • CLI : 開発者がcURLやPowerShellを使ってアプリケーションを生成できます。Webブラウザを開く必要はありません。
  • Tools integration : MicroProfileアプリケーション生成機能を統合開発環境やツールに統合するためのサービスを他社に提供します。

How to use the MicroProfile Starter CLI

一番簡単なプロジェクト生成方法は、サーバを選択し、すべての仕様がデフォルトで有効になっている最新のMicroProfileバージョンをサービスに選択することです。

$ curl -O -J 'https://start.microprofile.io/api/project?supportedServer=THORNTAIL_V2'
curl: Saved to filename 'demo.zip'

Shell session recording

cURLの例をテキストとして記録しました。動画から直接コピー&ペーストできます。利用可能な選択肢の並び方やサーバや仕様の選択方法がわかる動画になっています。

$ curl -O -J 'https://start.microprofile.io/api/project?supportedServer=PAYARA_MICRO&selectedSpecs=JWT_AUTH&selectedSpecs=METRICS'

asciicast

Windows PowerShell session

以下の動画では、PowerShellを使ってMicroProfileプロジェクトを生成する方法を紹介しています。

Invoke-WebRequest -OutFile project.zip -Uri https://start.microprofile.io/api/project?supportedServer=TOMEE
Expand-Archive ./project.zip

Noteworthy resources for selecting other servers and specifications are:

$ curl https://start.microprofile.io/api/mpVersion

$ curl https://start.microprofile.io/api/mpVersion/MP22

Documentation

最新のドキュメントやサンプルはプロジェクトリポジトリのREST-README.mdにあります。以下のように、コマンドラインからアクセスすることもできます。

$ curl https://start.microprofile.io/api/

Project generator REST API
https://github.com/eclipse/microprofile-starter/blob/master/src/main/resources/REST-README.md

さらに、正式な仕様がSwaggerHubでご覧頂けます。APIバージョンが指定されていない場合、最新のバージョンをデフォルトで選択します。例えば、start.microprofile.io/api/ は start.microprofile.io/api/1/ に相当します。WindowsユーザーにはcURL for WindowsやPowerShellを含め、多数の選択肢があります。

MicroProfile Starter – Project generator API
https://app.swaggerhub.com/apis-docs/microprofile/starter/1

Advanced usage

このAPIを使うと、JSONファイルをPOSTできます。cURLコマンドにクエリパラメータを渡す必要はありません。また、コード内でEtagレスポンスヘッダとIf-Node-Matchリクエストヘッダを使うことができます。これにより、同じZipファイルや同じJSONレスポンスの解析を何度も実行することがなくなります。

RFC7232 Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests
Etag
https://tools.ietf.org/html/rfc7232#section-2.3
If-None-Match
https://tools.ietf.org/html/rfc7232#section-3.2

EtagとIf-Node-Matchの利用方法ならびにJSONのPOSTの例はドキュメントに記載があります。

EtagとIf-Node-Matchの例
https://github.com/eclipse/microprofile-starter/blob/master/src/main/resources/REST-README.md#examples
Use JSON for get the project
https://github.com/eclipse/microprofile-starter/blob/master/src/main/resources/REST-README.md#use-json-for-get-the-project

大事なことを言い忘れていましたが、このAPIはツールやIDEと統合しやすいリソースを提供します。これらのリソースは、大きなJSONとして1つのHTTPレスポンスとして、有効なオプションのマトリックス全体を返します。

Integration with IDEs
https://github.com/eclipse/microprofile-starter/blob/master/src/main/resources/REST-README.md#integration-with-ides

Call to action

まもなく登場するMicroProfile Starter用VSCode extensionにご注目ください。さらに、MicroProfileコミュニティーでは、Eclipse Che、IntelliJ IDEA、Netbeansなど、他のIDE用のextensionの設計と実装のためのボランティアも募集しています。IntelliJのextensionをやってみたいという方はissue #170、Eclipse Cheのextensionをやってみたいという方はissue #171、Netbeansのextensionをやってみたいという方はissue #174にそれぞれコメントしてください。

Create Intellij extension for MP Starter #170
https://github.com/eclipse/microprofile-starter/issues/170
Create MP extension for Eclipse Che #171
https://github.com/eclipse/microprofile-starter/issues/171
Create MP extension for NetBean IDE #174
https://github.com/eclipse/microprofile-starter/issues/174

Microprofile CustomConfigSource with Database

このエントリは以下のエントリをベースにしています。
This entry is based on the following one written by Ralph Soika (Project lead of Imixs-Workflow).
https://microprofile.io/2019/06/18/microprofile-customconfigsource-with-ejbs/
https://ralph.blog.imixs.com/2019/06/11/microprofile-customconfigsource-with-database/

MicroProfile Config APIでは、アプリケーションの構成プロパティを簡単かつ新しい方法で扱うことができます。

Configuration for MicroProfile
https://microprofile.io/project/eclipse/microprofile-config

このAPIを使うと、以下のような異なるソースの構成やプロパティの値にアクセスできます。

  • System.getProperties() (ordinal=400)
  • System.getenv() (ordinal=300)
  • すべての META-INF/microprofile-config.properties ファイル

MicroProfile Config APIの手始めには以下をどうぞ。

Eclipse MicroProfile Config – what is it?
https://www.eclipse.org/community/eclipse_newsletter/2017/september/article3.php

もちろん、ご自身のConfigSourceも実装できますが、大多数は以下の例のように既存ファイルからのカスタム構成値の読み取りをベースにしています。

Microprofile Config: Creating a Custom ConfigSource
https://rhuanrocha.net/2018/12/21/microprofile-config-creating-a-custom-configsource/

このエントリではデータベースから読み取った値に基づいたMicroProfile ConfigSourceの実装方法をご紹介します。

How To Access a Database?

以下の例は、JPAデータソースもしくはEJBサービスから値を読み取るカスタムのConfigSourceを実装方法を示したものです。一見すると、アプリケーションが提供するカスタム構成ファイルへアクセスするための外部ソースやサービスを注入するのは簡単そうに見えます。

public class MyConfigSource implements ConfigSource {

    @PersistenceContext(unitName = ".....")
    private EntityManager manager;

    @Override
    public String getValue(String key) {
       .....
    }
    @Override
    public Map<String, String&gt; getProperties() {
       // read data form JPA Entity manager
       ....
    }
}

しかしながら、この直接的なやり方には問題があります。JPA Entity Managerや単なる別のEJBをCustomConfigSourceに注入しようとすると、このEntity ManagerがNullのため、値が想定通りに利用できないことに気づくでしょう。

この理由は、MicroProfile ConfigではすべてのConfigSourcesをPOJOとして取り扱うためです。そのため、注入された値は利用できません。例えば別のCDI beanが起動時に構成値が注入されることを想定していると考えてください。カスタムのConfigSource自体がCDIに依存していると、起動ループの問題が発生する可能性があります。その場合、どうすればよいでしょうか。

解決策は、Java Enterpriseではよくあることですが、非常にシンプルです。EntityManagerが注入済みであることを確実にするため、カスタムConfigSourceに@Startupを付け、@PostConstructをつけたメソッドを実装すればよいのです。

@Startup
@Singleton
public class MyConfigSource implements ConfigSource {
    @PersistenceContext(unitName = ".....")
    private EntityManager manager;

    @PostConstruct
    void init() {
        // load your data from teh JPA source or EJB
        ....
    }
   ...
}

こうすれば、init()メソッドで、自身で用意したEntity Manager(もしくは注入されたものすべて)にアクセスできます。MicroProfile Config APIは構成ソースをPOJOと引き続き見なしているため、作成したクラスを2度生成します(1回目はConfig APIから、2回目は@PostConstructのCDI実装からそれぞれコンストラクタが呼び出される)。では、両インスタンスに値を設定するにはどうすればよいのでしょうか。

こちらも解決策は極めてシンプルです。ConfigSourceはPOJOなので、静的メンバー値を使ってあたいを格納できます。この方法で、カスタムConfigSourceの各インスタンスで同一の値を確認できるのです。@PostConstructをつけると、ある種の遅延ロードで構成の値を設定します。以下の例をご覧ください。

@Startup
@Singleton
public class MyConfigSource implements ConfigSource {

    public static final String NAME = "MyConfigSource";
    public static Map<String, String&gt; properties = null; // note to use static here!

    @PersistenceContext(unitName = ".....")
    private EntityManager manager;

    @PostConstruct
    void init() {
        // load your data from teh JPA source or EJB
        ....
        // override the static property map..
        properties.put(....)
    }

    @Override
    public int getOrdinal() {
        return 890;
    }

    @Override
    public String getValue(String key) {
        if (properties != null) {
            return properties.get(key);
        } else {
            return null;
        }
    }

    @Override
    public String getName() {
        return NAME;
    }

    @Override
    public Map<String, String&gt; getProperties() {
        return properties;
    }
}

静的メンバー値であるpropertiesを使い、すでに生成済みのConfigSourceからの値をオーバーロードします。これにより、ConfigSourceの任意のインスタンスは同じ値を共有します。値は後でロードされるため、ConfigSourceで起動時に値は設定されません。これはつまり別のCDI beanがあれば、@PostConstructの愛大これらの値にアクセスできない、ということです。しかしながら、値は実行時には利用できるようになっています。

遅延ロードメカニズムの不利な点があるため、この解決策は実装が極めてシンプルかつ簡単です。もちろんJNDI Lookupを使って、遅延ロードのトリックを使わずにデータソースからデータを取得することもできます。ここで紹介した解決策を使うと、データソースだけでなく、任意のCDIにアクセスできます。オープンソースプロジェクトlmixs-Workflowの最新版はMicroProfile 2.2ベースですが、この中でこの解決策を使っています。

Imixs Workflow – Open Source Workflow Engine for Human-Centric BPM
https://www.imixs.org/

Project Helidon and OpenAPI

このエントリは以下のエントリをベースにしています。
This entry is based on the following written by Tim Quinn (Oracle).
https://medium.com/oracledevs/project-helidon-and-openapi-54a1fadc75b1

Helidon 1.1.1以後、SE/MPともOpenAPIをサポートしており、MPではMicroProfile OpenAPI仕様をサポートしています。

Helidon
https://helidon.io/
OpenAPI Specification
https://github.com/OAI/OpenAPI-Specification
MicroProfile
https://microprofile.io/
MicroProfile OpenAPI Specification
https://github.com/eclipse/microprofile-open-api

SE、MPの両方に対し、OpenAPI機能の利用方法を説明したドキュメントとサンプルコードを用意しています。

OpenAPI support in Helidon SE
https://helidon.io/docs/latest/index.html#/openapi/01_openapi
Helidon SE OpenAPI Example
https://github.com/oracle/helidon/tree/master/examples/openapi
OpenAPI support in Helidon MP
https://helidon.io/docs/latest/index.html#/microprofile/08_openapi
Helidon MP Basic OpenAPI Example
https://github.com/oracle/helidon/tree/master/examples/microprofile/openapi-basic

このエントリではOpenAPIのサポートをHelidonで作成したアプリケーションに追加する最もシンプルな方法をご紹介します。

変更点はMP、SEいずれを使っているかで変わりますので、それぞれ分けて説明します。アプリケーションのOpenAPIドキュメントにアクセスする方法は同じなので、それはひとまとめにして最後に記載します。

Helidon MPの場合

Update your pom.xml

OpenAPI関連のアノテーションのスキャン高速化のため、Jandexインデックスを作成します。セクションに以下を追加します。

<plugin>
    <groupId>org.jboss.jandex</groupId>
    <artifactId>jandex-maven-plugin</artifactId>
    <version>1.0.6</version>
    <executions>
      <execution>
          <id>make-index</id>
          <goals>
              <goal>jandex</goal>
          </goals>
      </execution>
    </executions>
</plugin>

依存関係を追加すると、OpenAPIアノテーションを利用できます。アプリケーションの実行時にHelidon OpenAPIランタイム(およびMicroProfile 2.2に対するHelidonのその他のサポート)が存在するようにします。

<dependency>
    <groupId>org.eclipse.microprofile.openapi</groupId>
    <artifactId>microprofile-openapi-api</artifactId>
    <version>1.1.2</version>
</dependency
<dependency>
    <groupId>io.helidon.microprofile.bundles</groupId>
    <artifactId>helidon-microprofile-2.2</artifactId>
    <version>1.1.2</version>
</dependency>

Annotate the endpoints

OpenAPIのアノテーションをアプリケーションのエンドポイントに追加します。以下の例はシンプルなGETエンドポイントにOpenAPIアノテーションを付加しています。

@GET
@Operation(
    summary = "Returns a generic greeting",
    description = "Greets the user generically")
@APIResponse(
    description = "Simple JSON containing the greeting",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = GreetingMessage.class)))
@Produces(MediaType.APPLICATION_JSON)
public JsonObject getDefaultMessage() {...}

@Operation@APIResponse は新規のアノテーションです。

Helidon SEの場合

SEにおけるOpenAPIのサポートは、基本的にMPと同じですが、SEはアノテーションの処理を含んでいません。そのため、OpenAPIはエンドポイントの情報を収集するためにアノテーションに依存できません。

その代わりに、SEで作成したアプリケーションにはアプリケーションのエンドポイントを記載したOpenAPIドキュメントの静的ファイルを含めることになるでしょう。

Update your pom.xml

依存関係を追加します。

<dependency>
     <groupId>io.helidon.openapi</groupId>
     <artifactId>helidon-openapi</artifactId>
     <version>1.1.2</version>
</dependency>

Register OpenAPISupport in your code

SEで作成したアプリケーションにはすでに以下のようなコードが含まれているはずです。OpenAPISupportを登録するために1行追加します。

Config config = Config.create();
...
return Routing.builder()
         .register(JsonSupport.create())
         .register(OpenAPISupport.create(config))
         .register(health)
         .register(metrics)
         .register("/greet", greetService)
         .build();

Add a static OpenAPI document file

Swaggerのようなツールを使って、アプリケーションのAPIを記述し、OpenAPIドキュメントファイルを生成しましょう。もしくは手作業でファイルを作成、編集することも可能です。ファイルができたら、プロジェクトのMETA-INF/openapi.ymlとして追加すれば、HelidonのOpenAPIサポート機能が自動検知してくれます(訳注:META-INF/openapi.yml以外には、META-INF/openapi.yamlもしくはMETA-INF/openapi.jsonとして追加できます)。

Access ths OpenAPI document

変更してアプリケーションをビルド後、実行してみましょう。自動的にサポートされる/openapiエンドポイントに対してGETリクエストを投げてください。上記のソースコードでエンドポイントにアノテーションで付加した情報を含む多数の情報を確認できます(訳注:OpenAPI 3ベースでした)。

paths:
  /greet:
    get:
      summary: Returns a generic greeting
      description: Greets the user generically
      responses:
        default:
          description: Simple JSON containing the greeting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GreetingMessage'

What next?

これはほんの初歩的なものにすぎないので、例えばMPとSEのアプリケーションに、エンドポイントのOpenAPIモデルにプログラムで追加したり変更したり(つまりモデルのReaderとFilter)するコードを含めてみてもよいでしょう。

実のところ、HelidonのOpenAPIサポートでは、これらのソースすべてからのエンドポイント情報を組み合わせます。

  • 静的ファイル
  • アノテーション(MPのみ)
  • configurationの設定
  • model reader
  • model filter