La version 4 de la bibliothèque client Java Nexmo est disponible

Nous avons publié aujourd'hui la version 4.0.0 de notre Bibliothèque Client Java Nexmo. Bien que nous soyons très satisfaits de nos versions 3.x de la bibliothèque, nous avons réalisé qu'il y avait quelques éléments qui l'empêchaient de fournir une expérience utilisateur idéale.

Une nouvelle version majeure signifie quelques ruptures de compatibilité ascendante, mais un grand nombre de nouvelles fonctionnalités. J'ai voulu donner quelques conseils de migration et expliquer pourquoi nous avons choisi cette direction.

Pour une liste complète des changements, vous pouvez trouver notre changelog sur la page de la version

Prise en charge de Java 7

La décision a été difficile à prendre, mais nous avons décidé qu'il était temps d'abandonner le support officiel de Java 7. Le choix de la prochaine version de Java à cibler a également été un défi, mais nous avons mis à jour la version cible à Java 8.

Fin de l'assistance Oracle

Oracle a mis fin aux mises à jour publiques de Java 7 en avril 2015. Bien qu'il offre encore un support étendu jusqu'en juillet 2020, il encourage les utilisateurs à se mettre à jour depuis un certain temps.

Wiki Java Version

Il est vrai que d'autres JDK sont encore mis à jour pour Java 7, mais nous pensons que c'est l'un des facteurs limitant qui nous permet d'aller de l'avant avec le développement.

Récemment, nous avons Fin de la prise en charge des anciens protocoles TLS. En outre, Maven Central a abandonné le support en mai 2018. Cela complique le processus d'intégration continue et rend la maintenance de la bibliothèque avec le support de Java 7 très difficile.

Les versions de Java évoluent

Nous n'avons pas pris cette décision à la légère et, avec le passage des nouvelles versions à une cadence de 6 moisnous ne pensons pas que les prochaines versions seront aussi drastiques. Donald Smith, d'Oracle, déclare

Passer de Java 9->10->11 est plus proche de passer de 8->8u20->8u40 que de 7->8->9. C'est effrayant à voir au début quand on est habitué à des versions majeures tous les trois ans et qu'on a un modèle mental de l'impact énorme de ces changements majeurs. La cadence de six mois n'a rien à voir avec cela.

Nous voulons être aussi inclusifs que possible, et nous avons ajouté quelques fonctionnalités au client pour aider à déterminer la meilleure version de Java à cibler à l'avenir.

Instanciation du client

L'instanciation de l'objet NexmoClient l'objet ne nécessite plus de réfléchir à comment d'authentification. Au lieu de cela, vous disposez maintenant d'un Builder pour vous aider à construire le client à l'aide de diverses options de configuration.

Ancienne

Voici comment le NexmoClient était instanciée pour être utilisée avec les API SMS et Voice :

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

Ce processus vous a permis de comprendre comment d'authentification. Nous avons également estimé que l'utilisation de noms tels que TokenAuthMethod et JWTAuthMethod n'étaient pas assez intuitifs.

Nouveau

Avec la nouvelle version, voici comment vous pouvez instancier NexmoClient pour l'utiliser avec les API SMS et Voice :

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

Vous pouvez également lui fournir le contenu de votre fichier de clé privée, si vous le chargez à partir d'une autre source :

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

En tant qu'utilisateur, vous ne devez vous préoccuper que des informations d'identification dont vous disposez. Vous ne devriez pas avoir à vous préoccuper de savoir quel type d'identifiant utiliser avec votre clé et votre secret d'API. AuthMethod à utiliser avec votre clé d'API et votre secret, il vous suffit de fournir à la fonction Builder toutes les informations d'identification dont vous disposez.

Il y a quelques mises en garde à propos de cette façon de procéder. Si vous fournissez une clé API, vous devez également fournir un secret ou un secret de signature. Si vous ne le faites pas, la méthode build lancera un NexmoClientCreationException.

L'objet de contrôle d'appel Nexmo

L'objet de contrôle d'appel Nexmo (NCCO) Nexmo Call Control Object (NCCO) ont fait l'objet d'une révision majeure dans cette mise à jour. A l'origine, nous appelions nos sérialiseurs des classes NCCO avec des noms comme TalkNcco, InputNcco, ConnectNcco. Cependant, cela ne correspond pas à la convention de nommage actuelle.

Notre Guide du BCN dit

