Skip to content

Commit aed398b

Browse files
jasoniharrisJason Harrisscottgerring
authored
docs: Adding Kotlin example. (#1454)
* Setting up Kotlin environment. Converting test to Kotlin. * Deploying via SAM successfully. * Added Kotlin example. * Removing unused Gradle build file. * Adding SAM template so can be used as an existing project and Java target compatibility * Adding SAM template so can be used as an existing project * Updating guidance to use SAM for build and deploy * Restructuring separate Java and Kotlin examples. * Updating core examples readme to represent new structure for Java and Kotlin examples. * Refactoring application code for efficiency, updating build to cover tests too and is more idiomatic and readme to be more descriptive * Updating to fix trailing \n * Updating guidance to be more specific for examples * Adopting new mechanism for specifying jvm target. * accommodating new project structure * Fixing link typo after refactoring * Setting up Kotlin environment. Converting test to Kotlin. * Deploying via SAM successfully. * Added Kotlin example. * Removing unused Gradle build file. * Adding SAM template so can be used as an existing project and Java target compatibility * Adding SAM template so can be used as an existing project * Updating guidance to use SAM for build and deploy * Restructuring separate Java and Kotlin examples. * Updating core examples readme to represent new structure for Java and Kotlin examples. * Refactoring application code for efficiency, updating build to cover tests too and is more idiomatic and readme to be more descriptive * Updating to fix trailing \n * Updating guidance to be more specific for examples * Adopting new mechanism for specifying jvm target. * accommodating new project structure * Fixing link typo after refactoring * Flattening structure back to original to make merging easier for v2 * Adding build for Kotlin Gradle * Adding build for Kotlin Gradle - Restructuring Java examples to v1 approach * Correcting paths * Adding SNAPSHOT support and local capability for Maven. Testing using Java 1.8 * Reviewed and updated against PR comments. * Un-commenting examples --------- Co-authored-by: Jason Harris <[email protected]> Co-authored-by: Scott Gerring <[email protected]>
1 parent 34fc20e commit aed398b

File tree

18 files changed

+840
-112
lines changed

18 files changed

+840
-112
lines changed

.github/workflows/pr_build.yml

+5-1
Original file line numberDiff line numberDiff line change
@@ -66,11 +66,15 @@ jobs:
6666
cache: 'maven'
6767
- name: Build with Maven
6868
run: mvn -B install --file pom.xml
69-
- name: Build Gradle Example
69+
- name: Build Gradle Example - Java
7070
if: ${{ matrix.java == '8' }} # Gradle example can only be built on Java 8
7171
run: |
7272
cd examples/powertools-examples-core/gradle
7373
./gradlew build
74+
- name: Build Gradle Example - Kotlin
75+
run: |
76+
cd examples/powertools-examples-core/kotlin
77+
./gradlew build
7478
- name: Setup Terraform
7579
if: ${{ matrix.java == '11' }}
7680
uses: hashicorp/setup-terraform@633666f66e0061ca3b725c73b2ec20cd13a8fdd1 #v2.0.3

examples/README.md

+4-2
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,12 @@ Each example can be copied from its subdirectory and used independently of the r
55

66
## Examples
77

8-
* [powertools-examples-core](powertools-examples-core) - Demonstrates the core logging, tracing, and metrics modules with different build tools
9-
* [SAM](./powertools-examples-core/sam)
8+
* [powertools-examples-core](powertools-examples-core) - Demonstrates the core logging, tracing, and metrics modules with different build tools and languages
109
* [CDK](./powertools-examples-core/cdk)
10+
* [Gradle](./powertools-examples-core/gradle)
11+
* [SAM](./powertools-examples-core/sam)
1112
* [Serverless](./powertools-examples-core/serverless)
13+
* [Kotlin](./powertools-examples-core/kotlin)
1214
* [powertools-examples-idempotency](powertools-examples-idempotency) - An idempotent HTTP API
1315
* [powertools-examples-parameters](powertools-examples-parameters) - Uses the parameters module to provide runtime parameters to a function
1416
* [powertools-examples-serialization](powertools-examples-serialization) - Uses the serialization module to serialize and deserialize API Gateway & SQS payloads
+23-13
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
1-
# Powertools for AWS Lambda (Java) - Core Utilities Example
1+
# Powertools for AWS Lambda (Java) - Core Utilities Example
22

33
This project demonstrates the Lambda for Powertools Java module - including
44
[logging](https://docs.powertools.aws.dev/lambda/java/core/logging/),
55
[tracing](https://docs.powertools.aws.dev/lambda/java/core/tracing/), and
66
[metrics](https://docs.powertools.aws.dev/lambda/java/core/metrics/).
77

8-
We provide examples for the following infrastructure-as-code tools:
8+
The example application is the same, and you can now also use Kotlin!
99

10+
## Java
1011
* [AWS SAM](sam/)
1112
* [AWS CDK](cdk/)
1213
* [Serverless framework](serverless/)
@@ -16,11 +17,21 @@ We also provide an example showing the integration of SAM, Powertools, and Gradl
1617

1718
* [AWS SAM with a Gradle build](gradle/)
1819

19-
For each of the tools, the example application is the same, and consists of the following files:
20+
- App.java - Code for the application's Lambda function.
21+
- AppTests.java - Unit tests for the application code.
22+
- events - Invocation events that you can use to invoke the function.
2023

21-
- [App.java](sam/src/main/java/helloworld/App.java) - Code for the application's Lambda function.
22-
- [AppTests.java](sam/src/test/java/helloworld/AppTest.java) - Unit tests for the application code.
23-
- [events](sam/events/event.json) - Invocation events that you can use to invoke the function.
24+
Configuration files and deployment process for each tool are described in corresponding README files.
25+
26+
## Kotlin
27+
28+
- [Gradle](kotlin/)
29+
30+
Example application consists of the following files:
31+
32+
- App.kt - Code for the application's Lambda function.
33+
- AppTests.kt - Unit tests for the application code.
34+
- events - Invocation events that you can use to invoke the function.
2435

2536
Configuration files and deployment process for each tool are described in corresponding README files.
2637

@@ -32,14 +43,13 @@ Once the app is deployed, you can invoke the endpoint like this:
3243
curl https://[REST-API-ID].execute-api.[REGION].amazonaws.com/Prod/hello/
3344
```
3445

35-
The response itself isn't particularly interesting - you will get back some information about your IP address. If
46+
The response itself isn't particularly interesting - you will get back some information about your IP address. If
3647
you go to the Lambda Console and locate the lambda you have deployed, then click the "Monitoring" tab you will
3748
be able to find:
3849

39-
* **View X-Ray traces** - Display the traces captured by the traces module. These include subsegments for the
40-
different function calls within the example
41-
* **View Cloudwatch logs** - Display the structured logging output of the example
50+
- **View X-Ray traces** - Display the traces captured by the traces module. These include subsegments for the
51+
different function calls within the example
52+
- **View Cloudwatch logs** - Display the structured logging output of the example
4253

43-
Likewise, from the CloudWatch dashboard, under **Metrics**, **all metrics**, you will find the namespaces `Another`
44-
and `ServerlessAirline`. The values in each of these are published by the code in
45-
[App.java](sam/src/main/java/helloworld/App.java).
54+
Likewise, from the CloudWatch dashboard, under **Metrics**, **all metrics**, you will find the namespaces `Another`
55+
and `ServerlessAirline`. The values in each of these are published by the code in the respective application's Lambda function.

examples/powertools-examples-core/cdk/README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ For general information on the deployed example itself, you can refer to the par
66

77
## Configuration
88
CDK uses the following project structure:
9-
- [app](./app) - stores the source code of your application, which is similar between all examples
10-
- [infra](./infra) - stores the definition of your infrastructure
11-
- [cdk.json](./infra/cdk.json) - tells the CDK Toolkit how to execute your app
9+
- [app](app) - stores the source code of your application, which is similar between all examples
10+
- [infra](infra) - stores the definition of your infrastructure
11+
- [cdk.json](infra/cdk.json) - tells the CDK Toolkit how to execute your app
1212
- [CdkApp](./infra/src/main/java/cdk/CdkApp.java) - bootstraps your stack, taking AWS `account` and `region` as input
1313
- [CdkStack](./infra/src/main/java/cdk/CdkStack.java) - defines the Lambda function to be deployed as well as API Gateway for it.
1414

Original file line numberDiff line numberDiff line change
@@ -1,92 +1,92 @@
1-
@rem
2-
@rem Copyright 2015 the original author or authors.
3-
@rem
4-
@rem Licensed under the Apache License, Version 2.0 (the "License");
5-
@rem you may not use this file except in compliance with the License.
6-
@rem You may obtain a copy of the License at
7-
@rem
8-
@rem https://www.apache.org/licenses/LICENSE-2.0
9-
@rem
10-
@rem Unless required by applicable law or agreed to in writing, software
11-
@rem distributed under the License is distributed on an "AS IS" BASIS,
12-
@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13-
@rem See the License for the specific language governing permissions and
14-
@rem limitations under the License.
15-
@rem
16-
17-
@if "%DEBUG%"=="" @echo off
18-
@rem ##########################################################################
19-
@rem
20-
@rem Gradle startup script for Windows
21-
@rem
22-
@rem ##########################################################################
23-
24-
@rem Set local scope for the variables with windows NT shell
25-
if "%OS%"=="Windows_NT" setlocal
26-
27-
set DIRNAME=%~dp0
28-
if "%DIRNAME%"=="" set DIRNAME=.
29-
@rem This is normally unused
30-
set APP_BASE_NAME=%~n0
31-
set APP_HOME=%DIRNAME%
32-
33-
@rem Resolve any "." and ".." in APP_HOME to make it shorter.
34-
for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
35-
36-
@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
37-
set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
38-
39-
@rem Find java.exe
40-
if defined JAVA_HOME goto findJavaFromJavaHome
41-
42-
set JAVA_EXE=java.exe
43-
%JAVA_EXE% -version >NUL 2>&1
44-
if %ERRORLEVEL% equ 0 goto execute
45-
46-
echo.
47-
echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
48-
echo.
49-
echo Please set the JAVA_HOME variable in your environment to match the
50-
echo location of your Java installation.
51-
52-
goto fail
53-
54-
:findJavaFromJavaHome
55-
set JAVA_HOME=%JAVA_HOME:"=%
56-
set JAVA_EXE=%JAVA_HOME%/bin/java.exe
57-
58-
if exist "%JAVA_EXE%" goto execute
59-
60-
echo.
61-
echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
62-
echo.
63-
echo Please set the JAVA_HOME variable in your environment to match the
64-
echo location of your Java installation.
65-
66-
goto fail
67-
68-
:execute
69-
@rem Setup the command line
70-
71-
set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
72-
73-
74-
@rem Execute Gradle
75-
"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
76-
77-
:end
78-
@rem End local scope for the variables with windows NT shell
79-
if %ERRORLEVEL% equ 0 goto mainEnd
80-
81-
:fail
82-
rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
83-
rem the _cmd.exe /c_ return code!
84-
set EXIT_CODE=%ERRORLEVEL%
85-
if %EXIT_CODE% equ 0 set EXIT_CODE=1
86-
if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
87-
exit /b %EXIT_CODE%
88-
89-
:mainEnd
90-
if "%OS%"=="Windows_NT" endlocal
91-
92-
:omega
1+
@rem
2+
@rem Copyright 2015 the original author or authors.
3+
@rem
4+
@rem Licensed under the Apache License, Version 2.0 (the "License");
5+
@rem you may not use this file except in compliance with the License.
6+
@rem You may obtain a copy of the License at
7+
@rem
8+
@rem https://www.apache.org/licenses/LICENSE-2.0
9+
@rem
10+
@rem Unless required by applicable law or agreed to in writing, software
11+
@rem distributed under the License is distributed on an "AS IS" BASIS,
12+
@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
@rem See the License for the specific language governing permissions and
14+
@rem limitations under the License.
15+
@rem
16+
17+
@if "%DEBUG%"=="" @echo off
18+
@rem ##########################################################################
19+
@rem
20+
@rem Gradle startup script for Windows
21+
@rem
22+
@rem ##########################################################################
23+
24+
@rem Set local scope for the variables with windows NT shell
25+
if "%OS%"=="Windows_NT" setlocal
26+
27+
set DIRNAME=%~dp0
28+
if "%DIRNAME%"=="" set DIRNAME=.
29+
@rem This is normally unused
30+
set APP_BASE_NAME=%~n0
31+
set APP_HOME=%DIRNAME%
32+
33+
@rem Resolve any "." and ".." in APP_HOME to make it shorter.
34+
for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
35+
36+
@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
37+
set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
38+
39+
@rem Find java.exe
40+
if defined JAVA_HOME goto findJavaFromJavaHome
41+
42+
set JAVA_EXE=java.exe
43+
%JAVA_EXE% -version >NUL 2>&1
44+
if %ERRORLEVEL% equ 0 goto execute
45+
46+
echo.
47+
echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
48+
echo.
49+
echo Please set the JAVA_HOME variable in your environment to match the
50+
echo location of your Java installation.
51+
52+
goto fail
53+
54+
:findJavaFromJavaHome
55+
set JAVA_HOME=%JAVA_HOME:"=%
56+
set JAVA_EXE=%JAVA_HOME%/bin/java.exe
57+
58+
if exist "%JAVA_EXE%" goto execute
59+
60+
echo.
61+
echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
62+
echo.
63+
echo Please set the JAVA_HOME variable in your environment to match the
64+
echo location of your Java installation.
65+
66+
goto fail
67+
68+
:execute
69+
@rem Setup the command line
70+
71+
set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
72+
73+
74+
@rem Execute Gradle
75+
"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
76+
77+
:end
78+
@rem End local scope for the variables with windows NT shell
79+
if %ERRORLEVEL% equ 0 goto mainEnd
80+
81+
:fail
82+
rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
83+
rem the _cmd.exe /c_ return code!
84+
set EXIT_CODE=%ERRORLEVEL%
85+
if %EXIT_CODE% equ 0 set EXIT_CODE=1
86+
if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
87+
exit /b %EXIT_CODE%
88+
89+
:mainEnd
90+
if "%OS%"=="Windows_NT" endlocal
91+
92+
:omega
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Powertools for AWS Lambda (Kotlin) - Core Utilities Example
2+
3+
This project demonstrates the Lambda for Powertools Kotlin module deployed using [Serverless Application Model](https://aws.amazon.com/serverless/sam/) with
4+
[Gradle](https://gradle.org/) running the build. This example is configured for Java 1.8 only; in order to use a newer version, check out the Gradle
5+
configuration guide [in the main project README](../../../README.md).
6+
7+
You can also use `sam init` to create a new Gradle-powered Powertools application - choose to use the **AWS Quick Start Templates**,
8+
and then **Hello World Example with Powertools for AWS Lambda**, **Java 17** runtime, and finally **gradle**.
9+
10+
For general information on the deployed example itself, you can refer to the parent [README](../README.md)
11+
12+
## Configuration
13+
SAM uses [template.yaml](template.yaml) to define the application's AWS resources.
14+
This file defines the Lambda function to be deployed as well as API Gateway for it.
15+
16+
The build of the project is managed by Gradle, and configured in [build.gradle.kts](build.gradle.kts)
17+
.
18+
19+
## Deploy the sample application
20+
To get started, you can use the included template with SAM to run the build and deploy to your AWS environment:
21+
22+
```bash
23+
sam build && sam deploy --guided
24+
```
25+
26+
Once this is done to deploy the example, check out the instructions for getting started with SAM in
27+
[the examples directory](../../README.md)
28+
29+
## Additional notes
30+
31+
You can watch the trace information or log information using the SAM CLI:
32+
```bash
33+
# Tail the logs
34+
sam logs --tail $MY_STACK
35+
36+
# Tail the traces
37+
sam traces --tail
38+
```
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
plugins {
2+
id("io.freefair.aspectj.post-compile-weaving") version "6.6.3"
3+
kotlin("jvm") version "1.9.10"
4+
}
5+
6+
repositories {
7+
mavenLocal()
8+
mavenCentral()
9+
}
10+
11+
dependencies {
12+
implementation("com.amazonaws:aws-lambda-java-core:1.2.2")
13+
implementation("com.fasterxml.jackson.core:jackson-annotations:2.13.2")
14+
implementation("com.fasterxml.jackson.core:jackson-databind:2.13.2.2")
15+
implementation("com.amazonaws:aws-lambda-java-events:3.11.0")
16+
implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.13.2")
17+
aspect("software.amazon.lambda:powertools-tracing:1.18.0-SNAPSHOT")
18+
aspect("software.amazon.lambda:powertools-logging:1.18.0-SNAPSHOT")
19+
aspect("software.amazon.lambda:powertools-metrics:1.18.0-SNAPSHOT")
20+
testImplementation("junit:junit:4.13.2")
21+
implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
22+
}
23+
24+
tasks.compileKotlin {
25+
kotlinOptions {
26+
jvmTarget = "1.8"
27+
}
28+
}
29+
30+
tasks.compileTestKotlin {
31+
kotlinOptions {
32+
jvmTarget = "1.8"
33+
}
34+
}
35+
36+
// If using JDK 11 or higher, use the following instead:
37+
//kotlin {
38+
// jvmToolchain(11)
39+
//}

0 commit comments

Comments
 (0)