Nexmo Javaクライアント・ライブラリのバージョン4が登場

本日、バージョン4.0.0をリリースしました。 Javaクライアント・ライブラリ.3.xバージョンのライブラリはとても気に入っていたのですが、理想的なユーザーエクスペリエンスを提供するには、いくつかの問題があることに気づきました。

新しいメジャーバージョンは、いくつかの後方互換性の破壊を意味するが、ピカピカの新機能のホストを意味する。私は移行のヒントを提供し、私たちがこの方向を選んだ理由について話したいと思う。

変更点の全リストは、変更履歴をご覧ください。 リリースページ

Java 7 サポート

難しい決断でしたが、Java 7の公式サポートを終了する時が来たと判断しました。次のバージョンのJavaをターゲットにすることを決めるのも大変でしたが、ターゲット・バージョンをJava 8に更新しました。

オラクル・サポート終了

オラクルは2015年4月にJava 7の公開アップデートを終了した。2020年7月までの延長サポートはまだ提供されているが、かなり以前からユーザーにアップデートを促していた。

Wiki Java Version

他のJDKがまだJava 7向けにアップデートされていないのは事実ですが、それが開発を進める上での制限要因のひとつだと考えています。

最近 レガシーTLSプロトコルのサポート終了.さらに メイブン・セントラルは2018年5月にサポートを終了した。これは継続的インテグレーションプロセスを複雑にし、Java 7をサポートするライブラリの保守を余計に難しくしている。

前進するJavaバージョン

私たちはこの決断を軽んじることはなかった。 6ヶ月リリース今後のリリースがこのように大幅に変更されることはないだろう。オラクルのドナルド・スミスはこう語る：

Java 9->10->11の流れは、7->8->9の流れよりも、8->8u20->8u40の流れに近い。約3年ごとのメジャーリリースに慣れていて、その大きな変更がもたらす大きな影響についてのメンタルモデルを持っている場合、最初にそれを見るのは恐ろしいことだ。6カ月という周期はそうではない。

我々は可能な限り包括的でありたいと考えており、今後ターゲットとするJavaの最適なバージョンを決定するのに役立ついくつかの機能をクライアントに追加した。

クライアントのインスタンス化

オブジェクトのインスタンス化 NexmoClientオブジェクトをインスタンス化する際に どのようにを考える必要はなくなった。その代わりに Builderが提供され、 さまざまな設定オプションを使ってクライアントを構築できるようになっています。

古い

以下は NexmoClientを SMS API と Voice API の両方で使用するためにインスタンス化する方法を示します：

AuthMethod tokenAuth = new TokenAuthMethod(NEXMO_API_KEY, NEXMO_API_SECRET);
AuthMethod applicationAuth = new JWTAuthMethod(NEXMO_APPLICATION_ID,
        FileSystems.getDefault().getPath(NEXMO_APPLICATION_PRIVATE_KEY_PATH)
);

NexmoClient client = new NexmoClient(tokenAuth, applicationAuth);

このプロセスでは どのようにを理解する必要がありました。また TokenAuthMethodと JWTAuthMethodのような名前を使うのは直感的でないと思った。

新しい

新しいバージョンでは、次のようにインスタンス化できます。 NexmoClientを SMS API と Voice API の両方で使用する方法です：

NexmoClient client = new NexmoClient.Builder()
        .apiKey(NEXMO_API_KEY)
        .apiSecret(NEXMO_API_SECRET)
        .applicationId(NEXMO_APPLICATION_ID)
        .privateKeyPath(NEXMO_PRIVATE_KEY_PATH)
        .build();

また、秘密鍵ファイルを他のソースから読み込む場合は、その内容を提供することもできる：

NexmoClient client = new NexmoClient.Builder()
        .apiKey(NEXMO_API_KEY)
        .apiSecret(NEXMO_API_SECRET)
        .applicationId(NEXMO_APPLICATION_ID)
        .privateKeyContents(NEXMO_PRIVATE_KEY_CONTENTS)
        .build();

ユーザーとしては、自分が持っているクレデンシャルだけを気にすればよい。APIキーとシークレットにどの AuthMethodをAPIキーとシークレットで使うか、などということを気にする必要はない。 Builderに持っているすべてのクレデンシャルを渡せばよい。

この方法で提供するにはいくつかの注意点がある。APIキーを提供する場合、シークレットかシグネチャ・シークレットも提供しなければならない。これを怠ると buildメソッドが NexmoClientCreationException.

Nexmoコール・コントロール・オブジェクト

Nexmo Nexmo Call Control Object (NCCO)シリアライザは、今回の更新で大幅に見直されました。元々、私たちはシリアライザを以下のような名前でNCCOクラスと呼んでいました。 TalkNcco, InputNcco, ConnectNcco.しかし、これは実際の命名規則と一致しません。

私たちの NCCOガイド曰く

Nexmo Call Control Object (NCCO)は、Voice API Callのフローを制御するために使用されるアクションのJSON配列です。

そこで、次のような名前のアクションクラスに名前を変更しました。 TalkAction, InputActionそして ConnectAction.という特別なコレクション・ラッパーを用意した。 Nccoという特別なコレクション・ラッパーを提供し、それらすべてを結びつけてJSON構造の構築を処理するようにした。

古い

ユーザーにメッセージを記録させるためにNCCOを作成する方法を説明します：

