Skip to content

Migration guide for v17

Jump to bottom
Olivier Bellone edited this page Jan 15, 2020 · 1 revision

Version 17 of stripe-java contains a number of changes. This guide will help you update your Stripe integration so that it keeps working as expected after you upgrade to v17.

Table of Contents

New features

Automatic request retries

The library can now automatically retry certain failed requests (on timeouts, or if the API returns an unexpected error). This behavior is disabled by default. You can enable it in one of two ways:

  • per request, by calling setMaxNetworkRetries() on RequestOptionsBuilder and passing the resulting RequestOptions instance to your request method calls
  • globally, by setting Stripe.setMaxNetworkRetries()

The former takes precedence over the latter.

We don't recommend setting this higher than 2 or 3.

Custom HTTP clients

The core of the library has been redesigned to make it much easier to write custom HTTP clients, allowing you to use your favorite HTTP library or mock requests easily.

In order to use a custom HTTP client, you would need to:

  • write a concrete class that extends the com.stripe.net.HttpClient abstract class (you can look at the source code for com.stripe.net.HttpURLConnectionClient for inspiration)

  • instruct the stripe-java library to use your custom client like so:

    import com.stripe.net.ApiResource;
import com.stripe.net.HttpClient;
import com.stripe.net.LiveStripeResponseGetter;
import com.stripe.net.StripeResponseGetter;

HttpClient myClient = new MyCustomClient();
StripeResponseGetter srg = new LiveStripeResponseGetter(myClient);
ApiResource.setStripeResponseGetter(srg);

The new design of the library also makes it much easier to use mocking libraries to mock requests without having to write a custom implementation. For instance, using Mockito, you can now do something like this:

HttpClient httpClient = Mockito.mock(
    HttpClient.class,
    withSettings().useConstructor().defaultAnswer(Mockito.CALLS_REAL_METHODS));
StripeResponseGetter srg = new LiveStripeResponseGetter(myClient);
ApiResource.setStripeResponseGetter(srg);

HttpHeaders emptyHeaders = HttpHeaders.of(Collections.emptyMap());
String json = "{\"id\": \"ch_123\", \"object\": \"charge\"}";

Mockito.when(this.client.request(any(StripeRequest.class)))
    .thenReturn(new StripeResponse(200, emptyHeaders, json));

Charge charge = Charge.retrieve("ch_123");

Breaking changes

Removals

Many deprecated methods were removed:

Class Removed method Replacement
Collection getCount() None
Collection getTotalCount() None
Event getUserId() getAccount()
issuing.Card getPhone() None
SetupIntentCreateParams.Builder setUsage(String) setUsage(Usage)
issuing.CardCreateParams.Builder setType(String) setType(Type)
issuing.CardholderCreateParams.Builder setName(String) None
issuing.CardholderUpdateParams.Builder setName(String) None
terminal.ConnectionTokenCreateParams.Builder setOperatorAccount(String) None
terminal.LocationCreateParams.Builder setOperatorAccount(String) None
terminal.LocationListParams.Builder setOperatorAccount(String) None
terminal.LocationRetrieveParams.Builder setOperatorAccount(String) None
terminal.LocationUpdateParams.Builder setOperatorAccount(String) None
terminal.ReaderCreateParams.Builder setOperatorAccount(String) None
terminal.ReaderListParams.Builder setDeviceType(String) setDeviceType(DeviceType)
terminal.ReaderListParams.Builder setOperatorAccount(String) None
terminal.ReaderListParams.Builder setStatus(String) setStatus(Status)
terminal.ReaderRetrieveParams.Builder setOperatorAccount(String) None
terminal.ReaderUpdateParams.Builder setOperatorAccount(String) None

The following classes were removed:

  • com.stripe.net.ClientTelemetryPayload
  • com.stripe.net.RequestMetrics
  • com.stripe.net.StripeHeaders

The following enum was removed:

  • com.stripe.net.ApiResource.RequestType

API changes

The StripeResponse class was updated to be more consistent with the rest of the codebase:

  • the existing constructors were removed. The class now has a single constructor with the following signature:

    StripeResponse(int code, HttpHeaders headers, String body)

    Both headers and body must not be null. If you're manually creating StripeResponses, you can create an empty headers object with HttpHeaders.of(Collections.emptyMap()) and pass an empty string "" for body.

  • headers() now returns a com.stripe.net.HttpHeaders (previously was a com.stripe.net.StripeHeaders). The API of com.stripe.net.HttpHeaders is close to that of the java.net.http.HttpHeaders class introduced in Java 11 (which stripe-java can't use, because it will support Java 8 for the foreseeable future). If you're accessing custom headers, you should be able to replace most calls to:

    stripeResponse.headers().get("My-Header")

    with:

    stripeResponse.headers().firstValue("My-Header").orElse(null)

  • ApiResource.CHARSET is now a Charset (was a String)

  • MultipartProcessor's constructor now accepts a Charset as its last parameter (previously was a String)

Behavior changes

DNS cache disabling

Previously, the library would try to disable the DNS cache by setting the networkaddress.cache.ttl property to 0.

While disabling the DNS cache can be helpful in some rare situations, we don't think a library should be changing a global setting like this, so we've removed this behavior entirely. If you need to disable the DNS cache for any reason, you'll now have to do it from your own code:

java.security.Security.setProperty("networkaddress.cache.ttl", "0");

Custom URLStreamHandler

Previously, the library would allow for setting a custom URLStreamHandler implementation by setting the com.stripe.net.customURLStreamHandler property to the name of the custom class.

Support for this has been removed entirely. If you need to provide a custom URLStreamHandler, you should also write a custom URLStreamHandlerFactory and register the factory using URL.setURLStreamHandlerFactory() in your application's startup code.

Clone this wiki locally