AWS cdk documentation change
Summary
Updated documentation formatting, fixed typographical apostrophes, removed redundant 'Topics' section, and adjusted code examples for consistency. Added shell prompt symbols ($) to command-line examples and corrected hyperlink formatting.
Security assessment
The changes are editorial and focus on documentation clarity, formatting, and structure. There are no references to security vulnerabilities, configurations, or features. Updates include typo fixes, command-line example formatting, and removal of redundant sections, none of which impact security practices or address vulnerabilities.
Diff
diff --git a/cdk/v2/guide/work-with-cdk-java.md b/cdk/v2/guide/work-with-cdk-java.md index 7bc7a8e6c..6e5d5ebc7 100644 --- a//cdk/v2/guide/work-with-cdk-java.md +++ b//cdk/v2/guide/work-with-cdk-java.md @@ -11 +11 @@ This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on -Java is a fully-supported client language for the AWS CDK and is considered stable. You can develop AWS CDK applications in Java using familiar tools, including the JDK (Oracle's, or an OpenJDK distribution such as Amazon Corretto) and Apache Maven. +Java is a fully-supported client language for the AWS CDK and is considered stable. You can develop AWS CDK applications in Java using familiar tools, including the JDK (Oracle’s, or an OpenJDK distribution such as Amazon Corretto) and Apache Maven. @@ -23,17 +22,0 @@ It is possible to write AWS CDK applications in JVM-hosted languages other than -###### Topics - - * Get started with Java - - * Creating a project - - * Managing AWS Construct Library modules - - * Managing dependencies in Java - - * AWS CDK idioms in Java - - * Build and run CDK applications - - - - @@ -44 +27 @@ To work with the AWS CDK, you must have an AWS account and credentials and have -Java AWS CDK applications require Java 8 (v1.8) or later. We recommend [Amazon Corretto](https://aws.amazon.com/corretto/), but you can use any OpenJDK distribution or [Oracle's JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). You will also need [Apache Maven](https://maven.apache.org/download.cgi) 3.5 or later. You can also use tools such as Gradle, but the application skeletons generated by the AWS CDK Toolkit are Maven projects. +Java AWS CDK applications require Java 8 (v1.8) or later. We recommend [Amazon Corretto](https://aws.amazon.com/corretto/), but you can use any OpenJDK distribution or [Oracle’s JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). You will also need [Apache Maven](https://maven.apache.org/download.cgi) 3.5 or later. You can also use tools such as Gradle, but the application skeletons generated by the AWS CDK Toolkit are Maven projects. @@ -55,3 +38,3 @@ You create a new AWS CDK project by invoking `cdk init` in an empty directory. U - mkdir my-project - cd my-project - cdk init app --language java + $ mkdir my-project + $ cd my-project + $ cdk init app --language java @@ -67 +50 @@ If you are using an IDE, you can now open or import the project. In Eclipse, for -Use Maven to install AWS Construct Library packages, which are in the group `software.amazon.awscdk`. Most constructs are in the artifact `aws-cdk-lib`, which is added to new Java projects by default. Modules for services whose higher-level CDK support is still being developed are in separate "experimental" packages, named with a short version (no AWS or Amazon prefix) of their service's name. [Search the Maven Central Repository](https://search.maven.org/search?q=software.amazon.awscdk) to find the names of all AWS CDK and AWS Construct Module libraries. +Use Maven to install AWS Construct Library packages, which are in the group `software.amazon.awscdk`. Most constructs are in the artifact `aws-cdk-lib`, which is added to new Java projects by default. Modules for services whose higher-level CDK support is still being developed are in separate "experimental" packages, named with a short version (no AWS or Amazon prefix) of their service’s name. [Search the Maven Central Repository](https://search.maven.org/search?q=software.amazon.awscdk) to find the names of all AWS CDK and AWS Construct Module libraries. @@ -75 +58 @@ Some services' AWS Construct Library support is in more than one namespace. For -The main AWS CDK package is imported in Java code as `software.amazon.awscdk`. Modules for the various services in the AWS Construct Library live under `software.amazon.awscdk.services` and are named similarly to their Maven package name. For example, the Amazon S3 module's namespace is `software.amazon.awscdk.services.s3`. +The main AWS CDK package is imported in Java code as `software.amazon.awscdk`. Modules for the various services in the AWS Construct Library live under `software.amazon.awscdk.services` and are named similarly to their Maven package name. For example, the Amazon S3 module’s namespace is `software.amazon.awscdk.services.s3`. @@ -77 +60 @@ The main AWS CDK package is imported in Java code as `software.amazon.awscdk`. M -We recommend writing a separate Java `import` statement for each AWS Construct Library class you use in each of your Java source files, and avoiding wildcard imports. You can always use a type's fully-qualified name (including its namespace) without an `import` statement. +We recommend writing a separate Java `import` statement for each AWS Construct Library class you use in each of your Java source files, and avoiding wildcard imports. You can always use a type’s fully-qualified name (including its namespace) without an `import` statement. @@ -79 +62 @@ We recommend writing a separate Java `import` statement for each AWS Construct L -If your application depends on an experimental package, edit your project's `pom.xml` and add a new `<dependency>` element in the `<dependencies>` container. For example, the following `<dependency>` element specifies the CodeStar experimental construct library module: +If your application depends on an experimental package, edit your project’s `pom.xml` and add a new `<dependency>` element in the `<dependencies>` container. For example, the following `<dependency>` element specifies the CodeStar experimental construct library module: @@ -90 +73 @@ If your application depends on an experimental package, edit your project's `pom -If you use a Java IDE, it probably has features for managing Maven dependencies. We recommend editing `pom.xml` directly, however, unless you are absolutely sure the IDE's functionality matches what you'd do by hand. +If you use a Java IDE, it probably has features for managing Maven dependencies. We recommend editing `pom.xml` directly, however, unless you are absolutely sure the IDE’s functionality matches what you’d do by hand. @@ -114 +97 @@ Many Java IDEs have integrated Maven support and visual `pom.xml` editors, which -Maven does not support dependency locking. Although it's possible to specify version ranges in `pom.xml`, we recommend you always use exact versions to keep your builds repeatable. +Maven does not support dependency locking. Although it’s possible to specify version ranges in `pom.xml`, we recommend you always use exact versions to keep your builds repeatable. @@ -118 +101 @@ Maven automatically installs transitive dependencies, but there can only be one -Maven automatically installs or updates your dependencies whenever you build (**mvn compile**) or package (**mvn package**) your project. The CDK Toolkit does this automatically every time you run it, so generally there is no need to manually invoke Maven. +Maven automatically installs or updates your dependencies whenever you build (`mvn compile`) or package (`mvn package`) your project. The CDK Toolkit does this automatically every time you run it, so generally there is no need to manually invoke Maven. @@ -136 +119 @@ The `BucketProps` class (like every AWS Construct Library props class) has an in -Constructs, and other classes that take a props-like object as their final argument, offer a shortcut. The class has a `Builder` of its own that instantiates it and its props object in one step. This way, you don't need to explicitly instantiate (for example) both `BucketProps` and a `Bucket`—and you don't need an import for the props type. +Constructs, and other classes that take a props-like object as their final argument, offer a shortcut. The class has a `Builder` of its own that instantiates it and its props object in one step. This way, you don’t need to explicitly instantiate (for example) both `BucketProps` and a `Bucket`\--and you don’t need an import for the props type. @@ -144 +127 @@ Constructs, and other classes that take a props-like object as their final argum -When deriving your own construct from an existing construct, you may want to accept additional properties. We recommend that you follow these builder patterns. However, this isn't as simple as subclassing a construct class. You must provide the moving parts of the two new `Builder` classes yourself. You may prefer to simply have your construct accept one or more additional arguments. You should provide additional constructors when an argument is optional. +When deriving your own construct from an existing construct, you may want to accept additional properties. We recommend that you follow these builder patterns. However, this isn’t as simple as subclassing a construct class. You must provide the moving parts of the two new `Builder` classes yourself. You may prefer to simply have your construct accept one or more additional arguments. You should provide additional constructors when an argument is optional. @@ -148 +131 @@ When deriving your own construct from an existing construct, you may want to acc -In some APIs, the AWS CDK uses JavaScript arrays or untyped objects as input to a method. (See, for example, AWS CodeBuild's [`BuildSpec.fromObject()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue) method.) In Java, these objects are represented as `java.util.Map<String, Object>`. In cases where the values are all strings, you can use `Map<String, String>`. +In some APIs, the AWS CDK uses JavaScript arrays or untyped objects as input to a method. (See, for example, AWS CodeBuild’s [`BuildSpec.fromObject()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue) method.) In Java, these objects are represented as `java.util.Map<String, Object>`. In cases where the values are all strings, you can use `Map<String, String>`. @@ -150 +133 @@ In some APIs, the AWS CDK uses JavaScript arrays or untyped objects as input to -Java does not provide a way to write literals for such containers like some other languages do. In Java 9 and later, you can use [`java.util.Map.of()`](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry...-) to conveniently define maps of up to ten entries inline with one of these calls. +Java does not provide a way to write literals for such containers like some other languages do. In Java 9 and later, you can use [`java.util.Map.of()`](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry%E2%80%A6%E2%80%8B-) to conveniently define maps of up to ten entries inline with one of these calls. @@ -158 +141 @@ Java does not provide a way to write literals for such containers like some othe -To create maps with more than ten entries, use [`java.util.Map.ofEntries()`](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry...-). +To create maps with more than ten entries, use [`java.util.Map.ofEntries()`](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry%E2%80%A6%E2%80%8B-). @@ -169 +152 @@ JavaScript arrays are represented as `List<Object>` or `List<String>` in Java. T -In Java, missing values in AWS CDK objects such as props are represented by `null`. You must explicitly test any value that could be `null` to make sure it contains a value before doing anything with it. Java does not have "syntactic sugar" to help handle null values as some other languages do. You may find Apache ObjectUtil's [defaultIfNull](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#defaultIfNull-T-T-) and [firstNonNull](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#firstNonNull-T...-) useful in some situations. Alternatively, write your own static helper methods to make it easier to handle potentially null values and make your code more readable. +In Java, missing values in AWS CDK objects such as props are represented by `null`. You must explicitly test any value that could be `null` to make sure it contains a value before doing anything with it. Java does not have "syntactic sugar" to help handle null values as some other languages do. You may find Apache ObjectUtil’s [`defaultIfNull`](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#defaultIfNull-T-T-) and [`firstNonNull`](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#firstNonNull-T%E2%80%A6%E2%80%8B-) useful in some situations. Alternatively, write your own static helper methods to make it easier to handle potentially null values and make your code more readable. @@ -173 +156 @@ In Java, missing values in AWS CDK objects such as props are represented by `nul -The AWS CDK automatically compiles your app before running it. However, it can be useful to build your app manually to check for errors and to run tests. You can do this in your IDE (for example, press Control-B in Eclipse) or by issuing `mvn compile` at a command prompt while in your project's root directory. +The AWS CDK automatically compiles your app before running it. However, it can be useful to build your app manually to check for errors and to run tests. You can do this in your IDE (for example, press Control-B in Eclipse) or by issuing `mvn compile` at a command prompt while in your project’s root directory. @@ -175 +158 @@ The AWS CDK automatically compiles your app before running it. However, it can b -Run any tests you've written by running `mvn test` at a command prompt. +Run any tests you’ve written by running `mvn test` at a command prompt.