Skip to content

Commit 9b771c6

Browse files
bretambroseBret Ambrose
bretambrose
and
Bret Ambrose
authored
Request response bindings (#860)
Co-authored-by: Bret Ambrose <[email protected]>
1 parent a5c53e6 commit 9b771c6

19 files changed

+2995
-28
lines changed

‎src/main/java/software/amazon/awssdk/crt/CrtRuntimeException.java

+5-1
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,10 @@ public CrtRuntimeException(int errorCode) {
6565

6666
@Override
6767
public String toString() {
68-
return String.format("%s %s(%d)", super.toString(), errorName, errorCode);
68+
if (this.errorCode == -1) {
69+
return super.toString();
70+
} else {
71+
return String.format("%s %s(%d)", super.toString(), errorName, errorCode);
72+
}
6973
}
7074
};

‎src/main/java/software/amazon/awssdk/crt/iot/IncomingPublishEvent.java

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/**
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
* SPDX-License-Identifier: Apache-2.0.
4+
*/
5+
6+
package software.amazon.awssdk.crt.iot;
7+
8+
public class IncomingPublishEvent {
9+
10+
private final byte[] payload;
11+
12+
private final String topic;
13+
14+
private IncomingPublishEvent(byte[] payload, String topic) {
15+
this.payload = payload;
16+
this.topic = topic;
17+
}
18+
19+
/**
20+
* Gets the payload of the IncomingPublishEvent.
21+
*
22+
* @return Payload of the IncomingPublishEvent.
23+
*/
24+
public byte[] getPayload() {
25+
return payload;
26+
}
27+
28+
/**
29+
* Gets the topic of the IncomingPublishEvent.
30+
*
31+
* @return Topic of the IncomingPublishEvent.
32+
*/
33+
public String getTopic() {
34+
return topic;
35+
}
36+
}

‎src/main/java/software/amazon/awssdk/crt/iot/MqttRequestResponse.java

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/**
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
* SPDX-License-Identifier: Apache-2.0.
4+
*/
5+
6+
package software.amazon.awssdk.crt.iot;
7+
8+
/**
9+
* Encapsulates a response to an AWS IoT Core MQTT-based service request
10+
*/
11+
public class MqttRequestResponse {
12+
13+
private String topic;
14+
private byte[] payload;
15+
16+
private MqttRequestResponse() {
17+
}
18+
19+
/**
20+
* Gets the MQTT topic that the response was received on.
21+
*
22+
* Different topics map to different types within the
23+
* service model, so we need this value in order to know what to deserialize the payload into.
24+
*
25+
* @return the MQTT topic that the response was received on
26+
*/
27+
public String getTopic() {
28+
return topic;
29+
}
30+
31+
/**
32+
* Gets the payload of the response that correlates to a submitted request.
33+
*
34+
* @return Payload of the response that correlates to a submitted request.
35+
*/
36+
public byte[] getPayload() {
37+
return payload;
38+
}
39+
}

‎src/main/java/software/amazon/awssdk/crt/iot/MqttRequestResponseClient.java

+171
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
/**
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
* SPDX-License-Identifier: Apache-2.0.
4+
*/
5+
6+
package software.amazon.awssdk.crt.iot;
7+
8+
import software.amazon.awssdk.crt.CrtResource;
9+
import software.amazon.awssdk.crt.CrtRuntimeException;
10+
import software.amazon.awssdk.crt.mqtt.MqttClientConnection;
11+
import software.amazon.awssdk.crt.mqtt5.Mqtt5Client;
12+
13+
import java.util.concurrent.CompletableFuture;
14+
import java.util.concurrent.locks.Lock;
15+
import java.util.concurrent.locks.ReentrantReadWriteLock;
16+
17+
/**
18+
* A helper class for AWS service clients that use MQTT as the transport protocol.
19+
*
20+
* The class supports orchestrating request-response operations and creating streaming operations. Used by the
21+
* IoT SDKs to implement higher-level service clients that provide a good user experience.
22+
*
23+
* Not intended to be constructed or used directly; the service client will create one during its construction.
24+
*/
25+
public class MqttRequestResponseClient extends CrtResource {
26+
27+
/*
28+
* Using a read-write lock to protect the native handle on Java -> Native calls is a new approach to handle
29+
* accidental misuse of CrtResource objects. The current method (no protection) works as long as the user
30+
* follows the rules, but race conditions can lead to crashes or undefined behavior if the user breaks the
31+
* rules (uses the CrtResource after or while the final close() call is in progress).
32+
*
33+
* For this new method to be correct, it must not be possible that Java -> Native calls ever call back
34+
* native -> Java in the same call stack. This is true for both the request response client and streaming
35+
* operations, allowing us to add this layer of safety.
36+
*/
37+
private final ReentrantReadWriteLock handleLock = new ReentrantReadWriteLock();
38+
private final Lock handleReadLock = handleLock.readLock();
39+
private final Lock handleWriteLock = handleLock.writeLock();
40+
41+
/**
42+
* MQTT5-based constructor for request-response service clients
43+
*
44+
* @param client MQTT5 client that the request-response client should use as transport
45+
* @param options request-response client configuration options
46+
*/
47+
public MqttRequestResponseClient(Mqtt5Client client, MqttRequestResponseClientOptions options) {
48+
acquireNativeHandle(mqttRequestResponseClientNewFrom5(
49+
this,
50+
client.getNativeHandle(),
51+
options.getMaxRequestResponseSubscriptions(),
52+
options.getMaxStreamingSubscriptions(),
53+
options.getOperationTimeoutSeconds()
54+
));
55+
}
56+
57+
/**
58+
* MQTT311-based constructor for request-response service clients
59+
*
60+
* @param client MQTT311 client that the request-response client should use as transport
61+
* @param options request-response client configuration options
62+
*/
63+
public MqttRequestResponseClient(MqttClientConnection client, MqttRequestResponseClientOptions options) {
64+
acquireNativeHandle(mqttRequestResponseClientNewFrom311(
65+
this,
66+
client.getNativeHandle(),
67+
options.getMaxRequestResponseSubscriptions(),
68+
options.getMaxStreamingSubscriptions(),
69+
options.getOperationTimeoutSeconds()
70+
));
71+
}
72+
73+
/**
74+
* Submits a request to the request-response client.
75+
*
76+
* @param request description of the request to perform
77+
*
78+
* @return future that completes with the result of performing the request
79+
*/
80+
public CompletableFuture<MqttRequestResponse> submitRequest(RequestResponseOperation request) {
81+
CompletableFuture<MqttRequestResponse> future = new CompletableFuture<>();
82+
83+
this.handleReadLock.lock();
84+
try {
85+
long handle = getNativeHandle();
86+
if (handle != 0) {
87+
mqttRequestResponseClientSubmitRequest(getNativeHandle(), request, future);
88+
} else {
89+
future.completeExceptionally(new CrtRuntimeException("Client already closed"));
90+
}
91+
} finally {
92+
this.handleReadLock.unlock();
93+
}
94+
95+
return future;
96+
}
97+
98+
/**
99+
* Creates a new streaming operation from a set of configuration options. A streaming operation provides a
100+
* mechanism for listening to a specific event stream from an AWS MQTT-based service.
101+
*
102+
* @param options configuration options for the streaming operation
103+
*
104+
* @return a new streaming operation instance
105+
*/
106+
public StreamingOperation createStream(StreamingOperationOptions options) {
107+
this.handleReadLock.lock();
108+
try {
109+
long handle = getNativeHandle();
110+
if (handle != 0) {
111+
return new StreamingOperation(this, options);
112+
} else {
113+
throw new CrtRuntimeException("Client already closed");
114+
}
115+
} finally {
116+
this.handleReadLock.unlock();
117+
}
118+
}
119+
120+
/**
121+
* Cleans up the native resources associated with this client. The client is unusable after this call
122+
*/
123+
@Override
124+
protected void releaseNativeHandle() {
125+
if (!isNull()) {
126+
mqttRequestResponseClientDestroy(getNativeHandle());
127+
}
128+
}
129+
130+
/**
131+
* Determines whether a resource releases its dependencies at the same time the native handle is released or if it waits.
132+
* Resources that wait are responsible for calling releaseReferences() manually.
133+
*/
134+
@Override
135+
protected boolean canReleaseReferencesImmediately() { return true; }
136+
137+
@Override
138+
public void close() {
139+
this.handleWriteLock.lock();
140+
try {
141+
super.close();
142+
} finally {
143+
this.handleWriteLock.unlock();
144+
}
145+
}
146+
147+
/*******************************************************************************
148+
* native methods
149+
******************************************************************************/
150+
151+
private static native long mqttRequestResponseClientNewFrom5(
152+
MqttRequestResponseClient client,
153+
long protocolClientHandle,
154+
int maxRequestResponseSubscriptions,
155+
int maxStreamingSubscriptions,
156+
int operationTimeoutSeconds
157+
) throws CrtRuntimeException;
158+
159+
private static native long mqttRequestResponseClientNewFrom311(
160+
MqttRequestResponseClient client,
161+
long protocolClientHandle,
162+
int maxRequestResponseSubscriptions,
163+
int maxStreamingSubscriptions,
164+
int operationTimeoutSeconds
165+
) throws CrtRuntimeException;
166+
167+
private static native void mqttRequestResponseClientDestroy(long client);
168+
169+
private static native void mqttRequestResponseClientSubmitRequest(long client, RequestResponseOperation request, CompletableFuture<MqttRequestResponse> future);
170+
171+
}

‎src/main/java/software/amazon/awssdk/crt/iot/MqttRequestResponseClientOptions.java

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
/**
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
* SPDX-License-Identifier: Apache-2.0.
4+
*/
5+
6+
package software.amazon.awssdk.crt.iot;
7+
8+
/**
9+
* Class to configure an MQTT-based request response client.
10+
*/
11+
public class MqttRequestResponseClientOptions {
12+
private int maxRequestResponseSubscriptions = 0;
13+
private int maxStreamingSubscriptions = 0;
14+
private int operationTimeoutSeconds = 0;
15+
16+
public static class MqttRequestResponseClientOptionsBuilder {
17+
private MqttRequestResponseClientOptions options = new MqttRequestResponseClientOptions();
18+
19+
private MqttRequestResponseClientOptionsBuilder() {}
20+
21+
/**
22+
* Sets the maximum number of subscriptions that the client will concurrently use for request-response operations
23+
*
24+
* @param maxRequestResponseSubscriptions maximum number of subscriptions that the client will concurrently use for request-response operations
25+
* @return the builder instance
26+
*/
27+
public MqttRequestResponseClientOptionsBuilder withMaxRequestResponseSubscriptions(int maxRequestResponseSubscriptions) {
28+
this.options.maxRequestResponseSubscriptions = maxRequestResponseSubscriptions;
29+
30+
return this;
31+
}
32+
33+
/**
34+
* Sets the maximum number of subscriptions that the client will concurrently use for streaming operations
35+
*
36+
* @param maxStreamingSubscriptions maximum number of subscriptions that the client will concurrently use for streaming operations
37+
* @return the builder instance
38+
*/
39+
public MqttRequestResponseClientOptionsBuilder withMaxStreamingSubscriptions(int maxStreamingSubscriptions) {
40+
this.options.maxStreamingSubscriptions = maxStreamingSubscriptions;
41+
42+
return this;
43+
}
44+
45+
/**
46+
* Sets the duration, in seconds, that a request-response operation will wait for completion before giving up
47+
*
48+
* @param operationTimeoutSeconds duration, in seconds, that a request-response operation will wait for completion before giving up
49+
* @return the builder instance
50+
*/
51+
public MqttRequestResponseClientOptionsBuilder withOperationTimeoutSeconds(int operationTimeoutSeconds) {
52+
this.options.operationTimeoutSeconds = operationTimeoutSeconds;
53+
54+
return this;
55+
}
56+
57+
/**
58+
* Creates a new MqttRequestResponseClientOptions instance based on current builder configuration
59+
* @return the builder instance
60+
*/
61+
public MqttRequestResponseClientOptions build() {
62+
return new MqttRequestResponseClientOptions(this.options);
63+
}
64+
}
65+
66+
private MqttRequestResponseClientOptions() {
67+
}
68+
69+
private MqttRequestResponseClientOptions(MqttRequestResponseClientOptions options) {
70+
this.maxRequestResponseSubscriptions = options.maxRequestResponseSubscriptions;
71+
this.maxStreamingSubscriptions = options.maxStreamingSubscriptions;
72+
this.operationTimeoutSeconds = options.operationTimeoutSeconds;
73+
}
74+
75+
/**
76+
* Creates a new builder for MqttRequestResponseClientOptions instances
77+
*
78+
* @return a new builder for MqttRequestResponseClientOptions instances
79+
*/
80+
public static MqttRequestResponseClientOptions.MqttRequestResponseClientOptionsBuilder builder() {
81+
return new MqttRequestResponseClientOptions.MqttRequestResponseClientOptionsBuilder();
82+
}
83+
84+
/**
85+
* @return the maximum number of subscriptions that the client will concurrently use for request-response operations
86+
*/
87+
int getMaxRequestResponseSubscriptions() {
88+
return this.maxRequestResponseSubscriptions;
89+
}
90+
91+
/**
92+
* @return the maximum number of subscriptions that the client will concurrently use for streaming operations
93+
*/
94+
int getMaxStreamingSubscriptions() {
95+
return this.maxStreamingSubscriptions;
96+
}
97+
98+
/**
99+
* @return the duration, in seconds, that a request-response operation will wait for completion before giving up
100+
*/
101+
int getOperationTimeoutSeconds() {
102+
return this.operationTimeoutSeconds;
103+
}
104+
}

0 commit comments

Comments
 (0)