このエントリは以下のエントリをベースにしています。
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!

このエントリは以下のエントリをベースにしています。
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'

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

このエントリは以下のエントリをベースにしています。
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/

このエントリは以下のエントリをベースにしています。
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