Skip to content

Commit f84e4da

Browse files
greenie-msftgreenie-msft
committed
Update Actors documentation to parking garage scenario
1 parent 8009fb4 commit f84e4da

File tree

1 file changed

+72
-118
lines changed
  • daprdocs/content/en/js-sdk-docs/js-actors

1 file changed

+72
-118
lines changed

‎daprdocs/content/en/js-sdk-docs/js-actors/_index.md‎

Lines changed: 72 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ weight: 1000
66
description: How to get up and running with Actors using the Dapr JavaScript SDK
77
---
88

9-
The Dapr actors package allows you to interact with Dapr virtual actors from a JavaScript application. The below examples demonstarte how to use the JavaScript SDK for interacting with virtual actors.
9+
The Dapr actors package allows you to interact with Dapr virtual actors from a JavaScript application. The examples below demonstrate how to use the JavaScript SDK for interacting with virtual actors.
1010

1111
For a more in-depth overview of Dapr actors and supported scenarios, visit the [actors overview page]({{< ref actors-overview >}}).
1212

@@ -16,35 +16,53 @@ For a more in-depth overview of Dapr actors and supported scenarios, visit the [
1616
- [Latest LTS version of Node or greater](https://nodejs.org/en/) d
1717
- [JavaScript NPM package installed](https://www.npmjs.com/package/dapr-client)
1818

19+
## Code Scenario
20+
The below code examples loosely describe the scenario of a Parking Garage Spot Monitoring System, which can be explained in detail by Mark Russinovich in [this video](https://www.youtube.com/watch?v=eJCu6a-x9uo&t=3785). The parking garage consists of hundreds of parking spots, where each parking spot includes a sensor that provides updates to a centralized monitoring system. The parking space sensors (our actors) detect if a parking space is occupied, or available.
21+
22+
To run this example, source code can be found [here](https://github.com/XavierGeerinck/js-sdk/tree/23e1f0ee2bd4c60a4906e38427547c4b3840f89e/examples/http/actor-parking-sensor).
23+
1924
## Actor Interface
20-
The actor interface defines the contract that is shared between the actor implementation and the clients calling the actor.
25+
The actor interface defines the contract that is shared between the actor implementation and the clients calling the actor. In the example below, we have created an interace for a parking garage sensor. Each sensor has 2 methods: carEnter and carLeave, which defines the state of the sensor:
2126

2227
```javascript
23-
export default interface ActorSayInterface {
24-
say(msg: string): string;
28+
export default interface ParkingSensorInterface {
29+
carEnter(): Promise<void>;
30+
carLeave(): Promise<void>;
2531
}
2632
```
2733

2834
## Actor Implementation
29-
An actor implementation defines a class by extending the base type `AbstractActor` and implements the interfaces defined in the actor interface.
35+
An actor implementation defines a class by extending the base type `AbstractActor` and implements the interfaces defined in the actor interface. The example below implements the methods defined in the `ParkingSensorInterface`, but also adds extra helper methods:
3036

3137
```javascript
3238
import { AbstractActor } from "dapr-client";
33-
import ActorSayInterface from "./ActorSayInterface";
39+
import ParkingSensorInterface from "./ParkingSensorInterface";
3440

35-
export default class ActorSayImp extends AbstractActor implements ActorSayInterface {
36-
say(msg: string): string {
37-
return `Actor said: "${msg}"`;
38-
}
41+
export default class ParkingSensorImpl extends AbstractActor implements ParkingSensorInterface {
42+
async carEnter(): Promise<void> {
43+
// Implementation that updates state that this parking spaces is occupied.
44+
}
45+
46+
async carLeave(): Promise<void> {
47+
// Implementation that updates state that this parking spaces is available.
48+
}
49+
50+
async getParkingSpaceUpdate(): Promise<object> {
51+
// Implementation of requesting an update from the parking space sensor.
52+
}
53+
54+
async onActivate(): Promise<void> {
55+
// Initialization logic called by AbstractActor.
56+
}
3957
}
4058
```
4159

42-
## Invoking Actors
43-
Use the DaprServer package to create your actors bindings, which will initalize and register your actors. After Actors are registered, use the DaprClient to invoke methods on an actor. The client will call the actor methods defined in the actor interface.
60+
## Registering Actors
61+
Use the DaprServer package to create your actors bindings, which will initalize and register your actors.
4462

4563
```javascript
4664
import { DaprServer, DaprClient } from "dapr-client";
47-
import ActorSayImp from "./actor/ActorSayImp";
65+
import ParkingSensorImpl from "./ParkingSensorImpl";
4866

4967
const daprHost = "127.0.0.1";
5068
const daprPort = "50000"; // Dapr Sidecar Port of this Example Server
@@ -53,68 +71,49 @@ const serverPort = "50001"; // App Port of this Example Server
5371

5472
async function start() {
5573
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort);
56-
const client = new DaprClient(daprHost, daprPort);
5774

58-
// Creating actor bindings
59-
await server.actor.init();
60-
server.actor.registerActor(ActorSayImp);
75+
await server.actor.init(); // Let the server know we need actors
76+
server.actor.registerActor(ParkingSensorImpl); // Register the actor
77+
await server.startServer(); // Start the server
78+
```
6179
62-
const actorId = "actor-id";
80+
## Invoking Actors
81+
After Actors are registered, use the DaprClient to invoke methods on an actor. The client will call the actor methods defined in the actor interface.
6382
64-
await server.startServer();
83+
```javascript
84+
...
85+
// Initialize Dapr client
86+
const client = new DaprClient(daprHost, daprPort);
6587

66-
// Invoke method 'say' with msg 'Hello World'");
67-
const resActorInvokeSay = await client.actor.invoke("PUT", ActorSayImp.name, actorId, "method-to-invoke", "Hello World");
68-
}
88+
await client.actor.invoke("PUT", ParkingSensorImpl.name, `actor-id`, "carEnter");
89+
...
6990
```
7091
7192
## Saving and Getting State
7293
7394
```javascript
74-
import { DaprServer, DaprClient } from "dapr-client";
75-
import StateActor from "./actor/StateActor";
76-
77-
const daprHost = "127.0.0.1";
78-
const daprPort = "50000"; // Dapr Sidecar Port of this Example Server
79-
const serverHost = "127.0.0.1"; // App Host of this Example Server
80-
const serverPort = "50001"; // App Port of this Example Server
81-
82-
async function start() {
83-
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort);
84-
const client = new DaprClient(daprHost, daprPort);
85-
86-
// Creating actor bindings
87-
await server.actor.init();
88-
server.actor.registerActor(StateActor);
89-
await server.startServer();
90-
91-
const actorId = "actor-id";
92-
93-
await client.actor.stateTransaction("StateActor", actorId, [
95+
...
96+
await client.actor.stateTransaction("ParkingSensorImpl", `actor-id`, [
9497
{
9598
operation: "upsert",
9699
request: {
97-
key: "first-key",
98-
value: "hello"
100+
key: "parking-sensor-location-lat",
101+
value: "location-x"
99102
}
100103
},
101104
{
102105
operation: "upsert",
103106
request: {
104-
key: "second-key",
105-
value: "world"
106-
}
107-
},
108-
{
109-
operation: "delete",
110-
request: {
111-
key: "second-key"
107+
key: "parking-sensor-location-lang",
108+
value: "location-y"
112109
}
113110
}
114111
]);
115112

116-
const ActorStateGet = await client.actor.stateGet("StateActor", actorId, "first-key");
117-
}
113+
114+
await client.actor.stateGet("ParkingSensorImpl", `actor-id`, `parking-sensor-location-lat`)
115+
await client.actor.stateGet("ParkingSensorImpl", `actor-id`, `parking-sensor-location-lang`)
116+
...
118117
```
119118
120119
## Actor Timers and Reminders
@@ -126,75 +125,30 @@ The scheduling interface of timers and reminders is identical. For an more in-de
126125
127126
### Actor Timers
128127
```javascript
129-
import { DaprServer, DaprClient } from "dapr-client";
130-
import ActorTimerImpl from "./actor/ActorTimerImpl";
131-
132-
const daprHost = "127.0.0.1";
133-
const daprPort = "50000"; // Dapr Sidecar Port of this Example Server
134-
const serverHost = "127.0.0.1"; // App Host of this Example Server
135-
const serverPort = "50001"; // App Port of this Example Server
136-
137-
async function start() {
138-
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort);
139-
const client = new DaprClient(daprHost, daprPort);
140-
141-
// Creating actor bindings
142-
await server.actor.init();
143-
server.actor.registerActor(ActorTimerImpl);
144-
await server.startServer();
145-
146-
const actorId = "actor-id";
147-
const timerId = "actor-timer-id";
148-
149-
// Activate actor
150-
await client.actor.invoke("PUT", ActorTimerImpl.name, actorId, "init");
151-
152-
// Register a timer
153-
await client.actor.timerCreate(ActorTimerImpl.name, actorId, timerId, {
154-
callback: "method-to-excute-on-actor",
155-
dueTime: Temporal.Duration.from({ seconds: 2 }),
156-
period: Temporal.Duration.from({ seconds: 1 })
157-
});
158-
159-
// Delete the timer
160-
await client.actor.timerDelete(ActorTimerImpl.name, actorId, timerId);
128+
...
129+
// Register a timer
130+
await client.actor.timerCreate(ParkingSensorImpl.name, `actor-id`, `timer-id`, {
131+
callback: "method-to-excute-on-actor",
132+
dueTime: Temporal.Duration.from({ seconds: 2 }),
133+
period: Temporal.Duration.from({ seconds: 1 })
134+
});
135+
136+
// Delete the timer
137+
await client.actor.timerDelete(ParkingSensorImpl.name, `actor-id`, `timer-id`);
161138
}
162139
```
163140

164141
### Actor Reminders
165142
```javascript
166-
import { DaprServer, DaprClient } from "dapr-client";
167-
import ActorReminderImpl from "./actor/ActorReminderImpl";
168-
169-
const daprHost = "127.0.0.1";
170-
const daprPort = "50000"; // Dapr Sidecar Port of this Example Server
171-
const serverHost = "127.0.0.1"; // App Host of this Example Server
172-
const serverPort = "50001"; // App Port of this Example Server
173-
174-
async function start() {
175-
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort);
176-
const client = new DaprClient(daprHost, daprPort);
177-
178-
// Creating actor bindings
179-
await server.actor.init();
180-
server.actor.registerActor(ActorReminderImpl);
181-
await server.startServer();
182-
183-
const actorId = "actor-id";
184-
const reminderId = "actor-timer-id";
185-
186-
// Activate our actor
187-
await client.actor.invoke("PUT", ActorReminderImpl.name, actorId, "init");
188-
189-
// Register a reminder, it has a default callback
190-
await client.actor.reminderCreate(ActorReminderImpl.name, actorId, reminderId, {
191-
dueTime: Temporal.Duration.from({ seconds: 2 }),
192-
period: Temporal.Duration.from({ seconds: 1 }),
193-
data: 100
194-
});
195-
196-
// Delete the reminder
197-
await client.actor.reminderDelete(ActorReminderImpl.name, actorId, reminderId);
143+
// Register a reminder, it has a default callback
144+
await client.actor.reminderCreate(DemoActorImpl.name, `actor-id`, `timer-id`, {
145+
dueTime: Temporal.Duration.from({ seconds: 2 }),
146+
period: Temporal.Duration.from({ seconds: 1 }),
147+
data: 100
148+
});
149+
150+
// Delete the reminder
151+
await client.actor.reminderDelete(DemoActorImpl.name, `actor-id`, `timer-id`);
198152
```
199153

200154
- For a full guide on actors visit [How-To: Use virtual actors in Dapr]({{< ref howto-actors.md >}}).

0 commit comments

Comments
 (0)