Route answerRoute = (req, res) -> {
    String recordingUrl = String.format("%s://%s/webhooks/recordings", req.scheme(), req.host());

    TalkNcco intro = new TalkNcco("Please leave a message after the tone, then press #.");

    RecordNcco record = new RecordNcco();
    record.setEventUrl(recordingUrl);
    record.setEndOnSilence(3);
    record.setEndOnKey('#');
    record.setBeepStart(true);

    TalkNcco outro = new TalkNcco("Thank you for your message. Goodbye");

    Ncco[] nccos = new Ncco[]{intro, record, outro};

    res.type("application/json");

    return new ObjectMapper().writer().writeValueAsString(nccos);
};

新しい

今ならこんなことができる：

Route answerRoute = (req, res) -> {
    String recordingUrl = String.format("%s://%s/webhooks/recordings", req.scheme(), req.host());

    TalkAction intro = new TalkAction.Builder("Please leave a message after the tone, then press #.").build();

    RecordAction record = new RecordAction.Builder()
            .eventUrl(recordingUrl)
            .endOnSilence(3)
            .endOnKey('#')
            .beepStart(true)
            .build();

    TalkAction outro = new TalkAction.Builder("Thank you for your message. Goodbye").build();

    res.type("application/json");

    return new Ncco(intro, record, outro).toJson();
};

あるいは、追加のローカル変数を作成することなく、オブジェクトを構築し、それを Nccoでラップすることもできる：

return new Ncco(
        new TalkAction.Builder("Please leave a message after the tone, then press #.").build(),
        new RecordAction.Builder()
                .eventUrl(recordingUrl)
                .endOnSilence(3)
                .endOnKey('#')
                .beepStart(true)
                .build(),
        new TalkAction.Builder("Thank you for your message. Goodbye").build()
).toJson();

この変更の目的は、多くのプロパティを持つオブジェクトをより直感的に作成できるようにすることでした。

のように TalkActionのような textプロパティしかないようないくつかの項目については、コードが増えるように思える。しかし、アクションが少し複雑になれば、その利点は十分に発揮される。

おそらくファクトリーメソッドを使って簡単なショートカットを提供できるだろう。

インサイトのリクエスト数

私たちの InsightClientには、さまざまなパラメーターの組み合わせで、かなりの数のメソッドがあった。ナンバーインサイトのオプションが増えれば増えるほど、パラメータリストも増える一方だ。

これらのアップデートの多くには共通の傾向があり、今回もビルダーのパターンを採用した。

古い

発信者番号通知(CNAM)情報を使って標準的な番号インサイトリクエストを実行するには、次のようにする：

StandardInsightResponse response = client.getInsightClient()
        .getStandardNumberInsight(INSIGHT_NUMBER, null, true);

第2パラメータに nullパラメータにアクセスするためには、2番目のパラメータに cnamパラメータにアクセスするためにはこれは間違っている。

新しい

今ならこれができる：

StandardInsightRequest request = new StandardInsightRequest.Builder(INSIGHT_NUMBER)
        .cnam(true)
        .build();

StandardInsightResponse response = client.getInsightClient()
        .getStandardNumberInsight(request);

既存のメソッドを廃止したわけではありませんが、次のメジャーバージョンではリクエストビルダーを削除して使用するため、非推奨とすることにしました。

ビルダーパターンがコードの冗長性を高める可能性があることをお話しました。そこで、リクエストオブジェクトの数を洞察するために、一般的なユースケースのための静的ファクトリメソッドもいくつか用意しました。

このようにリクエスト・オブジェクトを作ることができる：

AdvancedInsightRequest request = new AdvancedInsightRequest.Builder(INSIGHT_NUMBER).build();

このように、提供された静的ファクトリーメソッドを使うこともできる：

AdvancedInsightRequest request = AdvancedInsightRequest.withNumber(INSIGHT_NUMBER);

これらのファクトリーメソッドを、特に新しいアクションクラスのために、もう少し弄ってみたい。

スコープの制限

3.xバージョンでの標準的なワークフローは、APIにアクセスできる他のクライアントにアクセスするために NexmoClientを経由して、APIにアクセスする他のクライアントにアクセスすることだった。これは今でも変わりません。しかし、ほとんどの Endpointと Methodクラスはパブリックと宣言された。このため、アップデートを提供するのが難しくなっている。メジャー・バージョンのアップデートが必要なので、私たちが作成したパブリック・インターフェースを壊したくないからだ。

注意点として、他のクライアントのインスタンスを取得し、APIにアクセスするには、常に NexmoClientを使って他のクライアントのインスタンスを取得し、APIにアクセスすること：

NexmoClient client = new NexmoClient.Builder()
        .apiKey(NEXMO_API_KEY)
        .apiSecret(NEXMO_API_SECRET)
        .build();

SmsClient smsClient = client.getSmsClient();

TextMessage message = new TextMessage("Acme Inc", TO_NUMBER, "Hello World!");

SmsSubmissionResponse response = smsClient.submitMessage(message);

をインスタンス化する必要はないはずだ。 Endpointまたは Methodクラスをインスタンス化する必要はないはずだ。

ほとんどの内部クラスのスコープをパッケージのデフォルト・スコープに更新しました。これは本当の意味でのカプセル化を提供するものではありませんが、これらのクラスを直接使用しないようにし、より良いアップデートができるようにするためです。これにより、いくつかのパッケージの変更も必要になりました。いくつかのパッケージが削除されたり、名前が変更されたことに気づくかもしれません。

結論

まず第一に、いろいろと壊してしまって申し訳ない！しかし、これらの変更により、今後より良いアップデートを提供できるようになることを願っています。

移行プロセスで何か問題が発生した場合、またはバージョン4のライブラリで何かおかしな点にお気づきの場合は、ご遠慮なく以下までご連絡ください。 問題を提出するまでご連絡ください！

更新されたビルディング・ブロックのチェックもお忘れなく。 Nexmoデベロッパー.