Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lightbend/kalix-ws-loan-application-java


https://github.com/lightbend/kalix-ws-loan-application-java

Last synced: 10 months ago
JSON representation

Awesome Lists containing this project

README 

          
# 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](https://docs.kalix.io/kalix/install-kalix.html) 


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 `io.kx.loanapp.Main` replace `io.kx.loanapp.Main` with `io.kx.Main`

2. In `my-docker-repo/${project.artifactId}` 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](https://www.testcontainers.org/) 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](https://console.kalix.io/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 

```

Note: Replace `` 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: .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://.kalix.app/loanapp/1 -H "Content-Type: application/json"

```

Get loan application:

```

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

```

Approve:

```

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

```



# Loan application processing service



## Increment version

In `pom.xml` in `1.0-SNAPSHOT` 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](https://www.testcontainers.org/) 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://.kalix.app/loanproc/1 -H "Content-Type: application/json"

```



Get loan processing:

```

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

```



Approve:

```

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

```

## Increment version

In `pom.xml` in `1.1-SNAPSHOT` 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](https://github.com/lightbend/kalix-proxy/issues/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](https://www.testcontainers.org/) 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://.kalix.app/loanproc/views/by-status -H "Content-Type: application/json"

```



# Event driven communication



## Increment version

In `pom.xml` in `1.2-SNAPSHOT` 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](https://www.testcontainers.org/) 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://.kalix.app/loanapp/2 -H "Content-Type: application/json"

```

Approve loan processing:

```

curl -XPUT -d '{

"reviewer_id": "9999"

}' https://.kalix.app/loanproc/2/approve -H "Content-Type: application/json"

```

Get loan application :

```

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

```