spring-data-geode/README.adoc

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 image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-geode%2Fmain&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]]

Spring Data for Apache Geode brings the full power of the Spring Framework to your Apache Geode applications.

[[notice]]
== NOTICE

As of Spring Data `2022.0.0-RC1` / _Turing_ / `3.0.0-RC1`, the _Spring Data for Apache Geode_ (SDG) module has been removed
from the Spring Data BOM and Spring Data release train. SDG will no longer continue in the `3.0` generation
from this point forward.

In short, a https://markmail.org/message/oafksl5iufmqhuyg[decision] was made by VMware to discontinue its contributions
to the Apache Geode project at the Apache Software Foundation (ASF). VMware has committed to the Apache Geode project
at ASF up until 2023-October-1. This puts the SDG project at odds with the Apache Geode project, particularly with
respect to https://spring.io/projects/spring-data-geode#support[support timelines].

While SDG `2.7.x` is already GA and based on Apache Geode `1.14.x`, SDG `3.0` was targeting support for Apache Geode `1.15`
(see https://geode.apache.org/releases/[releases]). Support of Apache Geode `1.15` will now move into
_Spring Data for Apache Geode_ (SDG) `2.8`. SDG `2.8` will proceed with a series of milestone releases leading up to
a final `2.8.0` GA in a relatively compressed timeframe. Release schedule and dates to be determined.

In addition, service releases of SDG `2.8`, for example, a SDG `2.8.1`, will only occur on an as needed basis to address
any CVEs, bug reports, and to make minor enhancements as necessary in support of our users. No new or significant features,
or additions will be made to SDG beyond `2.7`. SDG `2.8` will close out more than decade long tenure (since its inception
in 2010) of the _Spring Data for Apache Geode_ project.

Finally, _Spring Data for VMware Tanzu GemFire_ (SDG) project will be the successor for the _Spring Data for Apache Geode_ project
and restored as an externally managed and community-led project. SD GemFire will not be part of the Spring Data BOM,
will not be released as part of the Spring Data release train and will not be maintained by the Spring (Data) team
any longer. It will be solely managed and maintained by the VMware GemFire team in the VMware data org as
an externally managed, community-led module.

Specifics of the _Spring Data for VMware Tanzu GemFire_ project and effort are beyond the scope this notice, but more
details will be provided in a blog post (pending review and approval) and on
the https://spring.io/projects/spring-data-gemfire[Spring Data for VMware Tanzu GemFire] project page at https://spring.io[spring.io].


[[features]]
== Features

* XML namespace to https://docs.spring.io/spring-data-geode/docs/current/reference/html/#bootstrap[configure and initialize 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[development 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 using 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 using 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 & Implementations]
* 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 within Apache Geode]
* https://docs.spring.io/spring-data/geode/docs/current/reference/html/#bootstrap-annotation-config-security[Support for configuring Apache Geode Security with Apache Shiro]
* Spring Tool Suite https://docs.spring.io/sts/nan/v310/NewAndNoteworthy.html[Spring Project Templates for Apache Geode]


[[code-of-conduct]]
== Code of Conduct

This project is governed by the https://github.com/spring-projects/.github/blob/e3cc2ff230d8f1dca06535aa6b5a4a23815861d4/CODE_OF_CONDUCT.md[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.


[[getting-started]]
== Getting Started

Here is a quick teaser of a Spring application using Spring Data Repositories in Java:

[source,java]
----
package com.example.app.model;

@Region("People")
public class Customer {

	private String firstName;
	private Strign lastName;

	// Getters and Setter omitted
}

package com.example.app.repo;

public interface CustomerRepository extends CrudRepository<Customer, Long> {

  List<Person> findByLastnameLike(String lastname);

  List<Person> findByFirstname(String firstname);
}

package com.example.app.service;

@Service
public class CustomereService {

  private final CustomerRepository repository;

  public MyService(CustomereService repository) {
    this.repository = repository;
  }

  public void doWork() {

    repository.deleteAll();

    Customer customer = new Customer();
    customer.setFirstname("John");
    customer.setLastname("Blum");

    repository.save(customer);

    List<Customer> lastNameResults = repository.findByLastnameLike("B%");
    List<Customer> firstNameResults = repository.findByFirstname("John");
 }
}
----

Configure an Apache Geode cache and Region (REPLICATE, PARTITION and so on):

[source,xml]
----
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:gfe="http://www.springframework.org/schema/gemfire"
	xmlns:gfe-data="http://www.springframework.org/schema/data/gemfire"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
  xsi:schemaLocation="
    http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd
    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">

  <gfe:client-cache/>

  <gfe:client-region id="People" shortcut="LOCAL">

  <bean id="gemfireTemplate" class="org.springframework.data.gemfire.GemfireTemplate" p:region-ref="ExampleRegion"/>
	<gfe-data:repositories base-package="example.app"/>
</beans>
----

=== Maven configuration

Add the Maven dependency:

[source,xml]
----
<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-geode</artifactId>
  <version>${version}.RELEASE</version>
</dependency>
----

If you'd rather use the latest snapshots of the upcoming major/minor version, use our Maven snapshot repository
and declare the appropriate dependency version:

[source,xml]
----
<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-geode</artifactId>
  <version>${version}.BUILD-SNAPSHOT</version>
</dependency>

<repository>
  <id>spring-snapshot</id>
  <name>Spring Snapshot Repository</name>
  <url>https://repo.spring.io/snapshot</url>
</repository>
----


[[help]]
== Getting Help

Having trouble with Spring Data? We’d love to help!

* 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://github.com/spring-projects/spring-data-geode/issues[github.com/spring-projects/spring-data-geode/issues].


[[issues]]
== Reporting Issues

Spring Data uses GitHub Issues as the 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
https://github.com/spring-projects/spring-data-geode/issues[GitHub Issues] to see if someone has already reported the problem.
* If the issue does not already exist, https://github.com/spring-projects/spring-data-geode/issues[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 markdown {backtick}{backtick}{backtick} escapes before and after your text.
* If possible try to create a test case or project that reproduces the issue. Attach a link to your code or a compressed file containing your code.


[[building-from-source]]
== 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]
----
 $ ./mvnw clean install
----

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].

_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 non-trivial change._


[[building-ref-doc]]
=== Building reference documentation

Building the documentation builds also the project without running tests.

[source,bash]
----
 $ ./mvnw clean install -Pdistribute
----

The generated documentation is available from `target/site/reference/html/index.html`.


[[license]]
== 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].