Skip to content

Commit d98b79d

Browse files
authored
Update optional guideline (#2749)
1 parent 538db74 commit d98b79d

File tree

1 file changed

+10
-12
lines changed

1 file changed

+10
-12
lines changed

docs/design/UseOfOptional.md

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,17 @@
22

33
## Use of Optional
44

5-
This page describes general guidelines of how we use
6-
`java.util.Optional`.
5+
This page describes a general guideline for the use of
6+
`java.util.Optional` in the AWS SDK for Java 2.x.
7+
8+
- `Optional` MUST NOT be used under any circumstances when the result will never be null.
9+
- For return types,
10+
- `Optional` SHOULD be used when it is not obvious to a caller whether a
11+
result will be null, e.g, `public <T> Optional<T> getValueForField(String fieldName, Class<T> clazz)`in [SdkResponse.java](https://github.com/aws/aws-sdk-java-v2/blob/aa161c564c580ced4a0381d3ed7d4d13120916fc/core/sdk-core/src/main/java/software/amazon/awssdk/core/SdkResponse.java#L59-L61)
12+
- `Optional` MUST NOT be used for "getters" in generated service model classes such as service Builders or POJOs.
13+
- For memember variables: `Optional` SHOULD NOT be used, e.g., `private final Optional<String> field;`
14+
- For method parameters: `Optional` MUST NOT be used, e.g., `private void test(Optional<String> value)`
715

8-
- `Optional` should be used when it isn't obvious to a caller whether a
9-
result will be null.
10-
- `Optional` must not be used when the result will never be
11-
`Optional.empty()`.
12-
- `Optional` must not be used for instance (in `@SdkPublicApi`s).
13-
- `Optional` must not be used for parameters (in `@SdkPublicApi`s).
14-
- `Optional` must not be used when the caller may know whether a value
15-
is present. As a consequence:
16-
- `Optional` must not be used in classes with "setters" and "getters",
17-
like Builders or POJOs.
1816

1917
References:
2018

0 commit comments

Comments
 (0)