Process overview
The main steps in developing a service include:
Specify service interface and domain model
The main components of a Kalix service are:
We recommend that you separate the service API and Entity domain data model in individual .proto files, as gRPC descriptors. Separating the service interface and data model in different files allows you to evolve them independently.
The gRPC definitions in .proto files describe the external interface, messages, and events. From the .proto files, the gRPC CLI (protoc), generates the code framework for remote procedure calls, data access, and serialization. Take a look at Writing gRPC descriptors for more information about defining messages and events.
| Kickstart a project using the project template. |
Understanding what an Effect is
Each component defines a set of operations through its application programming interface (API). These operations are specific to the semantics of each component. For the JVM SDKs, these APIs take the shape of an Effect.
An Effect is a description of what Kalix needs to do after an incoming command is handled. You can think of it as a set of instructions you are passing to Kalix. Kalix will process the instructions on your behalf.
The component Effect APIs play a central role when implementing a component as it provides the glue between your application logic and Kalix. For a more high-level overview of Kalix Architecture Style, check out the Programming model page.
The details of each component Effect type are explained in the component’s specific pages.
Implement components
Stateful services can implement Value Entity or Event Sourced Entity and View components. Stateless services implement Actions. Typically, a stateful service should only have one Entity type, but can also include Actions and Views.
Actions
Actions are stateless functions that can be triggered by gRPC or HTTP calls. They can also subscribe to published events, and they can send commands to other services based on the events they receive. For more information about writing actions see Implementing Actions.
Entities
Stateful services encapsulate business logic in Value Entities or Event Sourced Entities. At runtime, command messages invoke operations on Entities. A command may only act on one Entity at a time.
| To learn more about Kalix entities see Implementing Value Entities, Implementing Event Sourced Entities, and Implementing Replicated Entities. |
If you would like to update multiple Entities from a single command, you can use forwarding and side effects.
| For more information see Actions as Controllers and Running Side Effects. |
Services can interact asynchronously with other services and with external systems. Event Sourced Entities emit events to a journal, to which other services can subscribe. By configuring your own publish/subscribe (pub/sub) mechanism, any service can publish their own events and subscribe to events published by other services or external systems.
Views
A View provides a way to retrieve state from multiple Entities based on a query. You can create views from Value Entity state, Event Sourced Entity events, and by subscribing to topics. For more information about writing views see Implementing Views.
For more details and examples take a look at the following topics:
Create unit tests
It is good practice to write unit tests as you implement your services. The kickstart codegen project includes hooks for JUnit testing. For implementation details see the Project template - Create unit tests topic.
Package service
Use Docker to package your service and any of its dependencies. See Configuring registries for more information.
Run locally
You can test and debug your services by running them locally before deploying to Kalix.