//// DO NOT EDIT THIS FILE. IT WAS GENERATED. Manual changes to this file will be lost when it is generated again. Edit the files in the src/main/asciidoc/ directory instead. ////
= Spring Cloud for Amazon Web Services
Spring Cloud for Amazon Web Services, part of the Spring Cloud umbrella project, eases the integration with hosted Amazon Web Services. It offers a convenient way to interact with AWS provided services using well-known Spring idioms and APIs, such as the messaging or caching API. Developers can build their application around the hosted services without having to care about infrastructure or maintenance.
Note: Further Spring Cloud AWS versions development moved to https://github.com/awspring/spring-cloud-aws[awspring/spring-cloud-aws]. The only active branch in this repository is 2.2.x.
= Checking out and building To check out the project and build it from source, do the following:
If you encounter out of memory errors during the build, increase available heap and permgen for Maven:
To build and install jars into your local Maven cache:
= Building documentation
Documentation can be built by activating the docs
profile in the maven
build. If there is an ruby error like
then the user must install the asciidoctor gem and set the environment
variable GEM_HOME
to the ruby gem folder. For example:
gem environment
export GEM_HOME=
= Using IntelliJ IDEA Spring Cloud AWS development is done with https://www.jetbrains.com/idea/[IntelliJ IDEA]. In order to create all https://www.jetbrains.com/idea/[IntelliJ IDEA] project files, you have to import the file within idea as a maven project.
Note: Please make sure to revert all changes in the .idea config file directory, as the maven plugin overwrites the configuration files kept in the scm.
= Running integration tests
Spring Cloud AWS contains a test-suite which runs integration tests to ensure compatibility with the Amazon Web Services. In order to run the integration tests, the build process has to create different resources on the Amazon Webservice platform (Amazon EC2 instances, Amazon RDS instances, Amazon S3 Buckets, Amazon SQS Queues). Creating these resources takes time and costs money, because every instance creation is charged with a one hour usage. Therefore Spring Cloud AWS does not execute the integration tests by default.
In order to run integration tests you must prepare three properties named accessKey,secretKey and rdsPassword. These two properties accessKey and secretKey are account/user specific and should never be shared to anyone. To retrieve these settings you have to open your account inside the AWS console and retrieve them through the https://portal.aws.amazon.com/gp/aws/securityCredentials[Security Credentials Page]. Note: In general we recommend that you use an https://aws.amazon.com/iam/[Amazon IAM] user instead of the account itself. The last password rdsPassword is used to access the database inside the integration tests. This password has a minimum length of 8 characters.
Also you must prepare the sender and recipient mail addresses to test the https://aws.amazon.com/ses/[Amazon Simple E-Mail Service]. These two addresses must be verified for the Amazon SES Service.
To build with the integration tests you must execute
The integration test will create an https://aws.amazon.com/de/cloudformation/[Amazon Web Services CloudFormation] stack and execute the tests. The stack is destroyed after executing the tests (either successful or failed) to ensure that there are no unnecessary costs.
= Costs of integration tests The costs for one integration test run should not be more than 0.40 $ per hour (excl. VAT).
= Developing using Amazon Web Services
During development it might be time-consuming to run the integration tests regularly. In order to create a stack only once, and reuse them for the tests run, you have to create the stack manually using the template found in /spring-cloud-aws-integration-test/src/test/resources. You will need to create the stack with the name "IntegrationTestStack" to ensure that the integration tests will re-use the stack.
= Getting in touch
Spring Cloud Team on https://twitter.com/springcentral[Twitter]
Individual team members can be found on different social media channels
== Contributing
:spring-cloud-build-branch: master
Spring Cloud is released under the non-restrictive Apache 2.0 license, and follows a very standard Github development process, using Github tracker for issues and merging pull requests into master. If you want to contribute even something trivial please do not hesitate, but follow the guidelines below.
=== Sign the Contributor License Agreement Before we accept a non-trivial patch or pull request we will need you to sign the https://cla.pivotal.io/sign/spring[Contributor License Agreement]. Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join the core team, and given the ability to merge pull requests.
=== Code of Conduct This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[code of conduct]. By participating, you are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.
=== Code Conventions and Housekeeping None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge.
eclipse-code-formatter.xml
file from the
https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring
Cloud Build] project. If using IntelliJ, you can use the
https://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter
Plugin] to import the same file..java
files to have a simple Javadoc class comment with at least an
@author
tag identifying you, and preferably at least a paragraph on what the class is
for..java
files (copy from existing files
in the project)@author
to the .java files that you modify substantially (more
than cosmetic changes).Fixes gh-XXXX
at the end of the commit
message (where XXXX is the issue number).=== Checkstyle
Spring Cloud Build comes with a set of checkstyle rules. You can find them in the spring-cloud-build-tools
module. The most notable files under the module are: