Kotlin

Deprecated tool (since 2024.2.0, to be removed in 2026.1.0)

Use the NPL OpenAPI code generator to generate OpenAPI definitions from NPL source code, and then use the OpenAPI Generator to generate client code in your desired language instead.

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.

Naming collisions

The proxy methods have two different kinds of arguments: some are derived from the NPL parties and parameters, and some (such as e.g. authorizationContext and caller) are pre-defined and not derived. If there is a collision between the two kinds of arguments, the names of the derived arguments are preserved, but the names of the pre-defined arguments are prefixed with _ (so if you define an NPL party called caller, the proxy method argument for specifying the calling party will be _caller).

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")

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()