A lot has changed in the Java SDK since the last announcement post - over 17 thousand lines of code in fact! Although much of this is internal refactoring and quality of life improvements, there are some important changes to be aware of as this is a major version. Without further ado, let's dive into it!
Let's start with the big news: the Vonage Video API has now officially released. The transition from OpenTok to Vonage has been in the making for some time, hence the numerous beta versions of the SDK. Now that the API is stable, it is available in the com.vonage.client.video package of the Java Server SDK.
If there's one thing to take away from this article, it's the fact that the SDK has now migrated to a new artifactId on Maven Central. This has been on the roadmap since 2022, as evident by the various beta releases to the new location. The groupId is still the same (com.vonage), but the artifactId is now server-sdk instead of client. This migration has been signposted in the metadata, so some tools and websites may point you to the new artifact. You can see this notice on mvnrepository.com for example.
What motivated this change? The main reason is to avoid confusion with other tooling published under the com.vonage group. Since we also offer client-side SDKs for Android development, the client naming may create some confusion, since it is, in fact, the server-side SDK.
Updating your dependencies should still be a straightforward process: replace com.vonage:client:7.11.1 (or whatever version you are currently using) with com.vonage:server-sdk:8.0.0. Instructions for your particular build system can be found on the right-hand side of the Maven Central webpage.
As the semantic version number suggests, there are some backwards-incompatible changes to the public API of the SDK in this release, but don't let that put you off upgrading, since most of these are unlikely to affect you and if they do, should be quite easy to fix. The SDK still supports Java 8, and all the package names and classes are still the same. However, most of the deprecated members in the SDK have been removed as planned. For example, the WAPPush SMS message type, which is no longer supported by the API. Here is a list of removals and their replacements.
As with any project that has some history, there will inevitably be code that is no longer used or supported. In the Java SDK, there were a few packages that are no longer maintained due to their antiquity and the fact that they are not used. The SNS client is one such example (the API has long been dead), which also had dependencies on some XML utilities. The legacyutils, sns and logging packages have all been removed. This includes also the SNS URI configuration in HttpConfig as it is not used.
One of the most common issues when using any library is dependency conflicts. I wrote an article about how to resolve this, but generally it's prudent for library maintainers to minimise their dependency footprint where possible.
One such example in the SDK has been the javax.servlet dependency. Since it has now moved to the Jakarta namespace, it makes using the Java SDK with newer versions of Jakarta Servlet more challenging. Furthermore, the usage of this dependency was quite unnecessary, and the classes that used it are no longer maintained. Therefore, all methods and classes that referenced this - specifically, HttpServletRequest - have been removed. This includes the com.vonage.client.voice.servlet package and com.vonage.client.sms.callback.AbstractMOServlet. If you were using the RequestSigning class for verifying signatures of inbound messages from the SMS API, you can now use the replacement verifySignature method - see the code snippets repo for an example.
The other dependency that has been removed is jackson-dataformat-hal. This provided an extension to the Jackson library for deserialising HAL responses, but which was only by the Account API - specifically the ListSecretsResponse class. For consistency with the rest of the SDK, this has been refactored, thus dependency is no longer necessary.
Removals from the Verify API include the BaseResult class - which just had status codes but was unused across the rest of the SDK - and LineType, which was previously deprecated. That also includes methods that used LineType, of course. The ipAddress field has also been removed from both AdvancedInsightRequest (in Number Insight) and CheckRequest. The verify2 package is recommended to be used instead of verify as the Verify v2 API will receive more support. Speaking of which, there have been numerous locales added to Verify v2 - so much so that keeping on top of it has become a maintenance burden. For this reason, the custom com.vonage.client.verify2.Locale enum has been removed. Instead, you should use the built-in java.util.Locale. You can use the VerificationRequest.Builder#locale(String) for convenience, providing the two-letter language and region tags (for example, en-gb).
Some quality-of-life improvements to the Voice API implementation have been made, which include removing previously deprecated methods - for example, the setters in com.vonage.client.voice.Call class, in favour of using the builder which was added in v7.3.0. The two most impactful changes are on VoiceClient.
Firstly, the modifyCall method has been removed along with ModifyCallResponse. The implementation now simplifies call modification actions with direct method calls. For example, to terminate (hang up) a call, use the terminateCall(String) method, passing in only the call ID. Similar methods exist for the other actions (earmuff / unearmuff, mute / unmute).
The other change is to the downloadRecording method. This returned a Recording object, which had only two things you could do with it: either get the content as an InputStream or call the save(Path) method to store it in a file. The implementation of this internally was not pretty, so it has been simplified by providing two new methods on VoiceClient: void saveRecording(String recordingUrl, Path destination) and byte[] downloadRecordingRaw(String recordingUrl). The former, as its name suggests, will save the recording from the given URL (recordingUrl) to the desired file (destination). The latter will give you the binary contents of the recording (downloaded from the recordingUrl) as a byte array, so you can decide what to do with it if you don't want to save it in a file. Therefore, the previous Recording downloadRecording(String recordingUrl) method has been removed, along with the com.vonage.voice.client.Recording class.
Finally, the PayAction NCCO along with the PaymentPrompt class have been removed, as these are no longer supported by the API.
Besides removing legacy code to address technical debt, there are also some new features described below. If you're curious, the internal refactoring work to decouple API implementations from the underlying HTTP client that started in v7.7.0 has now been completed, which paves the way for updating the client in the future - for example, to enable supporting asynchronous requests. The tests have also been migrated to JUnit 5.
Version 7.8.0 added the ability to set a custom timeout for all requests sent from the SDK. Although our REST APIs usually respond in a timely manner (measured in milliseconds rather than seconds), some endpoints may take longer depending on the amount of processing required and network conditions. For time-sensitive applications, it may be useful to set a hard deadline for responses so that you are not waiting for longer than necessary without having to create separate threads. Before v7.8.0, the default timeout was system-dependent since it was the default value from the underlying Apache HTTP client (typically, 60 seconds). Now, this can be configured to the nearest millisecond using the HttpConfig.Builder#timeoutMillis(int) method. It is also now 60 seconds by default, irrespective of the system settings.
Some additional fields have been added for the Silent Auth workflow in the Verify v2 API. Namely, the sandbox and redirect_url parameters in SilentAuthWorkflow, check_url in VerificationResponse. Our docs have more information about the synchronous Silent Auth workflow and Silent Auth sandbox if you're curious.
AccountClient Improvements
The AccountClient class in the Java SDK has endpoints for both the Pricing and Account APIs. However, it was missing the outbound pricing for all countries endpoint implementation, so this has been added since v7.9.0. This endpoint - which can be invoked with the AccountClient#listPriceAllCountries(ServiceType) method - retrieves service pricing information for all available countries.
Furthermore, convenience method overloads have been added for secret management. Now, if you want to manage secrets for your main account (as opposed to subaccounts), you don't need to provide the API key to the method - this will automatically be derived from the authentication method used to construct the VonageClient.
When receiving webhooks from Vonage, it is recommended that you verify the authenticity of the payload by validating the token signature. This was previously a manual process, but as of v7.11.0, you can use the verifySignature(String jwt, String secret) helper method in VoiceClient and MessagesClient. This simply delegates to the new Jwt.verifySignature method in the com.vonage:jwt artifact, which has been updated to support this feature. Now, you no longer need to implement the logic for extracting and validating the signature of an inbound payload using third-party libraries - you just need to provide the JWT and shared secret. The method will return true if the token was signed by the given secret.
And that's all the changes you should know about in version 8.0.0 of the Java SDK. Remember to look out for releases under the com.vonage:server-sdk coordinates for future updates! If you do come across any issues or have suggestions for enhancements, feel free to raise an issue on GitHub, reach out to us on Twitter or drop by our Community Slack. I hope you have a great experience using the Vonage APIs with the latest version of the Java SDK!
){kind=small}
Sina is a Java Developer Advocate at Vonage. He comes from an academic background and is generally curious about anything related to cars, computers, programming, technology and human nature. In his spare time, he can be found walking or playing competitive video games.
