Next Generation Java Helper Library Release

October 14, 2016
Written by

Java Helper Library

Today, we are excited to announce the general availability of our next generation Java helper library.  Get ready to enjoy a whole new level of productivity.

The approach

Java is the second next generation helper library that we are releasing, after announcing the new PHP library last month. We’ve rebuilt it from the ground up based on your and your fellow Java developers’ feedback.

To learn more about our novel approach to make the helper-libraries more consistent, enable faster iteration, and improve the libraries by having a shared foundation across languages, check out our blog post that introduced the next generation Twilio Helper Libraries.

What’s new

The Twilio Java helper library has undergone significant changes from the previous version to make the new library easier and more intuitive to use.

The new library

  • Simplifies the basics like initializing the object and imports.
  • Improves network efficiency by introducing Actions.
  • Adds native paging support which was one of the most requested features.
  • Uses the type system to expose what parameters can be used when operating on a resource.

It is compatible with Java versions 7 and higher. Let’s look at some examples.

The basics

// In 7.x there is only one Twilio.
import com.twilio.Twilio;

//You can initialize Twilio by using:
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

Actions

Performing actions has been abstracted into 5 distinct types: Fetcher, Creator, Updater, Deleter, and Reader.

  • Fetcher: Gets an instance of a resource
  • Creator: Makes a new instance of a resource
  • Updater: Modifies an instance of a resource
  • Deleter: Removes an instance of a resource
  • Reader: Lists a resource

We only expose the actions that you can perform on a resource or that anything that compiles is a ‘legal’ action in the eyes of the API. Each type has a corresponding method to execute the HTTP request: fetch, create, update, delete, and read. This allows for better network efficiency and makes it clear when the library will perform HTTP requests.

Message message = Message.fetcher("SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").fetch();

Paging

As you iterate over the Iterable it will fetch the next page as necessary. For further customization, you may use setPageSize or setLimit on the Reader action to set the size of each page that is fetched or the max results you want to get returned.

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;

...

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

Iterable<Message> messages = Message.reader().read();
for (Message message : messages) {
    System.out.println("message sid: " + message.getSid());
    // message sid: SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
}

Builders

The new library use the Builder pattern. This makes it clear that the only field you can update on an existing message is the Body field. On the other hand, the Creator has these methods:

Yoyodyne Java Builder Pattern

Here’s an example showing how you can instantiate a Creator, set any parameters on it you wish, and then call Create:

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;

...

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

Message message = Message.creator(
        new PhoneNumber("+15558675309"),
        new PhoneNumber("+15017250604"),
        "This is the ship that made the Kessel Run in fourteen parsecs?")
    )
    .setMediaUrl("https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg")
    .create();

How to get started

The best place to start is the new Getting Started Guide that covers installation and how to send your first message. The Quickstart provides code samples for several use cases and our Javadoc provides great reference documentation.

Another great resource is the Migration Guide, especially if you are familiar with the previous generation. It covers some of the new features and highlights the differences.

The new libraries come in two lines. The ’mainline’ that contains our GA products and is the most stable release, and ‘edge’ which includes new features that are in Developer Preview or Beta. Here is a more detailed writeup about our Versioning Strategy.

Deprecation

Going forward, new functionality will only be added to the new libraries (Java 7.x). The old libraries (Java 6.x) will be officially supported until 01/15/17. After that day, Twilio will stop providing bug fixes and Support might ask you to upgrade before debugging issues.

Next-gen Release Candidates

We’d love your get your feedback on our other release candidates. They are available on Github now and we are interested in your issue tickets and pull requests.

The next language that we will release is C#. Stay tuned!