Version 4 der Nexmo Java Client Bibliothek ist da

Heute haben wir die Version 4.0.0 unserer Nexmo Java Klient Bibliothek. Während wir mit unseren 3.x-Versionen der Bibliothek sehr zufrieden waren, haben wir festgestellt, dass es ein paar Dinge gibt, die sie davon abhalten, die ideale Benutzererfahrung zu bieten.

Eine neue Hauptversion bedeutet ein paar Abwärtskompatibilitätsbrüche, aber auch eine ganze Reihe glänzender neuer Funktionen. Ich möchte Ihnen einige Migrationstipps geben und erläutern, warum wir uns für diesen Weg entschieden haben.

Eine vollständige Liste der Änderungen finden Sie in unserem Changelog auf der Release-Seite

Java 7-Unterstützung

Es war eine schwierige Entscheidung, aber wir haben beschlossen, dass es an der Zeit war, die offizielle Unterstützung für Java 7 einzustellen. Die Entscheidung über die nächste Java-Version, die wir unterstützen sollten, war ebenfalls eine Herausforderung, aber wir haben die Zielversion auf Java 8 aktualisiert.

Beendigung des Oracle-Supports

Oracle hat die öffentlichen Updates für Java 7 im April 2015 eingestellt. Das Unternehmen bietet zwar immer noch einen erweiterten Support bis Juli 2020 an, fordert die Nutzer aber schon seit geraumer Zeit zu einem Update auf.

Wiki Java Version

Es stimmt, dass andere JDKs immer noch für Java 7 aktualisiert werden, aber wir glauben, dass dies einer der limitierenden Faktoren ist, die uns erlauben, mit der Entwicklung voranzukommen.

Kürzlich haben wir Unterstützung für ältere TLS-Protokolle beendet. Zusätzlich, Maven Central die Unterstützung im Mai 2018 eingestellt. Dies erschwert den kontinuierlichen Integrationsprozess und macht die Pflege der Bibliothek mit Java 7-Unterstützung besonders schwierig.

Java-Versionen auf dem Vormarsch

Wir haben uns diese Entscheidung nicht leicht gemacht, und mit der Umstellung der neuen Versionen auf eine 6-monatigen Veröffentlichungsrhythmuswerden künftige Versionen wohl nicht mehr so drastisch ausfallen. Donald Smith von Oracle erklärt:

Der Wechsel von Java 9->10->11 ist eher ein Wechsel von 8->8u20->8u40 als von 7->8->9. Das ist zunächst erschreckend, wenn man daran gewöhnt ist, dass alle drei Jahre eine neue Version erscheint und man ein mentales Modell der enormen Auswirkungen dieser großen Änderungen hat. Das ist bei der sechsmonatigen Kadenz nicht der Fall.

Wir wollen so umfassend wie möglich sein und haben dem Client einige Funktionen hinzugefügt, die bei der Bestimmung der besten Java-Version helfen, die wir in Zukunft einsetzen wollen.

Client-Instantiierung

Die Instanziierung des NexmoClient Objekts müssen Sie nicht mehr darüber nachdenken wie zu authentifizieren. Stattdessen wird Ihnen jetzt ein Builder zur Verfügung, das Sie beim Aufbau des Clients unter Verwendung verschiedener Konfigurationsoptionen unterstützt.

Alte

So wird die NexmoClient für die Verwendung mit der SMS- und Voice API instanziiert werden:

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);

Für diesen Prozess mussten Sie verstehen wie das Authentifizierungsverfahren funktioniert. Wir waren auch der Meinung, dass die Verwendung von Namen wie TokenAuthMethod und JWTAuthMethod nicht intuitiv genug waren.

Neu

Mit der neuen Version können Sie Folgendes instanziieren NexmoClient für die Verwendung mit der SMS- und 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();

Sie können ihm auch den Inhalt Ihrer privaten Schlüsseldatei mitteilen, falls Sie diese aus einer anderen Quelle laden:

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

Als Benutzer sollten Sie sich nur um die Anmeldedaten kümmern müssen, die Sie haben. Sie sollten sich nicht darum kümmern müssen, welche AuthMethod Sie mit Ihrem API-Schlüssel und -Geheimnis verwenden sollen, geben Sie einfach dem Builder mit allen Anmeldeinformationen, die Sie haben.

Bei dieser Art der Bereitstellung gibt es einige Vorbehalte. Wenn Sie einen API-Schlüssel bereitstellen, müssen Sie auch entweder ein Geheimnis oder ein Signaturgeheimnis angeben. Wenn Sie dies nicht tun, wird die build Methode ein NexmoClientCreationException.

Das Nexmo Call Control Objekt

Das Nexmo Call Control Objekt (NCCO) Serialisierer haben in diesem Update eine große Überarbeitung erfahren. Ursprünglich nannten wir unsere Serialisierer NCCO-Klassen mit Namen wie TalkNcco, InputNcco, ConnectNcco. Dies entspricht jedoch nicht der tatsächlichen Namenskonvention.

