diff --git a/CI.adoc b/CI.adoc new file mode 100644 index 00000000..cc0c9b76 --- /dev/null +++ b/CI.adoc @@ -0,0 +1,42 @@ += Continuous Integration + +image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-geode%2Fmaster&subject=Moore%20(master)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-geode/] +image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-geode%2F2.1.x&subject=Lovelace%20(2.1.x)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-geode/] + +== Running CI tasks locally + +Since this pipeline is purely Docker-based, it's easy to: + +* Debug what went wrong on your local machine. +* Test out a a tweak to your `test.sh` script before sending it out. +* Experiment against a new image before submitting your pull request. + +All of these use cases are great reasons to essentially run what the CI server does on your local machine. + +IMPORTANT: To do this you must have Docker installed on your machine. + +1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-data-geode-github adoptopenjdk/openjdk8:latest /bin/bash` ++ +This will launch the Docker image and mount your source code at `spring-data-geode-github`. ++ +2. `cd spring-data-geode-github` ++ +Next, run your tests from inside the container: ++ +3. `./mvnw clean dependency:list test -Dsort` (or whatever profile you need to test out) + +Since the container is binding to your source, you can make edits from your IDE and continue to run build jobs. + +If you test building the artifact, do this: + +1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-data-geode-github adoptopenjdk/openjdk8:latest /bin/bash` ++ +This will launch the Docker image and mount your source code at `spring-data-geode-github`. ++ +2. `cd spring-data-geode-github` ++ +Next, try to package everything up from inside the container: ++ +3. `./mvnw -Pci,snapshot -Dmaven.test.skip=true clean package` + +NOTE: Docker containers can eat up disk space fast! From time to time, run `docker system prune` to clean out old images. diff --git a/README.adoc b/README.adoc index 1b943fde..9350d30b 100644 --- a/README.adoc +++ b/README.adoc @@ -1,172 +1,169 @@ -image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-geode%2Fmaster&subject=Moore%20(master)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-geode/] -image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-geode%2F2.1.x&subject=Lovelace%20(2.1.x)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-geode/] +image:https://spring.io/badges/spring-data-geode/ga.svg[Spring Data Geode,link=https://projects.spring.io/spring-data-geode#quick-start] image:https://spring.io/badges/spring-data-geode/snapshot.svg[Spring Data Geode,link=https://projects.spring.io/spring-data-geode#quick-start] -= Spring Data for Apache Geode += Spring Data for Apache Geode image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-geode%2Fmaster&subject=Build[link=https://jenkins.spring.io/view/SpringData/job/spring-data-geode/] https://gitter.im/spring-projects/spring-data[image:https://badges.gitter.im/spring-projects/spring-data.svg[Gitter]] -The primary goal of the https://projects.spring.io/spring-data-gemfire[Spring Data for Apache Geode] project is to -make it easier to build highly scalable, _Spring_ powered applications using https://geode.apache.org/[Apache Geode] -as the underlying distributed, in-memory data management platform. +Spring Data for Apache Geode brings the full power of the Spring Framework to your Apache Geode applications. -= Examples +== Features -For examples on using the _Spring Data for Apache Geode_, see the -https://github.com/SpringSource/spring-gemfire-examples[spring-gemfire-examples] project. +* XML namespace to http://docs.spring.io/spring-data-geode/docs/current/reference/html/#bootstrap[configure and create Apache Geode resources declaratively with Spring] +* Annotation model to https://docs.spring.io/spring-data/geode/docs/current/reference/html/#bootstrap-annotation-config[quickly and easily get started with Apache Geode out-of-the-box] +* Simplifies https://docs.spring.io/spring-data/geode/docs/current/reference/html/#apis[working with Apache Geode APIs] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#apis:spring-cache-abstraction[Spring Cache Abstraction backed by Apache Geode] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#mapping[Spring Data Mapping infrastructure applied to POJOs stored in Apache Geode] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#gemfire-repositories[Spring Data Repositories backed by Apache Geode] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#apis:transaction-management[Apache Geode Cache Transactions through Spring's Declarative Transaction Management] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#apis:global-transaction-management[Additional support for using Apache Geode in Global, JTA Transactions through Spring's Declarative Transaction Management] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#serialization[Enhanced support for Apache Geode Serialization] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#function-annotations[Annotations for Function Executions] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#apis:continuous-query[Support for Continuous Query] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#bootstrap:lucene[Enhanced support for Apache Lucene Integration] +* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#gemfire-bootstrap[Bootstrapping a Spring Context with Apache Geode] +* Spring Tool Suite http://docs.spring.io/sts/nan/v310/NewAndNoteworthy.html[Spring Project Templates for Apache Geode] -= Getting Help +== Code of Conduct -Read the main project https://projects.spring.io/spring-data-gemfire/[website] along with the https://docs.spring.io/spring-data-gemfire/docs/current/reference/html/[User Guide]. +This project is governed by the link:CODE_OF_CONDUCT.adoc[Spring Code of Conduct]. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. -Look at the source code and the https://docs.spring.io/spring-data-gemfire/docs/current/api/[JavaDocs]. +== Getting Started -For more detailed questions, visit https://stackoverflow.com/questions/tagged/spring-data-gemfire[StackOverflow]. +Here is a quick teaser of an application using Spring Data Repositories in Java: -If you are new to _Spring_ as well as _Spring Data for Apache Geode_, look for information about -https://spring.io/projects[Spring projects]. - -== Quick Start - -For those in a hurry: - -* - -Download the jar through - -* - -Maven: - -[source,xml] +[source,java] ---- - - org.springframework.data - spring-data-geode - ${version} - +public interface PersonRepository extends CrudRepository { - - - spring-maven-snapshot - Spring Maven SNAPSHOT Repository - https://repo.spring.io/snapshot - true - + List findByLastname(String lastname); - - - spring-maven-milestone - Spring Maven Milestone Repository - https://repo.spring.io/milestone - ----- - -* Gradle: -[source,groovy] ----- -repositories { - mavenRepo name: "spring-snapshot", urls: "https://repo.spring.io/snapshot" - mavenRepo name: "spring-milestone", urls: "https://repo.spring.io/milestone" - mavenRepo name: "spring-plugins" , urls: "https://repo.spring.io/plugins-release" + List findByFirstnameLike(String firstname); } -dependencies { - compile "org.springframework.data:spring-data-geode:${version}" +@Service +public class MyService { + + private final PersonRepository repository; + + public MyService(PersonRepository repository) { + this.repository = repository; + } + + public void doWork() { + + repository.deleteAll(); + + Person person = new Person(); + person.setFirstname("John"); + person.setLastname("Blum"); + repository.save(person); + + List lastNameResults = repository.findByLastname("Blum"); + List firstNameResults = repository.findByFirstnameLike("J*"); + } } ---- -* Configure a Geode cache and Region (REPLICATE, PARTITION and so on): +Configure a Pivotal Geode cache and Region (REPLICATE, PARTITION and so on): + [source,xml] ---- + http://www.springframework.org/schema/geode https://www.springframework.org/schema/geode/spring-geode.xsd + http://www.springframework.org/schema/data/gemfire https://www.springframework.org/schema/data/geode/spring-data-gemfire.xsd"> + ---- -* Use the Region to read/write data: -[source,java] +=== Maven configuration + +Add the Maven dependency: + +[source,xml] ---- -region.put(Long.valueOf(1), new Person("Jane", "Smith")); + + org.springframework.data + spring-data-geode + ${version}.RELEASE + ---- -* And/Or `GemFireTemplate` to interact with Geode: -[source,java] +If you'd rather like the latest snapshots of the upcoming major version, use our Maven snapshot repository and declare the appropriate dependency version. + +[source,xml] ---- -template.query("person = 1"); + + org.springframework.data + spring-data-geode + ${version}.BUILD-SNAPSHOT + + + + spring-libs-snapshot + Spring Snapshot Repository + https://repo.spring.io/libs-snapshot + ---- -= Building +== Getting Help -_Spring Data for Apache Geode_ uses Maven as its build system. To compile the project, simply type from the root folder +Having trouble with Spring Data? We’d love to help! -[source] +* Check the +https://docs.spring.io/spring-data/geode/docs/current/reference/html/[reference documentation], and https://docs.spring.io/spring-data/geode/docs/current/api/[Javadocs]. +* Learn the Spring basics – Spring Data builds on Spring Framework, check the https://spring.io[spring.io] web-site for a wealth of reference documentation. +If you are just starting out with Spring, try one of the https://spring.io/guides[guides]. +* If you are upgrading, check out the https://docs.spring.io/spring-data/geode/docs/current/changelog.txt[changelog] for "`new and noteworthy`" features. +* Ask a question - we monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-data[`spring-data-geode`]. +You can also chat with the community on https://gitter.im/spring-projects/spring-data[Gitter]. +* Report bugs with Spring Data for Apache Geode at https://jira.spring.io/browse/DATAGEODE[jira.spring.io/browse/DATAGEODE]. + +== Reporting Issues + +Spring Data uses JIRA as issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below: + +* Before you log a bug, please search the +https://jira.spring.io/browse/DATAGEODE[issue tracker] to see if someone has already reported the problem. +* If the issue doesn’t already exist, https://jira.spring.io/browse/DATAGEODE[create a new issue]. +* Please provide as much information as possible with the issue report, we like to know the version of Spring Data that you are using and JVM version. +* If you need to paste code, or include a stack trace use JIRA `{code}…{code}` escapes before and after your text. +* If possible try to create a test-case or project that replicates the issue. Attach a link to your code or a compressed file containing your code. + +== Building from Source + +You don’t need to build from source to use Spring Data (binaries in https://repo.spring.io[repo.spring.io]), but if you want to try out the latest and greatest, Spring Data can be easily built with the https://github.com/takari/maven-wrapper[maven wrapper]. +You also need JDK 1.8. + +[source,bash] ---- -mvn clean install + $ ./mvnw clean install ---- -= Contributing +If you want to build with the regular `mvn` command, you will need https://maven.apache.org/run-maven/index.html[Maven v3.5.0 or above]. -Here are some ways for you to get involved in the community: +_Also see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] if you wish to submit pull requests, and in particular please sign the https://cla.pivotal.io/sign/spring[Contributor’s Agreement] before your first change, is trivial._ -* Get involved with the Spring community on the Spring Community Forums (now on StackOverflow). -Please help out on the https://stackoverflow.com/questions/tagged/spring-data-gemfire[forum] -by responding to questions and joining the debate. -* Create https://jira.spring.io/browse/SGF[JIRA] tickets for bugs and new features and comment and vote on the bugs -you are interested in. -* GitHub is for social coding. If you want to write code, we encourage contributions through pull requests -from https://help.github.com/forking/[forks of this repository]. If you want to contribute code this way, -please reference a JIRA ticket as well covering the specific issue you are addressing. -* Watch for upcoming articles on Spring by https://spring.io/blog[subscribing] to spring.io. +=== Building reference documentation -Before we accept a non-trivial patch or pull request we will need you to -https://cla.pivotal.io/sign/spring[sign the 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. If you forget to do so, you'll be reminded when you submit a pull request. -Active contributors might be asked to join the core team, and given the ability to merge pull requests. +Building the documentation builds also the project without running tests. -= Running CI tasks locally +[source,bash] +---- + $ ./mvnw clean install -Pdistribute +---- -Since this pipeline is purely Docker-based, it's easy to: +The generated documentation is available from `target/site/reference/html/index.html`. -* Debug what went wrong on your local machine. -* Test out a a tweak to your `test.sh` script before sending it out. -* Experiment against a new image before submitting your pull request. -All of these use cases are great reasons to essentially run what the CI server does on your local machine. - -IMPORTANT: To do this you must have Docker installed on your machine. - -1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-data-geode-github adoptopenjdk/openjdk8:latest /bin/bash` -+ -This will launch the Docker image and mount your source code at `spring-data-geode-github`. -+ -2. `cd spring-data-geode-github` -+ -Next, run your tests from inside the container: -+ -3. `./mvnw clean dependency:list test -Dsort` (or whatever profile you need to test out) - -Since the container is binding to your source, you can make edits from your IDE and continue to run build jobs. - -If you test building the artifact, do this: - -1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-data-geode-github adoptopenjdk/openjdk8:latest /bin/bash` -+ -This will launch the Docker image and mount your source code at `spring-data-geode-github`. -+ -2. `cd spring-data-geode-github` -+ -Next, try to package everything up from inside the container: -+ -3. `./mvnw -Pci,snapshot -Dmaven.test.skip=true clean package` - -NOTE: Docker containers can eat up disk space fast! From time to time, run `docker system prune` to clean out old images. +== License +Spring Data for Apache Geode is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].