SOAP with Helidon

原文はこちら。
The original article was written by Lukas Jungmann (Consulting Member Of Technical Staff, Oracle).
https://medium.com/helidon/soap-with-helidon-51bb2dc3189e

SOAPベースのWebサービスの開発や、そういったWebサービスをマイクロサービスとしてデプロイするのは困難な作業になる場合があります。この記事では、簡単なSOAPベースのWebサービスをEclipse Metroを使って開発し、そのWebサービスをHelidon WebServer上で動作させる方法をご紹介します。これにより、フル機能を備えたJava EEアプリケーションサーバーをDockerに移行する必要はありません。

Set up a project

このチュートリアルでは、Helidon SEのQuick Start archetypeを使います。

mvn -U archetype:generate -DinteractiveMode=false \
 -DarchetypeGroupId=io.helidon.archetypes \
 -DarchetypeArtifactId=helidon-quickstart-se \
 -DarchetypeVersion=2.3.2 \
 -DgroupId=org.glassfish.metro \
 -DartifactId=helidon-sample \
 -Dpackage=org.glassfish.metro.helidon.sample

Add Dependencies

続いて、Eclipse Metroへの依存関係をこのプロジェクトに追加しましょう。Eclipse Metroは主としてJava EE/Jakarta EEランタイム環境を対象にしており、HelidonはJava/Jakarta EEランタイム環境は提供していませんが、Eclipse MetroをHelidonと統合するためのコネクターが必要であるためです。このコネクターを利用するためには、最初の依存関係として org.glassfish.netro:helidon-se を先ほど作成したプロジェクトのpomファイルに追加してください。

<dependency>
    <groupId>org.glassfish.metro</groupId>
    <artifactId>helidon-se</artifactId>
    <version>1.0.1</version>
</dependency>

これにより、他の必要な依存関係もすべて組み込まれるので、それらを明示的に定義する必要はありません。

Create a SOAP-based Web Service

“Hello World” のサンプルを使い、呼び出し元に挨拶する、典型的なSOAPベースのWebサービスを作成してみましょう。

package org.glassfish.metro.helidon.sample;
import javax.jws.WebService;
@WebService
public class GreetSOAP {
    public String hello(String who) {
        return "Hello " + who;
    }
}

これはこれまで見た他のSOAPベースのWebサービスと違いはありません。古いJava EEスタイルと同じ一連のアノテーションを利用できます。Tomcat向けのWebサービス開発になれている方であれば、作成が必要な、以下のコンテンツを含む  sun-jaxws.xml というリソースファイルのことをご存知でしょう。

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime' version='2.0'>
  <endpoint
      name="SoapWs"
      implementation="org.glassfish.metro.helidon.sample.GreetSOAP"
      url-pattern="/SoapWsService">
  </endpoint>
</endpoints>

このdescriptorファイルの詳細はMetroのドキュメントをご覧ください。

14.2. The sun-jaxws.xml File
https://eclipse-ee4j.github.io/metro-jax-ws/3.0.0/docs/release-documentation.html#the-sun-jaxws-xml-file

Mainクラスに作成しているcreateRoutingメソッドを更新して、これでHelidon WebServerのリクエストに対して応答するWebサービスができました。

...
import org.eclipse.metro.helidon.MetroSupport;

private static Routing createRouting(Config config) {
    MetroSupport ms = MetroSupport.builder()
                .dumpService(true) //print SOAP messages to the log
                .build();
    ...
    return Routing.builder()
        ...
        .register(ms)
        .build();
}

プロジェクトをビルド、実行してみましょう。

> mvn package
> java -jar target/helidon-sample.jar

サービスが立ち上がって実行中であることを確認するために、 http://localhost:8080/SoapWsService?WSDL へアクセスしてWSDLファイルを確認しましょう。

Consuming the SOAP service

サービスをテストする上で最善の方法はサービスを利用することです(当たり前ですが)。それでは別のプロジェクトを作成し、サービスを使うようにしてみましょう。

mvn -U archetype:generate -DinteractiveMode=false \
    -DarchetypeGroupId=io.helidon.archetypes \
    -DarchetypeArtifactId=helidon-quickstart-se \
    -DarchetypeVersion=2.3.2 \
    -DgroupId=org.glassfish.metro \
    -DartifactId=helidon-sample.client \
    -Dpackage=org.glassfish.metro.helidon.sample.client

まず最初にやるべきことは、Helidon SE WebServerがリスニングしているデフォルトポートをapplication.yamlで変更することです。今回は8081にしましょう。

続いて、Helidon統合レイヤーという、Metroへの依存関係を追加する必要があります。サービスを使ってプロジェクトを作成したときにやったことと同じです。

<dependency>
    <groupId>org.glassfish.metro</groupId>
    <artifactId>helidon-se</artifactId>
    <version>1.0.1</version>
</dependency>

WSDLファイルからJAX-WSポータブル・アーティファクトを生成できるwsimportを呼び出すようにpom.xmlに追加します。

