From 8a228cfbf8ac1120f15df42deb420f5029ec733b Mon Sep 17 00:00:00 2001 From: Hunter Mellema <124718352+hpmellema@users.noreply.github.com> Date: Wed, 12 Feb 2025 10:18:50 -0700 Subject: [PATCH] Update README.md (#591) --- README.md | 39 +++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index d80ae64f8..04f51c94c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# Smithy Smithy Java +# Smithy Smithy Java + [![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) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) @@ -8,6 +9,7 @@ > This project is still in development and is not intended for use in production. --- + This repository contains two major components: 1. Smithy code generators for Java 2. Core modules and interfaces for building services and clients in Java @@ -19,11 +21,12 @@ The [codegen](./codegen) directory contains the source code for generating clien > This repository does not contain any generated clients, such as for S3 or other AWS services. > Rather, these are the tools that facilitate the generation of those clients and non-AWS Smithy clients. -## Getting Started +## Getting Started + If this is your first time using Smithy, follow the [Smithy Quickstart guide](https://smithy.io/2.0/quickstart.html) to learn the basics and create a simple Smithy model. -For a guided tour of this project, see the [Smithy Java Quickstart guide](https://smithy.io/2.0/java/quickstart.html). +For a guided introduction to this project, see the [Smithy Java Quickstart guide](https://smithy.io/2.0/java/quickstart.html). The [examples](./examples) are standalone projects that showcase the usage of Smithy Java for generating clients and building services. These examples can be used as a template for a new project using the @@ -35,6 +38,7 @@ and building services. These examples can be used as a template for a new projec > Smithy-Java only supports **Java 17** or later. Older Java versions are not supported. ### Codegen (Gradle) + To use the Smithy Java code generators with Gradle, first create a Smithy Gradle project. > [!NOTE] @@ -97,11 +101,14 @@ tasks.named("compileJava") { ``` ### Stability + Classes and API's annotated with `@SmithyInternal` are for internal use by Smithy-Java libraries and should **not** be used by Smithy users. API's annotated with `@SmithyUnstableApi` are subject to change in future releases. ## Core modules and Interfaces + ### Common + - `core` - Provides basic functionality for (de)serializing generated types and defining `Schema`'s, minimal representations of the Smithy data model for use at runtime. - `io` - Common I/O functionality for clients/servers. @@ -109,17 +116,20 @@ used by Smithy users. API's annotated with `@SmithyUnstableApi` are subject to c - `framework-errors` - Common errors that could be thrown by the Smithy Java framework. ### Client + - `client-core` - Provides protocol and transport agnostic functionality for clients. All generated clients require this package as a runtime dependency. - `client-http` - Client-side implementation of HTTP transport. - `dynamic-client` - Smithy client that exposes a dynamic API that doesn't require codegen. ### Server + - `server-core` - Provides protocol and transport agnostic functionality for servers. All generated server-stubs require this package as a runtime dependency. - `server-netty` - Provides an HTTP server implementation using the [Netty](https://netty.io/) runtime. -### Codegen +### Codegen + - `codegen:core` - Provides the basic framework necessary for codegen plugins and integrations to generate Java code from a Smithy model. Only codegen plugins and integrations should depend on this directly. - `codegen:plugins` - Aggregate package that provides all code generation plugins. @@ -127,45 +137,58 @@ used by Smithy users. API's annotated with `@SmithyUnstableApi` are subject to c Codegen integrations that modify the code generated by codegen plugins can be found in [codegen/integrations](codegen/integrations). ### Protocols -Smithy Java, like the Smithy IDL, is protocol-agnostic. Servers to support any number of protocols and clients can + +Smithy Java, like the Smithy IDL, is protocol-agnostic. Servers support any number of protocols and clients can set the protocol to use at runtime. +> [!NOTE] +> The `rpcv2-cbor`protocol is a generic binary protocol provided by Smithy Java that can be a good +> choice for services that want a fast, compact data format. + The [`protocol-test-harness`](protocol-test-harness) package provides a framework for testing protocols. -#### Client +#### Client + - `client-rpcv2-cbor` - Implementation [rpcv2-cbor](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html#smithy-rpc-v2-cbor-protocol) protocol. - `aws-client-awsjson` - Implementation of [AWS JSON 1.0](https://smithy.io/2.0/aws/protocols/aws-json-1_0-protocol.html#aws-json-1-0-protocol) 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-restjson` - Implementation of [AWS restJson1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol) protocol. -- `aws-client-restXml` - Implementation of [AWS restXml](https://smithy.io/2.0/aws/protocols/aws-restxml-protocol.html#aws-restxml-protocol) protocol. +- `aws-client-restXml` - Implementation of [AWS restXml](https://smithy.io/2.0/aws/protocols/aws-restxml-protocol.html#aws-restxml-protocol) protocol. #### Server + - `server-rpcv2-cbor` - Implementation [rpcv2-cbor](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html#smithy-rpc-v2-cbor-protocol) protocol. - `aws-server-restjson` - Implementation of [AWS restJson1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol) protocol. #### Codecs + Codecs provide basic (de)serialization functionality for protocols. - `json-codec` - (de)serialization functionality for [JSON](https://www.json.org/json-en.html) format - `cbor-codec` - Binary (de)serialization functionality for [CBOR](https://cbor.io/) format - `xml-codec` - (de)serialization functionality for [XML](https://www.w3.org/TR/REC-xml/) format ### Utilities + - `jmespath` - [JMESPath](https://jmespath.org/) implementation that allows querying a `Document` using a JMESPath expression. ## Development + See [CONTRIBUTING](CONTRIBUTING.md) for more information on contributing to the Smithy-Java project. ### Pre-push hooks + Pre-push hooks are automatically added for unix users via the `addGitHooks` gradle task. -**Note**: In order to successfully execute the pre-defined hooks you must have the `smithy` CLI installed. +**Note**: In order to successfully execute the pre-defined git hooks you must have the `smithy` CLI installed. See [installation instructions](https://smithy.io/2.0/guides/smithy-cli/cli_installation.html) if you do not already have the CLI installed. ## Security + If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue. ## License + This project is licensed under the Apache-2.0 License.