From 38620362cde0bd2f3080498595201ef75dc98d60 Mon Sep 17 00:00:00 2001 From: Michael Dowling Date: Mon, 2 Mar 2020 12:55:27 -0800 Subject: [PATCH] Add unstable, internal, and generated annotations These annotations allows different parts of the Smithy implementation to evolve at their own pace and better communicate how end users should use the code. The SmithyUnstableApi annotations indicates that an API is subject to change and should be considered experimental. The SmithyInternalApi annotation indicates that an API should not be relied on by end users outside of the Smithy software.amazon.smithy packages. The SmithyGenerated annotation indicates that a package or type was generated and should not be edited by hand. --- .../aws/apigateway/openapi/package-info.java | 22 +++++++++++++ .../smithy/aws/traits/iam/package-info.java | 22 +++++++++++++ .../smithy/codegen/core/package-info.java | 22 +++++++++++++ .../smithy/jsonschema/package-info.java | 22 +++++++++++++ .../smithy/mqtt/traits/package-info.java | 22 +++++++++++++ .../amazon/smithy/openapi/package-info.java | 22 +++++++++++++ .../amazon/smithy/utils/SmithyGenerated.java | 27 ++++++++++++++++ .../smithy/utils/SmithyInternalApi.java | 30 ++++++++++++++++++ .../smithy/utils/SmithyUnstableApi.java | 31 +++++++++++++++++++ 9 files changed, 220 insertions(+) create mode 100644 smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/package-info.java create mode 100644 smithy-aws-traits/src/main/java/software/amazon/smithy/aws/traits/iam/package-info.java create mode 100644 smithy-codegen-core/src/main/java/software/amazon/smithy/codegen/core/package-info.java create mode 100644 smithy-jsonschema/src/main/java/software/amazon/smithy/jsonschema/package-info.java create mode 100644 smithy-mqtt-traits/src/main/java/software/amazon/smithy/mqtt/traits/package-info.java create mode 100644 smithy-openapi/src/main/java/software/amazon/smithy/openapi/package-info.java create mode 100644 smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyGenerated.java create mode 100644 smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyInternalApi.java create mode 100644 smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyUnstableApi.java diff --git a/smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/package-info.java b/smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/package-info.java new file mode 100644 index 00000000000..c91d9cdda41 --- /dev/null +++ b/smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +/** + * Defines traits for integrating Smithy with Amazon API Gateway. + */ +@SmithyUnstableApi +package software.amazon.smithy.aws.apigateway.openapi; + +import software.amazon.smithy.utils.SmithyUnstableApi; diff --git a/smithy-aws-traits/src/main/java/software/amazon/smithy/aws/traits/iam/package-info.java b/smithy-aws-traits/src/main/java/software/amazon/smithy/aws/traits/iam/package-info.java new file mode 100644 index 00000000000..6701b2bbc96 --- /dev/null +++ b/smithy-aws-traits/src/main/java/software/amazon/smithy/aws/traits/iam/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +/** + * Defines AWS specific traits for Smithy. + */ +@SmithyUnstableApi +package software.amazon.smithy.aws.traits.iam; + +import software.amazon.smithy.utils.SmithyUnstableApi; diff --git a/smithy-codegen-core/src/main/java/software/amazon/smithy/codegen/core/package-info.java b/smithy-codegen-core/src/main/java/software/amazon/smithy/codegen/core/package-info.java new file mode 100644 index 00000000000..3dadafb6b4b --- /dev/null +++ b/smithy-codegen-core/src/main/java/software/amazon/smithy/codegen/core/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +/** + * Defines abstractions for implementing Smithy model code generation. + */ +@SmithyUnstableApi +package software.amazon.smithy.codegen.core; + +import software.amazon.smithy.utils.SmithyUnstableApi; diff --git a/smithy-jsonschema/src/main/java/software/amazon/smithy/jsonschema/package-info.java b/smithy-jsonschema/src/main/java/software/amazon/smithy/jsonschema/package-info.java new file mode 100644 index 00000000000..4ff56146d1a --- /dev/null +++ b/smithy-jsonschema/src/main/java/software/amazon/smithy/jsonschema/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +/** + * Converts Smithy models to JSON Schema. + */ +@SmithyUnstableApi +package software.amazon.smithy.jsonschema; + +import software.amazon.smithy.utils.SmithyUnstableApi; diff --git a/smithy-mqtt-traits/src/main/java/software/amazon/smithy/mqtt/traits/package-info.java b/smithy-mqtt-traits/src/main/java/software/amazon/smithy/mqtt/traits/package-info.java new file mode 100644 index 00000000000..9cafabb572c --- /dev/null +++ b/smithy-mqtt-traits/src/main/java/software/amazon/smithy/mqtt/traits/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +/** + * Defines MQTT bindings for Smithy. + */ +@SmithyUnstableApi +package software.amazon.smithy.mqtt.traits; + +import software.amazon.smithy.utils.SmithyUnstableApi; diff --git a/smithy-openapi/src/main/java/software/amazon/smithy/openapi/package-info.java b/smithy-openapi/src/main/java/software/amazon/smithy/openapi/package-info.java new file mode 100644 index 00000000000..ba91cf36880 --- /dev/null +++ b/smithy-openapi/src/main/java/software/amazon/smithy/openapi/package-info.java @@ -0,0 +1,22 @@ +/* + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +/** + * Converts Smithy models to OpenAPI 3.0+. + */ +@SmithyUnstableApi +package software.amazon.smithy.openapi; + +import software.amazon.smithy.utils.SmithyUnstableApi; diff --git a/smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyGenerated.java b/smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyGenerated.java new file mode 100644 index 00000000000..87b1dfe9aec --- /dev/null +++ b/smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyGenerated.java @@ -0,0 +1,27 @@ +/* + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +package software.amazon.smithy.utils; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Target; + +/** + * Annotation used to indicate that a package or class was generated and + * should not be edited directly. + */ +@Target({ElementType.PACKAGE, ElementType.TYPE}) +public @interface SmithyGenerated { +} diff --git a/smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyInternalApi.java b/smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyInternalApi.java new file mode 100644 index 00000000000..ca4e17f93ca --- /dev/null +++ b/smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyInternalApi.java @@ -0,0 +1,30 @@ +/* + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +package software.amazon.smithy.utils; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Target; + +/** + * Annotation used to indicate that an API is considered internal to Smithy + * and subject to change. Breaking changes can and will be introduced to + * elements marked as {@link SmithyInternalApi}. Users of Smithy should not + * depend on any packages, types, fields, constructors, or methods with this + * annotation. + */ +@Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD}) +public @interface SmithyInternalApi { +} diff --git a/smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyUnstableApi.java b/smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyUnstableApi.java new file mode 100644 index 00000000000..9fdc8ae1f55 --- /dev/null +++ b/smithy-utils/src/main/java/software/amazon/smithy/utils/SmithyUnstableApi.java @@ -0,0 +1,31 @@ +/* + * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +package software.amazon.smithy.utils; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Target; + +/** + * Annotation used to indicate that an API is considered unstable and subject + * to change. + * + *

Breaking changes may be introduced to elements marked as {@link SmithyUnstableApi}. + * Users of Smithy may implement and use APIs marked as unstable with the caveat that + * they may need to make changes to their implementations as unstable APIs evolve. + */ +@Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD}) +public @interface SmithyUnstableApi { +}