Kalix Workshop - Loan application - Java

Not supported by Lightbend in any conceivable way, not open for contributions.

Prerequisite

Java 11 or later
Apache Maven 3.6 or higher
Kalix CLI
Docker 20.10.8 or higher (client and daemon)
Container registry with public access (like Docker Hub)
Access to the gcr.io/kalix-public container registry
cURL
IDE / editor

Create kickstart maven project

mvn archetype:generate \
-DarchetypeGroupId=io.kalix \
-DarchetypeArtifactId=kalix-maven-archetype \
-DarchetypeVersion=LATEST

Define value for property 'groupId': io.kx
Define value for property 'artifactId': loan-application
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' io.kx: : io.kx.loanapp

Import generated project in your IDE/editor

Delete all proto files after done

Update main class

In pom.xml:

1. In <mainClass>io.kx.loanapp.Main</mainClass> replace io.kx.loanapp.Main with io.kx.Main
2. In <dockerImage>my-docker-repo/${project.artifactId}</dockerImage> replace my-docker-repo with the right dockerId

Loan application service

Define API data structure and endpoints (GRPC)

Create io/kx/loanapp/api folder in src/main/proto folder.
Create loan_app_api.proto in src/main/proto/io/kx/loanapp/api folder.
Create:

• headers
• state
• commands
• service

Tip: Check content in step-1 git branch

Define persistence (domain) data structure (GRPC)

Create io/kx/loanapp/doman folder in src/main/proto folder.
Create loan_app_domain.proto in src/main/proto/io/kx/loanapp/domain folder.
Create:

• headers
• state
• events

Tip: Check content in step-1 git branch

Add codegen annotations in API data structure and endpoints (GRPC)

In src/main/proto/io/kx/loanapp/api/loan_app_api.proto add AkkaServerless codegen annotations to GRPC service

service LoanAppService {

option (kalix.codegen) = {
    event_sourced_entity: {
      name: "io.kx.loanapp.domain.LoanAppEntity"
      entity_type: "loanapp"
      state: "io.kx.loanapp.domain.LoanAppDomainState"
      events: [
        "io.kx.loanapp.domain.Submitted",
        "io.kx.loanapp.domain.Approved",
        "io.kx.loanapp.domain.Declined"
      ]
    }
  };

...

Note: event_sourced_entity.name has to be a unique name

Compile maven project to trigger codegen

mvn compile

Compile will generate help classes (target/generated-* folders) and skeleton classes

Business logic:
src/main/java/io/kx/Main
src/main/java/io/kx/loanapp/domain/LoanAppEntity

Unit tests:
src/test/java/io/kx/loanapp/domain/LoanAppEntityTest
Integration tests:
src/it/java/io/kx/loanapp/api/LoanAppEntityIntegrationTest

Tip: If required reimport/re-sync project in your IDE

Implement entity skeleton class

Implement src/main/java/io/kx/loanapp/domain/LoanAppEntity class
Tip: Check content in step-1 git branch

Implement unit test

Implement src/test/java/io/kx/loanapp/domain/LoanAppEntityTest class
Tip: Check content in step-1 git branch

Run unit test

mvn test

Implement integration test

Implement src/it/java/io/kx/loanapp/api/LoanAppEntityIntegrationTest class
Tip: Check content in step-1 git branch

Run integration test

mvn -Pit verify

Note: Integration tests uses TestContainers to span integration environment so it could require some time to download required containers. Also make sure docker is running.

Run locally

In project root folder there is docker-compose.yaml for running kalix proxy and (optionally) google pubsub emulator. Tip: If you do not require google pubsub emulator then comment it out in docker-compose.yaml

docker-compose up

Start the service:

mvn compile exec:exec

Test service locally

Submit loan application:

curl -XPOST -d '{
  "client_id": "12345",
  "client_monthly_income_cents": 60000,
  "loan_amount_cents": 20000,
  "loan_duration_months": 12
}' http://localhost:9000/loanapp/1 -H "Content-Type: application/json"

Get loan application:

curl -XGET http://localhost:9000/loanapp/1 -H "Content-Type: application/json"

Approve:

curl -XPUT http://localhost:9000/loanapp/1/approve -H "Content-Type: application/json"

Package

Note: Make sure you have updated dockerImage in your pom.xml and that your local docker is authenticated with your docker container registry

mvn package

Push docker image to docker repository:

mvn docker:push

Register for Kalix account or Login with existing account

Register

kalix CLI

Validate version:

kalix version

Login (need to be logged in the Kalix Console in web browser):

kalix auth login

Create new project:

kalix projects new loan-application --region <REGION>

Note: Replace <REGION> with desired region

List projects:

kalix projects list

Set project:

kalix config set project loan-application

Deploy service

kalix service deploy loan-application my-docker-repo/loan-application:1.0-SNAPSHOT

Note: Replace my-docker-repo with your docker repository

List services:

kalix services list