Un Nexmo Call Control Object (NCCO) est un tableau JSON d'actions utilisé pour contrôler le flux d'un appel Voice API.

Nous les avons donc renommées en classes d'action avec des noms comme TalkAction, InputActionet ConnectAction. En outre, nous avons fourni un wrapper de collection spécial appelé Ncco pour les relier entre elles et gérer la construction de la structure JSON.

Ancienne

Voici comment vous pourriez créer un NCCO pour qu'un utilisateur enregistre un message :

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

Nouveau

Maintenant, vous pouvez faire quelque chose comme ça :

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

Ou bien, vous pouvez construire les objets et les envelopper dans un fichier Ncco sans créer de variables locales supplémentaires :

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

L'objectif de cette modification était de créer une expérience plus intuitive pour la création d'objets avec de nombreuses propriétés.

Pour certains éléments, comme TalkAction qui n'ont qu'une propriété text cela semble être plus de code. Cependant, l'avantage est pleinement réalisé lorsque vos actions deviennent un peu plus complexes.

Nous voulons examiner d'autres moyens de faciliter cette tâche, peut-être en utilisant des méthodes d'usine pour fournir des raccourcis faciles.

Nombre de demandes Insight

Notre InsightClient comportait un certain nombre de méthodes avec diverses combinaisons de paramètres. Au fur et à mesure que le nombre d'options pour la compréhension des nombres augmente, la liste des paramètres ne peut que s'allonger.

Une tendance commune se dégage de la plupart de ces mises à jour et, une fois de plus, nous avons opté pour le modèle du constructeur.

Ancienne

Pour effectuer une demande standard de recherche de numéro avec les informations d'identification de l'appelant (CNAM), vous devez procéder de la manière suivante :

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

Notez que vous devez utiliser null dans le deuxième paramètre afin d'accéder au paramètre cnam pour avoir accès au paramètre Ce n'est pas correct.

Nouveau

Maintenant, vous pouvez le faire :

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

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

Nous n'avons pas supprimé la méthode existante, mais nous avons décidé de l'abandonner en faveur de l'utilisation des constructeurs de requêtes avec suppression dans la prochaine version majeure.

J'ai parlé de la façon dont le modèle du constructeur peut augmenter la verbosité du code. Ainsi, pour le nombre d'objets de requête perspicaces, nous avons également inclus quelques méthodes d'usine statiques pour les cas d'utilisation courants.

Bien que vous puissiez construire des objets de requête comme ceci :

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

Vous pouvez également utiliser une méthode d'usine statique fournie comme ceci :

AdvancedInsightRequest request = AdvancedInsightRequest.withNumber(INSIGHT_NUMBER);

Nous voulons jouer un peu plus avec ces méthodes d'usine, en particulier pour nos nouvelles classes d'action.

Limitation du champ d'application

Le flux de travail standard dans les versions 3.x a toujours été de passer par NexmoClient pour accéder aux autres clients qui donnent accès à l'API. C'est toujours le cas. Cependant, la plupart de nos clients Endpoint et Method ont été déclarées publiques. Cela a rendu les mises à jour difficiles, car nous ne voulons pas casser l'interface publique que nous avons créée, ce qui nécessiterait une mise à jour majeure de la version.

Pour rappel, vous devez toujours utiliser NexmoClient pour obtenir des instances d'autres clients et accéder à l'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);

Il ne devrait pas être nécessaire d'instancier un nouveau fichier Endpoint ou Method car elles sont utilisées en interne et sont susceptibles d'être modifiées.

Nous avons mis à jour la portée de la plupart des classes internes pour qu'elle corresponde à la portée par défaut du paquet. Bien que cela ne fournisse pas une véritable encapsulation, nous faisons cela pour décourager toute utilisation de ces classes directement afin de pouvoir mieux les mettre à jour. Cela a nécessité quelques changements de paquets également, vous pouvez remarquer que certains paquets ont été supprimés ou renommés.

Conclusion

Tout d'abord, nous sommes désolés d'avoir cassé des choses ! Mais nous espérons que ces changements nous permettront d'être mieux à même de fournir des mises à jour à l'avenir.

Si vous rencontrez des problèmes lors du processus de migration, ou si vous remarquez des anomalies dans la bibliothèque de la version 4, n'hésitez pas à Soumettre un problème et à nous en faire part !

N'oubliez pas de consulter nos blocs de construction mis à jour sur Nexmo Developer.