Skip to content

Commit ef9b3ab

Browse files
zoewanggzoewangg
committed
Move wiki pages to docs folder
1 parent 5d37010 commit ef9b3ab

8 files changed

+320
-4
lines changed

‎CONTRIBUTING.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ Please keep the following in mind when considering a code contribution:
110110

111111
### Your First Code Change
112112
For detailed information on getting started building and making code changes to
113-
the SDK, refer to our [Working on the SDK][working-on-the-sdk] wiki page.
113+
the SDK, refer to our [Working on the SDK](./docs/GettingStarted.md) doc
114114

115115
### Pull Request Readiness
116116
Before submitting your pull request, refer to the pull request readiness
@@ -153,7 +153,7 @@ asked to [squash][git-rewriting-history] them into a single commit before it is
153153
merged in.
154154

155155
## Additional Resources
156-
We maintain a [wiki][wiki] where information like design decisions, internal
156+
We maintain [docs](docs/README.md) where information like design decisions, internal
157157
architecture, and style conventions are documented that you may find helpful
158158
when contributing to the SDK.
159159

@@ -166,8 +166,6 @@ when contributing to the SDK.
166166
[issues]: https://github.com/aws/aws-sdk-java-v2/issues
167167
[pull-requests]: https://github.com/aws/aws-sdk-java-v2/pulls
168168
[cla]: https://github.com/aws/aws-cla
169-
[wiki]: https://github.com/aws/aws-sdk-java-v2/wiki
170-
[working-on-the-sdk]: https://github.com/aws/aws-sdk-java-v2/wiki/Working-on-the-SDK
171169
[label-bug]: https://github.com/aws/aws-sdk-java-v2/labels/Bug
172170
[label-doc-issue]: https://github.com/aws/aws-sdk-java-v2/labels/Documentation%20Issue
173171
[label-feature-request]: https://github.com/aws/aws-sdk-java-v2/labels/Feature%20Request