NAME               AGE    REPLICAS   STATUS   DESCRIPTION   
loan-application   102s   1          Ready  

Expose service

kalix services expose loan-application

Result: Service 'loan-application' was successfully exposed at: <some_host>.us-east1.kalix.app

Test service in production

Submit loan application:

curl -XPOST -d '{
  "client_id": "12345",
  "client_monthly_income_cents": 60000,
  "loan_amount_cents": 20000,
  "loan_duration_months": 12
}' https://<somehost>.kalix.app/loanapp/1 -H "Content-Type: application/json"

Get loan application:

curl -XGET https://<somehost>.kalix.app/loanapp/1 -H "Content-Type: application/json"

Approve:

curl -XPUT https://<somehost>.kalix.app/loanapp/1/approve -H "Content-Type: application/json"

Loan application processing service

Increment version

In pom.xml in <version>1.0-SNAPSHOT</version> replace 1.0-SNAPSHOT with 1.1-SNAPSHOT

Define API data structure and endpoints (GRPC)

Create io/kx/loanproc/api folder in src/main/proto folder.
Create loan_proc_api.proto in src/main/proto/io/kx/loanproc/api folder.
Create:

• state
• commands
• service

Tip: Check content in step-2 git branch

Define persistence (domain) data structure (GRPC)

Create io/kx/loanproc/domain folder in src/main/proto folder.
Create loan_proc_domain.proto in src/main/proto/io/kx/loanproc/domain folder.
Create:

• state
• events

Tip: Check content in step-2 git branch

Add codegen annotations in API data structure and endpoints (GRPC)

In src/main/proto/io/kx/loanproc/api/loan_proc_api.proto add AkkaServerless codegen annotations to GRPC service

service LoanProcService {

option (kalix.codegen) = {
    event_sourced_entity: {
      name: "io.kx.loanproc.domain.LoanProcEntity"
      entity_type: "loanproc"
      state: "io.kx.loanproc.domain.LoanProcDomainState"
      events: [
        "io.kx.loanproc.domain.ReadyForReview",
        "io.kx.loanproc.domain.Approved",
        "io.kx.loanproc.domain.Declined"
      ]
    }
  };

...

Note: event_sourced_entity.name has to be a unique name

Compile maven project to trigger codegen

mvn compile

Compile will generate help classes (target/generated-* folders) and skeleton classes

Business logic:
src/main/java/io/kx/loanproc/domain/LoanProcEntity

Unit tests:
src/test/java/io/kx/loanproc/domain/LoanProcEntityTest
Integration tests:
src/it/java/io/kx/loanproc/api/LoanProcEntityIntegrationTest

Tip: If required reimport project in your IDE

Update Main class

In src/main/java/io/kx/Main you need to add new entity component (LoanProcEntity):

 return AkkaServerlessFactory.withComponents(LoanAppEntity::new, LoanProcEntity::new);

Implement entity skeleton class

Implement src/main/java/io/kx/loanproc/domain/LoanProcEntity class
Tip: Check content in step-2 git branch

Implement unit test

Implement src/test/java/io/kx/loanproc/domain/LoanProcEntityTest class
Tip: Check content in step-2 git branch

Run unit test

mvn test

Implement integration test

Implement src/it/java/io/kx/loanproc/api/LoanProcEntityIntegrationTest class
Tip: Check content in step-2 git branch

Run integration test

mvn -Pit verify

Note: Integration tests uses TestContainers to span integration environment so it could require some time to download required containers. Also make sure docker is running.

Run locally

In project root folder there is docker-compose.yaml for running kalix proxy and (optionally) google pubsub emulator. Tip: If you do not require google pubsub emulator then comment it out in docker-compose.yaml

docker-compose up

Start the service:

mvn compile exec:exec

Test service locally

Start processing:

curl -XPOST -d '{
  "client_monthly_income_cents": 60000,
  "loan_amount_cents": 20000,
  "loan_duration_months": 12
}' http://localhost:9000/loanproc/1 -H "Content-Type: application/json"

Get loan processing:

curl -XGET http://localhost:9000/loanproc/1 -H "Content-Type: application/json"

Approve:

curl -XPUT http://localhost:9000/loanproc/1/approve -H "Content-Type: application/json"

Package

mvn package

Push docker image to docker repository:

mvn docker:push

Deploy service

kalix service deploy loan-application my-docker-repo/loan-application:1.1-SNAPSHOT

Test service in production

Start processing:

curl -XPOST -d '{
  "client_monthly_income_cents": 60000,
  "loan_amount_cents": 20000,
  "loan_duration_months": 12
}' https://<somehost>.kalix.app/loanproc/1 -H "Content-Type: application/json"

Get loan processing:

curl -XGET https://<somehost>.kalix.app/loanproc/1 -H "Content-Type: application/json"

Approve:

curl -XPUT https://<somehost>.kalix.app/loanproc/1/approve -H "Content-Type: application/json"

Increment version

