Migration guide for v3

Version 3.x of chargebee-java contains some very sizable breaking changes:

• All numeric currency fields have been upgraded from 32-bit to 64-bit.
• The minimum supported version of Java is Java 8.

Reason for the change

v2.x of the SDK supported a maximum value of 214,748,3647—the maximum value for the int type—for all numeric currency fields. Consequently, when using v2.x, the following code—which creates an item price—would cause a compilation error:

Environment.configure("{site}","{site_api_key}");
Result result = ItemPrice.create()
	.id("silver-USD-monthly")
	.itemId("silver")
	.name("silver USD monthly")
	.#Model(#Model.PER_UNIT)
	.Price(21474836478) // Error! Value greater than max possible for `int`.
	.externalName("silver USD")
	.periodUnit(PeriodUnit.MONTH)
	.period(1)
	.request();
ItemPrice itemPrice = result.itemPrice();

This has been a grave limitation for many users.

What has changed

As part of v3.x, all numeric currency field types have been changed from int to long, bumping up the maximum supported numeric currency value in the API to 9,223,372,036,854,775,807.

Below is an example of the change introduced.

In version v2.x the return type of price() is defined as Integer:

        public Integer price() {
            return reqInteger("price");
        }

With v3.x, the return type has been changed to Long:

        public Long price() {
            return reqLong("price");
        }

Steps to migrate from v2.x to v3.x

1. Identify all the places in your codebase where Chargebee's numeric currency fields are used. Numeric currency fields can be identified by checking their data type in API docs. The data type for such fields is listed as in cents in the docs. See the screenshot below.

2. Change the data type for all those fields from int to long.