Destructuring accessors for SecureCellData in Kotlin

[ilammy]

This is the final item of API updates planned in RFC 3.9.

Kotlin supports tuples and destructuring assignment which results in a much nicer APIs with multiple return values. Implement special accessor methods for SecureCellData to enable that:

// You can now write like this:
val (encrypted, authToken) = cellTP.encrypt(message, context)

// Instead of having to spell it out like this:
val result = cellTP.protect(context, message)
val encrypted = result.protectedData
val authToken = result.additionalData

This is implemented by a couple of special methods. They are available to users (i.e., IDEs will show them up in Java autocomplete) but these methods are not intended for general use. The methods also have appropriate @NotNull annotations to make Kotlin experience better.

Initially, RFC 3.9 also suggested some accessor renaming for Java:

• getProtectedData() ⟹ getEncryptedData()
• getAdditionalData() ⟹ getToken()

However, after giving it a second though, I believe that we don’t need to do this. Renaming is hard, it causes developer pain. While it is justified with new Secure Cell API that has its own improvements, here we’d be renaming for the sake of renaming. While the names are not ideal, they are not that ambiguous either. Furthermore, Android users are likely to use Kotlin in the first place so they will not have to deal with these names anymore.

Checklist

• Change is covered by automated tests
• The coding guidelines are followed
• Public API has proper documentation
• Example projects and code samples are up-to-date (no Kotlin examples)
• Changelog is updated