Unser NCCO-Leitfaden sagt

Ein Nexmo Call Control Object (NCCO) ist ein JSON-Array von Aktionen, das zur Steuerung des Ablaufs eines Voice API Call verwendet wird.

Also haben wir sie in Aktionsklassen umbenannt, mit Namen wie TalkAction, InputAction, und ConnectAction. Außerdem haben wir einen speziellen Sammel-Wrapper namens Ncco um sie alle miteinander zu verbinden und die JSON-Struktur zu erstellen.

Alte

So könnten Sie ein NCCO erstellen, um einen Benutzer eine Nachricht aufzeichnen zu lassen:

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);
};

Neu

Jetzt können Sie so vorgehen:

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();
};

Oder Sie könnten die Objekte erstellen und sie in eine Ncco verpacken, ohne die zusätzlichen lokalen Variablen zu erstellen:

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();

Das Ziel dieser Änderung war es, die Erstellung von Objekten mit vielen Eigenschaften intuitiver zu gestalten.

Für einige Artikel, wie TalkAction mit nur einer text Eigenschaft, erscheint es wie mehr Code. Der Nutzen wird jedoch voll ausgeschöpft, wenn Ihre Aktionen etwas komplexer werden.

Wir wollen nach anderen Möglichkeiten suchen, wie wir dabei helfen können, vielleicht durch den Einsatz von Fabrikmethoden, um einige einfache Abkürzungen zu schaffen.

Anzahl Einsichtsanträge

Unser InsightClient hatte eine ganze Reihe von Methoden mit verschiedenen Parameterkombinationen. Da die Zahl der Optionen für die Zahleneinsicht wächst, wird die Parameterliste nur mit ihr wachsen.

Bei den meisten dieser Aktualisierungen gibt es einen gemeinsamen Trend, und wir haben uns wieder einmal für das Muster des Bauherrn entschieden.

Alte

Um eine Standardabfrage zur Nummerneinsicht mit Informationen zur Anrufer-ID (CNAM) durchzuführen, würden Sie etwa so vorgehen:

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

Beachten Sie, dass Sie null im zweiten Parameter verwenden müssen, um Zugriff auf den cnam Parameter zu erhalten. Das fühlt sich falsch an.

Neu

Das können Sie jetzt tun:

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

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

Wir haben die bestehende Methode nicht abgeschafft, aber wir haben beschlossen, sie zugunsten der Request Builder zu verwerfen, die in der nächsten Hauptversion entfernt werden.

Ich habe darüber gesprochen, wie das Builder-Muster die Ausführlichkeit des Codes erhöhen kann. Daher haben wir für die Anzahl der Anfrageobjekte auch einige statische Fabrikmethoden für häufige Anwendungsfälle aufgenommen.

Sie können zwar Anforderungsobjekte wie dieses erstellen:

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

Sie können auch eine bereitgestellte statische Fabrikmethode wie die folgende verwenden:

AdvancedInsightRequest request = AdvancedInsightRequest.withNumber(INSIGHT_NUMBER);

Wir wollen noch ein wenig mit diesen Fabrikmethoden herumspielen, insbesondere für unsere neuen Aktionsklassen.

Umfang begrenzen

Der Standard-Workflow in den 3.x-Versionen war immer, dass man über NexmoClient um Zugang zu anderen Clients zu erhalten, die Zugriff auf die API gewähren. Dies ist immer noch der Fall. Allerdings sind die meisten unserer Endpoint und Method Klassen wurden als öffentlich deklariert. Dies hat die Bereitstellung von Aktualisierungen zu einer Herausforderung gemacht, da wir die von uns geschaffene öffentliche Schnittstelle nicht zerstören wollen, da dies ein größeres Versionsupdate erfordert.

Zur Erinnerung: Sie sollten immer NexmoClient verwenden, um Instanzen anderer Clients zu erhalten und auf die API zuzugreifen:

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);

Es sollte nicht nötig sein, eine neue Endpoint oder Method Klasse zu instanziieren, da diese intern verwendet werden und Änderungen unterworfen sind.

Wir haben den Bereich der meisten internen Klassen auf den Standardbereich des Pakets aktualisiert. Dies bietet zwar keine echte Kapselung, aber wir tun dies, um die direkte Verwendung dieser Klassen zu verhindern, damit wir sie besser aktualisieren können. Dies erforderte auch einige Paketänderungen. Sie werden feststellen, dass einige Pakete entfernt oder umbenannt wurden.

Schlussfolgerung

Zunächst einmal: Es tut uns leid, dass wir etwas kaputt gemacht haben! Aber wir hoffen, dass diese Änderungen uns in die Lage versetzen, in Zukunft bessere Updates zu liefern.

Wenn Sie Probleme bei der Migration haben oder irgendwelche Merkwürdigkeiten mit der Bibliothek der Version 4 feststellen, zögern Sie nicht, uns ein Problem einreichen und lassen Sie es uns wissen!

Vergessen Sie nicht, sich unsere aktualisierten Bausteine auf Nexmo Entwickler.