diff --git a/docs/build.gradle b/docs/build.gradle index 9b082ea7c..d43fdef39 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -23,7 +23,9 @@ docbookFoPdf.imgSrcPath = "${imagesDir}" refSpec = copySpec { into ('reference') { - from("$buildDir/docs") + from("$buildDir/docs") { + exclude '*.fo' + } from("$projectDir/src/reference/resources") } into ('reference/images') { diff --git a/docs/src/reference/docbook/appendix/appendix-schema.xml b/docs/src/reference/docbook/appendix/appendix-schema.xml index 2e23ffcd8..227465593 100644 --- a/docs/src/reference/docbook/appendix/appendix-schema.xml +++ b/docs/src/reference/docbook/appendix/appendix-schema.xml @@ -1,9 +1,9 @@ - Spring Data Key Value Schema(s) + Spring Data Redis Schema(s) - Spring Data - Redis support - + Core schema + FIXME: REDIS SCHEMA LOCATION/NAME CHANGED diff --git a/docs/src/reference/docbook/appendix/introduction.xml b/docs/src/reference/docbook/appendix/introduction.xml index 6d9d95050..c99bab635 100644 --- a/docs/src/reference/docbook/appendix/introduction.xml +++ b/docs/src/reference/docbook/appendix/introduction.xml @@ -5,6 +5,5 @@ Various appendixes outside the reference documentation. - defines the schemas provided by Spring Data - Key Value. + defines the schemas provided by Spring Data Redis. \ No newline at end of file diff --git a/docs/src/reference/docbook/index.xml b/docs/src/reference/docbook/index.xml index aa44ad050..c91c35ec6 100644 --- a/docs/src/reference/docbook/index.xml +++ b/docs/src/reference/docbook/index.xml @@ -35,7 +35,7 @@ Introduction - + @@ -68,5 +68,4 @@ --> - \ No newline at end of file diff --git a/docs/src/reference/docbook/introduction/getting-started.xml b/docs/src/reference/docbook/introduction/getting-started.xml index 755444df9..291b1af41 100644 --- a/docs/src/reference/docbook/introduction/getting-started.xml +++ b/docs/src/reference/docbook/introduction/getting-started.xml @@ -10,9 +10,9 @@
First Steps - As explained in , Spring Data Key Value (SDKV) provides integration - between Spring framework and key value (KV) stores. Thus, it is important to become acquainted with both of these - frameworks (storages or environments depending on how you want to name them). Throughout the SDKV documentation, + As explained in , Spring Data Redis (SDR) provides integration + between Spring framework and the Redis key value store. Thus, it is important to become acquainted with both of these + frameworks (storages or environments depending on how you want to name them). Throughout the SDR documentation, each section provides links to resources relevant however, it is best to become familiar with these topics beforehand.
diff --git a/docs/src/reference/docbook/introduction/introduction.xml b/docs/src/reference/docbook/introduction/introduction.xml index 3e11048f5..8dfa2ee58 100644 --- a/docs/src/reference/docbook/introduction/introduction.xml +++ b/docs/src/reference/docbook/introduction/introduction.xml @@ -2,12 +2,12 @@ - This document is the reference guide for Spring Data - Key Value Support. + This document is the reference guide for Spring Data Redis (SDR) Support. It explains Key Value module concepts and semantics and the syntax for various stores namespaces. For an introduction to key value stores or Spring, or Spring Data examples, please refer to - - this documentation refers only to Spring Data Key Value Support and + - this documentation refers only to Spring Data Redis Support and assumes the user is familiar with the key value storages and Spring concepts. diff --git a/docs/src/reference/docbook/introduction/requirements.xml b/docs/src/reference/docbook/introduction/requirements.xml index 6f3c0198e..8a96f8460 100644 --- a/docs/src/reference/docbook/introduction/requirements.xml +++ b/docs/src/reference/docbook/introduction/requirements.xml @@ -1,11 +1,11 @@ Requirements - Spring Data Key Value 1.x binaries requires JDK level 6.0 and above, + Spring Data Redis 1.x binaries requires JDK level 6.0 and above, and Spring Framework 3.0.x and above. - In terms of key value stores, Redis 2.0.x - and Riak 0.13 are required. + In terms of key value stores, Redis 2.2.x + is required. \ No newline at end of file diff --git a/docs/src/reference/docbook/introduction/why-sd-kv.xml b/docs/src/reference/docbook/introduction/why-sdr.xml similarity index 71% rename from docs/src/reference/docbook/introduction/why-sd-kv.xml rename to docs/src/reference/docbook/introduction/why-sdr.xml index 4983b5023..efd53144e 100644 --- a/docs/src/reference/docbook/introduction/why-sd-kv.xml +++ b/docs/src/reference/docbook/introduction/why-sdr.xml @@ -1,6 +1,6 @@ - - Why Spring Data - Key Value? + + Why Spring Data Redis? The Spring Framework is the leading full-stack Java/JEE application framework. It provides a lightweight container and a @@ -12,8 +12,8 @@ and speed. In terms of implementation, Key Value stores represent one of the largest (and oldest) member in the NoSQL space. - The Spring Data Key Value (or SDKV) framework makes it easy to - write Spring applications that use a Key Value store by eliminating the redundant + The Spring Data Redis (or SDR) framework makes it easy to + write Spring applications that use the Redis key value store by eliminating the redundant tasks and boiler place code required for interacting with the store through Spring's excellent infrastructure support. \ No newline at end of file diff --git a/docs/src/reference/docbook/preface.xml b/docs/src/reference/docbook/preface.xml index dd182d079..04ecd0da0 100644 --- a/docs/src/reference/docbook/preface.xml +++ b/docs/src/reference/docbook/preface.xml @@ -2,7 +2,7 @@ Preface - The Spring Data Key-Value project applies core Spring concepts to the development of solutions using a key-value style data store. + The Spring Data Redis project applies core Spring concepts to the development of solutions using a key-value style data store. We provide a "template" as a high-level abstraction for sending and receiving messages. You will notice similarities to the JDBC support in the Spring Framework. diff --git a/docs/src/reference/docbook/reference/introduction.xml b/docs/src/reference/docbook/reference/introduction.xml index 1bba3527a..67cdd8ed3 100644 --- a/docs/src/reference/docbook/reference/introduction.xml +++ b/docs/src/reference/docbook/reference/introduction.xml @@ -2,9 +2,8 @@ Document structure This part of the reference documentation explains the core functionality - offered by Spring Data Key Value. + offered by Spring Data Redis. introduces the Redis module feature set. - introduces the Riak module feature set. \ No newline at end of file diff --git a/docs/src/reference/docbook/reference/redis.xml b/docs/src/reference/docbook/reference/redis.xml index 607dc2cca..f21e19c73 100644 --- a/docs/src/reference/docbook/reference/redis.xml +++ b/docs/src/reference/docbook/reference/redis.xml @@ -2,7 +2,7 @@ Redis support - One of the key value stores supported by SDKV is Redis. + One of the key value stores supported by Spring Data is Redis. To quote the project home page: Redis is an advanced key-value store. It is similar to memcached but the dataset is not volatile, and values can be strings, @@ -10,14 +10,14 @@ to push/pop elements, add/remove elements, perform server side union, intersection, difference between sets, and so forth. Redis supports different kind of sorting abilities. - Spring Data Key Value provides easy configuration and access to Redis from Spring application. Offers both low-level and + Spring Data Redis provides easy configuration and access to Redis from Spring application. Offers both low-level and high-level abstraction for interacting with the store, freeing the user from infrastructural concerns.
Redis Requirements - SDKV requires Redis 2.0 or above (Redis 2.2 is recommended) and Java SE 6.0 or above. - In terms of language bindings (or connectors), SDKV integrates with Jedis, + Spring Redis requires Redis 2.0 or above (Redis 2.2 is recommended) and Java SE 6.0 or above. + In terms of language bindings (or connectors), Spring Redis integrates with Jedis, JRedis and RJC, three popular open source Java libraries for Redis. If you are aware of any other connector that we should be integrating is, please send us feedback. @@ -45,7 +45,7 @@ Connecting to Redis One of the first tasks when using Redis and Spring is to connect to the store through the IoC container. To do that, a Java connector (or binding) is required; - currently SDKV has support for Jedis and JRedis. No matter the library one chooses, there only one set of SDKV API that one needs to use that behaves consistently + currently Spring Redis has support for Jedis and JRedis. No matter the library one chooses, there only one set of Spring Redis API that one needs to use that behaves consistently across all connectors, namely the org.springframework.data.redis.connection package and its RedisConnection and RedisConnectionFactory interfaces for working respectively for retrieving active connection to Redis. @@ -116,9 +116,9 @@
Configuring JRedis connector - JRedis is another popular, open-source connector supported by SDKV through the + JRedis is another popular, open-source connector supported by Spring Redis through the org.springframework.data.redis.connection.jredis package. - Since JRedis itself does not support (yet) Redis 2.x commands, SDKV uses an updated fork available + Since JRedis itself does not support (yet) Redis 2.x commands, Spring Redis uses an updated fork available here. A typical JRedis configuration can looks like this: @@ -148,7 +148,7 @@
Configuring RJC connector - RJC is the third, open-source connector supported by SDKV through the + RJC is the third, open-source connector supported by Spring Redis through the org.springframework.data.redis.connection.rjc package. Similar to the other connectors, a typical RJC configuration can looks like this: @@ -354,7 +354,7 @@ From the framework perspective, the data stored in Redis are just bytes. While Redis itself supports various types, for the most part these refer to the way the data is stored rather then what it represents. It is up to the user to decide whether the information gets translated into Strings or any other objects. The conversion between the user (custom) - types and raw data (and vice-versa) is handled in SDKV Redis through the RedisSerializer interface + types and raw data (and vice-versa) is handled in Spring Redis Redis through the RedisSerializer interface (package org.springframework.data.redis.serializer) which as the name implies, takes care of the serialization process. Multiple implementations are available out of the box, two of which have been already mentioned before in this documentation: the StringRedisSerializer and the JdkSerializationRedisSerializer. However one can use OxmSerializer for Object/XML mapping through Spring 3 diff --git a/docs/src/reference/docbook/reference/riak.xml b/docs/src/reference/docbook/reference/riak.xml deleted file mode 100644 index 6c5acdc66..000000000 --- a/docs/src/reference/docbook/reference/riak.xml +++ /dev/null @@ -1,547 +0,0 @@ - - - Riak Support - - Riak is a Key/Value datastore that supports Internet-scale data replication for high performance and high availability. Spring Data Key/Value (SDKV) provides access to the Riak datastore over the HTTP REST API using a built-in driver based on Spring 3.0's RestTemplate. In addition to making Key/Value datastore access easier from Java, the RiakTemplate has been designed, from the ground up, to be used from alternative JVM languages like Groovy or JRuby. - - Since the SDKV support for Riak uses the stateless REST API, there are no connection factories to manage or other stateful objects to keep tabs on. The helper you'll spend the most time working with is likely the thread-safe RiakTemplate or RiakKeyValueTemplate. Your choice of which to use will depend on how you want to manage buckets and keys. SDKV supports two ways to interact with Riak. If you want to use the convention you're likely already familiar with, namely of storing an entry with a given key in a "bucket" by passing the bucket and key name separately, you'll want to use the RiakTemplate. If you want to use a single object to represent your bucket and key pair, you can use the RiakKeyValueTemplate. It supports a key object that is encoded using one of several different methods: - - Using a String - You can concatenate two strings, separated by a colon: "mybucket:mykey". - Using a BucketKeyPair - You can pass an instance of BucketKeyPair, like SimpleBucketKeyPair. - Using a Map - You can pass a Map with keys for "bucket" and "key". - - - -
- Configuring the <classname>RiakTemplate</classname> - - This is likely the easiest path to using SDKV for Riak, as the bucket and key are passed separately. The examples that follow will assume you're using this version of the the template. - - There are only two options you need to set to specify the Riak server to use in your RiakTemplate object: "defaultUri" and "mapReduceUri". Encoded with the URI should be placeholders for the bucket and the key, which will be filled in by the RestTemplate when the request is made. - - You can also turn the internal, ETag-based object cache off by setting useCache="false". It's generally recommended, however, to leave the internal cache on as the ETag matching will pick up any changes made to the entry on the Riak side and your application will benefit from greatly-increased performance for often-requested objects. - - - - - - -]]> - - -
- Advanced Template Configuration - - There are a couple additional properties on the RiakTemplate that can be changed from their defaults. If you want to specify your own ConversionService to use when converting objects for storage inside Riak, then set it on the "conversionService" property: - - - - - - - -]]> - - - Depending on the application, it might be useful to set default Quality-of-Service parameters. In Riak paralance, these are the "dw", "w", and "r" parameters. They can be set to an integer representing the number of vnodes that need to report having received the data before declaring the operation a success, or the string "one", "all", or (the default) "quorum". These values can be overridden by passing a different set of QosParameters to the set/get operation you're performing. - - - - - - - -]]> - - - You can also set a specific ClassLoader to use when loading objects from Riak. Just set the classLoader property: - - - - - - -]]> - - - -
-
- -
- Working with Objects using the <classname>RiakTemplate</classname> - - One of the primary goals of the SDKV project is to make accessing Key/Value stores easier for the developer by taking away the mundane tasks of basic IO, buffering, type conversion, exception handling, and sundry other logistical concerns so the developer can focus on creating great applications. SDKV for Riak works toward this goal by making basic persistence and data access as easy as using a Map. - -
- Saving data into Riak - - To store data in Riak, use one of the six different set methods: - - - - Additionally, there is a setWithMetaData method that takes a Map of metadata that will be set as the outgoing HTTP headers. To set custom metadata, your key should be prefixed with X-Riak-Meta- e.g. X-Riak-Meta-Custom-Header. - -
- Letting Riak generate the key - - Riak has the ability to generate random IDs for you when storing objects. The RiakTemplate exposes this capability via the put method. It will return the ID it generated for you as a String. - - -
-
- -
- Retrieving data from Riak - - Retrieving data from Riak is just as easy. There are actually 13 different get methods on RiakTemplate that give the developer a wide range options for accessing and converting your data. - - Assuming you've stored a POJO using an appropriate set method, you can retrieve that object from Riak using a get: - - -
-
- - - -
- Map/Reduce - - Riak supports Map/Reduce functionality in a couple different ways. You can specify the Javascript source to execute (termed "anonymous" Javascript), you can reference some Javascript already stored in Riak at a specfic bucket and key, or you can reference an Erlang module and function. The Map/Reduce support in SDKV covers all these bases by giving you meaningful abstractions over the Map/Reduce job that represent the various aspects of the Map/Reduce process. - - At the highest level, every Map/Reduce request is represented by a MapReduceJob. The MapReduceJob represents the inputs, the phases, and the optional arg to send to Riak to execute the Map/Reduce job. The toJson method is responsible for serializing the entire job into the appropriate JSON data to send to Riak. - -
- Specifying Inputs - - Riak will accept either a string denoting the bucket in which to get the list of keys to operate on, or a List of Lists denoting the bucket/key pairs to operate on while executing this Map/Reduce job. If you call the addInputs method on the job passing a List with a single string entry, the job will assume you want to operate on an entire bucket. Otherwise, you'll need to pass a multi-dimensional List of bucket/key pairs. - - To operate on an entire bucket: - bucket = new ArrayList() {{ - add("mybucket"); -}}; -job.addInputs(bucket); // Will M/R entire bucket - ]]> - - - To operate on a set of keys: - pair = new ArrayList() {{ - add("mybucket"); - add("mykey"); -}}; -List> keys = new ArrayList>() {{ - add(pair); -}}; -job.addInputs(keys); // Will M/R only specified keys - ]]> - -
- -
- Defining Phases - - Map/Reduce operations in Riak are broken up into phases. Phases contain a MapReduceOperation. There are currently two implementations to handle Javascript or Erlang M/R operations: JavascriptMapReduceOperation and ErlangMapReduceOperation. - - An example Map/Reduce job defining a single "map" phase defined in anonymous Javascript might look like this: - bucket = new ArrayList() {{ - add("mybucket"); -}}; - -job.addInputs(bucket); // M/R the entire bucket - -MapReduceOperation mapOper = new JavascriptMapReduceOperation("function(v){ ...M/R function body... }"); -MapReducePhase mapPhase = new RiakMapReducePhase("map", "javascript", mapOper); - -job.addPhase(mapPhase); - ]]> - -
- -
- Executing and Working with the Result - - To execute a configured job on your Riak server, use either the synchronous execute or asynchronous submit methods of your configured RiakTemplate: - - - -...or... - -List o = riak.execute(job, MyPojo.class); // Coerce to given type - -...or... - -Future> f = riak.submit(job); // Job runs in a separate thread - ]]> - -
-
- -
- Managing Bucket Properties - - It's sometimes useful to manage settings like the Quality-of-Service parameters w and dw (write and durable write thresholds) and the n_val setting at the bucket level. It's also possible to list the keys in a particular bucket by calling the getBucketSchema method, passing true as the second parameter, which tells the RiakTemplate to list the keys. - - To list the keys in a bucket, you would do something like this: - - schema = riak.getBucketSchema("mybucket", true); -List keys = schema.get("keys") -for(String key : keys) { - ...do something with each key... -} - ]]> - - - To update the bucket settings, pass a Map of properties: - - props = new HashMap(); -props.put("n_val", 6); -props.put("dw", 3); - -riak.updateBucketSchema("mybucket", props); - ]]> - - Only the properties specified in the passed-in Map will be updated. Properties that have already been set in previous operations and not specified in this operation will be unaffected. - - -
- -
- Asynchronous Access - - SDKV for Riak also includes an asynchronous version of most of the methods available to the RiakTemplate, whose method calls are all synchronous. The asynchronous version of the template is called AsyncRiakTemplate. - -
- Template Configuration - - The AsyncRiakTemplate has the same basic configuration properties as the synchronous RiakTemplate. The only other property specific to the AsyncRiakTemplate you might want to configure is the thread pool the template uses to execute tasks asynchronously (by default a cached ThreadPoolExecutor). Set your ExecutorService on the template's workerPool property. - -
- -
- Callbacks - - Using the asynchronous Riak support in SDKV means you'll be relying on callbacks to execute your business logic when the requested operation is completed. All asynchronous operations follow a similar pattern: - - They are named similarly to their synchronous counterparts. - They take a AsyncKeyValueStoreOperation<?, ?> as a final parameter. - They return a Future<?>. - - - - To perform an asynchronous get on a JSON-serialized Map object which returns a custom object from the callback, you'd do something like: - future = riak.get("mybucket", "mykey", new AsyncKeyValueStoreOperation() { - - MyObject obj = new MyObject(); - - MyObject completed(KeyValueStoreMetaData meta, Map result) { - obj.setName(result.get("name")); - return obj; - } - - MyObject failed(Throwable error) { - obj.setError(error); - return obj; - } - -}); - -// Maybe do other work while waiting... -MyObject obj = future.get(); - ]]> - -
- -
- -
- Groovy Builder Support - - If your application uses Groovy, either in a standalone context, or as part of a Grails application, then you could benefit from using the Groovy RiakBuilder that comes with SDKV for Riak. Underneath, it uses the AsyncRiakTemplate. To use the RiakBuilder, pass the constructor a configured AsyncRiakTemplate. - - Instances of RiakBuilder are NOT thread-safe and should not be shared across threads. - - The RiakBuilder implements an easy-to-use DSL for interacting with Riak. It doesn't implement the full set of methods available on the underlying AsyncRiakTemplate but a subset. The methods that the RiakBuilder responds to are: - - set - setAsBytes - put - get - getAsBytes - getAsType - containsKey - delete - foreach - - - -
- Riak DSL Usage - - The following example illustrates the different uses of the Riak DSL, including batching requests together into a logical group, using a default bucket name (the node directly beneath riak will be considered the default bucket to use for the contained operations unless a different one is specified on the operation itself): - meta.key }} - put(value: [test: "value"]) { completed { v, meta -> meta.key }} - put(value: [test: "value"]) { completed { v, meta -> meta.key }} - put(value: [test: "value"]) { completed { v, meta -> meta.key }} - - mapreduce { - query { - map(arg: [test: "arg", alist: [1, 2, 3, 4]]) { - source "function(v, keyInfo, arg){ return [1]; }" - } - reduce { - source "function(v){ return Riak.reduceSum(v); }" - } - } - failed { it.printStackTrace() } - } - } -} -def results = riak.results - -riak.foreach(bucket: "test") { - completed { v, meta -> - riak.delete(bucket: "test", key: meta.key) - } -} - ]]> - - - Some important things to note from this example: - - Each operation in the Riak DSL has two callbacks: completed and failed. - The completed closure is passed either the result object, or, if your closure is defined with two parameters, the result object and the metadata associated with that entry. - Operations can be enclosed in an arbitrarily-named closure which the builder interprets as a default bucket name (in this case, the node "test" tells the builder to use the bucket name "test" for a default, unless one is specified on one of the enclosed operations). - Each operation within a builder's execution will be accumulated inside the special results property. Code that needs to know the output of individual operations within the batch can get access to that object through this property. Note that this means that RiakBuilder instances are NOT thread-safe. - - - - Even though the Riak DSL uses an asynchronous template underneath, all operations performed through the DSL will, by default, block until complete. To get a truly asynchronous operation, pass the parameter wait: 0 (or give a meaningful timeout in milliseconds to wait for the operation to complete) on the operation. - -
- QosParameters on Riak DSL Operations - - You can pass QosParameters to Riak DSL operations by simply defining them as parameters to the operation: - - -
- -
- Working with Riak DSL Output - - The output of DSL operations will either be passed to the configured completed callback, or be returned to the caller if no callback is specified. In the example above, the mapreduce operation has no completed closure. Therefore, the return of the reduce phase is simply passed back to the builder, which makes that output available on the special results property. - - To gain access to the operation's results immediately, simply assign it to a variable: - - - If you add a non-zero wait value to the operation, "myobj" will contain a Future<?> rather than the result object itself. - - -
-
-
- -
- Working with streams - - SDKV for Riak includes a couple of useful helper objects to make reading and writing plain text or binary data in Riak really easy. If you want to store a file in Riak, then you can create a RiakOutputStream and simply write your data to it (making sure to call the "flush" method, which actually sends the data to Riak). - - - - Reading data from Riak is similarly easy. SDKV provides a java.io.File subclass that represents a resource in Riak. There's also a Spring IO Resource abstraction called RiakResource that can be used anywhere a Resource is required. There's also an InputStream implementation called RiakInputStream. - - - - -
- \ No newline at end of file diff --git a/docs/src/reference/resources/xsl/fopdf.xsl b/docs/src/reference/resources/xsl/fopdf.xsl index 4b3692f19..8582406da 100644 --- a/docs/src/reference/resources/xsl/fopdf.xsl +++ b/docs/src/reference/resources/xsl/fopdf.xsl @@ -106,7 +106,7 @@ - Spring Data Key Value () + Spring Data Redis ()