Document best approach for working with Java apps

[notmandatory]

Reported by SeverinAlexB on discord. See also:

https://github.com/SeverinAlexB/bdk-java-ulong-bug

[thunderbiscuit]

@SeverinAlexB

[artfuldev]

I think ULong is the stricter type-safe API for Kotlin consumers but Java doesn't have the concept of unsigned numbers. I'm not sure if we're just targeting Kotlin consumers though. The way to solve this in a Java project is to just use Kotlin's libraries (which are JVM compatible) so we can either make that part of our documentation, or decide to weaken our type-safety in the APIs.

Refer: kotlin package in kotlin-stdlib, for example (for ULong) https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-u-long/

[thunderbiscuit]

Yeah I'm not sure where the bug is coming from, but for some reason this Kotlin/Java compatibility breaks here for ULong (shouldn't it just work out of the box? that's what I would have assumed).

Also of interest (not sure how related) is the fact that on the Java side, the ElectrumConfig is private (even though it's a public data class).

Keeping these here for archives (issue was discussed on the #ffi-bindings channel a bit more):

If you use incorrect syntax on the Java side, the IDE will suggest something, and the tooltip box shows a public data class:

If you accept the changes proposed (adding the new keyword), now you get an error telling you the constructor for ElectrumConfig is private:

[thunderbiscuit]

Notice in the second picture the type for timeout is kotlin.UByte, whereas the type for retry and stopGap are byte and long respectively...

[SeverinAlexB]

Hey guys, thanks for taking this on

I saw another issue I can't explain. For some reason, I can't call methods that are available in Kotlin. For example, sync or getBalance are just not available. As always, it works with a custom Kotlin wrapper.

All methods that are available in Java:

[artfuldev]

I'll take a deeper look at this, thanks!

[thunderbiscuit]

Will attempt to keep track of the known issues and some hacks/fixes to get around them for the time being here.

[thunderbiscuit]

This issue has been further investigated, and I want to provide links for people stumbling on this. The core problem is that unsigned types are inline classes, and their names get mangled. The primary fix is to write small Kotlin wrapper classes, but I will expand on different approaches in a separate issue, #322.

Links:

1. Kotlin YouTrack Issue
2. Mangling