Skip to content

Commit ea31722

Browse files
millemsmillems
committed
Add union type design overview.
1 parent cefc536 commit ea31722

File tree

2 files changed

+155
-3
lines changed

2 files changed

+155
-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: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
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 TranscribeStreaming's `software.amazon.awssdk.services.transcribestreaming.model.AudioStream` 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 `AudioStream` would not be backwards-compatible with existing types and does not function particularly well for union type members that are not structures.
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 `<T> T accept(X.Visitor<T>)` method for transforming the union type. e.g. `String transformedOutput = getItemResponse.item().accept(new AttributeValue.Visitor<String>() {...})`
50+
3. A `void accept(X.VoidVisitor)` method for branching out on the union type. e.g. `getItemResponse.item().accept(new AttributeValue.VoidVisitor() { ... })`
51+
4. A `X.Type type()` method for determining the type contained within the union. e.g. `AttributeValue.Type type = getItemResponse.item().type()`
52+
53+
For example, an `AttributeValue` union type containing `String s`, `String n` and `SdkBytes b` would have the following public methods:
54+
```java
55+
class AttributeValue {
56+
static AttributeValue.Builder builder();
57+
static fromS(String s);
58+
static fromN(String s);
59+
static fromB(String s);
60+
61+
String s();
62+
String n();
63+
SdkBytes b();
64+
65+
AttributeValue.Type type();
66+
void accept(AttributeValue.VoidVisitor visitor);
67+
<T> T accept(AttributeValue.Visitor<T> visitor);
68+
69+
enum Type {
70+
S,
71+
N,
72+
B,
73+
UNKNOWN_TO_SDK_VERSION
74+
}
75+
76+
class Visitor<T> {
77+
T visitS(String s);
78+
T visitN(String n);
79+
T visitB(String b);
80+
T visitUnknownType();
81+
}
82+
83+
class VoidVisitor {
84+
void visitS(String s);
85+
void visitN(String n);
86+
void visitB(String b);
87+
void visitUnknownType();
88+
}
89+
90+
class Builder {
91+
// ...
92+
}
93+
94+
// ...
95+
}
96+
```
97+
98+
## Customer Experience
99+
100+
The following section outlines example customer code before and after the union types changes:
101+
102+
### Creating a union type
103+
104+
**Before Changes**
105+
```java
106+
AttributeValue.builder().s("foo").build()
107+
```
108+
109+
**After Changes**
110+
```java
111+
AttributeValue.fromS("foo")
112+
```
113+
114+
### Reading a field with an unknown type
115+
116+
**Before Changes**
117+
```java
118+
String result;
119+
if (attributeValue.s() != null) { result = attributeValue.s(); }
120+
else if (attributeValue.n() != null) { result = attributeValue.n(); }
121+
else if (attributeValue.b() != null) { result = attributeValue.b().asUtf8String(); }
122+
else { result = null; }
123+
```
124+
125+
**After Changes**
126+
```java
127+
String result = attributeValue.visit(new AttributeValue.Visitor<String>(){
128+
String visitS(String s) { return s; }
129+
String visitN(String n) { return n; }
130+
String visitB(SdkBytes b) { return b.asUtf8String(); }
131+
});
132+
```
133+
134+
### Using a field with an unknown type
135+
136+
**Before Changes**
137+
```java
138+
if (attributeValue.s() != null) { System.out.println(attributeValue.s()); }
139+
else if (attributeValue.n() != null) { System.out.println(attributeValue.n()); }
140+
else if (attributeValue.b() != null) { System.out.println(attributeValue.b().asUtf8String()); }
141+
```
142+
143+
**After Changes**
144+
```java
145+
attributeValue.visit(new AttributeValue.VoidVisitor() {
146+
void visitS(String s) { System.out.println(s); }
147+
void visitN(String n) { System.out.println(n); }
148+
void visitB(SdkBytes b) { System.out.println(b.asUtf8String()); }
149+
)
150+
```

0 commit comments

Comments
 (0)