Skip to content

Commit dda771f

Browse files
sleipnirsleipnir
committed
Better api and javadoc
1 parent d53671f commit dda771f

File tree

8 files changed

+234
-54
lines changed

8 files changed

+234
-54
lines changed

‎README.md

+20-23
Original file line numberDiff line numberDiff line change
@@ -462,29 +462,28 @@ public final class Joe {
462462
}
463463
```
464464

465-
Then you also need to register your Actor passing arguments like as follows:
465+
Then you also need to register your Actor passing arguments like as follows:
466466

467467
```java
468468
package io.eigr.spawn.java.demo;
469469

470470
import io.eigr.spawn.api.Spawn;
471-
import io.eigr.spawn.api.actors.ActorRef;
472471

473472
import java.util.HashMap;
474473
import java.util.Map;
475474

476475
public class App {
477-
public static void main(String[] args) {
478-
Map<String, String> actorConstructorArgs = new HashMap<>();
479-
actorConstructorArgs.put("someKey", "someValue");
480-
481-
Spawn spawnSystem = new Spawn.SpawnSystem()
482-
.create("spawn-system")
483-
.withActor(Joe.class, actorConstructorArgs, arg -> new Joe((Map<String, String>) arg))
484-
.build();
476+
public static void main(String[] args) {
477+
Map<String, String> actorConstructorArgs = new HashMap<>();
478+
actorConstructorArgs.put("someKey", "someValue");
485479

486-
spawnSystem.start();
487-
}
480+
Spawn spawnSystem = new Spawn.SpawnSystem()
481+
.create("spawn-system")
482+
.withActor(Joe.class, actorConstructorArgs, arg -> new Joe((Map<String, String>) arg))
483+
.build();
484+
485+
spawnSystem.start();
486+
}
488487
}
489488
```
490489

@@ -635,9 +634,9 @@ See an example:
635634
```Java
636635
package io.eigr.spawn.java.demo;
637636

637+
import io.eigr.spawn.api.ActorRef;
638638
import io.eigr.spawn.api.actors.Value;
639639
import io.eigr.spawn.api.actors.ActorContext;
640-
import io.eigr.spawn.api.actors.ActorRef;
641640
import io.eigr.spawn.api.actors.annotations.Action;
642641
import io.eigr.spawn.api.actors.annotations.stateful.StatefulNamedActor;
643642
import io.eigr.spawn.api.actors.workflows.SideEffect;
@@ -683,7 +682,7 @@ package io.eigr.spawn.java.demo;
683682

684683
import io.eigr.spawn.api.actors.Value;
685684
import io.eigr.spawn.api.actors.ActorContext;
686-
import io.eigr.spawn.api.actors.ActorRef;
685+
import io.eigr.spawn.api.ActorRef;
687686
import io.eigr.spawn.api.actors.annotations.Action;
688687
import io.eigr.spawn.api.actors.annotations.stateful.StatefulNamedActor;
689688
import io.eigr.spawn.api.actors.workflows.Forward;
@@ -725,7 +724,7 @@ package io.eigr.spawn.java.demo;
725724

726725
import io.eigr.spawn.api.actors.Value;
727726
import io.eigr.spawn.api.actors.ActorContext;
728-
import io.eigr.spawn.api.actors.ActorRef;
727+
import io.eigr.spawn.api.ActorRef;
729728
import io.eigr.spawn.api.actors.annotations.Action;
730729
import io.eigr.spawn.api.actors.annotations.stateful.StatefulNamedActor;
731730
import io.eigr.spawn.api.actors.workflows.Pipe;
@@ -848,22 +847,20 @@ package io.eigr.spawn.java.demo;
848847

849848
import io.eigr.spawn.api.Spawn;
850849
import io.eigr.spawn.api.Spawn.SpawnSystem;
851-
import io.eigr.spawn.api.actors.ActorRef;
850+
import io.eigr.spawn.api.ActorRef;
852851
import io.eigr.spawn.api.TransportOpts;
853852
import io.eigr.spawn.java.demo.domain.Domain;
854853

855-
import java.util.Optional;
856-
857854
public class App {
858855
public static void main(String[] args) throws Exception {
859856
Spawn spawnSystem = new SpawnSystem()
860857
.create("spawn-system")
861858
.withActor(Joe.class)
862859
.withTransportOptions(
863-
TransportOpts.builder()
864-
.port(8091)
865-
.proxyPort(9003)
866-
.build()
860+
TransportOpts.builder()
861+
.port(8091)
862+
.proxyPort(9003)
863+
.build()
867864
)
868865
.build();
869866

@@ -944,7 +941,7 @@ just a fire-and-forget call.
944941
Therefore, to call an actor's function asynchronously, just use the invokeAsync method:
945942

946943
```Java
947-
mike.invokeAsync("setLanguage", msg, Domain.Reply.class);
944+
mike.invokeAsync("setLanguage", msg);
948945
```
949946

950947
## Deploy

‎src/main/java/io/eigr/spawn/api/actors/ActorRef.java renamed to ‎src/main/java/io/eigr/spawn/api/ActorRef.java

+122-22
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package io.eigr.spawn.api.actors;
1+
package io.eigr.spawn.api;
22

33
import com.github.benmanes.caffeine.cache.Cache;
44
import com.github.benmanes.caffeine.cache.Caffeine;
@@ -7,7 +7,6 @@
77
import com.google.protobuf.GeneratedMessageV3;
88
import io.eigr.functions.protocol.Protocol;
99
import io.eigr.functions.protocol.actors.ActorOuterClass;
10-
import io.eigr.spawn.api.InvocationOpts;
1110
import io.eigr.spawn.api.exceptions.ActorInvokeException;
1211
import io.eigr.spawn.api.exceptions.ActorNotFoundException;
1312
import io.eigr.spawn.internal.transport.client.SpawnClient;
@@ -16,6 +15,12 @@
1615
import java.util.Objects;
1716
import java.util.Optional;
1817

18+
/**
19+
* ActorRef is responsible for representing an instance of an Actor
20+
*
21+
* @author Adriano Santos
22+
*
23+
*/
1924
public final class ActorRef {
2025
private static final int CACHE_MAXIMUM_SIZE = 1_000;
2126
private static final int CACHE_EXPIRE_AFTER_WRITE_SECONDS = 60;
@@ -32,8 +37,17 @@ private ActorRef(ActorOuterClass.ActorId actorId, SpawnClient client) {
3237
this.client = client;
3338
this.actorId = actorId;
3439
}
35-
36-
public static ActorRef of(SpawnClient client, String system, String name) throws Exception {
40+
41+
/**
42+
* <p>This method is responsible for creating instances of the ActorRef class
43+
* </p>
44+
* @param client is the client part of the Spawn protocol and is responsible for communicating with the Proxy.
45+
* @param system ActorSystem name of the actor that this ActorRef instance should represent
46+
* @param name the name of the actor that this ActorRef instance should represent
47+
* @return the ActorRef instance
48+
* @since 0.0.1
49+
*/
50+
protected static ActorRef of(SpawnClient client, String system, String name) throws Exception {
3751
ActorOuterClass.ActorId actorId = buildActorId(system, name);
3852
ActorRef ref = ACTOR_REF_CACHE.getIfPresent(actorId);
3953
if (Objects.nonNull(ref)){
@@ -45,7 +59,17 @@ public static ActorRef of(SpawnClient client, String system, String name) throws
4559
return ref;
4660
}
4761

48-
public static ActorRef of(SpawnClient client, String system, String name, String parent) throws Exception {
62+
/**
63+
* <p>This method is responsible for creating instances of the ActorRef class when Actor is a UnNamed actor.
64+
* </p>
65+
* @param client is the client part of the Spawn protocol and is responsible for communicating with the Proxy.
66+
* @param system ActorSystem name of the actor that this ActorRef instance should represent
67+
* @param name the name of the actor that this ActorRef instance should represent
68+
* @param parent the name of the unnamed parent actor
69+
* @return the ActorRef instance
70+
* @since 0.0.1
71+
*/
72+
protected static ActorRef of(SpawnClient client, String system, String name, String parent) throws Exception {
4973
ActorOuterClass.ActorId actorId = buildActorId(system, name, parent);
5074
ActorRef ref = ACTOR_REF_CACHE.getIfPresent(actorId);
5175
if (Objects.nonNull(ref)){
@@ -58,70 +82,146 @@ public static ActorRef of(SpawnClient client, String system, String name, String
5882
return ref;
5983
}
6084

61-
public <T extends GeneratedMessageV3> Optional<Object> invoke(String cmd, Class<T> outputType) throws Exception {
62-
Optional<Object> res = invokeActor(cmd, Empty.getDefaultInstance(), outputType, Optional.empty());
85+
/**
86+
* <p>This method synchronously invokes an action on the actor that this ActorRef instance represents through the Spawn Proxy.
87+
* Used when it is not necessary to send parameters to the Action.
88+
* </p>
89+
* @param action name of the action to be called.
90+
* @param outputType the class that corresponds to the expected return type
91+
* @return an Optional containing, or not, the response object to the Action call
92+
* @since 0.0.1
93+
*/
94+
public <T extends GeneratedMessageV3> Optional<Object> invoke(String action, Class<T> outputType) throws Exception {
95+
Optional<Object> res = invokeActor(action, Empty.getDefaultInstance(), outputType, Optional.empty());
6396
if(res.isPresent() ){
6497
return Optional.of(outputType.cast(res.get()));
6598
}
6699

67100
return res;
68101
}
69102

70-
public <T extends GeneratedMessageV3> Optional<Object> invoke(String cmd, Class<T> outputType, InvocationOpts opts) throws Exception {
71-
Optional<Object> res = invokeActor(cmd, Empty.getDefaultInstance(), outputType, Optional.ofNullable(opts));
103+
/**
104+
* <p>This method synchronously invokes an action on the actor that this ActorRef instance represents through the Spawn Proxy.
105+
* Used when it is not necessary to send parameters to the Action.
106+
* </p>
107+
* @param action name of the action to be called.
108+
* @param outputType the class that corresponds to the expected return type
109+
* @param opts options that can be passed during the invocation of the Action.
110+
* Please see the {@link io.eigr.spawn.api.InvocationOpts} class for more information
111+
* @return an Optional containing, or not, the response object to the Action call
112+
* @since 0.0.1
113+
*/
114+
public <T extends GeneratedMessageV3> Optional<Object> invoke(String action, Class<T> outputType, InvocationOpts opts) throws Exception {
115+
Optional<Object> res = invokeActor(action, Empty.getDefaultInstance(), outputType, Optional.ofNullable(opts));
72116
if(res.isPresent() ){
73117
return Optional.of(outputType.cast(res.get()));
74118
}
75119

76120
return res;
77121
}
78122

79-
public <T extends GeneratedMessageV3, S extends GeneratedMessageV3> Optional<Object> invoke(String cmd, S value, Class<T> outputType) throws Exception {
80-
Optional<Object> res = invokeActor(cmd, value, outputType, Optional.empty());
123+
/**
124+
* <p>This method synchronously invokes an action on the actor that this ActorRef instance represents through the Spawn Proxy.
125+
* Used when it is not necessary to send parameters to the Action.
126+
* </p>
127+
* @param action name of the action to be called.
128+
* @param value the action argument object.
129+
* @param outputType the class that corresponds to the expected return type
130+
* @return an Optional containing, or not, the response object to the Action call
131+
* @since 0.0.1
132+
*/
133+
public <T extends GeneratedMessageV3, S extends GeneratedMessageV3> Optional<Object> invoke(String action, S value, Class<T> outputType) throws Exception {
134+
Optional<Object> res = invokeActor(action, value, outputType, Optional.empty());
81135
if(res.isPresent() ){
82136
return Optional.of(outputType.cast(res.get()));
83137
}
84138

85139
return res;
86140
}
87141

88-
public <T extends GeneratedMessageV3, S extends GeneratedMessageV3> Optional<Object> invoke(String cmd, S value, Class<T> outputType, InvocationOpts opts) throws Exception {
89-
Optional<Object> res = invokeActor(cmd, value, outputType, Optional.ofNullable(opts));
142+
/**
143+
* <p>This method synchronously invokes an action on the actor that this ActorRef instance represents through the Spawn Proxy.
144+
* Used when it is not necessary to send parameters to the Action.
145+
* </p>
146+
* @param action name of the action to be called.
147+
* @param value the action argument object.
148+
* @param outputType the class that corresponds to the expected return type
149+
* @param opts options that can be passed during the invocation of the Action.
150+
* Please see the {@link io.eigr.spawn.api.InvocationOpts} class for more information
151+
* @return an Optional containing, or not, the response object to the Action call
152+
* @since 0.0.1
153+
*/
154+
public <T extends GeneratedMessageV3, S extends GeneratedMessageV3> Optional<Object> invoke(String action, S value, Class<T> outputType, InvocationOpts opts) throws Exception {
155+
Optional<Object> res = invokeActor(action, value, outputType, Optional.ofNullable(opts));
90156
if(res.isPresent() ){
91157
return Optional.of(outputType.cast(res.get()));
92158
}
93159

94160
return res;
95161
}
96162

97-
public <T extends GeneratedMessageV3> void invokeAsync(String cmd, Class<T> outputType) throws Exception {
163+
/**
164+
* <p>This method asynchronously invokes an action on the actor that this ActorRef instance represents via the Spawn Proxy.
165+
* Used when it is not necessary to send parameters to the Action.
166+
* </p>
167+
* @param action name of the action to be called.
168+
* @since 0.0.1
169+
*/
170+
public <T extends GeneratedMessageV3> void invokeAsync(String action) throws Exception {
98171
InvocationOpts opts = InvocationOpts.builder().async(true).build();
99-
invokeActor(cmd, Empty.getDefaultInstance(), outputType, Optional.of(opts));
172+
invokeActor(action, Empty.getDefaultInstance(), null, Optional.of(opts));
100173
}
101174

102-
public <T extends GeneratedMessageV3> void invokeAsync(String cmd, Class<T> outputType, InvocationOpts opts) throws Exception {
175+
/**
176+
* <p>This method asynchronously invokes an action on the actor that this ActorRef instance represents via the Spawn Proxy.
177+
* Used when it is not necessary to send parameters to the Action.
178+
* </p>
179+
* @param action name of the action to be called.
180+
* @param opts options that can be passed during the invocation of the Action.
181+
* Please see the {@link io.eigr.spawn.api.InvocationOpts} class for more information
182+
* @since 0.0.1
183+
*/
184+
public <T extends GeneratedMessageV3> void invokeAsync(String action, InvocationOpts opts) throws Exception {
103185
InvocationOpts mergedOpts = InvocationOpts.builder()
104186
.async(true)
105187
.delay(opts.getDelay())
106188
.scheduledTo(opts.getScheduledTo())
107189
.build();
108190

109-
invokeActor(cmd, Empty.getDefaultInstance(), outputType, Optional.ofNullable(mergedOpts));
191+
invokeActor(action, Empty.getDefaultInstance(), null, Optional.ofNullable(mergedOpts));
110192
}
111193

112-
public <T extends GeneratedMessageV3, S extends GeneratedMessageV3> void invokeAsync(String cmd, S value, Class<T> outputType) throws Exception {
194+
/**
195+
* <p>This method asynchronously invokes an action on the actor that this ActorRef instance represents through the Spawn Proxy.
196+
* Used when it is not necessary to send parameters to the Action.
197+
* </p>
198+
* @param action name of the action to be called.
199+
* @param value the action argument object.
200+
* @since 0.0.1
201+
*/
202+
public <T extends GeneratedMessageV3, S extends GeneratedMessageV3> void invokeAsync(String action, S value) throws Exception {
113203
InvocationOpts opts = InvocationOpts.builder().async(true).build();
114-
invokeActor(cmd, value, outputType, Optional.of(opts));
204+
invokeActor(action, value, null, Optional.of(opts));
115205
}
116206

117-
public <T extends GeneratedMessageV3, S extends GeneratedMessageV3> void invokeAsync(String cmd, S value, Class<T> outputType, InvocationOpts opts) throws Exception {
207+
/**
208+
* <p>This method asynchronously invokes an action on the actor that this ActorRef instance represents through the Spawn Proxy.
209+
* Used when it is not necessary to send parameters to the Action.
210+
* </p>
211+
* @param action name of the action to be called.
212+
* @param value the action argument object.
213+
* @param opts options that can be passed during the invocation of the Action.
214+
* Please see the {@link io.eigr.spawn.api.InvocationOpts} class for more information
215+
* @since 0.0.1
216+
*/
217+
public <T extends GeneratedMessageV3, S extends GeneratedMessageV3> void invokeAsync(String action, S value, InvocationOpts opts) throws Exception {
118218
InvocationOpts mergedOpts = InvocationOpts.builder()
119219
.async(true)
120220
.delay(opts.getDelay())
121221
.scheduledTo(opts.getScheduledTo())
122222
.build();
123223

124-
invokeActor(cmd, value, outputType, Optional.of(mergedOpts));
224+
invokeActor(action, value, null, Optional.of(mergedOpts));
125225
}
126226

127227
public String getActorSystem() {
@@ -187,7 +287,7 @@ private <T extends GeneratedMessageV3, S extends GeneratedMessageV3> Optional<Ob
187287
case ACTOR_NOT_FOUND:
188288
throw new ActorNotFoundException();
189289
case OK:
190-
if (resp.hasValue()) {
290+
if (resp.hasValue() && Objects.nonNull(outputType)) {
191291
return Optional.of(resp.getValue().unpack(outputType));
192292
}
193293
return Optional.empty();

0 commit comments

Comments
 (0)