<plugin>
    <groupId>com.sun.xml.ws</groupId>
    <artifactId>jaxws-maven-plugin</artifactId>
    <version>2.3.5</version>
    <executions>
        <execution>
            <id>create-client</id>
            <goals>
                <goal>wsimport</goal>
            </goals>
            <configuration>
                <packageName>org.glassfish.metro.helidon.sample.client</packageName>
                <wsdlUrls>
                    <wsdlUrl>http://localhost:8080/SoapWsService?WSDL</wsdlUrl>
                </wsdlUrls>
            </configuration>
        </execution>
    </executions>
</plugin>

先ほど作成したサービスを呼び出すHelidonサービスを作成します。

package org.glassfish.metro.helidon.sample.client;

import io.helidon.faulttolerance.Async;
import io.helidon.webserver.Routing;
import io.helidon.webserver.ServerRequest;
import io.helidon.webserver.ServerResponse;
import io.helidon.webserver.Service;

public class GreetClient implements Service {

    private GreetSOAP port;
    
    @Override
    public void update(Routing.Rules rules) {
        rules.get("/client", this::soapCall);
    }
    
    private void soapCall(ServerRequest request, ServerResponse response) {
        //the call to web service is blocking,
        //therefore to avoid blocking the web server
        //we have to wrap the call into Async
        Async a = Async.create();
        a.invoke(() ->
                call(request.queryParams().first("who").orElse("You")))
                .thenApply(response::send);
    }
    
    private GreetSOAP getPort() {
        if (port == null) {
            port = new GreetSOAPService().getGreetSOAPPort();
        }
        return port;
    }

    private String call(String s) {
        return getPort().hello(s) + "!\n";
    }
}

MainクラスにあるcreateRouting メソッドにサービスを登録します。

private static Routing createRouting(Config config) {
    ...
    return Routing.builder()
            ...
            .register("/metro", new GreetClient())
            .build();
}

アプリケーションをビルドし実行しましょう。

> mvn package
> java -jar target/helidon-sample.client.jar

実際のテストができるようになりました。

> curl http://localhost:8081/metro/client?who=Joe
Hello Joe!

(訳注)SOAPベースのWebサービスのコンソールでは、以下のようなトレースが確認できます。

Frequently Asked Questions

QuestionsAnswers
いい例だけど、Helidon MPに関心があるもので…。
これはMPでも動くのか?
pom.xmlで org.glassfish.metro:helidon-seではなく、 org.glassfish.metro:helidon-mpを使えばMPでも使える。createReoutingメソッドは変更しなくてよい。
APIはJava EE (javaxパッケージ)じゃなくてJakarta EE (jakartaパッケージ) 版を使いたいのだが、大丈夫か?helidon-se/helidon-mpのアーティファクトには2種類のバージョンがある。
1.x.y : 古いMetro 2.x (javaxパッケージ名前空間を持つJava EE由来) をサポート
2.x.y : 新しいMetro 3.x (jakartaパッケージ名前空間を持つ Jakarta EE由来) をサポート
他のサンプルはどこにあるか?ソースコードは他のサンプルと併せてGitHubから利用可能。同様のJava EEバージョンのサンプルは同じリポジトリのEE8ブランチにある。
Eclipse Metro greets Helidon
https://github.com/eclipse-ee4j/metro-jax-ws/tree/master/jaxws-ri/extras/helidon-integration
EE8ブランチ
https://github.com/eclipse-ee4j/metro-jax-ws/tree/EE8/jaxws-ri/extras/helidon-integration
Metroのドキュメントはどこにあるか?基本的な使い方はjax-wsユーザーガイドにある。
Eclipse Implementation of XML Web Services Release Documentation
https://eclipse-ee4j.github.io/metro-jax-ws/3.0.0/docs/

詳細機能はMetroユーザーガイドにある。
Metro user guide
https://eclipse-ee4j.github.io/metro-wsit/3.0.0/guide/

Mavenプラグインのドキュメントは以下にある。
JAX-WS Maven Plugin
https://eclipse-ee4j.github.io/metro-jax-ws/jaxws-maven-plugin/

MetroSupportと利用可能な構成オプションのドキュメントはGitHubにある。
https://github.com/eclipse-ee4j/metro-jax-ws/blob/master/jaxws-ri/extras/helidon-integration/README.md
バグ登録はRFE (Request for Enhancement) はどこからやればいいか?こちらからどうぞ。
metro-jax-ws issues
https://github.com/eclipse-ee4j/metro-jax-ws/issues

Conclusion

この記事では、簡単なSOAPベースのWebサービスをEclipse Metroで作成し、Helidon WebServerで動作させて、このサービスを呼び出す方法をご紹介しました。FAQの章では、このサンプルをHelidon MPで使用できるように拡張するする上でのガイドや、新しいJakarta EE APIを利用できるようにするために必要な変更をご紹介しました。

コメントを残す

以下に詳細を記入するか、アイコンをクリックしてログインしてください。

WordPress.com ロゴ

WordPress.com アカウントを使ってコメントしています。 ログアウト /  変更 )

Google フォト

Google アカウントを使ってコメントしています。 ログアウト /  変更 )

Twitter 画像

Twitter アカウントを使ってコメントしています。 ログアウト /  変更 )

Facebook の写真

Facebook アカウントを使ってコメントしています。 ログアウト /  変更 )

%s と連携中