In pom.xml in <version>1.1-SNAPSHOT</version> replace 1.1-SNAPSHOT with 1.2-SNAPSHOT

Create a view

Create io/kx/loanproc/view folder in src/main/proto folder.
Create loan_proc_by_status_view.proto in src/main/proto/io/kx/loanproc/view folder.
Create:

• state
• request/response
• service

Note: SELECT result alias AS results needs to correspond with GetLoanProcByStatusResponse parameter name repeated LoanProcViewState results
Note: Currently enums are not supported as query parameters (issue 1141) so enum number value is used for query
Tip: Check content in step-3 git branch

Compile maven project to trigger codegen for views

mvn compile

Compile will generate help classes (target/generated-* folders) and skeleton classes

src/main/java/io/kx/loanproc/view/LoanProcByStatusView

In src/main/java/io/kx/Main you need to add view (LoanProcByStatusView) initialization:

 return AkkaServerlessFactory.withComponents(LoanAppEntity::new, LoanProcEntity::new, LoanProcByStatusView::new);

Implement view LoanProcByStatusView skeleton class

Implement src/main/java/io/kx/loanproc/view/LoanProcByStatusView class
Tip: Check content in step-3 git branch

##Unit test

Because of the nature of views only Integration tests are done.

Create integration tests for view

1. Copy io/kx/loanproc/view/LoanProcEntityIntegrationTest class to io/kx/loanproc/view/LoanProcViewIntegrationTest
2. Remove all methods annotated with @Test
3. Add test case

@Test
public void viewTest() throws Exception {
...  

Tip: Check content in step-3 git branch

Run integration test

mvn verify -Pit

Note: Integration tests uses TestContainers to span integration environment so it could require some time to download required containers. Also make sure docker is running.

Package

mvn package

Push docker image to docker repository:

mvn docker:push

Deploy service

kalix service deploy loan-application my-docker-repo/loan-application:1.2-SNAPSHOT

Test service in production

Get loan processing by status:

curl -XPOST -d {"status_id":2} https://<somehost>.kalix.app/loanproc/views/by-status -H "Content-Type: application/json"

Event driven communication

Increment version

In pom.xml in <version>1.2-SNAPSHOT</version> replace 1.3-SNAPSHOT with 1.3-SNAPSHOT

Action for submitted event (Loan application service -> Loan application processing service)

Create io/kx/loanapp/action folder in src/main/proto folder.
Create loan_app_eventing_to_proc_action.proto in src/main/proto/io/kx/loanapp/action folder.
Create:

• service

Tip: Check content in step-4 git branch

Action for approved & declined processing event (Loan application processing service -> Loan application service)

Create io/kx/loanproc/action folder in src/main/proto folder.
Create loan_proc_eventing_to_app_action.proto in src/main/proto/io/kx/loanproc/action folder.
Create:

• service

Tip: Check content in step-4 git branch

Compile maven project to trigger codegen for action

mvn compile

Compile will generate help classes (target/generated-* folders) and skeleton classes

src/main/java/io/kx/loanapp/action/LoanAppEventingToProcAction
src/main/java/io/kx/loanproc/action/LoanProcEventingToAppAction

In src/main/java/io/kx/Main you need to add view (LoanAppEventingToProcAction & LoanProcEventingToAppAction) initialization:

 return AkkaServerlessFactory.withComponents(LoanAppEntity::new, LoanProcEntity::new, LoanAppEventingToProcAction::new, LoanProcByStatusView::new, LoanProcEventingToAppAction::new);

Implement view LoanAppEventingToProcAction skeleton class

Implement src/main/java/io/kx/loanapp/action/LoanAppEventingToProcAction class
Tip: Check content in step-4 git branch

Implement view LoanProcEventingToAppAction skeleton class

Implement src/main/java/io/kx/loanproc/action/LoanProcEventingToAppAction class
Tip: Check content in step-4 git branch

System integration tests (multiple services)

In src/it/java/io/kx folder create new class SystemIntegrationTest. Tip: Check content in step-4 git branch

Run integration test

mvn verify -Pit

Note: Integration tests uses TestContainers to span integration environment so it could require some time to download required containers. Also make sure docker is running.

Package

mvn package

Push docker image to docker repository:

mvn docker:push

Deploy service

kalix service deploy loan-application my-docker-repo/loan-application:1.3-SNAPSHOT

Note: Replace my-docker-repo with your docker repository

Test service in production

Submit loan application:

curl -XPOST -d '{
  "client_id": "123456",
  "client_monthly_income_cents": 60000,
  "loan_amount_cents": 20000,
  "loan_duration_months": 12
}' https://<somehost>.kalix.app/loanapp/2 -H "Content-Type: application/json"

Approve loan processing:

curl -XPUT -d '{
"reviewer_id": "9999"
}' https://<somehost>.kalix.app/loanproc/2/approve -H "Content-Type: application/json"

Get loan application :

curl -XGET https://<somehost>.kalix.app/loanapp/2 -H "Content-Type: application/json"