Skip to content

Commit 3518d26

Browse files
hpmellemahpmellema
authored
Add README's for most modules. (#573)
1 parent ce216dc commit 3518d26

File tree

45 files changed

+423
-9
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+423
-9
lines changed

‎README.md

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,35 @@
1-
# <img alt="Smithy" src="https://github.com/smithy-lang/smithy/blob/main/docs/_static/smithy-anvil.svg?raw=true" width="32"> Smithy Java
1+
# <img alt="Smithy" src="https://github.com/smithy-lang/smithy/blob/main/docs/_static/smithy-anvil.svg?raw=true" width="32"> Smithy Java
22
[![ci](https://github.com/smithy-lang/smithy-java/actions/workflows/ci.yml/badge.svg)](https://github.com/smithy-lang/smithy-java/actions/workflows/ci.yml)
3+
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
34

4-
[Smithy](https://smithy.io/2.0/index.html) code generators for [Java](https://java.com/).
5+
[Smithy](https://smithy.io/2.0/index.html) code generators for clients, servers, and shapes for [Java](https://java.com/).
56

6-
> [!Caution]
7-
> This project is confidential until the repository is made public.
7+
> [!WARNING]
8+
> This project is still in development and is not intended for use in production.
89
10+
## Usage
911
> [!WARNING]
10-
> This project is in early development and is not intended for use in production.
12+
> Smithy-Java only supports **Java 17** or later. Older Java versions are not supported.
13+
14+
### API Stability
15+
APIs annotated with `@SmithyInternal` are for internal use by Smithy-Java libraries and should not be used by Smithy users.
16+
APIs annotated with `@SmithyUnstableApi` are subject to change in future releases, and library code that other projects
17+
may depend on should not use these APIs.
1118

1219
## Development
20+
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information on contributing to the Smithy-Java project.
1321

1422
### Pre-push hooks
15-
Pre-push hooks are automatically added for unix users via the `addPrePushHooks` gradle task.
23+
Pre-push hooks are automatically added for unix users via the `addGitHooks` gradle task.
24+
1625
**Note**: In order to successfully execute the pre-defined hooks you must have the `smithy` CLI installed.
1726
See [installation instructions](https://smithy.io/2.0/guides/smithy-cli/cli_installation.html) if you do not already have the CLI installed.
1827

1928
## Security
20-
21-
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
29+
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our
30+
[vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/).
31+
Please do **not** create a public GitHub issue.
2232

2333
## License
24-
2534
This project is licensed under the Apache-2.0 License.
2635

‎auth-api/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
## auth-api
2+
This module provides the auth API for clients and servers.

‎aws/README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
## AWS SDK Packages
2+
Packages within this directory are specific to AWS SDKs and the use of AWS services.
3+
4+
### Service Integrations
5+
The following integrations for AWS services are provided:
6+
- [lambda](./integrations/lambda) - Wrapper for running Smithy Java services on AWS Lambda

‎aws/client/aws-client-awsjson/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## aws-client-awsjson
2+
Client implementation of the [AWS JSON 1.0](https://smithy.io/2.0/aws/protocols/aws-json-1_0-protocol.html#aws-json-1-0-protocol)
3+
and [AWS JSON 1.1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol) protocols.

‎aws/client/aws-client-core/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
## aws-client-core
2+
Provides common client functionality for AWS SDKs.

‎aws/client/aws-client-http/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
## aws-client-http
2+
Provides common HTTP functionality for AWS SDKs.

‎aws/client/aws-client-restjson/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## aws-client-restjson
2+
Client implementation of the [AWS restJson1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol)
3+
protocol.

‎aws/client/aws-client-restxml/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## aws-client-restxml
2+
Client implementation of the [AWS restXml](https://smithy.io/2.0/aws/protocols/aws-restxml-protocol.html#aws-restxml-protocol)
3+
protocol.

‎aws/server/aws-server-restjson/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## aws-server-restjson
2+
Server implementation of the [AWS restJson1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol)
3+
protocol.

‎client/client-core/README.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## client-core
2+
This module provides the core functionality required to execute the client
3+
request pipeline. This module is used by both code generated and dynamic clients.
4+
5+
**Note:** Code generated clients require this module as a runtime dependency.
6+
7+
The functionality provided by this module includes:
8+
- Auth Scheme API and Auth Scheme Resolution
9+
- Identity Resolution
10+
- Endpoint API and Endpoint Resolution
11+
- Client Interceptors
12+
- Pagination
13+
- Exception Mapping
14+
- Client Plugin API
15+
- Client Transport API
16+
- Client Protocol API
17+
- Default Client Plugins
18+
- Base Client settings
19+
20+
To generate a client see the [client-codegen plugin](../codegen/plugins/client).
21+
To use a dynamic client see the [dynamic-client](../dynamic-client) module.

‎client/client-core/src/main/java/software/amazon/smithy/java/client/core/package-info.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@SmithyUnstableApi
2+
package software.amazon.smithy.java.client.core;
3+
4+
import software.amazon.smithy.utils.SmithyUnstableApi;

‎client/client-http-binding/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
### client-http-binding
2+
Provides client specific [http-binding](https://smithy.io/2.0/spec/http-bindings.html#http-bindings) functionality.
3+
Http-binding allows Smithy-modeled data to be bound to various parts of an HTTP message such
4+
as headers, query parameters, or the message body.

‎client/client-http-binding/src/main/java/software/amazon/smithy/java/client/http/binding/package-info.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@SmithyUnstableApi
2+
package software.amazon.smithy.java.client.http.binding;
3+
4+
import software.amazon.smithy.utils.SmithyUnstableApi;

‎client/client-http/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
### client-http
2+
Provides a client-side implementation of HTTP transport.

‎client/client-http/src/main/java/software/amazon/smithy/java/client/http/package-info.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@SmithyUnstableApi
2+
package software.amazon.smithy.java.client.http;
3+
4+
import software.amazon.smithy.utils.SmithyUnstableApi;

‎client/client-rpcv2-cbor/README.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
## client-rpcv2-cbor
2+
Client implementation of the [rpcv2-cbor](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html#smithy-rpc-v2-cbor-protocol) protocol.
3+
4+
### Usage
5+
To use this protocol as the default in a generated client, first add the `@rpcv2Cbor` trait
6+
to your service.
7+
8+
```diff
9+
$version: "2"
10+
11+
namespace smithy.example
12+
13+
+ use smithy.protocols#rpcv2Cbor
14+
15+
+@rpcv2Cbor
16+
service MyService {
17+
version: "2020-07-02"
18+
}
19+
```
20+
21+
Then add this module as a runtime dependency of your project
22+
```diff
23+
dependencies {
24+
+ implementation("software.amazon.smithy.java:client-rpcv2-cbor")
25+
}
26+
```
27+
28+
Finally, configure the client codegen plugin to use this protocol as the
29+
default
30+
```diff
31+
{
32+
"version": "1.0",
33+
"plugins": {
34+
"java-client-codegen": {
35+
"service": "com.example#CoffeeShop",
36+
"namespace": "com.example.cafe",
37+
+ "protocol": "smithy.protocols#rpcv2Cbor"
38+
}
39+
}
40+
}
41+
```

‎client/dynamic-client/README.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
### dynamic-client
2+
Provides a dynamic client that can be used without code generation.
3+
4+
The dynamic client can load Smithy models at runtime, convert them to a schema-based client,
5+
and call a service using `Document` types as input and output.
6+
7+
### Example usage
8+
```java
9+
// (1) Load up a model
10+
var model = Model.assembler()
11+
.addImport("/path/to/model.json")
12+
.assemble()
13+
.unwrap();
14+
15+
// (2) Which service to call
16+
var shapeId = ShapeId.from("com.example#CoffeeShop");
17+
18+
// (3) make the client and manually wire up the protocol, transport, etc.
19+
var client = DynamicClient.builder()
20+
.service(shapeId)
21+
.model(model)
22+
.protocol(new RestJsonClientProtocol(shapeId))
23+
.transport(new JavaHttpClientTransport())
24+
.endpointResolver(EndpointResolver.staticEndpoint("https://api.cafe.example.com"))
25+
.build();
26+
27+
// (4) Input is defined using a document that mirrors what you'd see in the Smithy model.
28+
var input = Document.createFromObject(Map.of("coffeeType", "COLD_BREW"));
29+
30+
// (5) "call" is used to send the input to an operation by name, and it returns a document too.
31+
var result = client.call("CreateOrder", input).get();
32+
33+
System.out.println(result);
34+
```

‎client/dynamic-client/src/main/java/software/amazon/smithy/java/dynamicclient/package-info.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@SmithyUnstableApi
2+
package software.amazon.smithy.java.dynamicclient;
3+
4+
import software.amazon.smithy.utils.SmithyUnstableApi;

‎client/mock-client-plugin/README.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## mock-client-plugin
2+
The MockPlugin is used to intercept client requests and return canned
3+
responses, shapes, or exceptions.
4+
5+
### Usage
6+
```java
7+
// (1) Create a response queue and add a set of canned responses that will be returned
8+
// from client in the order in which they were added to the queue.
9+
var mockQueue = new MockQueue();
10+
mockQueue.enqueue(
11+
HttpResponse.builder()
12+
.statusCode(200)
13+
.body(DataStream.ofString("{\"id\":\"1\"}"))
14+
.build()
15+
);
16+
mockQueue.enqueue(
17+
HttpResponse.builder()
18+
.statusCode(429)
19+
.body(DataStream.ofString("{\"__type\":\"InvalidSprocketId\"}"))
20+
.build()
21+
);
22+
23+
// (2) Create a MockPlugin instance using the request queue created above.
24+
var mockPlugin = MockPlugin.builder().addQueue(mockQueue).build();
25+
26+
// (3) Create a client instance that uses the MockPlugin.
27+
var client = SprocketClient.builder()
28+
.addPlugin(mockPlugin)
29+
.build();
30+
31+
// (4) Call client to get the first canned response from the queue.
32+
var response = client.createSprocket(CreateSprocketRequest.builder().id(2).build());
33+
34+
// (5) Inspect the HTTP requests that were sent to the client.
35+
var requests = mock.getRequests();
36+
37+
```
38+

‎client/waiters/README.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## waiters
2+
Provides the core runtime functionality for [Waiters](https://smithy.io/2.0/additional-specs/waiters.html#waiters).
3+
4+
Waiters are a client-side abstraction used to poll a resource until a desired state is reached,
5+
or until it is determined that the resource will never enter into the desired state.
6+
7+
### Usage
8+
A Waiter can be manually created using:
9+
```java
10+
// Create a waiter with a single failure acceptor
11+
var waiter = Waiter.builder(client::getFoosSync)
12+
.failure(Matcher.output(o -> o.status().equals("FAILED")))
13+
.build();
14+
// Wait for up to 2 seconds for waiter to complete
15+
waiter.wait(input, Duration.ofSeconds(2));
16+
```
17+
18+
Waiters can also be code generated for your client based on the presence of the `smithy.waiters#waitable` trait.
19+
To code generate waiters see: [waiter-integration](../../codegen/integrations/waiters-codegen)
20+

‎codecs/cbor-codec/README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
### rpcv2-cbor-codec
2+
Provides a codec for serializing or deserializing CBOR data to/from
3+
Smithy-Java `SerializableShape`'s.
4+
5+
> [!NOTE]
6+
> This codec follows the [Smithy RPCv2 CBOR specification](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html#shape-serialization)
7+
> for the encoding of BigIntegers, BigDecimals, and Timestamps.
8+
9+
CBOR Protocol implementation can use this package to provide basic serde functionality.

‎codecs/json-codec/README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## json-codec
2+
Provides a codec for serializing or deserializing JSON data to/from
3+
Smithy-Java `SerializableShape`'s.
4+
5+
JSON Protocol implementation can use this package to provide basic serde capabilities.
6+
7+
**Note:** This codec can discover custom `JsonSerdeProvider` service implementations via SPI.
8+
By default, [Jackson](https://github.com/FasterXML/jackson) is used to provide JSON serde.

‎codecs/json-codec/src/main/java/software/amazon/smithy/java/json/package-info.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@SmithyUnstableApi
2+
package software.amazon.smithy.java.json;
3+
4+
import software.amazon.smithy.utils.SmithyUnstableApi;

‎codecs/xml-codec/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## xml-codec
2+
Provides a codec for serializing or deserializing XML data to/from
3+
Smithy-Java `SerializableShape`'s.
4+
5+
XML Protocol implementation can use this package to provide basic serde.

‎codegen/core/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## codegen-core
2+
Provides the base functionality for Java code generation used
3+
by all Smithy Java codegen plugins.

‎codegen/integrations/waiters-codegen/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## waiters-codegen
2+
Codegen integration to generate pre-defined waiters based on
3+
[waitable](https://smithy.io/2.0/additional-specs/waiters.html#smithy-waiters-waitable-trait) traits in the service model.
4+
5+
### Usage
6+
```kotlin
7+
dependencies {
8+
// Add codegen integration as a smithy-build dependency, so it can be
9+
// discovered by the client codegen plugin
10+
smithyBuild("software.amazon.smithy.java.codegen:waiters:<VERSION>")
11+
12+
// Add waiters core package as a runtime dependency
13+
implementation("software.amazon.smithy.java:waiters:<VERSION>")
14+
}
15+
```
16+

‎codegen/plugins/client/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
### codegen-client
2+
Codegen plugin to generate a Java client from a Smithy model.

‎codegen/plugins/server/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
### codegen-server
2+
Codegen plugin to generate Java server stubs from a Smithy model.

‎codegen/plugins/types/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
### codegen-types
2+
Codegen plugin to generate standalone "plain old Java objects" (POJOs)
3+
from a Smithy model.

‎context/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## context
2+
Provides a typed property map that can be used to store
3+
contextual data.

‎core/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## core
2+
Provides the core functionality common to all clients and servers
3+
using the Smithy Java framework.

‎framework-errors/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## framework-errors
2+
> [!WARNING]
3+
> Frameworks errors are a preview feature and may change significantly before 1.0 release.
4+
5+
Provides framework errors common to all Smithy-Java clients and servers.

‎http-api/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
## http-api
2+
Provides the Smithy Java HTTP API.

‎http-binding/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
### http-binding
2+
Provides [http-binding](https://smithy.io/2.0/spec/http-bindings.html#http-bindings) functionality. This allows Smithy-modeled
3+
data to be bound to various parts of an HTTP message such
4+
as headers, query parameters, or the message body.

‎http-binding/src/main/java/software/amazon/smithy/java/http/binding/package-info.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@SmithyUnstableApi
2+
package software.amazon.smithy.java.http.binding;
3+
4+
import software.amazon.smithy.utils.SmithyUnstableApi;

‎io/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## io
2+
Provides the common I/O functionality for Smithy Java such
3+
as construction and encoding of URL's and handling of data streams.

‎jmespath/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## jmespath
2+
Provides functionality to perform a [JMESPath](https://jmespath.org/) query
3+
against a Smithy-Java `Document`.
4+
5+
### Example Usage
6+
Given a `Document` representing the JSON object `{"foo": [1,2,3,4]}`,
7+
all items in member `foo` greater than 2 could be queried as:
8+
9+
```java
10+
Document result = JMESPathDocumentQuery.query("foo[?@ > `2`]", myDocument);
11+
```

‎jmespath/src/main/java/software/amazon/smithy/java/jmespath/package-info.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@SmithyUnstableApi
2+
package software.amazon.smithy.java.jmespath;
3+
4+
import software.amazon.smithy.utils.SmithyUnstableApi;

‎logging/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## logging
2+
> [!WARNING]
3+
> This module is intended for internal components of the Smithy Java framework
4+
> and should not be depended on by projects outside of this repository.
5+
6+
This package provides a common logging facade for internal
7+
Smithy-Java logging. This logging facade supports the following
8+
logger implementations:
9+
- JDK System Logger (default)
10+
- Log4j2 Logger
11+
- Slf4j2 Logger

0 commit comments

Comments
 (0)