diff --git a/src/main/asciidoc/old-to-migrate/caching.adoc b/src/main/asciidoc/old-to-migrate/caching.adoc new file mode 100644 index 00000000..d2d0f903 --- /dev/null +++ b/src/main/asciidoc/old-to-migrate/caching.adoc @@ -0,0 +1,56 @@ +[[couchbase.caching]] += Caching + +This chapter describes additional support for caching and `@Cacheable`. + +[[caching.usage]] +== Configuration & Usage + +Technically, caching is not part of spring-data, but is implemented directly in the spring core. Most database implementations in the spring-data package can't support `@Cacheable`, because it is not possible to store arbitrary data. + +Couchbase supports both binary and JSON data, so you can get both out of the same database. + +To make it work, you need to add the `@EnableCaching` annotation and configure the `cacheManager` bean: + +.`AbstractCouchbaseConfiguration` for Caching +==== +[source,java] +---- + +@Configuration +@EnableCaching +public class Config extends AbstractCouchbaseConfiguration { + // general methods + + @Bean + public CouchbaseCacheManager cacheManager() throws Exception { + HashMap instances = new HashMap(); + instances.put("persistent", couchbaseClient()); + return new CouchbaseCacheManager(instances); + } +} +---- +==== + +The `persistent` identifier can then be used on the `@Cacheable` annotation to identify the cache manager to use (you can have more than one configured). + +Once it is set up, you can annotate every method with the `@Cacheable` annotation to transparently cache it in your couchbase bucket. You can also customize how the key is generated. + +.Caching example +==== +[source,java] +---- +@Cacheable(value="persistent", key="'longrunsim-'+#time") +public String simulateLongRun(long time) { + try { + Thread.sleep(time); + } catch(Exception ex) { + System.out.println("This shouldnt happen..."); + } + return "I've slept " + time + " miliseconds.; +} +---- +==== + +If you run the method multiple times, you'll see a set operation happening first, followed by multiple get operations and no sleep time (which fakes the expensive execution). You can store whatever you want, if it is JSON of course you can access it through views and look at it in the Web UI. + diff --git a/src/main/asciidoc/old-to-migrate/configuration.adoc b/src/main/asciidoc/old-to-migrate/configuration.adoc new file mode 100644 index 00000000..f95c794b --- /dev/null +++ b/src/main/asciidoc/old-to-migrate/configuration.adoc @@ -0,0 +1,114 @@ +[[couchbase.configuration]] += Installation & Configuration + +This chapter describes the common installation and configuration steps needed when working with the library. + +[[installation]] +== Installation + +All versions intented for production use are distributed across Maven Central and the Spring release repository. As a result, the library can be included like any other maven dependency: + +.Including the dependency through maven +==== +[source,xml] +---- + + org.springframework.data + spring-data-couchbase + 1.0.0.RELEASE + +---- +==== + +This will pull in several dependencies, including the underlying Couchbase Java SDK, common Spring dependencies and also Jackson as the JSON mapping infrastructure. + +You can also grab snapshots from the http://repo.spring.io/libs-snapshot[spring snapshot repository] and milestone releases from the http://repo.spring.io/libs-milestone[milestone repository]. Here is an example on how to use the current SNAPSHOT dependency: + +.Using a snapshot version +==== +[source,xml] +---- + + org.springframework.data + spring-data-couchbase + 1.1.0.BUILD-SNAPSHOT + + + + spring-libs-snapshot + Spring Snapshot Repository + https://repo.spring.io/libs-snapshot + +---- +==== + +Once you have all needed dependencies on the classpath, you can start configuring it. Both Java and XML config are supported. The next sections describe both approaches in detail. + +[[configuration-java]] +== Annotation-based Configuration ("JavaConfig") + +The annotation based configuration approach is getting more and more popular. It allows you to get rid of XML configuration and treat configuration as part of your code directly. To get started, all you need to do is sublcass the `AbstractCouchbaseConfiguration` and implement the abstract methods. + +Please make sure to have cglib support in the classpath so that the annotation based configuration works. + +.Extending the `AbstractCouchbaseConfiguration` +==== +[source,java] +---- + +@Configuration +public class Config extends AbstractCouchbaseConfiguration { + + @Override + protected List bootstrapHosts() { + return Collections.singletonList("127.0.0.1"); + } + + @Override + protected String getBucketName() { + return "beer-sample"; + } + + @Override + protected String getBucketPassword() { + return ""; + } +} +---- +==== + +All you need to provide is a list of Couchbase nodes to bootstrap into (without any ports, just the IP address or hostname). Please note that while one host is sufficient in development, it is recommended to add 3 to 5 bootstrap nodes here. Couchbase will pick up all nodes from the cluster automatically, but it could be the case that the only node you've provided is experiencing issues while you are starting the application. + +The `bucketName` and `password` should be the same as configured in Couchbase Server itself. In the example given, we are connecting to the `beer-sample` bucket which is one of the sample buckets shipped with Couchbase Server and has no password set by default. + +Depending on how your environment is setup, the configuration will be automatically picked up by the context or you need to instantiate your own one. How to manage configurations is not scope of this manual, please refer to the spring documentation for more information on that topic. + +While not immediately obvious, much more things can be customized and overridden as custom beans from this configuration - we'll touch them in the individual manual sections as needed (for example repositories, validation and custom converters). + +[[configuration-xml]] +== XML-based Configuration + +The library provides a custom namespace that you can use in your XML configuration: + +.Basic XML configuration +==== +[source,xml] +---- + + + + + + +---- +==== +This code is equivalent to the java configuration approach shown above. It is also possible to configure templates and repositories, which is shown in the appropriate sections. + +If you start your application, you should see Couchbase INFO level logging in the logs, indicating that the underlying Couchbase Java SDK is connecting to the database. If any errors are reported, make sure that the given credentials and host information is correct. + diff --git a/src/main/asciidoc/old-to-migrate/entity.adoc b/src/main/asciidoc/old-to-migrate/entity.adoc new file mode 100644 index 00000000..26b1e86f --- /dev/null +++ b/src/main/asciidoc/old-to-migrate/entity.adoc @@ -0,0 +1,381 @@ +[[couchbase.entity]] += Modeling Entities + +This chapter describes how to model Entities and explains their counterpart representation in Couchbase Server itself. + +[[basics]] +== Documents and Fields + +All entities should be annotated with the `@Document` annotation. Also, every field in the entity should be annotated with the `@Field` annotation. While this is - strictly speaking - optional, it helps to reduce edge cases and clearly shows the intent and design of the entity. + +There is also a special `@Id` annotation which needs to be always in place. Best practice is to also name the property `id`. Here is a very simple `User` entity: + +.A simple Document with Fields +==== +[source,java] +---- +import org.springframework.data.annotation.Id; +import org.springframework.data.couchbase.core.mapping.Document; +import org.springframework.data.couchbase.core.mapping.Field; + +@Document +public class User { + + @Id + private String id; + + @Field + private String firstname; + + @Field + private String lastname; + + public User(String id, String firstname, String lastname) { + this.id = id; + this.firstname = firstname; + this.lastname = lastname; + } + + public String getId() { + return id; + } + + public String getFirstname() { + return firstname; + } + + public String getLastname() { + return lastname; + } +} + +---- +==== + +Couchbase Server supports automatic expiration for documents. The library implements support for it through the `@Document` annotation. You can set a `expiry` value which translates to the number of seconds until the document gets removed automatically. If you want to make it expire in 10 seconds after mutation, set it like `@Document(expiry = 10)`. + +If you want a different representation of the field name inside the document in contrast to the field name used in your entity, you can set a different name on the `@Field` annotation. For example if you want to keep your documents small you can set the firstname field to `@Field("fname")`. In the JSON document, you'll see `{"fname": ".."}` instead of `{"firstname": ".."}`. + +The `@Id` annotation needs to be present because every document in Couchbase needs a unique key. This key needs to be any string with a length of maximum 250 characters. Feel free to use whatever fits your use case, be it a UUID, an email address or anything else. + +[[datatypes]] +== Datatypes and Converters + +The storage format of choice is JSON. It is great, but like many data representations it allows less datatypes than you could express in Java directly. Therefore, for all non-primitive types some form of conversion to and from supported types needs to happen. + +For the following entity field types, you don't need to add special handling: + + +[cols="2", options="header"] +.Primitive Types +|=== +| Java Type +| JSON Representation + +| string +| string + +| boolean +| boolean + +| byte +| number + +| short +| number + +| int +| number + +| long +| number + +| float +| number + +| double +| number + +| null +| Ignored on write +|=== +Since JSON supports objects ("maps") and lists, `Map` and `List` types can be converted naturally. If they only contain primitive field types from the last paragraph, you don't need to add special handling too. Here is an example: + +.A Document with Map and List +==== +[source,java] +---- + +@Document +public class User { + + @Id + private String id; + + @Field + private List firstnames; + + @Field + private Map childrenAges; + + public User(String id, List firstnames, Map childrenAges) { + this.id = id; + this.firstnames = firstnames; + this.childrenAges = childrenAges; + } + +} +---- +==== + +Storing a user with some sample data could look like this as a JSON representation: + +.A Document with Map and List - JSON +==== +[source,json] +---- + +{ + "_class": "foo.User", + "childrenAges": { + "Alice": 10, + "Bob": 5 + }, + "firstnames": [ + "Foo", + "Bar", + "Baz" + ] +} +---- +==== + +You don't need to break everything down to primitive types and Lists/Maps all the time. Of course, you can also compose other objects out of those primitive values. Let's modify the last example so that we want to store a `List` of `Children`: + +.A Document with composed objects +==== +[source,java] +---- +@Document +public class User { + + @Id + private String id; + + @Field + private List firstnames; + + @Field + private List children; + + public User(String id, List firstnames, List children) { + this.id = id; + this.firstnames = firstnames; + this.children = children; + } + + static class Child { + private String name; + private int age; + + Child(String name, int age) { + this.name = name; + this.age = age; + } + + } + +} +---- +==== + +A populated object can look like: + +.A Document with composed objects - JSON +==== +[source,json] +---- + +{ + "_class": "foo.User", + "children": [ + { + "age": 4, + "name": "Alice" + }, + { + "age": 3, + "name": "Bob" + } + ], + "firstnames": [ + "Foo", + "Bar", + "Baz" + ] +} +---- +==== + +Most of the time, you also need to store a temporal value like a `Date`. Since it can't be stored directly in JSON, a conversion needs to happen. The library implements default converters for `Date`, `Calendar` and JodaTime types (if on the classpath). All of those are represented by default in the document as a unix timestamp (number). You can always override the default behavior with custom converters as shown later. Here is an example: + +.A Document with Date and Calendar +==== +[source,java] +---- +@Document +public class BlogPost { + + @Id + private String id; + + @Field + private Date created; + + @Field + private Calendar updated; + + @Field + private String title; + + public BlogPost(String id, Date created, Calendar updated, String title) { + this.id = id; + this.created = created; + this.updated = updated; + this.title = title; + } + +} +---- +==== + +A populated object can look like: + +.A Document with Date and Calendar - JSON +==== +[source,json] +---- +{ + "title": "a blog post title", + "_class": "foo.BlogPost", + "updated": 1394610843, + "created": 1394610843897 +} +---- +==== + +If you want to override a converter or implement your own one, this is also possible. The library implements the general Spring Converter pattern. You can plug in custom converters on bean creation time in your configuration. Here's how you can configure it (in your overriden `AbstractCouchbaseConfiguration`): + +.Custom Converters +==== +[source,java] +---- +@Override +public CustomConversions customConversions() { + return new CustomConversions(Arrays.asList(FooToBarConverter.INSTANCE, BarToFooConverter.INSTANCE)); +} + +@WritingConverter +public static enum FooToBarConverter implements Converter { + INSTANCE; + + @Override + public Bar convert(Foo source) { + return /* do your conversion here */; + } + +} + +@ReadingConverter +public static enum BarToFooConverter implements Converter { + INSTANCE; + + @Override + public Foo convert(Bar source) { + return /* do your conversion here */; + } + +} +---- +==== + +There are a few things to keep in mind with custom conversions: + +* To make it unambiguous, always use the `@WritingConverter` and `@ReadingConverter` annotations on your converters. Especially if you are dealing with primitive type conversions, this will help to reduce possible wrong conversions. +* If you implement a writing converter, make sure to decode into primitive types, maps and lists only. If you need more complex object types, use the `CouchbaseDocument` and `CouchbaseList` types, which are also understood by the underlying translation engine. Your best bet is to stick with as simple as possible conversions. +* Always put more special converters before generic converters to avoid the case where the wrong converter gets executed. + +[[version]] +== Optimistic Locking + +Couchbase Server does not support multi-document transactions or rollback. To implement optimistic locking, Couchbase uses a CAS (compare and swap) approach. When a document is mutated, the CAS value also changes. The CAS is opaque to the client, the only thing you need to know is that it changes when the content or a meta information changes too. + +In other datastores, similar behavior can be achieved through an arbitrary version field whith a incrementing counter. Since Couchbase supports this in a much better fashion, it is easy to implement. If you want automatic optimistic locking support, all you need to do is add a `@Version` annotation on a long field like this: + +.A Document with optimistic locking. +==== +[source,java] +---- +@Document +public class User { + + @Version + private long version; + + // constructor, getters, setters... +} +---- +==== + +If you load a document through the template or repository, the version field will be automatically populated with the current CAS value. It is important to note that you shouldn't access the field or even change it on your own. Once you save the document back, it will either succeed or fail with a `OptimisticLockingFailureException`. If you get such an exception, the further approach depends on what you want to achieve application wise. You should either retry the complete load-update-write cycle or propagate the error to the upper layers for proper handling. + +[[validation]] +== Validation + +The library supports JSR 303 validation, which is based on annotations directly in your entities. Of course you can add all kinds of validation in your service layer, but this way its nicely coupled to your actual entities. + +To make it work, you need to include two additional dependencies. JSR 303 and a library that implements it, like the one supported by hibernate: + +.Validation dependencies +==== +[source,xml] +---- + + javax.validation + validation-api + + + org.hibernate + hibernate-validator + +---- +==== +Now you need to add two beans to your configuration: + +.Validation beans +==== +[source,java] +---- +@Bean +public LocalValidatorFactoryBean validator() { + return new LocalValidatorFactoryBean(); +} + +@Bean +public ValidatingCouchbaseEventListener validationEventListener() { + return new ValidatingCouchbaseEventListener(validator()); +} +---- +==== + +Now you can annotate your fields with JSR303 annotations. If a validation on `save()` fails, a `ConstraintViolationException` is thrown. + +.Sample Validation Annotation +==== +[source,java] +---- +@Size(min = 10) +@Field +private String name; +---- +==== diff --git a/src/main/asciidoc/old-to-migrate/index.adoc b/src/main/asciidoc/old-to-migrate/index.adoc new file mode 100644 index 00000000..f5ce97ca --- /dev/null +++ b/src/main/asciidoc/old-to-migrate/index.adoc @@ -0,0 +1,39 @@ += Spring Data Couchbase - Reference Documentation +Michael Nitschinger, Oliver Gierke +:revnumber: {version} +:revdate: {localdate} +:toc: +:toc-placement!: +:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc + +(C) 2014-2015 The original author(s). + +NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. + +toc::[] + +include::preface.adoc[] + +[[reference]] += Reference Documentation + +:leveloffset: +1 +include::configuration.adoc[] +include::entity.adoc[] +include::{spring-data-commons-docs}/repositories.adoc[] +include::repository.adoc[] +include::template.adoc[] +include::caching.adoc[] +:leveloffset: -1 + + +[[appendix]] += Appendix + +:numbered!: +:leveloffset: +1 +include::{spring-data-commons-docs}/repository-namespace-reference.adoc[] +include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[] +include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[] +include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[] +:leveloffset: -1 diff --git a/src/main/asciidoc/old-to-migrate/preface.adoc b/src/main/asciidoc/old-to-migrate/preface.adoc new file mode 100644 index 00000000..eeb37728 --- /dev/null +++ b/src/main/asciidoc/old-to-migrate/preface.adoc @@ -0,0 +1,15 @@ +[[couchbase.preface]] += Preface + +This reference documentation describes the general usage of the Spring Data Couchbase library. + +[[metadata]] +[preface] +== Project Information + +* Version control - https://github.com/spring-projects/spring-data-couchbase +* Bugtracker - https://jira.springsource.org/browse/DATACOUCH +* Release repository - https://repo.spring.io/libs-release +* Milestone repository - https://repo.spring.io/libs-milestone +* Snapshot repository - https://repo.spring.io/libs-snapshot + diff --git a/src/main/asciidoc/old-to-migrate/repository.adoc b/src/main/asciidoc/old-to-migrate/repository.adoc new file mode 100644 index 00000000..fed39222 --- /dev/null +++ b/src/main/asciidoc/old-to-migrate/repository.adoc @@ -0,0 +1,191 @@ +[[couchbase.repository]] += Couchbase repositories + +The goal of Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores. + +[[couchbase.repository.configuration]] +== Configuration + +While support for repositories is always present, you need to enable them in general or for a specific namespace. If you extend `AbstractCouchbaseConfiguration`, just use the `@EnableCouchbaseRepositories` annotation. It provides lots of possible options to narrow or customize the search path, one of the most common ones is `basePackages`. + +.Annotation-Based Repository Setup +==== +[source,java] +---- +@Configuration +@EnableCouchbaseRepositories(basePackages = {"com.couchbase.example.repos"}) +public class Config extends AbstractCouchbaseConfiguration { + //... +} +---- +==== + +XML-based configuration is also available: + +.XML-Based Repository Setup +==== +[source,xml] +---- + +---- +==== + +[[couchbase.repository.usage]] +== Usage + +In the simplest case, your repository will extend the `CrudRepository`, where T is the entity that you want to expose. Let's look at a repository for a user: + +.A User repository +==== +[source,java] +---- +import org.springframework.data.repository.CrudRepository; + +public interface UserRepository extends CrudRepository { +} +---- +==== + +Please note that this is just an interface and not an actual class. In the background, when your context gets initialized, actual implementations for your repository descriptions get created and you can access them through regular beans. This means you will save lots of boilerplate code while still exposing full CRUD semantics to your service layer and application. + +Now, let's imagine we `@Autowrie` the `UserRepository` to a class that makes use of it. What methods do we have available? + +[cols="2", options="header"] +.Exposed methods on the UserRepository +|=== +| Method +| Description + +| User save(User entity) +| Save the given entity. + +| Iterable save(Iterable entity) +| Save the list of entities. + +| User findOne(String id) +| Find a entity by its unique id. + +| boolean exists(String id) +| Check if a given entity exists by its unique id. + +| Iterable findAll() (*) +| Find all entities by this type in the bucket. + +| Iterable findAll(Iterable ids) +| Find all entities by this type and the given list of ids. + +| long count() (*) +| Count the number of entities in the bucket. + +| void delete(String id) +| Delete the entity by its id. + +| void delete(User entity) +| Delete the entity. + +| void delete(Iterable entities) +| Delete all given entities. + +| void deleteAll() (*) +| Delete all entities by type in the bucket. +|=== + +Now thats awesome! Just by defining an interface we get full CRUD functionality on top of our managed entity. All methods suffixed with (*) in the table are backed by Views, which is explained later. + +If you are coming from other datastore implementations, you might want to implement the `PagingAndSortingRepository` as well. Note that as of now, it is not supported but will be in the future. + +While the exposed methods provide you with a great variety of access patterns, very often you need to define custom ones. You can do this by adding method declarations to your interface, which will be automatically resolved to view requests in the background. Here is an example: + +.An extended User repository +==== +[source,java] +---- +public interface UserRepository extends CrudRepository { + + List findAllAdmins(); + + List findByFirstname(Query query); +} +---- +==== + +Since we've came across views now multiple times and the `findByFirstname(Query query)` exposes a yet unknown parameter, let's cover that next. + +[[couchbase.repository.views]] +== Backing Views + +As a rule of thumb, all repository access methods which are not "by a specific key" require a backing view to find the one or more matching entities. We'll only cover views to the extend which they are needed, if you need in-depth information about them please refer to the official Couchbase Server manual and the Couchbase Java SDK manual. + +To cover the basic CRUD methods from the `CrudRepository`, one view needs to be implemented in Couchbase Server. It basically returns all documents for the specific entity and also adds the optional reduce function `_count`. + +Since every view has a design document and view name, by convention we default to `all` as the view name and the lower-cased entity name as the design document name. So if your entity is named `User`, then the code expects the `all` view in the `user` design document. It needs to look like this: + +.The all view map function +==== +[source,javascript] +---- +// do not forget the _count reduce function! +function (doc, meta) { + if (doc._class == "namespace.to.entity.User") { + emit(null, null); + } +} +---- +==== + +Note that the important part in this map function is to only include the document IDs which correspond to our entity. Because the library always adds the `_class` property, this is a quick and easy way to do it. If you have another property in your JSON which does the same job (like a explicit `type` field), then you can use that as well - you don't have to stick to `_class` all the time. + +Also make sure to publish your design documents into production so that they can be picked up by the library! Also, if you are curious why we use `emit(null, null)` in the view: the document id is always sent over to the client implicitly, so we can shave off a view bytes in our view by not duplicating the id. If you use `emit(meta.id, null)` it won't hurt much too. + +Implementing your custom repository finder methods works the same way. The `findAllAdmins` calls the `allAdmins` view in the `user` design document. Imagine we have a field on our entity which looks like `boolean isAdmin`. We can write a view like this to expose them (we don't need a reduce function for this one): + +.A custom view map function +==== +[source,javascript] +---- +function (doc, meta) { + if (doc._class == "namespace.to.entity.User" && doc.isAdmin) { + emit(null, null); + } +} +---- +==== + +By now, we've never actually customized our view at query time. This is where the special `Query` argument comes along - like in our `findByFirstname(Query query)` method. + +.A parameterized view map function +==== +[source,javascript] +---- +function (doc, meta) { + if (doc._class == "namespace.to.entity.User") { + emit(doc.firstname, null); + } +} +---- +==== + +This view not only emits the document id, but also the firstname of every user as the key. We can now run a `Query` which returns us all users with a firstname of "Michael" or "Thomas". + +.Query a repository method with custom params. +==== +[source,java] +---- +// Load the bean, or @Autowire it +UserRepository repo = ctx.getBean(UserRepository.class); + +// Create the CouchbaseClient Query object +Query query = new Query(); + +// Filter on those two keys +query.setKeys(ComplexKey.of("Michael", "Thomas")); + +// Run the query and get all matching users returned +List users = repo.findByFirstname(query)); +---- +==== + +On all custom finder methods, you can use the `@View` annotation to both customize the design document and view name (to override the conventions). + +Please keep in mind that by default, the `Stale.UPDATE_AFTER` mechanism is used. This means that whatever is in the index gets returned, and then the index gets updated. This strikes a good balance between performance and data freshness. You can tune the behavior through the `setStale()` method on the query object. For more details on behavior, please consult the Couchbase Server and Java SDK documentation directly. + diff --git a/src/main/asciidoc/old-to-migrate/template.adoc b/src/main/asciidoc/old-to-migrate/template.adoc new file mode 100644 index 00000000..9b05fbb4 --- /dev/null +++ b/src/main/asciidoc/old-to-migrate/template.adoc @@ -0,0 +1,20 @@ +[[couchbase.template]] += Template & direct operations + +The template provides lower level access to the underlying database and also serves as the foundation for repositories. Any time a repository is too high-level for you needs chances are good that the templates will serve you well. + +[[template.ops]] +== Supported operations + +The template can be accessed through the `couchbaseTemplate` bean out of your context. Once you've got a reference to it, you can run all kinds of operations against it. Other than through a repository, in a template you need to always specify the target entity type which you want to get converted. + +To mutate documents, you'll find `save`, `insert` and `update` methods exposed. Saving will insert or update the document, insert will fail if it has been created already and update only works against documents that have already been created. + +Since Couchbase Server has different levels of persistence (by default you'll get a positive response if it has been acknowledged in the managed cache), you can provide higher durability options through the overloaded `PersistTo` and/or `ReplicateTo` options. The behaviour is part of the Couchbase Java SDK, please refer to the official documentation for more details. + +Removing documents through the `remove` methods works exactly the same. + +If you want to load documents, you can do that through the `findById` method, which is the fastest and if possible your tool of choice. The find methods for views are `findByView` which converts it into the target entity, but also `queryView` which exposes lower level semantics. + +If you really need low-level semantics, the `couchbaseClient` bean is also always in scope. + diff --git a/src/main/java/org/springframework/data/couchbase/config/package-info.java b/src/main/java/org/springframework/data/couchbase/config/package-info.java new file mode 100644 index 00000000..4bfb6547 --- /dev/null +++ b/src/main/java/org/springframework/data/couchbase/config/package-info.java @@ -0,0 +1,5 @@ +/** + * This package contains all classes needed for specific configuration of + * Spring Data Couchbase. + */ +package org.springframework.data.couchbase.config; \ No newline at end of file diff --git a/src/main/java/org/springframework/data/couchbase/core/package-info.java b/src/main/java/org/springframework/data/couchbase/core/package-info.java new file mode 100644 index 00000000..de398688 --- /dev/null +++ b/src/main/java/org/springframework/data/couchbase/core/package-info.java @@ -0,0 +1,5 @@ +/** + * This package contains the specific implementations and core classes for + * Spring Data Couchbase internals. + */ +package org.springframework.data.couchbase.core; \ No newline at end of file diff --git a/src/main/java/org/springframework/data/couchbase/monitor/package-info.java b/src/main/java/org/springframework/data/couchbase/monitor/package-info.java new file mode 100644 index 00000000..d64a4c07 --- /dev/null +++ b/src/main/java/org/springframework/data/couchbase/monitor/package-info.java @@ -0,0 +1,5 @@ +/** + * This package contains all classes related to monitoring the Couchbase cluster, + * statistics that will be exposed as JMX beans. + */ +package org.springframework.data.couchbase.monitor; \ No newline at end of file diff --git a/src/main/java/org/springframework/data/couchbase/repository/package-info.java b/src/main/java/org/springframework/data/couchbase/repository/package-info.java new file mode 100644 index 00000000..b01e083a --- /dev/null +++ b/src/main/java/org/springframework/data/couchbase/repository/package-info.java @@ -0,0 +1,7 @@ +/** + * This package contains the Couchbase implementation to support the Spring Data repository abstraction. + *
+ * The goal of Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to + * implement data access layers for various persistence stores. + */ +package org.springframework.data.couchbase.repository; \ No newline at end of file diff --git a/src/main/java/org/springframework/data/couchbase/template/package-info.java b/src/main/java/org/springframework/data/couchbase/template/package-info.java new file mode 100644 index 00000000..c0df3239 --- /dev/null +++ b/src/main/java/org/springframework/data/couchbase/template/package-info.java @@ -0,0 +1,8 @@ +/** + * This package contains the Couchbase implementation to support the Spring Data template abstraction. + *
+ * The template provides lower level access to the underlying database and also serves as the foundation for + * repositories. Any time a repository is too high-level for you needs chances are good that the templates will serve + * you well. + */ +package org.springframework.data.couchbase.template; \ No newline at end of file diff --git a/src/main/resources/changelog.txt b/src/main/resources/changelog.txt new file mode 100644 index 00000000..6d419b2f --- /dev/null +++ b/src/main/resources/changelog.txt @@ -0,0 +1,219 @@ +Spring Data Couchbase Changelog +=============================== + +New Major Version: 2.0 +---------------------- +This version is a complete rewrite of the Spring Data Couchbase project, using the newer 2.x generation +of the Couchbase Java SDK. + + +================================================================================= +| Below are older release notes for the 1st generation of Spring Data Couchbase | +| (based on the 1.x Couchbase Java SDK) | +================================================================================= + + +Changes in version 1.4.0.M1 (2015-06-02) +---------------------------------------- +* DATACOUCH-127 - Release 1.4 M1 (Gosling). +* DATACOUCH-126 - @EnableCouchbaseRespositories does not implement the `repositoryBaseClass` attribute. + + +Changes in version 1.3.0.RELEASE (2015-03-23) +--------------------------------------------- +* DATACOUCH-122 - Release 1.3 GA. + + +Changes in version 1.3.0.RC1 (2015-03-05) +----------------------------------------- +* DATACOUCH-121 - Release 1.3 RC1. +* DATACOUCH-120 - Update Java SDK to 1.4.7. +* DATACOUCH-117 - Fix shaky builds. +* DATACOUCH-110 - Custom converted objects in map/collection property are not serialized correctly. +* DATACOUCH-109 - Add support for custom implementations in CDI repositories. +* DATACOUCH-102 - Pass source object to AbstractCouchbaseEventListener's onBeforeDelete and onAfterDelete. +* DATACOUCH-25 - Cache TTL (Time To Live) property required. + + +Changes in version 1.2.2.RELEASE (2015-01-28) +--------------------------------------------- +* DATACOUCH-119 - Release 1.2.2. +* DATACOUCH-117 - Fix shaky builds. + + +Changes in version 1.1.5.RELEASE (2015-01-27) +--------------------------------------------- +* DATACOUCH-118 - Release 1.1.5. +* DATACOUCH-117 - Fix shaky builds. + + +Changes in version 1.3.0.M1 (2014-12-01) +---------------------------------------- +* DATACOUCH-116 - Release 1.3 M1. +* DATACOUCH-113 - Ensure Spring 4.1 compatibility. + + +Changes in version 1.2.1.RELEASE (2014-10-30) +--------------------------------------------- +* DATACOUCH-114 - Release 1.2.1. +* DATACOUCH-113 - Ensure Spring 4.1 compatibility. + + +Changes in version 1.2.0.RELEASE (2014-09-05) +--------------------------------------------- +* DATACOUCH-108 - Make sure Spring Data Couchbase can be built using a JDK 8. +* DATACOUCH-107 - Release 1.2 GA. +* DATACOUCH-105 - Update to Java SDK 1.4.4. +* DATACOUCH-103 - Polish reference documentation. +* DATACOUCH-97 - Support for createRepositoryFactory(CouchbaseOperations operations), getCouchbaseClient(). +* DATACOUCH-94 - Move to FieldNamingStrategy SPI in Spring Data Commons. + + +Changes in version 1.1.4.RELEASE (2014-08-27) +--------------------------------------------- +* DATACOUCH-106 - Release 1.1.4. + + +Changes in version 1.2.0.RC1 (2014-08-13) +----------------------------------------- +* DATACOUCH-101 - Release 1.2 RC1. +* DATACOUCH-100 - Move to Asciidoctor for reference documentation. + + +Changes in version 1.1.2.RELEASE (2014-07-28) +--------------------------------------------- +* DATACOUCH-99 - Release 1.1.2. + + +Changes in version 1.2.0.M1 (2014-07-10) +---------------------------------------- +* DATACOUCH-96 - Release 1.2 M1. + + +Changes in version 1.1.1.RELEASE (2014-06-30) +--------------------------------------------- +* DATACOUCH-95 - Release 1.1.1. + + +Changes in version 1.1.0.RELEASE (2014-05-20) +--------------------------------------------- +* DATACOUCH-89 - Upgrade Java SDK to 1.4.1. +* DATACOUCH-88 - Upgrade to latest HttpClient for Spring 4 build compatibility. +* DATACOUCH-87 - Release 1.1 GA. +* DATACOUCH-86 - Fix compile errors against Spring 4's Cache interface. + + +Changes in version 1.1.0.RC1 (2014-05-02) +----------------------------------------- +* DATACOUCH-84 - Release 1.1 RC1. +* DATACOUCH-82 - Allow custom FieldNamingStrategies. + + +Release Notes - Spring Data Couchbase - Version 1.1 M1 - 2014-03-31 +------------------------------------------------------------------- +** Task + * [DATACOUCH-78] - Adapt to changes in BeanWrapper generics + * [DATACOUCH-79] - Release 1.1 M1 + +Release Notes - Spring Data Couchbase - Version 1.0.0.RELEASE - 2014-03-13 +-------------------------------------------------------------------------- +** Bug + * [DATACOUCH-50] - findAll(Iterable ids) in CrudRepository throws java.util.concurrent.ExecutionException + * [DATACOUCH-61] - NPE when saving object containing Joda DateTime field + * [DATACOUCH-69] - Can't deserialize Date field + * [DATACOUCH-70] - Bundle could not be resolved in non J2SE-1.6 runtime environment + +** Improvement + * [DATACOUCH-55] - Allow support for custom object mapping (like Date objects) + * [DATACOUCH-72] - Update Couchbase SDK , Jackson and Spring-Data-Commons + * [DATACOUCH-75] - Trim off find on custom repository finder methods. + * [DATACOUCH-76] - Upgrade to latest spring-data-commons and parent + +** New Feature + * [DATACOUCH-71] - Support for JS303 Validation (& template events) + +** Task + * [DATACOUCH-73] - Release 1.0 GA + * [DATACOUCH-74] - Initial Documentation for 1.0 GA + +Release Notes - Spring Data Couchbase - Version 1.0 RC1 - 2014-02-06 +-------------------------------------------------------------------- +** Bug + * [DATACOUCH-30] - ObjectMapper configuration must be supported + * [DATACOUCH-44] - Not consistent unit tests + * [DATACOUCH-47] - Connecting to multiple buckets fails + * [DATACOUCH-51] - update(java.util.Collection) adds new document object + * [DATACOUCH-52] - CouchbaseCacheManager does not shutdown couchbase connections + * [DATACOUCH-53] - NPE on CouchbaseCache puting null + * [DATACOUCH-58] - Allow null values for List elements and Map values + +** Improvement + * [DATACOUCH-14] - Enable default support for slf4j in couchbase-client + * [DATACOUCH-20] - @View annotation on repository finder methods + * [DATACOUCH-49] - Enhance @View "Query" params customization + * [DATACOUCH-56] - Update Couchbase Client to 1.2.3 + * [DATACOUCH-57] - Allow for configuring of CouchbaseClient with property/SPEL expressions + * [DATACOUCH-60] - Upgrade Dependencies (Couchbase, Jackson, Commons) + * [DATACOUCH-62] - Upgrade couchbase java SDK to latest stable version + * [DATACOUCH-64] - Add View query methods to repositories + * [DATACOUCH-65] - Add @Version support on top of CAS for optimistic locking + +** New Feature + * [DATACOUCH-63] - support optimistic locking through CAS methods + +** Task + * [DATACOUCH-66] - Release 1.0 RC1 + +Release Notes - Spring Data Couchbase - Version 1.0 M2 - 2013-11-14 +------------------------------------------------------------------- +** Bug + * [DATACOUCH-25] - Cache TTL (Time To Live) property required. + * [DATACOUCH-27] - MappingCouchbaseConverter skips ID field in read operation + * [DATACOUCH-34] - Can't deserialize long/Long/Date fields + * [DATACOUCH-35] - Can't deserialize Class fields + * [DATACOUCH-36] - Can't store a map with null value + * [DATACOUCH-37] - Refactor Deprecated JUnit Asserts + * [DATACOUCH-38] - Can't deserialize enum + * [DATACOUCH-39] - Fix bundlor compile issues + * [DATACOUCH-42] - spring-data threads should be daemon threads + * [DATACOUCH-43] - Bad handling of non ASCII Strings + +** Improvement + * [DATACOUCH-16] - Allow View customization through @View annotations + * [DATACOUCH-31] - Ignore IntelliJ IDE files + * [DATACOUCH-32] - Upgrade Couchbase SDK to 1.2.0 + * [DATACOUCH-40] - Make ClusterInfo more reliable (long/int) + * [DATACOUCH-41] - Update Couchbase SDK to 1.2.1 + +** Task + * [DATACOUCH-45] - Upgrade Couchbase Client to 1.2.2 + * [DATACOUCH-46] - Release 1.0 M2 + +Release Notes - Spring Data Couchbase - Version 1.0 M1 - 2013-09-11 +------------------------------------------------------------------- +** Bug + * [DATACOUCH-11] - Upgrade Jackson to 2.2 Release + * [DATACOUCH-22] - Spring Data Couchbase build fails when not having bundlor maven plugin + +** Improvement + * [DATACOUCH-5] - Add AbstractCouchbaseConfiguration for JavaConfig + * [DATACOUCH-6] - Add simple support for XML configurations + * [DATACOUCH-7] - Implement find* methods on SimpleCouchbaseRepository + * [DATACOUCH-12] - Support arbitrary Objects on encode/decode + * [DATACOUCH-13] - Upgrade Couchbase-Client to 1.1.7 + * [DATACOUCH-15] - Upgrade Couchbase Java Client to 1.1.8 + * [DATACOUCH-17] - Make sure default template ops are sync & exceptions are mapped + * [DATACOUCH-19] - Deploy Snapshots & Integrate CI + * [DATACOUCH-21] - Improve API Documentation & Formatting before M1 + * [DATACOUCH-23] - Make Testsuite clean the bucket on every run. + * [DATACOUCH-24] - Add testing for view-based operations on template and repository. + * [DATACOUCH-26] - Upgrade Couchbase Java Client to 1.1.9 + +** Task + * [DATACOUCH-1] - Use Spring Data Build parent + * [DATACOUCH-2] - Release 1.0 M1 + * [DATACOUCH-3] - Rename packages to org.springframework.data.couchbase + * [DATACOUCH-4] - Add Apache 2 license headers + * [DATACOUCH-8] - Overhaul README with uptodate information + * [DATACOUCH-9] - Add View query support to the Template + * [DATACOUCH-10] - Upgrade parent pom to 1.1.0.RELEASE \ No newline at end of file diff --git a/src/main/resources/licence.txt b/src/main/resources/licence.txt new file mode 100644 index 00000000..7b1adee7 --- /dev/null +++ b/src/main/resources/licence.txt @@ -0,0 +1,216 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +======================================================================= + +To the extent any open source subcomponents are licensed under the EPL and/or other +similar licenses that require the source code and/or modifications to +source code to be made available (as would be noted above), you may obtain a +copy of the source code corresponding to the binaries for such open source +components and modifications thereto, if any, (the "Source Files"), by +downloading the Source Files from http://www.springsource.org/download, +or by sending a request, with your name and address to: VMware, Inc., 3401 Hillview +Avenue, Palo Alto, CA 94304, United States of America or email info@vmware.com. All +such requests should clearly specify: OPEN SOURCE FILES REQUEST, Attention General +Counsel. VMware shall mail a copy of the Source Files to you on a CD or equivalent +physical medium. This offer to obtain a copy of the Source Files is valid for three +years from the date you acquired this Software product. \ No newline at end of file diff --git a/src/main/resources/notice.txt b/src/main/resources/notice.txt new file mode 100644 index 00000000..942ed0ad --- /dev/null +++ b/src/main/resources/notice.txt @@ -0,0 +1,10 @@ +Spring Data Couchbase 2.0 BETA +Copyright (c) [2013-2015] Couchbase / Pivotal Software, Inc. + +This product is licensed to you under the Apache License, Version 2.0 (the "License"). +You may not use this product except in compliance with the License. + +This product may include a number of subcomponents with +separate copyright notices and license terms. Your use of the source +code for these subcomponents is subject to the terms and +conditions of the subcomponent's license, as noted in the LICENSE file. \ No newline at end of file