‎docs/ClientConfiguraion.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Client Configuration
2+
3+
This page describes the structure and conventions used for client configuration objects. Client configuration objects are any objects used to configure an AWS client builder.
4+
5+
#### Example
6+
7+
This section walks through an example configuration class structure and describes each of its components at a high level.
8+
9+
```Java
10+
/**
11+
* Configuration Description // (1)
12+
*/
13+
@Immutable
14+
@ThreadSafe // (2)
15+
public final class SdkConfiguration // (3)
16+
implements ToCopyableBuilder<SdkConfiguration.Builder, SdkConfiguration> { // (4)
17+
private final String option; // (5)
18+
19+
/**
20+
* @see #builder() // (6)
21+
*/
22+
private SdkClientConfiguration(DefaultSdkConfigurationBuilder builder) {
23+
this.option = builder.option;
24+
}
25+
26+
public static Builder builder() {
27+
return new DefaultSdkConfigurationBuilder();
28+
}
29+
30+
/**
31+
* @see #Builder#option(String) // (7)
32+
*/
33+
public String option() {
34+
return this.option;
35+
}
36+
37+
@Override
38+
public ClientHttpConfiguration.Builder toBuilder() {
39+
return builder().option(option);
40+
}
41+
42+
@NotThreadSafe
43+
public interface Builder extends CopyableBuilder<Builder, SdkConfiguration> { // (8)
44+
/**
45+
* Configuration Option Description // (9)
46+
*/
47+
Builder option(String option);
48+
}
49+
50+
private static final class DefaultSdkConfigurationBuilder implements Builder { // (10)
51+
private String option;
52+
53+
@Override
54+
public Builder option(String option) { // (11)
55+
this.option = option;
56+
return this;
57+
}
58+
59+
public void setOption(String option) { // (12)
60+
this.option = option;
61+
}
62+
63+
@Override
64+
public SdkConfiguration build() {
65+
return new SdkConfiguration(this);
66+
}
67+
}
68+
}
69+
```
70+
71+
1. A detailed description should be given of what types of options the user might find in this object.
72+
2. Configuration objects should be `@Immutable`, and therefore `@ThreadSafe`.
73+
3. Configuration classes should be defined as `final` to prevent extension.
74+
4. Configuration classes should extend `ToCopyableBuilder` to ensure they can be converted back to a builder object.
75+
5. All configuration fields should be defined as `private final` to prevent reassignment.
76+
6. Configuration constructors should be `private` to enforce creation by the `Builder` and refer curious eyes to the `builder()` method for creating the object.
77+
7. One "get" method should be created for each configuration field. This method's name should exactly match the name of the field it is retrieving.
78+
8. Each builder should have its own interface. This allows hiding certain public methods from auto-complete (see below).
79+
9. A detailed description of each option should be given, including what it does, and **why** a user could want to change its default value.
80+
10. A `private static final` implementation of the `Builder` interface should be created that is not exposed outside of the scope of the configuration class.
81+
11. One "set" method should be created for each option to mutate the value in this builder. This method's name should exactly match the name of the field it is setting.
82+
12. Each option should have a bean-style setter to allow configuring the object reflectively using `Inspector`-based frameworks, like spring XML.
83+
84+
#### Configuration Fields
85+
86+
This section details the semantics of configuration fields.
87+
88+
1. Configuration fields must be **immutable**.
89+
1. Fields must be marked as `final`.
90+
2. Mutable types, like `List` and `Set` should be wrapped in a type that prevents their modification (eg. `Collections.unmodifiableList`) when referenced through the "get" method.
91+
3. Mutable types, like `List` and `Set` should be copied in the "set" method to prevent their modification by mutating the original object.
92+
2. Configuration fields must be **reference types**. Primitive types like `boolean` or `int` should not be used because they can not convey the absence of configuration.
93+
3. Configuration field names should **not start with a verb** (eg. `config.enableRedirect()` should instead be `config.redirectEnabled()`). This is to avoid confusing their "get" methods for a mutating action.
94+
95+
Special notes for collection types, like `List`, `Set`, and `Map`:
96+
97+
1. Collection type field names must be plural.
98+
2. Collection types should be accompanied by an `addX` method on the builder that permits adding one item to the collection. This `addX` method should be singular.
99+
100+
```Java
101+
public interface Builder {
102+
Builder options(List<String> options);
103+
Builder addOption(String option);
104+
105+
Builder headers(Map<String, String> headers);
106+
Builder addHeader(String key, String value);
107+
}

‎docs/FavorStaticFactoryMethods.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
## Favor Static Factory Methods Over Constructors
2+
3+
This page describes the structures and conventions used to initialize a class.
4+
5+
### Static Factory Methods vs. Constructors
6+
Static factory methods are preferable than constructors for the following reasons:
7+
- Static factory methods provide meaningful names compared with constructors, which improves the readability of the codes by describing the objects being returned.
8+
```java
9+
// With static factory method, giving a hint that a foobar provider with default settings is being created.
10+
FoobarProvider defaultProvider = FoobarProvider.defaultFoobarProvider();
11+
12+
// With constructor
13+
FoobarProvider defaultProvider = new FoobarProvider();
14+
```
15+
- They are useful when work with immutable classes as we can reuse the same object instead of creating new object every time when it is invoked.
16+
- Static factory methods can return any subtype of that class and this gives us flexibility to write a separate factory class to return different subclasses if needed.
17+
18+
There are a few disadvantages of static factory methods:
19+
- It might not be straightforward for the users to use static factory method to create new instances compared with constructors, but this can be improved by providing a set of common method names such as `create()` and smart IDEs such as IntelliJ and Eclipse can also give hints and help auto-completing.
20+
- Classes without public or protected constructors cannot be subclassed, but this could encourage us to use composition instead of inheritance.
21+
22+
In general, we should favor static factory methods over constructors.
23+
24+
### Example
25+
```java
26+
public class DefaultCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable {
27+
28+
private static final DefaultCredentialsProvider DEFAULT_CREDENTIALS_PROVIDER = new DefaultCredentialsProvider(builder());
29+
30+
private DefaultCredentialsProvider(Builder builder) {
31+
this.providerChain = createChain(builder);
32+
}
33+
34+
public static DefaultCredentialsProvider create() {
35+
return DEFAULT_CREDENTIALS_PROVIDER;
36+
}
37+
38+
public static Builder builder() {
39+
return new Builder();
40+
}
41+
42+
public static final class Builder {
43+
// ...
44+
}
45+
// ...
46+
}
47+
48+
49+
// There are two ways to create new instance
50+
DefaultCredentialsProvider defaultCredentialsProvider1 = DefaultCredentialsProvider.create();
51+
DefaultCredentialsProvider defaultCredentialsProvider2 = DefaultCredentialsProvider.builder().build;
52+
```
53+
### Naming Conventions
54+
The naming conventions for the static factory methods:
55+
- `create()`, `create(params)` when creating a new instance
56+
eg: `DynamoDBClient.create()`
57+
- `defaultXXX()` when returning an instance with default settings.
58+
eg: `BackoffStrategy.defaultStrategy()`

‎docs/GettingStarted.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Working on the SDK
2+
3+
# Things to Know
4+
* The SDK is built on Java 8
5+
* [Maven][maven] is used as the build and dependency management system
6+
* The majority of the service client code is auto-generated using the [code
7+
generator][codegen]
8+
9+
# Development Environment Setup Tips
10+
If you use IntelliJ IDEA, we include some helpful config files that will make your development experience smoother:
11+
- [intellij-codestyle.xml](https://github.com/aws/aws-sdk-java-v2/blob/master/build-tools/src/main/resources/software/amazon/awssdk/intellij-codestyle.xml)
12+
13+
This will help ensure your code follows our code style guidelines.
14+
15+
- [intellij-copyright-profile.xml](https://github.com/aws/aws-sdk-java-v2/blob/master/build-tools/src/main/resources/software/amazon/awssdk/intellij-copyright-profile.xml)
16+
17+
This automatically inserts the license header to the top of source files that you create.
18+
19+
If you have Checkstyle integrated with your IDE, we also recommend configuring it with our [Checkstyle config](https://github.com/aws/aws-sdk-java-v2/blob/master/build-tools/src/main/resources/software/amazon/awssdk/checkstyle.xml) so you can see any violations in line with the code.
20+
21+
# Getting Around
22+
At a high level, the SDK is comprised of two parts: the core runtime, and the
23+
service clients, including their higher level abstractions.
24+
25+
*TODO*
26+
27+
# Building
28+
Since the SDK is a normal Maven project, the usual `mvn package` and `mvn
29+
install` commands are all you need to build the SDK.
30+
31+
One important thing to note is that if you're working on the [code
32+
generator][codegen], be sure to do a `mvn install` rather than a phase that
33+
comes earlier such as `compile` or `test` so that the build uses the uses the
34+
correct code generator JAR (i.e. the one including your changes). When in
35+
doubt, just use `mvn package`.
36+
37+
## Disabling Checkstyle/FindBugs
38+
Normally Checkstyle and FindBugs scans run as part of the build process.
39+
However, this slows down the build significantly so if you need to be able to
40+
iterate quickly locally, you can turn either of them off by setting the
41+
appropriate properties:
42+
43+
```sh
44+
# skips both Checkstyle and FindBugs
45+
$ mvn install -Dfindbugs.skip=true -Dcheckstyle.skip=true
46+
```
47+
48+
# Testing
49+
## Unit Tests
50+
As described in the project structure, tests are split between unit and
51+
integration tests. During the normal `test` lifecycle phase, only the unit
52+
tests are run.
53+
54+
```sh
55+
# runs the unit tests
56+
mvn install
57+
```
58+
59+
## Integration Tests
60+
__Before running the integration tests, be aware that they require active AWS
61+
IAM credentials, and because they will make actual calls to AWS, will incur a
62+
cost to the owner of the account.__
63+
64+
If you're writing an integration test, try to see if it's possible to write it
65+
as a set of unit tests with mocked responses instead.
66+
67+
### Test Credentials
68+
69+
As mentioned above, you will need to have active IAM credentials that the tests
70+
will use to authenticate with AWS, and it will need to have an attached IAM
71+
policy that is allowed to perform the actions the tests will be running.
72+
73+
All integration tests are written to locate these credentials in
74+
`$HOME/.aws/awsTestAccount.properties`:
75+
76+
```
77+
$ cat $HOME/.aws/awsTestAccount.properties
78+
79+
accessKey = ...
80+
secretKey = ...
81+
```
82+
83+
### Running the Integration Tests
84+
85+
In order to run the integration tests along with the unit tests, you must
86+
activate the `integration-tests` profile
87+
88+
```sh
89+
# runs both unit and integration tests
90+
mvn install -P integration-tests
91+
```
92+
93+
[maven]: https://maven.apache.org/
94+
[codegen]: https://github.com/aws/aws-sdk-java-v2/blob/master/codegen

‎docs/NamingConventions.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
## Naming Conventions
2+
3+
This page describes the naming conventions, nouns and common terms
4+
5+
- Abbreviations must follow the same conventions as any other word (eg. use `DynamoDbClient`, not `DynamoDBClient`)
6+
7+
- Use Singular Enum Name
8+
9+
For enum classes or "pseudo-enums" classes(classes with public static fields), we should use singular name. (eg. use `SdkSystemSetting`, not `SdkSystemSettings`)
10+
11+
- Use of `Provider`, `Supplier` and `Factory` in the class name.
12+
- For general supplier classes (loading/creating resources of the same kind), prefer `Provide` unless the class extends from Java `Supplier` class. (eg. `AwsCredentialsProvider`)
13+
- For factories classes (creating resources of same or different kinds), prefer `Factory`. (eg. `AwsJsonProtocolFactory`)
14+
15+

‎docs/README.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# AWS SDK for Java 2.0 Docs
2+
3+
## New Contributions
4+
[GettingStarted](GettingStarted.md)
5+
6+
## Style Conventions
7+
- [Client Configuration](ClientConfiguraion.md)
8+
- [Favor Static Factory Methods Over Constructors](FavorStaticFactoryMethods.md)
9+
- [Use of Optional](UseOfOptional.md)
10+
- [Naming Conventions](NamingConventions.md)
11+
12+
## Key Design Decisions
13+
- [Use of CompletableFuture](UseOfCompletableFuture.md)

‎docs/UseOfCompletableFuture.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
## Use of CompletableFuture
2+
3+
Operations on the asynchronous clients return [`CompleteableFuture<T>`][1] where `T` is the response type for the operation. This is somewhat curious in that [`CompleteableFuture`][1] is a concrete implementation rather than an interface. The alternative to returning a [`CompleteableFuture`][1] would be to return a [`CompletionStage`][2], an interface intended to allow chaining of asynchronous operations.
4+
5+
The key advantage of [`CompleteableFuture`][1] is that it implements both the [`CompletionStage`][2] and [`Future`][3] interfaces - giving users of the SDK maximum flexibilty when it comes to handling responses from their asynchronous calls.
6+
7+
Currently [`CompleteableFuture`][1] is the only implementation of [`CompletionStage`][2] that ships with the JDK. Whilst it's possible that future implementations will be added [`CompletionStage`][2] will always be tied to [`CompleteableFuture`][1] via the [`#toCompletableFuture`][4] method. Additionally, [`CompleteableFuture`][1] is not a `final` class and thus could be extended if there was a requirement to do so.
8+
9+
One of the perceived risks with exposing [`CompleteableFuture`][1] rather than [`CompletionStage`][2] is that a user of the SDK may spuriously call [`#complete`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html#complete-T-) or [`#completeExceptionally`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html#completeExceptionally-java.lang.Throwable-) which could cause unintended consequences in their application and the SDK itself. However this risk is also present on the [`CompletionStage`][2] via the [`#toCompletableFuture`][4] method.
10+
11+
If the [`CompletionStage`][2] interface did not have a [`#toCompletableFuture`][4] method the argument for using it would be a lot stronger, however as it stands the interface and its implementation are tightly coupled.
12+
13+
Using [`CompleteableFuture`][1] gives users the best bang for their buck without much additional risk.
14+
15+
[1]: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html
16+
[2]: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html
17+
[3]: https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html
18+
[4]: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html#toCompletableFuture--

‎docs/UseOfOptional.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## Use of Optional
2+
3+
This page describes general guidelines of how we use `Optional`.
4+
5+
- Do not declare any instance variable of type Optional in public API.
6+
- Do not use Optional in parameters in public API
7+
- Do not use Optional in Builder classes
8+
- Do not use Optional in POJOs.
9+
- Use Optional for getters that access the field that's we know always going to be optional.
10+
- Use Optional as a return type for any methods that have a result that's we know always going to be optional.
11+
12+
References:
13+
- http://blog.joda.org/2015/08/java-se-8-optional-pragmatic-approach.html

0 commit comments

Comments
 (0)