Skip to content

Commit 064d697

Browse files
millemsmillems
authored
Add union type design overview. (#3119)
1 parent 271d032 commit 064d697

File tree

2 files changed

+162
-3
lines changed

2 files changed

+162
-3
lines changed

‎docs/design/README.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,6 @@ significantly from the state proposed in these documents.*
1010

1111
* [S3 Transfer Manager](services/s3/transfermanager/README.md) -
1212
Simplifies uploading and downloading of objects to and from Amazon S3.
13-
* [Dynamo DB Enhanced Client](services/dynamodb/high-level-library/README.md)
14-
\- Simplifies writing and reading objects to and from Amazon DynamoDB.
1513

1614
**Proposed**
1715

@@ -27,6 +25,8 @@ decided.*
2725
* [Event Streaming Auto-Reconnect](core/event-streaming/reconnect/README.md)
2826
\- Automatically reconnects to an event streaming session when they are
2927
interrupted by a network error.
28+
* [Tagged Unions](core/tagged-unions/README.md)
29+
\- Usability improvements for union types, like DynamoDB's `AttributeValue`.
3030

3131
**Released**
3232

@@ -36,7 +36,9 @@ design elements or features can be implemented incrementally based on customer
3636
demand.*
3737

3838
* [Request Presigners](core/presigners/README.md) - Makes it possible to sign
39-
requests to be executed at a later time.
39+
requests to be executed at a later time.
40+
* [Dynamo DB Enhanced Client](services/dynamodb/high-level-library/README.md)
41+
\- Simplifies writing and reading objects to and from Amazon DynamoDB.
4042

4143
**Rejected**
4244

‎docs/design/core/tagged-unions/README.md

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
**Design:** New Feature, **Status:** [Proposed](../../README.md)
2+
3+
# Tagged Unions
4+
5+
## Motivation
6+
By defining a structure that requires a single member to be set at any given time, service teams have been defining tagged unions in AWS services for years. However, the AWS SDK for Java has yet to provide first-class support for them.
7+
8+
The quintessential example of a tagged union is DynamoDB's `AttributeValue`:
9+
10+
```java
11+
class AttributeValue {
12+
private String s;
13+
private String n;
14+
private SdkBytes b;
15+
private List<String> ss;
16+
private List<String> ns;
17+
private List<SdkBytes> bs;
18+
19+
// ...
20+
}
21+
```
22+
23+
Currently, customers are left to perform ad-hoc matching on the value to first determine what kind of value is provided for a union, and then dispatch to branching code to interact with the value. Rather than ask customers to do this themselves, we should provide abstractions that make it easy for customers to use these values.
24+
25+
## Goal
26+
27+
The goal of this project is to provide a backwards-compatible customer-friendly abstraction for existing and new union types within the 2.x SDK.
28+
29+
## Prior Art
30+
31+
We currently implement friendly tagged unions in at least two external places within the SDK already:
32+
1. The `software.amazon.awssdk.core.document.Document` type.
33+
2. Event stream types, like Lex's `software.amazon.awssdk.services.lexruntimev2.model.StartConversationRequestEventStream` type.
34+
35+
And at least one internal place:
36+
1. The `software.amazon.awssdk.protocols.jsoncore.JsonNode` type.
37+
38+
## Union Type Definition
39+
40+
We will follow the patterns set by `Document` and `JsonNode`, because the pattern used by `StartConversationRequestEventStream` would not be backwards-compatible with existing types.
41+
42+
Existing structures primarily contain the following methods:
43+
1. A static `builder()` method for creating the structure and setting its mutually exclusive members.
44+
2. "Get" methods for each member in the union.
45+
3. "Has" methods for each collection or map member, to allow for differentiating between absent and missing values.
46+
47+
In addition to the above methods, new and existing union types will have the following additional methods:
48+
1. A static `T fromN(...)` method for creating the structure with its single exclusive member initialized. e.g. `AttributeValue s = AttributeValue.fromS("string")`
49+
2. A `X.Type type()` method for determining the type contained within the union. e.g. `AttributeValue.Type type = getItemResponse.item().type()`
50+
51+
For example, an `AttributeValue` union type containing `String s`, `String n` and `SdkBytes b` would have the following public methods:
52+
```java
53+
class AttributeValue {
54+
static AttributeValue.Builder builder();
55+
static fromS(String s);
56+
static fromN(String n);
57+
static fromB(SdkBytes b);
58+
59+
String s();
60+
String n();
61+
SdkBytes b();
62+
63+
AttributeValue.Type type();
64+
65+
enum Type {
66+
S,
67+
N,
68+
B,
69+
UNKNOWN_TO_SDK_VERSION
70+
}
71+
72+
class Builder {
73+
// ...
74+
}
75+
76+
// ...
77+
}
78+
```
79+
80+
## Customer Experience
81+
82+
The following section outlines example customer code before and after the union types changes:
83+
84+
### Creating a union type
85+
86+
**Before Changes**
87+
```java
88+
AttributeValue.builder().s("foo").build()
89+
```
90+
91+
**After Changes**
92+
```java
93+
AttributeValue.fromS("foo")
94+
```
95+
96+
### Reading a field with an unknown type
97+
98+
**Before Changes**
99+
```java
100+
String result;
101+
if (attributeValue.s() != null) { result = attributeValue.s(); }
102+
else if (attributeValue.n() != null) { result = attributeValue.n(); }
103+
else if (attributeValue.b() != null) { result = attributeValue.b().asUtf8String(); }
104+
else { result = null; }
105+
```
106+
107+
**After Changes**
108+
```java
109+
// (Java 17+)
110+
String result = switch (attributeValue.type()) {
111+
case S -> attributeValue.s();
112+
case N -> attributeValue.n();
113+
case B -> attributeValue.b().asUtf8String();
114+
default -> null;
115+
}
116+
117+
// Java (8-16)
118+
String result = null;
119+
switch (attributeValue.type()) {
120+
case S: result = attributeValue.s(); break;
121+
case N: result = attributeValue.n(); break;
122+
case B: result = attributeValue.b().asUtf8String(); break;
123+
}
124+
```
125+
126+
### Using a field with an unknown type
127+
128+
**Before Changes**
129+
```java
130+
if (attributeValue.s() != null) { System.out.println(attributeValue.s()); }
131+
else if (attributeValue.n() != null) { System.out.println(attributeValue.n()); }
132+
else if (attributeValue.b() != null) { System.out.println(attributeValue.b().asUtf8String()); }
133+
```
134+
135+
**After Changes**
136+
```java
137+
attributeValue.visit(new AttributeValue.VoidVisitor() {
138+
void visitS(String s) { System.out.println(s); }
139+
void visitN(String n) { System.out.println(n); }
140+
void visitB(SdkBytes b) { System.out.println(b.asUtf8String()); }
141+
)
142+
143+
// (Java 17+)
144+
System.out.println(switch (attributeValue.type()) {
145+
case S -> attributeValue.s();
146+
case N -> attributeValue.n();
147+
case B -> attributeValue.b().asUtf8String();
148+
default -> null;
149+
});
150+
151+
// Java (8-16)
152+
switch (attributeValue.type()) {
153+
case S: System.out.println(attributeValue.s()); break;
154+
case N: System.out.println(attributeValue.n()); break;
155+
case B: System.out.println(attributeValue.b().asUtf8String()); break;
156+
}
157+
```

0 commit comments

Comments
 (0)