|
| 1 | += Spring Data Couchbase image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-couchbase%2Fmain&subject=Build[link=https://jenkins.spring.io/view/SpringData/job/spring-data-couchbase/] https://gitter.im/spring-projects/spring-data[image:https://badges.gitter.im/spring-projects/spring-data.svg[Gitter]] image:https://img.shields.io/badge/Revved%20up%20by-Develocity-06A0CE?logo=Gradle&labelColor=02303A["Revved up by Develocity", link="https://ge.spring.io/scans?search.rootProjectNames=Spring Data Couchbase"] |
| 2 | + |
| 3 | +The primary goal of the https://www.springsource.org/spring-data[Spring Data] project is to make it easier to build |
| 4 | +Spring-powered applications that use new data access technologies such as non-relational databases, map-reduce |
| 5 | +frameworks, and cloud based data services. |
| 6 | + |
| 7 | +The Spring Data Couchbase project aims to provide a familiar and consistent Spring-based programming model for Couchbase |
| 8 | +Server as a document database and cache while retaining store-specific features and capabilities. Key functional areas |
| 9 | +of Spring Data Couchbase are a POJO centric model for interacting with a Couchbase Server Bucket and easily writing a |
| 10 | +repository style data access layer. |
| 11 | + |
| 12 | +Integration tests require a couchbase server with a bucket name "protected" with "password" as the password set. |
| 13 | +If the server allows users, then an user with username "protected" with "password" as the password should also be set. |
| 14 | +The recommended way to run tests is to install docker and use container in server.properties. |
| 15 | + |
| 16 | +This project is lead and maintained by Couchbase, Inc. |
| 17 | + |
| 18 | +== Features |
| 19 | + |
| 20 | +* Spring configuration support using Java based `@Configuration` classes or an XML namespace for the Couchbase driver (Java SDK version 2.x). |
| 21 | +* `CouchbaseTemplate` helper class that increases productivity performing common Couchbase operations. Includes integrated object mapping between documents and POJOs. |
| 22 | +* Exception translation into Spring’s portable Data Access Exception hierarchy. |
| 23 | +* Feature Rich Object Mapping integrated with Spring’s Conversion Service. |
| 24 | +* Annotation based mapping metadata but extensible to support other metadata formats. |
| 25 | +* Automatic implementation of `Repository` interfaces including support for custom finder methods (backed by Couchbase’s query language, `N1QL`) and `PagingAndSortingRepository`. |
| 26 | +* For Couchbase server versions < 4.0, repositories can still be backed by Couchbase Views. |
| 27 | +* Support for geospatial and multidimensional querying (backed by Couchbase Spatial Views) |
| 28 | +* JMX administration and monitoring |
| 29 | +* Can serve as the backend for `@Cacheable` support, to cache any objects you need for high performance access (see sibling Spring Cache project in Couchbase’s github, https://github.com/couchbaselabs/couchbase-spring-cache[couchbaselabs/couchbase-spring-cache]). |
| 30 | + |
| 31 | +== Version compatibility |
| 32 | + |
| 33 | +`Spring-Data Couchbase` is the Spring Data connector for the `Couchbase Java SDK 2.x` generation. |
| 34 | + |
| 35 | +Both the SDK and this Spring Data community project are major version changes with lots of differences from their respective previous versions. |
| 36 | + |
| 37 | +Notably, this version is compatible with `Couchbase Server 4.0`, bringing support for the `N1QL` query language. |
| 38 | + |
| 39 | +include::https://raw.githubusercontent.com/spring-projects/spring-data-build/refs/heads/main/etc/readme/code-of-conduct.adoc[] |
| 40 | + |
| 41 | +== Getting Started |
| 42 | + |
| 43 | +Here is a quick teaser of an application using Spring Data Repositories in Java: |
| 44 | + |
| 45 | +[source,java] |
| 46 | +---- |
| 47 | +public interface PersonRepository extends CrudRepository<Person, Long> { |
| 48 | +
|
| 49 | + List<Person> findByLastname(String lastname); |
| 50 | +
|
| 51 | + List<Person> findByFirstnameLike(String firstname); |
| 52 | +} |
| 53 | +
|
| 54 | +@Service |
| 55 | +public class MyService { |
| 56 | +
|
| 57 | + private final PersonRepository repository; |
| 58 | +
|
| 59 | + public MyService(PersonRepository repository) { |
| 60 | + this.repository = repository; |
| 61 | + } |
| 62 | +
|
| 63 | + public void doWork() { |
| 64 | +
|
| 65 | + repository.deleteAll(); |
| 66 | +
|
| 67 | + Person person = new Person(); |
| 68 | + person.setFirstname("Couch"); |
| 69 | + person.setLastname("Base"); |
| 70 | + repository.save(person); |
| 71 | +
|
| 72 | + List<Person> lastNameResults = repository.findByLastname("Base"); |
| 73 | + List<Person> firstNameResults = repository.findByFirstnameLike("Cou*"); |
| 74 | + } |
| 75 | +} |
| 76 | +
|
| 77 | +@Configuration |
| 78 | +@EnableCouchbaseRepositories |
| 79 | +public class Config extends AbstractCouchbaseConfiguration { |
| 80 | +
|
| 81 | + @Override |
| 82 | + protected List<String> getBootstrapHosts() { |
| 83 | + return Arrays.asList("host1", "host2"); |
| 84 | + } |
| 85 | +
|
| 86 | + @Override |
| 87 | + protected String getBucketName() { |
| 88 | + return "default"; |
| 89 | + } |
| 90 | +
|
| 91 | + @Override |
| 92 | + protected String getPassword() { |
| 93 | + return ""; |
| 94 | + } |
| 95 | +} |
| 96 | +---- |
| 97 | + |
| 98 | +include::https://raw.githubusercontent.com/spring-projects/spring-data-build/refs/heads/main/etc/readme/dependencies.adoc[] |
| 99 | + |
| 100 | +include::https://raw.githubusercontent.com/spring-projects/spring-data-build/refs/heads/main/etc/readme/getting-help.adoc[] |
| 101 | + |
| 102 | +=== Building and staging reference documentation for review |
| 103 | + |
| 104 | +[source,bash] |
| 105 | +---- |
| 106 | + export MY_GIT_USER=<github-user> |
| 107 | + mvn generate-resources |
| 108 | + docs=`pwd`/target/site/reference/html |
| 109 | + pushd /tmp |
| 110 | + mkdir $$ |
| 111 | + cd $$ |
| 112 | + # see https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site |
| 113 | + # this examples uses a repository named "staged" |
| 114 | + git clone git@github.com:${MY_GIT_USER}/staged.git -b gh-pages |
| 115 | + cd staged |
| 116 | + cp -R $docs/* . |
| 117 | + git add . |
| 118 | + git commit --message "stage for review" |
| 119 | + git push origin gh-pages |
| 120 | + popd |
| 121 | +---- |
| 122 | + |
| 123 | +include::https://raw.githubusercontent.com/spring-projects/spring-data-build/refs/heads/main/etc/readme/license.adoc[] |
0 commit comments