197 lines
8.2 KiB
Plaintext
197 lines
8.2 KiB
Plaintext
////
|
|
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.
|
|
////
|
|
|
|
|
|
:jdkversion: 1.8
|
|
:github-tag: master
|
|
:github-repo: spring-cloud/spring-cloud-stream-binder-kafka
|
|
|
|
:github-raw: https://raw.githubusercontent.com/{github-repo}/{github-tag}
|
|
:github-code: https://github.com/{github-repo}/tree/{github-tag}
|
|
|
|
image::https://circleci.com/gh/spring-cloud/spring-cloud-stream-binder-kafka.svg?style=svg["CircleCI", link="https://circleci.com/gh/spring-cloud/spring-cloud-stream-binder-kafka"]
|
|
image::https://codecov.io/gh/spring-cloud/spring-cloud-stream-binder-kafka/branch/{github-tag}/graph/badge.svg["codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-stream-binder-kafka"]
|
|
image::https://badges.gitter.im/spring-cloud/spring-cloud-stream.svg[Gitter, link="https://gitter.im/spring-cloud/spring-cloud-stream?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]
|
|
|
|
// ======================================================================================
|
|
|
|
//= Overview
|
|
[partintro]
|
|
--
|
|
This guide describes the Apache Kafka implementation of the Spring Cloud Stream Binder.
|
|
It contains information about its design, usage, and configuration options, as well as information on how the Stream Cloud Stream concepts map onto Apache Kafka specific constructs.
|
|
In addition, this guide explains the Kafka Streams binding capabilities of Spring Cloud Stream.
|
|
--
|
|
|
|
== ANNOUNCEMENT
|
|
|
|
**IMPORTANT: This repository is now migrated as part of core Spring Cloud Stream - https://github.com/spring-cloud/spring-cloud-stream.
|
|
Please create new issues over at the core repository.**
|
|
|
|
|
|
== Apache Kafka Binder
|
|
|
|
=== Usage
|
|
|
|
To use Apache Kafka binder, you need to add `spring-cloud-stream-binder-kafka` as a dependency to your Spring Cloud Stream application, as shown in the following example for Maven:
|
|
|
|
[source,xml]
|
|
----
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-stream-binder-kafka</artifactId>
|
|
</dependency>
|
|
----
|
|
|
|
Alternatively, you can also use the Spring Cloud Stream Kafka Starter, as shown in the following example for Maven:
|
|
|
|
[source,xml]
|
|
----
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-stream-kafka</artifactId>
|
|
</dependency>
|
|
----
|
|
|
|
== Apache Kafka Streams Binder
|
|
|
|
=== Usage
|
|
|
|
To use Apache Kafka Streams binder, you need to add `spring-cloud-stream-binder-kafka-streams` as a dependency to your Spring Cloud Stream application, as shown in the following example for Maven:
|
|
|
|
[source,xml]
|
|
----
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-stream-binder-kafka-streams</artifactId>
|
|
</dependency>
|
|
----
|
|
|
|
= Appendices
|
|
[appendix]
|
|
[[building]]
|
|
== Building
|
|
|
|
:jdkversion: 1.7
|
|
|
|
=== Basic Compile and Test
|
|
|
|
To build the source you will need to install JDK {jdkversion}.
|
|
|
|
The build uses the Maven wrapper so you don't have to install a specific
|
|
version of Maven. To enable the tests, you should have Kafka server 0.9 or above running
|
|
before building. See below for more information on running the servers.
|
|
|
|
The main build command is
|
|
|
|
----
|
|
$ ./mvnw clean install
|
|
----
|
|
|
|
You can also add '-DskipTests' if you like, to avoid running the tests.
|
|
|
|
NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command
|
|
in place of `./mvnw` in the examples below. If you do that you also
|
|
might need to add `-P spring` if your local Maven settings do not
|
|
contain repository declarations for spring pre-release artifacts.
|
|
|
|
NOTE: Be aware that you might need to increase the amount of memory
|
|
available to Maven by setting a `MAVEN_OPTS` environment variable with
|
|
a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in
|
|
the `.mvn` configuration, so if you find you have to do it to make a
|
|
build succeed, please raise a ticket to get the settings added to
|
|
source control.
|
|
|
|
|
|
The projects that require middleware generally include a
|
|
`docker-compose.yml`, so consider using
|
|
https://compose.docker.io/[Docker Compose] to run the middeware servers
|
|
in Docker containers.
|
|
|
|
=== Documentation
|
|
|
|
There is a "full" profile that will generate documentation.
|
|
|
|
=== Working with the code
|
|
If you don't have an IDE preference we would recommend that you use
|
|
https://www.springsource.com/developer/sts[Spring Tools Suite] or
|
|
https://eclipse.org[Eclipse] when working with the code. We use the
|
|
https://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools
|
|
should also work without issue.
|
|
|
|
==== Importing into eclipse with m2eclipse
|
|
We recommend the https://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with
|
|
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
|
|
marketplace".
|
|
|
|
Unfortunately m2e does not yet support Maven 3.3, so once the projects
|
|
are imported into Eclipse you will also need to tell m2eclipse to use
|
|
the `.settings.xml` file for the projects. If you do not do this you
|
|
may see many different errors related to the POMs in the
|
|
projects. Open your Eclipse preferences, expand the Maven
|
|
preferences, and select User Settings. In the User Settings field
|
|
click Browse and navigate to the Spring Cloud project you imported
|
|
selecting the `.settings.xml` file in that project. Click Apply and
|
|
then OK to save the preference changes.
|
|
|
|
NOTE: Alternatively you can copy the repository settings from https://github.com/spring-cloud/spring-cloud-build/blob/master/.settings.xml[`.settings.xml`] into your own `~/.m2/settings.xml`.
|
|
|
|
==== Importing into eclipse without m2eclipse
|
|
If you prefer not to use m2eclipse you can generate eclipse project metadata using the
|
|
following command:
|
|
|
|
[indent=0]
|
|
----
|
|
$ ./mvnw eclipse:eclipse
|
|
----
|
|
|
|
The generated eclipse projects can be imported by selecting `import existing projects`
|
|
from the `file` menu.
|
|
[[contributing]
|
|
== Contributing
|
|
|
|
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://support.springsource.com/spring_committer_signup[contributor's 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 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.
|
|
|
|
* Use the Spring Framework code format conventions. If you use Eclipse
|
|
you can import formatter settings using the
|
|
`eclipse-code-formatter.xml` file from the
|
|
https://github.com/spring-cloud/build/tree/master/eclipse-coding-conventions.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.
|
|
* Make sure all new `.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.
|
|
* Add the ASF license header comment to all new `.java` files (copy from existing files
|
|
in the project)
|
|
* Add yourself as an `@author` to the .java files that you modify substantially (more
|
|
than cosmetic changes).
|
|
* Add some Javadocs and, if you change the namespace, some XSD doc elements.
|
|
* A few unit tests would help a lot as well -- someone has to do it.
|
|
* If no-one else is using your branch, please rebase it against the current master (or
|
|
other target branch in the main project).
|
|
* When writing a commit message please follow https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions],
|
|
if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit
|
|
message (where XXXX is the issue number).
|
|
|
|
// ======================================================================================
|