Skip to content

Commit 9dcbdd8

Browse files
Document all event-stream-rpc classes (#317)
Add documentation to all event-stream-rpc classes.
1 parent 472d0ec commit 9dcbdd8

35 files changed

+542
-110
lines changed

sdk/greengrass/event-stream-rpc-client/src/main/java/software/amazon/awssdk/eventstreamrpc/EventStreamRPCClient.java

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ public class EventStreamRPCClient {
2323
private static final Logger LOGGER = Logger.getLogger(EventStreamRPCClient.class.getName());
2424
private final EventStreamRPCConnection connection;
2525

26+
/**
27+
* Creates a new EventStreamRPCClient
28+
* @param connection The connection for the EventStreamRPCClient to use
29+
*/
2630
public EventStreamRPCClient(EventStreamRPCConnection connection) {
2731
if (connection == null) {
2832
throw new IllegalArgumentException("Cannot create eventstream RPC client with null connection");
@@ -32,8 +36,14 @@ public EventStreamRPCClient(EventStreamRPCConnection connection) {
3236

3337
/**
3438
* Work horse of all operations, streaming or otherwise.
35-
*
36-
* @return
39+
* @param <ReqType> The request type
40+
* @param <RespType> The response type
41+
* @param <StrReqType> The streaming request type
42+
* @param <StrRespType> The streaming response type
43+
* @param operationModelContext The operation context
44+
* @param request The request
45+
* @param streamResponseHandler The streaming handler
46+
* @return The operation result
3747
*/
3848
public <ReqType extends EventStreamJsonMessage,
3949
RespType extends EventStreamJsonMessage,
@@ -135,7 +145,7 @@ protected void onContinuationMessage(List<Header> headers, byte[] payload, Messa
135145
}
136146
}
137147
}
138-
148+
139149
@Override
140150
protected void onContinuationClosed() {
141151
super.onContinuationClosed();
@@ -159,10 +169,10 @@ protected void onContinuationClosed() {
159169
return response;
160170
}
161171

162-
172+
163173

164174
/**
165-
* Sends an empty close message on the open stream.
175+
* Sends an empty close message on the open stream.
166176
* @param continuation continuation to send the close message on
167177
* @return CompletableFuture indicating flush of the close message.
168178
*/

sdk/greengrass/event-stream-rpc-client/src/main/java/software/amazon/awssdk/eventstreamrpc/EventStreamRPCConnection.java

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,13 @@
1919
import java.util.logging.Logger;
2020
import java.util.stream.Collectors;
2121

22+
/**
23+
* A connection for an EventStreamRPC client
24+
*/
2225
public class EventStreamRPCConnection implements AutoCloseable {
26+
/**
27+
* Class containing the possible connection states of the EventStreamRPCConnection
28+
*/
2329
protected static class ConnectionState {
2430
enum Phase {
2531
DISCONNECTED,
@@ -45,8 +51,15 @@ protected ConnectionState(Phase phase, ClientConnection connection) {
4551
private static final Logger LOGGER = Logger.getLogger(EventStreamRPCConnection.class.getName());
4652

4753
private final EventStreamRPCConnectionConfig config;
54+
/**
55+
* The connection state of the EventStreamRPCConnection
56+
*/
4857
protected ConnectionState connectionState;
4958

59+
/**
60+
* Constructs a new EventStreamRPCConnection from the given configuration
61+
* @param config The configuration used to construct the EventStreamRPCConnection
62+
*/
5063
public EventStreamRPCConnection(final EventStreamRPCConnectionConfig config) {
5164
this.config = config;
5265
this.connectionState = new ConnectionState(ConnectionState.Phase.DISCONNECTED, null);
@@ -63,7 +76,7 @@ protected String getVersionString() {
6376
/**
6477
* Connects to the event stream RPC server asynchronously
6578
*
66-
* @return
79+
* @return A future that completes when connected
6780
*/
6881
public CompletableFuture<Void> connect(final LifecycleHandler lifecycleHandler) {
6982
synchronized (connectionState) {
@@ -206,6 +219,13 @@ protected void onConnectionClosed(int errorCode) {
206219
return initialConnectFuture;
207220
}
208221

222+
/**
223+
* Creates a new stream with the given continuation handler.
224+
* Trhows an exception if not connected
225+
*
226+
* @param continuationHandler The continuation handler to use
227+
* @return A new ClientConnectionContinuation containing the new stream.
228+
*/
209229
public ClientConnectionContinuation newStream(ClientConnectionContinuationHandler continuationHandler) {
210230
synchronized (connectionState) {
211231
if (connectionState.connectionPhase == ConnectionState.Phase.CONNECTED) {
@@ -216,6 +236,9 @@ public ClientConnectionContinuation newStream(ClientConnectionContinuationHandle
216236
}
217237
}
218238

239+
/**
240+
* Disconnects the EventStreamRPCConnection
241+
*/
219242
public void disconnect() {
220243
synchronized (connectionState) {
221244
if (connectionState.connectionPhase != ConnectionState.Phase.CLOSING &&
@@ -269,8 +292,8 @@ private void doOnDisconnect(LifecycleHandler lifecycleHandler, int errorCode) {
269292
/**
270293
* Interface to send ping. Optional MessageAmendInfo will use the headers and payload
271294
* for the ping message verbatim. Should trigger a pong response and server copies back
272-
* @param pingData
273-
* @return
295+
* @param pingData The ping data to send
296+
* @return A future that completes when the pong response is receieved
274297
*/
275298
public CompletableFuture<Void> sendPing(Optional<MessageAmendInfo> pingData) {
276299
ClientConnection connection;
@@ -291,8 +314,8 @@ public CompletableFuture<Void> sendPing(Optional<MessageAmendInfo> pingData) {
291314
/**
292315
* Interface to send pingResponse. Optional MessageAmendInfo will use the headers and payload
293316
* for the ping message verbatim. Should trigger a pong response and server copies back
294-
* @param pingResponseData
295-
* @return
317+
* @param pingResponseData The ping response data to send
318+
* @return A future that completes when the pong response is receieved
296319
*/
297320
public CompletableFuture<Void> sendPingResponse(Optional<MessageAmendInfo> pingResponseData) {
298321
ClientConnection connection;
@@ -329,7 +352,7 @@ public interface LifecycleHandler {
329352
/**
330353
* Invoked for both connect failures and disconnects from a healthy state
331354
*
332-
* @param errorCode
355+
* @param errorCode A code indicating the reason for the disconnect
333356
*/
334357
void onDisconnect(int errorCode);
335358

@@ -348,11 +371,14 @@ public interface LifecycleHandler {
348371
*/
349372
boolean onError(Throwable t);
350373

351-
/**
352-
* Do nothing on ping by default. Inform handler of ping data
374+
/**
375+
* Do nothing on ping by default. Inform handler of ping data
353376
*
354377
* TODO: Could use boolean return here as a hint on whether a pong reply should be sent?
355-
*/
378+
*
379+
* @param headers The ping headers
380+
* @param payload The ping payload
381+
*/
356382
default void onPing(List<Header> headers, byte[] payload) { };
357383
}
358384
}

sdk/greengrass/event-stream-rpc-client/src/main/java/software/amazon/awssdk/eventstreamrpc/EventStreamRPCConnectionConfig.java

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,16 @@ public class EventStreamRPCConnectionConfig {
3131
*/
3232
private final Supplier<CompletableFuture<MessageAmendInfo>> connectMessageAmender;
3333

34+
/**
35+
* Creates a new EventStreamRPCConnectionConfig with the given data
36+
* @param clientBootstrap The ClientBootstrap to use
37+
* @param eventLoopGroup The EventLoopGroup to use
38+
* @param socketOptions The SocketOptions to use
39+
* @param tlsContext The TlsContext to use
40+
* @param host The host name to use
41+
* @param port The host port to use
42+
* @param connectMessageAmender The connect message amender to use
43+
*/
3444
public EventStreamRPCConnectionConfig(ClientBootstrap clientBootstrap, EventLoopGroup eventLoopGroup,
3545
SocketOptions socketOptions, ClientTlsContext tlsContext,
3646
String host, int port, Supplier<CompletableFuture<MessageAmendInfo>> connectMessageAmender) {
@@ -52,30 +62,58 @@ public EventStreamRPCConnectionConfig(ClientBootstrap clientBootstrap, EventLoop
5262
}
5363
}
5464

65+
/**
66+
* Returns the ClientBootstrap associated with the EventStreamRPCConnectionConfig
67+
* @return the ClientBootstrap associated with the EventStreamRPCConnectionConfig
68+
*/
5569
public ClientBootstrap getClientBootstrap() {
5670
return clientBootstrap;
5771
}
5872

73+
/**
74+
* Returns the EventLoopGroup associated with the EventStreamRPCConnectionConfig
75+
* @return the EventLoopGroup associated with the EventStreamRPCConnectionConfig
76+
*/
5977
public EventLoopGroup getEventLoopGroup() {
6078
return eventLoopGroup;
6179
}
6280

81+
/**
82+
* Returns the SocketOptions associated with the EventStreamRPCConnectionConfig
83+
* @return The SocketOptions associated with the EventStreamRPCConnectionConfig
84+
*/
6385
public SocketOptions getSocketOptions() {
6486
return socketOptions;
6587
}
6688

89+
/**
90+
* Returns the TlsContext associated with the EventStreamRPCConnectionConfig
91+
* @return The TlsContext associated with the EventStreamRPCConnectionConfig
92+
*/
6793
public ClientTlsContext getTlsContext() {
6894
return tlsContext;
6995
}
7096

97+
/**
98+
* Returns the host name associated with the EventStreamRPCConnectionConfig
99+
* @return The host name associated with the EventStreamRPCConnectionConfig
100+
*/
71101
public String getHost() {
72102
return host;
73103
}
74104

105+
/**
106+
* Returns the port associated with the EventStreamRPCConnectionConfig
107+
* @return The port associated with the EventStreamRPCConnectionConfig
108+
*/
75109
public int getPort() {
76110
return port;
77111
}
78112

113+
/**
114+
* Returns the connect message amender associated with the EventStreamRPCConnectionConfig
115+
* @return The connect message amender associated with the EventStreamRPCConnectionConfig
116+
*/
79117
public Supplier<CompletableFuture<MessageAmendInfo>> getConnectMessageAmender() {
80118
return connectMessageAmender;
81119
}

sdk/greengrass/event-stream-rpc-client/src/main/java/software/amazon/awssdk/eventstreamrpc/GreengrassConnectMessageSupplier.java

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,16 @@
99
import java.util.concurrent.CompletableFuture;
1010
import java.util.function.Supplier;
1111

12+
/**
13+
* The connect message supplier for Greengrass
14+
*/
1215
public class GreengrassConnectMessageSupplier {
13-
16+
17+
/**
18+
* Returns a new connect message supplier using the given token
19+
* @param authToken The auth token to use
20+
* @return A new connect message supplier
21+
*/
1422
public static Supplier<CompletableFuture<MessageAmendInfo>> connectMessageSupplier(String authToken) {
1523
return () -> {
1624
final List<Header> headers = new LinkedList<>();

sdk/greengrass/event-stream-rpc-client/src/main/java/software/amazon/awssdk/eventstreamrpc/GreengrassEventStreamConnectMessage.java

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,24 @@
11
package software.amazon.awssdk.eventstreamrpc;
22

3+
/**
4+
* A Greengrass EventStream connection message
5+
*/
36
public class GreengrassEventStreamConnectMessage {
47

58
private String authToken;
69

10+
/**
11+
* Sets the authorization token in the connect message
12+
* @param authToken the authorization token to use
13+
*/
714
public void setAuthToken(String authToken) {
815
this.authToken = authToken;
916
}
1017

18+
/**
19+
* Returns the authorization token in the connect message
20+
* @return authorization token in the connect message
21+
*/
1122
public String getAuthToken() {
1223
return this.authToken;
1324
}

sdk/greengrass/event-stream-rpc-client/src/main/java/software/amazon/awssdk/eventstreamrpc/OperationResponse.java

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@
1717
* client, closing of any open stream, and retrieval of response. Specific generated operation response
1818
* handlers are usually simple wrappers with the generic types specified
1919
*
20-
* @param <ResponseType>
21-
* @param <StreamRequestType>
20+
* @param <ResponseType> The response type
21+
* @param <StreamRequestType> The stream response type
2222
*/
2323
public class OperationResponse<ResponseType extends EventStreamJsonMessage,
2424
StreamRequestType extends EventStreamJsonMessage>
@@ -30,6 +30,13 @@ public class OperationResponse<ResponseType extends EventStreamJsonMessage,
3030
private final CompletableFuture<Void> requestFlushFuture;
3131
private final AtomicBoolean isClosed;
3232

33+
/**
34+
* Creates a new OperationResponse from the given data
35+
* @param operationModelContext The operation model context to use
36+
* @param continuation The continuation to use
37+
* @param responseFuture The response future to use
38+
* @param requestFlushFuture The request flush future to use
39+
*/
3340
public OperationResponse(OperationModelContext<ResponseType, ?, StreamRequestType, ?> operationModelContext,
3441
ClientConnectionContinuation continuation,
3542
CompletableFuture<ResponseType> responseFuture,
@@ -41,6 +48,10 @@ public OperationResponse(OperationModelContext<ResponseType, ?, StreamRequestTyp
4148
this.isClosed = new AtomicBoolean(continuation != null && !continuation.isNull());
4249
}
4350

51+
/**
52+
* Returns the request flush future to use
53+
* @return The request flush future to use
54+
*/
4455
final public CompletableFuture<Void> getRequestFlushFuture() {
4556
return requestFlushFuture;
4657
}
@@ -52,7 +63,8 @@ final public CompletableFuture<Void> getRequestFlushFuture() {
5263
* May throw exception if requestFlushFuture throws an exception and will
5364
* block if requestFlush has not completed.
5465
*
55-
* @return
66+
* @return the response completable future to wait on the initial response
67+
* if there is one.
5668
*/
5769
public CompletableFuture<ResponseType> getResponse() {
5870
//semantics here are: if the request was never successfully sent
@@ -98,7 +110,7 @@ public CompletableFuture<Void> sendStreamEvent(final StreamRequestType streamEve
98110
/**
99111
* Initiate a close on the event stream from the client side.
100112
*
101-
* @return
113+
* @return A future that completes when the event stream is closed
102114
*/
103115
@Override
104116
public CompletableFuture<Void> closeStream() {
@@ -120,7 +132,7 @@ public CompletableFuture<Void> closeStream() {
120132

121133
/**
122134
* Checks if the stream is closed
123-
* @return
135+
* @return True if the stream is closed
124136
*/
125137
public boolean isClosed() {
126138
return isClosed.get();

sdk/greengrass/event-stream-rpc-client/src/main/java/software/amazon/awssdk/eventstreamrpc/StreamResponse.java

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,28 @@
44

55
import java.util.concurrent.CompletableFuture;
66

7+
/**
8+
* Interface for stream responses
9+
*/
710
public interface StreamResponse<ResponseType extends EventStreamJsonMessage, StreamRequestType extends EventStreamJsonMessage>
811
extends StreamEventPublisher<StreamRequestType> {
912
/**
1013
* Completable future indicating flush of the request that initiated the stream operation
1114
*
12-
* @return
15+
* @return Completable future indicating flush of the request that initiated the stream operation
1316
*/
1417
CompletableFuture<Void> getRequestFlushFuture();
1518

1619
/**
1720
* Completable future for retrieving the initial-response of the stream operation
1821
*
19-
* @return
22+
* @return Completable future for retrieving the initial-response of the stream operation
2023
*/
2124
CompletableFuture<ResponseType> getResponse();
2225

2326
/**
2427
* Tests if the stream is closed
25-
* @return
28+
* @return True if the stream is closed
2629
*/
2730
boolean isClosed();
2831
}

0 commit comments

Comments
 (0)