Kotlin

Kotlin code generator

Code generation takes NPL prototypes and produces facades, proxies, and a facade factory function. These may be used directly with the engine HTTP clients from the clients module.

The Kotlin code generator is invoked with the npl-codegen target of the NPL Maven Plugin.

Output

Facades

Facades provide a type layer for properties. These are generated for structs, identifiers, and protocols. A facade is a type-safe layer around objects that are obtained directly from the API.

For a struct named Foo, the generated Kotlin class FooFacade's constructor takes a ClientStructValue.

For an identifier named Id, the generated Kotlin class IdFacade's constructor takes a ClientIdentifierValue.

For a protocol named Iou, the generated Kotlin class _iou_npl_IouFacade's constructor takes a ClientProtocolState. The facade for the protocol also provides a iou_npl_IouFacade.create(...) method, used to create new protocol instances of this type.

Proxies

Proxies provide easy invocation of permissions and obligations. They require an instance of ApplicationClient, and expose permissions and obligations in a type-safe manner.

Factory function

The facade factory function can be used to create a protocol facade with test data, which can be useful for unit testing purposes. This allows the quick turn around of updating an NPL protocol definition and usage of a facade in unit tests, without the manual process of updating a custom created factory to initialise a protocol facade's ClientProtocolState.

Facade factory function generation is enabled by default, with the maven property generateFacadeFactory. It can be disabled by setting it to false. See the NPL Maven Plugin for more details.

For a protocol named Iou,

protocol[p] Iou(var amount: Number, purpose: Text) { /* ... */ }

the generated Kotlin function createIouFacade returns an instance of an IouFacade.

val iouFacade = createIouFacade()

The resulting function has default values for all fields (that is, parameters and body fields) of the corresponding NPL protocol. It is possible to override the default value with another of your choice:

val iouFacade = createIouFacade(amount = 10_000, purpose = "Car purchase")

Nullable properties

Option

The protocol proxy methods that are generated for permissions, return an instance of ApiResult<T>(result: T, ...). The type of T depends on the return type of the permission in question. In the case where the permission returns an option, T will be nullable.

For the following permission definition

permission[p] foo() returns Option<Text> { ... }

produced type T will be a nullable String?:

fun foo(/* ... */): APiResult<String?> = client.selectAction(/* ... */)

This proxy method will return "bar" if foo() returns optionOf<Text>("bar"), and null if it returns optionOf<Text>().

Optional

The auto-generated OptionalFacade is cumbersome to work with out-of-the-box. Three utility functions are available for Kotlin development. They are automatically generated as part of the Code Generation step and are located in the package namespace com.noumenadigital.codegen.

• OptionalFacade<T>.asOptional(): converts the OptionalFacade into a Java Optional
• OptionalFacade.some(payload: T): creates a non-empty OptionalFacade with a payload
• OptionalFacade.none(): creates an empty OptionalFacade

Examples:

val big1 = OptionalFacade.some(BigDecimal(1))
val big1AsOpt = big1.asOptional()

val none = OptionalFacade.none<BigDecimal>()
val noneAsOpt = none.asOptional()