From 3a434851754f197dcc8ea3dfed7c67f98c8bae34 Mon Sep 17 00:00:00 2001 From: Brian Roach Date: Sat, 29 Mar 2014 16:12:28 -0600 Subject: [PATCH] WIP commit. Added a doclet that allows filtering out inner classes (the extendable builder thing clutters up the javadoc) --- pom.xml | 21 ++-- .../client/annotations/RiakBucketName.java | 31 ++++- .../client/annotations/RiakBucketType.java | 33 ++++- .../client/annotations/RiakContentType.java | 36 +++++- .../riak/client/annotations/RiakIndex.java | 60 +++++---- .../riak/client/annotations/RiakKey.java | 46 ++++--- .../client/annotations/RiakLastModified.java | 26 +++- .../riak/client/annotations/RiakLinks.java | 68 ++++++---- .../client/annotations/RiakTombstone.java | 29 ++++- .../riak/client/annotations/RiakUsermeta.java | 53 ++++++-- .../riak/client/annotations/RiakVClock.java | 34 ++++- .../riak/client/annotations/RiakVTag.java | 26 +++- .../riak/client/annotations/package-info.java | 51 ++++++++ .../riak/client/convert/ConverterFactory.java | 48 +++++-- .../riak/client/convert/JSONConverter.java | 10 +- .../client/convert/RiakJacksonModule.java | 32 +---- .../convert/reflection/AnnotationCache.java | 6 +- .../convert/reflection/AnnotationUtil.java | 59 ++++----- .../client/convert/reflection/ClassUtil.java | 9 +- .../riak/client/javadoc/JavadocFilter.java | 119 ++++++++++++++++++ .../operations/StoreBucketProperties.java | 24 +--- .../client/operations/kv/DeleteValue.java | 4 +- .../riak/client/operations/kv/FetchValue.java | 17 +-- .../client/operations/kv/KvResponseBase.java | 3 + .../riak/client/operations/kv/MultiFetch.java | 37 +++--- .../riak/client/operations/kv/StoreValue.java | 3 + .../client/operations/kv/UpdateValue.java | 3 + .../client/operations/kv/package-info.java | 4 + .../com/basho/riak/client/query/Location.java | 4 + .../riak/client/query/links/RiakLinks.java | 2 +- 30 files changed, 669 insertions(+), 229 deletions(-) create mode 100644 src/main/java/com/basho/riak/client/annotations/package-info.java create mode 100644 src/main/java/com/basho/riak/client/javadoc/JavadocFilter.java create mode 100644 src/main/java/com/basho/riak/client/operations/kv/package-info.java diff --git a/pom.xml b/pom.xml index 7784bd016..7cb4e0808 100755 --- a/pom.xml +++ b/pom.xml @@ -168,27 +168,20 @@ com.basho.riak riak-client - 2.0.0-ALPHA1-SNAPSHOT + 2.0.0-SNAPSHOT + com.basho.riak.client.javadoc.JavadocFilter + + com.basho.riak + riak-client + 2.0.0-SNAPSHOT + - - - netty-snapshot-repository - http://repository-netty.forge.cloudbees.com/snapshot/ - - false - - - true - - - - com.sun diff --git a/src/main/java/com/basho/riak/client/annotations/RiakBucketName.java b/src/main/java/com/basho/riak/client/annotations/RiakBucketName.java index 9e16cb300..c04956fd5 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakBucketName.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakBucketName.java @@ -22,8 +22,37 @@ import java.lang.annotation.Target; /** - * + * Annotates a field or getter/setter method pair in a class to serve as the bucket name. + *

+ * The type must be a {@code String}. + * + * 

+ * class MyPojo
+ * {
+ *     {@literal @}RiakBucketName
+ *     String bucketName;
+ * }
+ * 
+ * class MyPojo
+ * {
+ *     private String bucketName;
+ * 
+ *     {@literal @}RiakBucketName
+ *     public void setBucketName(String bucketName)
+ *     {
+ *         this.bucketName = bucketName;
+ *     }
+ * 
+ *     {@literal @}RiakBucketName
+ *     public String getBucketName()
+ *     {
+ *         return bucketName;
+ *     }
+ * }
+ *
+ *

* @author Brian Roach + * @since 2.0 */ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.METHOD}) public @interface RiakBucketName { diff --git a/src/main/java/com/basho/riak/client/annotations/RiakBucketType.java b/src/main/java/com/basho/riak/client/annotations/RiakBucketType.java index cea55a5e4..3aeaa8263 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakBucketType.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakBucketType.java @@ -1,5 +1,5 @@ /* - * Copyright 2014 Basho Technologies + * Copyright 2014 Basho Technologies Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -22,8 +22,37 @@ import java.lang.annotation.Target; /** - * + * Annotates a field or getter/setter method pair in a class to server as the bucket type. + *

+ * The type must be a {@code String}. + * + * 

+ * class MyPojo
+ * {
+ *     {@literal @}RiakBucketType
+ *     String bucketType;
+ * }
+ * 
+ * class MyPojo
+ * {
+ *     private String bucketType;
+ * 
+ *     {@literal @}RiakBucketType
+ *     public void setBucketType(String bucketType)
+ *     {
+ *         this.bucketType = bucketType;
+ *     }
+ * 
+ *     {@literal @}RiakBucketType
+ *     public String getBucketType()
+ *     {
+ *         return bucketType;
+ *     }
+ * }
+ *
+ *

* @author Brian Roach + * @since 2.0 */ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.METHOD}) public @interface RiakBucketType { diff --git a/src/main/java/com/basho/riak/client/annotations/RiakContentType.java b/src/main/java/com/basho/riak/client/annotations/RiakContentType.java index 8d61c1710..e2c94473d 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakContentType.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakContentType.java @@ -9,7 +9,7 @@ * * 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. + * WITHOUT WARANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ @@ -23,7 +23,39 @@ /** - * + * Annotates a field or getter/setter method pair in a class to serve as the content-type. + *

+ * The type must be a {@code String}. + *

+ *

+ * In most cases this is not needed as the {@link com.basho.riak.client.convert.Converter} + * will supply the appropriate content-type during serialization. + * + * 

+ * class MyPojo
+ * {
+ *     {@literal @}RiakContentType
+ *     String contentType;
+ * }
+ * 
+ * class MyPojo
+ * {
+ *     private String contentType;
+ * 
+ *     {@literal @}RiakContentType
+ *     public void setContentType(String contentType)
+ *     {
+ *         this.contentType = contentType;
+ *     }
+ * 
+ *     {@literal @}RiakContentType
+ *     public String getContentType()
+ *     {
+ *         return contentType;
+ *     }
+ * }
+ *
+ *

* @author Brian Roach * @since 2.0 */ diff --git a/src/main/java/com/basho/riak/client/annotations/RiakIndex.java b/src/main/java/com/basho/riak/client/annotations/RiakIndex.java index 04f1bafdd..8eeda27bf 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakIndex.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakIndex.java @@ -19,42 +19,58 @@ import java.lang.annotation.Target; /** - * Annotation to declare a field or getter/setter pair as a RiakIndex. + * Annotates a field or getter/setter method pair in a class to serve as a RiakIndex. *

- * You do not need to specify the index type prefix (_bin/_int). It will be - * inferred from the type of the annotated field. - * - * Only String/Long/long or {@code Set} / {@code Set} fields - * may be annotated with RiakIndex. + * You do not need to specify the index type suffix ({@code _bin}/{@code _int}). It will be + * inferred from the type of the annotated field except when using {@code byte[]}; + * in this case the full index name including the suffix must be supplied. *

*

- * NOTE: if there are *multiple* values for the same named index and the field - * in the domain object is an long, Long, or String only the 1st will find - * it's way into the domain object + * For {@code _bin} indexes, {@code String} and {@code byte[]} types are supported. + * For {@code _int} indexes, {@code Long}, {@code BigInteger} and {@code byte[]} + * are supported. This can either be a single instance or a {@code Set}. *

*

- * For example: + * Important Note: if there are multiple index keys for the object and the field + * is a single value rather than a {@code Set}, only a single index key will be + * set (the first returned). *

* 
- * 
- * public class MyClass {
- *     @RiakKey
+ * public class MyClass 
+ * {
+ *     {@literal @}RiakKey
  *     private String myKeyString;
  *     
- *     @RiakIndex(name="email")
- *     private String emailAddress; // will be indexed in email_bin index
+ *     {@literal @}RiakIndex(name="email")
+ *     private {@literal Set} emailAddress; // will be indexed in the email_bin index
  *     
- *     @RiakIndex(name="age")
- *     private long age; // will be index in age_int index
+ *     {@literal @}RiakIndex(name="age")
+ *     private long age; // will be indexed in the age_int index
  * }
- *  
- *
* + * public class MyClass + * { + * private {@literal Set} categoryIds; * + * {@literal @}RiakIndex(name="category_ids") + * public {@literal Set} getCategoryIds() + * { + * return categoryIds; + * } * - * @author russell - * @see JSONConverter - */ + * {@literal @}RiakIndex(name="category_ids") + * public void setCategoryIds({@literal Set} ids) + * { + * categoryIds = ids; + * } + * } + * + * + * + * @author Russell Brown + * @author Brian Roach + * @since 1.0 +*/ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.METHOD}) public @interface RiakIndex { /** * @return the index name diff --git a/src/main/java/com/basho/riak/client/annotations/RiakKey.java b/src/main/java/com/basho/riak/client/annotations/RiakKey.java index eb58639f6..a147fc7d3 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakKey.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakKey.java @@ -1,15 +1,17 @@ /* - * This file is provided to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance with the License. + * Copyright 2014 Basho Technologies Inc. + * + * 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 - * + * + * 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. + * 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. */ package com.basho.riak.client.annotations; @@ -19,31 +21,37 @@ import java.lang.annotation.Target; /** - * Annotation to declare a field or getter/setter pair as the key to a data item in Riak. + * Annotates a field or getter/setter method pair in a class to serve as the key. *

- * This annotation can be used either on a field, or getter/setter pair of methods. + * The type must be a {@code String}. *

- * * 

- * public class MyPojo {
- *     @RiakKey public String key;
+ * public class MyPojo 
+ * {
+ *     {@literal @}RiakKey 
+ *     public String key;
  * }
  * 
- * public class AnotherPojo {
+ * public class AnotherPojo 
+ * {
  *     private String key;
  *     
- *     @RiakKey public String getKey() {
+ *     {@literal @}RiakKey 
+ *     public String getKey() 
+ *     {
  *         return key;
  *     }
  * 
- *     @RiakKey public void setKey(String key) {
+ *     {@literal @}RiakKey 
+ *     public void setKey(String key) 
+ *     {
  *         this.key = key;
  *     }
  * }
  *
- * @author russell + * @author Russell Brown * @author Brian Roach - * @see JSONConverter + * @since 1.0 */ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.METHOD}) public @interface RiakKey { diff --git a/src/main/java/com/basho/riak/client/annotations/RiakLastModified.java b/src/main/java/com/basho/riak/client/annotations/RiakLastModified.java index 637bee35d..b764eaa6a 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakLastModified.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakLastModified.java @@ -22,7 +22,31 @@ import java.lang.annotation.Target; /** - * + * Annotates a field or setter method in a class to store last modified. + *

+ * This value is only populated when fetching an object from riak. Setting it when + * storing an object has no effect. A getter method is not supported; only a setter + * method may be annotated. The type must be {@literal long} or {@literal Long}. + * + * 

+ * class MyPojo
+ * {
+ *     {@literal @}RiakLastModified
+ *     Long lastModified;
+ * }
+ * 
+ * class MyPojo
+ * {
+ *     private Long lastModified;
+ * 
+ *     {@literal @}RiakLastModified
+ *     public void setLastModified(Long lastModified)
+ *     {
+ *         this.lastModified = lastModified;
+ *     }
+ * }
+ *
+ * * @author Brian Roach * @since 2.0 */ diff --git a/src/main/java/com/basho/riak/client/annotations/RiakLinks.java b/src/main/java/com/basho/riak/client/annotations/RiakLinks.java index 5fd9abc9b..11c9ff7b7 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakLinks.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakLinks.java @@ -1,15 +1,17 @@ /* - * This file is provided to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance with the License. + * Copyright 2014 Basho Technologies Inc. + * + * 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 - * + * + * 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. + * 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. */ package com.basho.riak.client.annotations; @@ -19,27 +21,39 @@ import java.lang.annotation.Target; /** - * Annotation to declare a field or a getter/setter pair as holding a collection of RiakLinks - *

- * Annotate a single field in your domain class. It must be a - * Collection. This is so ORM features can still be used and RiakLink - * data made available. - *

+ * Annotates a field or getter/setter method pair in a class to serve as a set of links. *

- * For example: 

- * public class MyClass {
- *     \@RiakKey
- *     private String myKeyString;
- *     
- *     \@RiakLinks
- *     private Collection links;
+ * The type must be {@literal Collection}. 
+ * 
+ * class MyPojo
+ * {
+ *     {@literal @}RiakLinks
+ *     {@literal Collection} riakLinks;
  * }
- * 

- * 

  * 
+ * class MyPojo
+ * {
+ *     private {@literal Collection} riakLinks;
  * 
- * @author russell
- * @see JSONConverter
- */
+ *     {@literal @}RiakLinks
+ *     public void setRiakLinks({@literal Collection} riakLinks)
+ *     {
+ *         this.riakLinks = riakLinks;
+ *     }
+ * 
+ *     {@literal @}RiakLinks
+ *     public {@literal Collection} getRiakLinks()
+ *     {
+ *         return riakLinks;
+ *     }
+ * }
+ * 
+ *
+ * + * + * @author Russell Brown + * @author Brian Roach + * @since 1.0 +*/ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.METHOD}) public @interface RiakLinks { } diff --git a/src/main/java/com/basho/riak/client/annotations/RiakTombstone.java b/src/main/java/com/basho/riak/client/annotations/RiakTombstone.java index ecf3f460a..2a23549d4 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakTombstone.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakTombstone.java @@ -18,11 +18,38 @@ import java.lang.annotation.Target; /** - * + * Annotates a field or getter/setter method pair in a class to serve as the tombstone indicator. + *

* This annotation is used to denote a boolean field or getter/setter pair that will be marked true * if the object is a tombstone (deleted vector clock) * + * 

+ * public class MyPojo 
+ * {
+ *     {@literal @}RiakTombstone 
+ *     public boolean tombstone;
+ * }
+ * 
+ * public class AnotherPojo 
+ * {
+ *     private boolean tombstone;
+ *     
+ *     {@literal @}RiakTombstone 
+ *     public boolean getTombstone() 
+ *     {
+ *         return tombstone;
+ *     }
+ * 
+ *     {@literal @}RiakTombstone 
+ *     public void setTombstone(boolean tombstone) 
+ *     {
+ *         this.tombstone = tombstone;
+ *     }
+ * }
+ *
+ * * @author Brian Roach + * @since 2.0 */ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.METHOD}) public @interface RiakTombstone { diff --git a/src/main/java/com/basho/riak/client/annotations/RiakUsermeta.java b/src/main/java/com/basho/riak/client/annotations/RiakUsermeta.java index 13cf55154..0875fd2e8 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakUsermeta.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakUsermeta.java @@ -19,31 +19,60 @@ import java.lang.annotation.Target; /** - * Annotation to declare a map field or getter/setter pair as containing user meta data for a Riak + * Annotates a field or getter/setter method pair in a class to serve as containing user meta data for a Riak * object. *

* If you set the key value (to anything other than the empty string) then you * can use the annotation to map a single key of user meta data to a field. *

*

- * For example: - * 

- * public class MyClass {
- *     \@RiakKey
- *     private String myKeyString;
+ * 
+ * public class MyClass 
+ * {
  *     
- *     \@RiakUsermeta
- *     private Map usermetaData;
- *     // - OR -
- *     \@RiakUsermeta("usermeta-data-key1") 
+ *     {@literal @}RiakUsermeta
+ *     private {@literal Map} usermetaData;
+ *     
+ *     {@literal @}RiakUsermeta("usermeta-data-key1") 
  *     private String usermetaDataItem1;
  * }
- * 

+ * 
+ * public class MyClass
+ * {
+ *     private {@literal Map} usermetaData;
+ *     private String usermetaDataItem1;
+ * 
+ *     {@literal @}RiakUsermeta
+ *     public {@literal Map} getMeta()
+ *     {
+ *         return usermetaData;
+ *     }
+ * 
+ *     {@literal @}RiakUsermeta
+ *     public void setMeta({@literal Map} meta)
+ *     {
+ *         usermetaData = meta;
+ *     }
+ * 
+ *     {@literal @}RiakUsermeta("usermeta-data-key1") 
+ *     public String getSingleMeta()
+ *     {
+ *          return usermetaDataItem1;
+ *     }
+ * 
+ *     {@literal @}RiakUsermeta("usermeta-data-key1")
+ *     public void setSingleMeta(String meta)
+ *     {
+ *         usermetaDataItem1 = meta;
+ *     }
+ *  }
+ *
*

* * * @author Russel Brown - * @see JSONConverter + * @author Brian Roach + * @since 1.0 */ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.METHOD}) public @interface RiakUsermeta { /** diff --git a/src/main/java/com/basho/riak/client/annotations/RiakVClock.java b/src/main/java/com/basho/riak/client/annotations/RiakVClock.java index 82402a3cb..d570d6e3a 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakVClock.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakVClock.java @@ -1,4 +1,7 @@ -/*Licensed under the Apache License, Version 2.0 (the "License"); +/* + * Copyright 2014 Basho Technologies Inc. + * + * 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 * @@ -18,11 +21,36 @@ import java.lang.annotation.Target; /** - * Annotation to declare a field or getter/setter pair as the vector clock to a data item in Riak. + * Annotates a field or getter/setter method pair in a class to serve as the vector clock. *

- * This annotation can be used with either byte[] or VClock types. + * This annotation can be used with either {@code byte[]} or {@code VClock} types. *

+ * 
+ * public class MyPojo 
+ * {
+ *     {@literal @}RiakVClock 
+ *     public VClock vclock;
+ * }
+ * 
+ * public class AnotherPojo 
+ * {
+ *     private VClock vclock;
+ *     
+ *     {@literal @}RiakVClock 
+ *     public VClock getVClock() 
+ *     {
+ *         return vclock;
+ *     }
+ * 
+ *     {@literal @}RiakVClock 
+ *     public void setVClock(VClock vclock) 
+ *     {
+ *         this.vclock = vclock;
+ *     }
+ * }
+ *
* @author Brian Roach + * @since 1.4 */ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.METHOD}) public @interface RiakVClock { diff --git a/src/main/java/com/basho/riak/client/annotations/RiakVTag.java b/src/main/java/com/basho/riak/client/annotations/RiakVTag.java index 29a657502..70209855b 100644 --- a/src/main/java/com/basho/riak/client/annotations/RiakVTag.java +++ b/src/main/java/com/basho/riak/client/annotations/RiakVTag.java @@ -22,7 +22,31 @@ import java.lang.annotation.Target; /** - * + * Annotates a field or setter method in a class to store the VTag. + *

+ * This value is only populated when fetching an object from riak. Setting it when + * storing an object has no effect. A getter method is not supported; only a setter + * method may be annotated. The type must be {@literal String}. + * + * 

+ * class MyPojo
+ * {
+ *     {@literal @}RiakVTag
+ *     String vtag;
+ * }
+ * 
+ * class MyPojo
+ * {
+ *     private String vtag;
+ * 
+ *     {@literal @}RiakVTag
+ *     public void setVTag(String vtag)
+ *     {
+ *         this.vtag = vtag;
+ *     }
+ * }
+ *
+ * * @author Brian Roach * @since 2.0 */ diff --git a/src/main/java/com/basho/riak/client/annotations/package-info.java b/src/main/java/com/basho/riak/client/annotations/package-info.java new file mode 100644 index 000000000..11e502ace --- /dev/null +++ b/src/main/java/com/basho/riak/client/annotations/package-info.java @@ -0,0 +1,51 @@ +/** + * Annotations to use for ORM. + * + *

Introduction

+ * The Riak Java client provides a full set of annotations to facilitate simply + * storing/retrieving your own domain object. All annotations can be applied to + * a field or a getter/setter pair of methods. + *

+ * In addition, the {@link com.basho.riak.client.convert.Converter} + * interface allows for serialization/deserialization for the data portion. + *

+ *

+ * By annotating your own domain object, you can simply pass an instance of it + * to {@link com.basho.riak.client.operations.kv.StoreValue}. + *

+ *

+ * When fetching data from Riak, the reverse is also true. The {@link com.basho.riak.client.operations.kv.FetchValue.Response} + * handles injecting your domain object with any of the annotated values. + *

+ *

+ * Raw types as well as Generic types are supported. The latter is done via Jackson's + * {@code TypeReferece} class. + *

+ *

OverView

+ * To store an object in Riak there's a minimum of four pieces of information + * required; a bucket type, a bucket name, a key, and a vector clock. For an + * annotated domain object, only three of these are required as in the absence of + * a bucket type, the default "default" type is supplied. + * 
+ * 
+ * public class AnnotatedPojo
+ * {
+ *     {@literal @}RiakBucketType
+ *     public String bucketType;
+ *     
+ *     {@literal @}RiakBucketName
+ *     public String bucketName;
+ *     
+ *     {@literal @}RiakKey
+ *     public String key; 
+ *     
+ *     {@literal @}RiakVClock
+ *     VClock clock;
+ * 
+ *     public String value;
+ * }
+ * 
+ *
+ * + */ +package com.basho.riak.client.annotations; diff --git a/src/main/java/com/basho/riak/client/convert/ConverterFactory.java b/src/main/java/com/basho/riak/client/convert/ConverterFactory.java index d96d49d32..e9f0f43e9 100644 --- a/src/main/java/com/basho/riak/client/convert/ConverterFactory.java +++ b/src/main/java/com/basho/riak/client/convert/ConverterFactory.java @@ -18,13 +18,25 @@ import com.basho.riak.client.query.RiakObject; import com.fasterxml.jackson.core.type.TypeReference; -import java.lang.reflect.Constructor; import java.lang.reflect.Type; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; /** - * + * Holds instances of converters to be used for serialization / deserialization + * of objects stored and fetched from Riak. + *

+ * When storing and retrieving your own domain objects to/from Riak, they + * need to be serialized / deserialized. By default the {@link JSONConverter} + * is provided. This uses the Jackson JSON library to translate your object to/from + * JSON. In many cases you will never need to create or register your own + * converter with the ConverterFactory. + *

+ *

+ * In the case you do need custom conversion, you would extend {@link Converter} + * and then register it with the ConverterFactory for your classes. + *

+ * * @author Brian Roach * @since 2.0 */ @@ -41,8 +53,8 @@ public enum ConverterFactory /** - * Get the instance of the ConverterFactory; - * @return + * Get the instance of the ConverterFactory. + * @return the ConverterFactory */ public static ConverterFactory getInstance() { @@ -52,18 +64,26 @@ public static ConverterFactory getInstance() /** * Returns a Converter instance for the supplied class. *

- * If no converter is registered, the default converter is returned. + * If no converter is registered, the default {@link JSONConverter} is returned. *

* @param The type for the converter * @param type The type used to look up the converter * @return an instance of the converter for this class - * @see #setDefaultConverter(java.lang.Class) */ public Converter getConverter(Type type) { return getConverter(type, null); } + /** + * Returns a Converter instance for the supplied class. + *

+ * If no converter is registered, the default {@link JSONConverter} is returned. + *

+ * @param The type for the converter + * @param typeReference the TypeReference for the class being converted. + * @return an instance of the converter for this class + */ public Converter getConverter(TypeReference typeReference) { return getConverter(null, typeReference); @@ -102,13 +122,22 @@ private Converter getConverter(Type type, TypeReference typeReference) *

* @param The type being converted * @param clazz the class for this converter. - * @param converter an instance of Converter + * @param converter an instance of Converter */ public void registerConverterForClass(Class clazz, Converter converter) { converterInstances.put((Type)clazz, converter); } + /** + * Register a converter for the supplied class. + *

+ * This instance be re-used for every conversion. + *

+ * @param The type being converted + * @param typeReference the TypeReference for the class being converted. + * @param converter an instance of Converter + */ public void registerConverterForClass(TypeReference typeReference, Converter converter) { Type t = typeReference.getType(); @@ -125,6 +154,11 @@ public void unregisterConverterForClass(Class clazz) converterInstances.remove((Type)clazz); } + /** + * Unregister a converter. + * @param The type + * @param typeReference the TypeReference for the class being converted. + */ public void unregisterConverterForClass(TypeReference typeReference) { Type t = typeReference.getType(); diff --git a/src/main/java/com/basho/riak/client/convert/JSONConverter.java b/src/main/java/com/basho/riak/client/convert/JSONConverter.java index 2f3652846..3bcd6791d 100644 --- a/src/main/java/com/basho/riak/client/convert/JSONConverter.java +++ b/src/main/java/com/basho/riak/client/convert/JSONConverter.java @@ -29,9 +29,11 @@ import java.lang.reflect.Type; /** - * Converts a RiakObject's value to an instance of T. T must have a field - * annotated with {@link RiakKey} or you must construct the converter with a key to use. RiakObject's value *must* be a JSON string. - * + * The default Converter used when storing and fetching domain objects from Riak. + *

+ * This uses the Jackson JSON library to serialize / deserialize objects to JSON. + * The reulsting JSON is then stored in Riak. + *

* @author Brian Roach * @param type to convert to/from * @@ -48,7 +50,7 @@ public class JSONConverter extends Converter { /** * Create a JSONConverter for creating instances of type from - * JSON and instances of {@link IRiakObject} with a JSON payload from + * JSON and instances of {@literal RiakObject} with a JSON payload from * instances of clazz * * @param type diff --git a/src/main/java/com/basho/riak/client/convert/RiakJacksonModule.java b/src/main/java/com/basho/riak/client/convert/RiakJacksonModule.java index 67fd1cd40..cf6262b12 100644 --- a/src/main/java/com/basho/riak/client/convert/RiakJacksonModule.java +++ b/src/main/java/com/basho/riak/client/convert/RiakJacksonModule.java @@ -17,13 +17,14 @@ import com.fasterxml.jackson.databind.Module; /** - * A Jackson {@link Module} that customises Jackson's object - * mapper so we can handle Riak annotations like {@link RiakKey}, - * {@link RiakUsermeta}, and RiakLink correctly. + * A Jackson module that customizes Jackson's object + * mapper so we can handle Riak annotations like {@literal @RiakKey}, + * {@literal @RiakUsermeta}, etc correctly. * - * Adds a {@link RiakBeanSerializerModifier} that removes any RiakXXX annotated + * Adds a {@link RiakBeanSerializerModifier} that removes any {@literal @RiakXXX} annotated * fields from the JSON output (since they will be persisted as object meta data - * and not as part of the object) + * and not as part of the object). Explicitly adding an additional {@literal @JsonProperty} + * annotation overrides this exclusion. * * @author russell * @@ -32,45 +33,24 @@ public class RiakJacksonModule extends Module { private static final String NAME = "RiakJacksonModule"; - // TODO get this from pom, or update it per release? private static final Version VERSION = Version.unknownVersion(); - /** - * - */ public RiakJacksonModule() { } - /* - * (non-Javadoc) - * - * @see org.codehaus.jackson.map.Module#getModuleName() - */ @Override public String getModuleName() { return NAME; } - /* - * (non-Javadoc) - * - * @see org.codehaus.jackson.map.Module#version() - */ @Override public Version version() { return VERSION; } - /* - * (non-Javadoc) - * - * @see - * org.codehaus.jackson.map.Module#setupModule(org.codehaus.jackson.map. - * Module.SetupContext) - */ @Override public void setupModule(SetupContext context) { diff --git a/src/main/java/com/basho/riak/client/convert/reflection/AnnotationCache.java b/src/main/java/com/basho/riak/client/convert/reflection/AnnotationCache.java index e2145e2bf..7d25f3fdf 100644 --- a/src/main/java/com/basho/riak/client/convert/reflection/AnnotationCache.java +++ b/src/main/java/com/basho/riak/client/convert/reflection/AnnotationCache.java @@ -21,16 +21,14 @@ /** * TODO: consider class reloading and re-scanning * @author russell - * @param * */ public class AnnotationCache { @SuppressWarnings("rawtypes") private final ConcurrentHashMap> cache = new ConcurrentHashMap>(); /** - * @param - * @param name - * @return + * @param clazz the class to be scanned and cached. + * @return an AnnotationInfo instance. */ public AnnotationInfo get(Class clazz) { diff --git a/src/main/java/com/basho/riak/client/convert/reflection/AnnotationUtil.java b/src/main/java/com/basho/riak/client/convert/reflection/AnnotationUtil.java index 93b029d82..dce707c45 100644 --- a/src/main/java/com/basho/riak/client/convert/reflection/AnnotationUtil.java +++ b/src/main/java/com/basho/riak/client/convert/reflection/AnnotationUtil.java @@ -33,15 +33,15 @@ public class AnnotationUtil private AnnotationUtil() {} /** - * Attempts to inject key as the value of the {@link RiakKey} - * annotated field of domainObject + * Attempts to inject key as the value of the {@literal @RiakKey} + * annotated member of domainObject * * @param the type of domainObject * @param domainObject the object to inject the key into * @param key the key to inject - * @return domainObject with {@link RiakKey} annotated field + * @return domainObject with {@literal @RiakKey} annotated member * set to key - * @throws ConversionException if there is a {@link RiakKey} annotated field + * @throws ConversionException if there is a {@literal @RiakKey} annotated member * but it cannot be set to the value of key */ public static T setKey(T domainObject, BinaryValue key) throws ConversionException @@ -52,7 +52,7 @@ public static T setKey(T domainObject, BinaryValue key) throws ConversionExc /** * Attempts to get a key from domainObject by looking for a - * {@link RiakKey} annotated field. If non-present it simply returns + * {@literal @RiakKey} annotated member. If non-present it simply returns * defaultKey * * @param the type of domainObject @@ -60,7 +60,7 @@ public static T setKey(T domainObject, BinaryValue key) throws ConversionExc * @param defaultKey the pass through value that will get returned if no key * found on domainObject * @return either the value found on domainObject;s - * {@link RiakKey} field or defaultkey + * {@literal @RiakKey} member or defaultkey */ public static BinaryValue getKey(T domainObject, BinaryValue defaultKey) { @@ -74,13 +74,13 @@ public static BinaryValue getKey(T domainObject, BinaryValue defaultKey) /** * Attempts to get a key from domainObject by looking for a - * {@link RiakKey} annotated field. If non-present it simply returns + * {@literal @RiakKey} annotated member. If non-present it simply returns * null * * @param the type of domainObject * @param domainObject the object to search for a key * @return either the value found on domainObject;s - * {@link RiakKey} field or null + * {@literal @RiakKey} member or null */ public static BinaryValue getKey(T domainObject) { @@ -121,15 +121,15 @@ public static BinaryValue getBucketType(T domainObject) /** * Attempts to inject vclock as the value of the - * {@link RiakVClock} annotated field of domainObject + * {@literal @RiakVClock} annotated member of domainObject * * @param the type of domainObject * @param domainObject the object to inject the key into * @param vclock the vclock to inject - * @return domainObject with {@link RiakVClock} annotated field + * @return domainObject with {@literal @RiakVClock} annotated member * set to vclock - * @throws ConversionException if there is a {@link RiakVClock} annotated - * field but it cannot be set to the value of vclock + * @throws ConversionException if there is a {@literal @RiakVClock} annotated + * member but it cannot be set to the value of vclock */ public static T setVClock(T domainObject, VClock vclock) throws ConversionException { @@ -145,13 +145,13 @@ public static VClock getVClock(T domainObject, VClock defaultVClock) /** * Attempts to get a vector clock from domainObject by looking - * for a {@link RiakVClock} annotated field. If non-present it simply + * for a {@literal @RiakVClock} annotated member. If non-present it simply * returns null * * @param the type of domainObject * @param domainObject the object to search for a key * @return either the value found on domainObject;s - * {@link RiakVClock} field or null + * {@literal @RiakVClock} member or null */ public static VClock getVClock(T domainObject) { @@ -160,15 +160,15 @@ public static VClock getVClock(T domainObject) /** * Attempts to inject isTombstone as the value of the - * {@link RiakTombstone} annotated field of domainObject + * {@literal @RiakTombstone} annotated member of domainObject * * @param the type of domainObject * @param domainObject the object to inject the key into * @param isTombstone the boolean to inject - * @return domainObject with {@link RiakTombstone} annotated - * field set to isTombstone - * @throws ConversionException if there is a {@link Riaktombstone} annotated - * field but it cannot be set to the value of isTombstone + * @return domainObject with {@literal @RiakTombstone} annotated + * member set to isTombstone + * @throws ConversionException if there is a {@literal @RiakTombstone} annotated + * member but it cannot be set to the value of isTombstone */ public static T setTombstone(T domainObject, boolean isTombstone) throws ConversionException { @@ -178,13 +178,13 @@ public static T setTombstone(T domainObject, boolean isTombstone) throws Con /** * Attempts to get boolean from domainObject by looking for a - * {@link RiakTombstone} annotated field. If non-present it simply returns + * {@literal @RiakTombstone} annotated member. If non-present it simply returns * null * * @param the type of domainObject * @param domainObject the object to search for a key * @return either the value found on domainObject's - * {@link RiakTombstone} field or null + * {@literal @RiakTombstone} member or null */ public static Boolean getTombstone(T domainObject) { @@ -193,7 +193,7 @@ public static Boolean getTombstone(T domainObject) /** * Attempts to get all the riak indexes from a domain object by looking for - * a {@link RiakIndexes} annotated field or getter method. + * a {@literal @RiakIndexes} annotated member. *

* If no indexes are present, an empty RiakIndexes is returned.

* @@ -208,8 +208,7 @@ public static RiakIndexes getIndexes(RiakIndexes container, T domainObject) /** * Attempts to populate a domain object with the contents of the supplied - * RiakIndexes by looking for a {@link RiakIndexes} annotated field or - * setter method. + * RiakIndexes by looking for a {@literal @RiakIndex} annotated member * * @param the type of the domain object * @param indexes a populated RiakIndexes object. @@ -222,10 +221,11 @@ public static T populateIndexes(RiakIndexes indexes, T domainObject) } /** - * Attempts to get the the riak links from a domain object by looking for a - * {@link RiakLinks} annotated field or getter method. + * Attempts to get the the Riak links from a domain object by looking for a + * {@literal @RiakLinks} annotated member. * * @param the domain object type + * @param container the RiakLinks container * @param domainObject the domain object * @return a Collection of RiakLink objects. */ @@ -236,7 +236,7 @@ public static RiakLinks getLinks(RiakLinks container, T domainObject) /** * Attempts to populate a domain object with riak links by looking for a - * {@link RiakLinks} annotated field or setter method. + * {@literal @RiakLinks} annotated member. * * @param the type of the domain object * @param links a collection of RiakLink objects @@ -250,9 +250,10 @@ public static T populateLinks(RiakLinks links, T domainObject) /** * Attempts to get the riak user metadata from a domain object by looking - * for a {@link RiakUsermeta} annotated field or getter method. + * for a {@literal @RiakUsermeta} annotated field or getter method. * * @param the type of the domain object + * @param metaContainer the RiakUserMetadata container * @param domainObject the domain object * @return a Map containing the user metadata. */ @@ -263,7 +264,7 @@ public static RiakUserMetadata getUsermetaData(RiakUserMetadata metaContaine /** * Attempts to populate a domain object with user metadata by looking for a - * {@link RiakUsermeta} annotated field or setter method. + * {@literal @RiakUsermeta} annotated member. * * @param the type of the domain object * @param usermetaData a Map of user metadata. diff --git a/src/main/java/com/basho/riak/client/convert/reflection/ClassUtil.java b/src/main/java/com/basho/riak/client/convert/reflection/ClassUtil.java index 3d14031fd..dd845eba4 100644 --- a/src/main/java/com/basho/riak/client/convert/reflection/ClassUtil.java +++ b/src/main/java/com/basho/riak/client/convert/reflection/ClassUtil.java @@ -18,11 +18,11 @@ import java.lang.reflect.InvocationTargetException; import java.lang.reflect.Method; /** - * Reflection/class utilities. Delegates to - * {@link org.codehaus.jackson.map.util.ClassUtil}. + * Reflection/class utilities. * * @author russell * @author Brian Roach + * @since 1.0 */ public final class ClassUtil { @@ -32,8 +32,9 @@ private ClassUtil() {} * Make the {@link Member} accessible if possible, throw * {@link IllegalArgumentException} is not. * - * @param member - * @throw {@link IllegalArgumentException} if cannot set accessibility + * @param member the member to check + * @return the member + * @throws IllegalArgumentException if cannot set accessibility */ public static T checkAndFixAccess(T member) { com.fasterxml.jackson.databind.util.ClassUtil.checkAndFixAccess(member); diff --git a/src/main/java/com/basho/riak/client/javadoc/JavadocFilter.java b/src/main/java/com/basho/riak/client/javadoc/JavadocFilter.java new file mode 100644 index 000000000..ab7f818a7 --- /dev/null +++ b/src/main/java/com/basho/riak/client/javadoc/JavadocFilter.java @@ -0,0 +1,119 @@ +package com.basho.riak.client.javadoc; + +import java.lang.reflect.Array; +import java.lang.reflect.InvocationHandler; +import java.lang.reflect.InvocationTargetException; +import java.lang.reflect.Method; +import java.lang.reflect.Proxy; +import java.util.ArrayList; +import java.util.List; + +import com.sun.javadoc.Doc; +import com.sun.javadoc.DocErrorReporter; +import com.sun.javadoc.LanguageVersion; +import com.sun.javadoc.ProgramElementDoc; +import com.sun.javadoc.RootDoc; +import com.sun.tools.doclets.standard.Standard; +import com.sun.tools.javadoc.Main; + +/** + * Used to decide what gets included/excluded in the Javadoc + *

+ *

  • It filters out all inner classes with "UnitTest" in their name.
    • + *
  • It filters out classes with @ExcludeFromJavadoc in the javadoc comment
    • + */ +public class JavadocFilter { + public static void main(String[] args) { + String name = JavadocFilter.class.getName(); + Main.execute(name, name, args); + } + + public static boolean validOptions(String[][] options, DocErrorReporter reporter) throws java.io.IOException { + return Standard.validOptions(options, reporter); + } + + public static LanguageVersion languageVersion() { + return LanguageVersion.JAVA_1_5; + } + + public static int optionLength(String option) { + return Standard.optionLength(option); + } + + public static boolean start(RootDoc root) throws java.io.IOException { + return Standard.start((RootDoc) process(root, RootDoc.class)); + } + + private static boolean exclude(Doc doc) { + if (doc.name().contains("UnitTest")) { + return true; + } else if (doc.tags("@ExcludeFromJavadoc").length > 0) { + return true; + } else if (doc instanceof ProgramElementDoc) { + if (((ProgramElementDoc) doc).containingPackage().tags("@ExcludeFromJavadoc").length > 0) + return true; + } + // nothing above found a reason to exclude + return false; + } + + private static Object process(Object obj, Class expect) { + if (obj == null) + return null; + Class cls = obj.getClass(); + if (cls.getName().startsWith("com.sun.")) { + return Proxy.newProxyInstance(cls.getClassLoader(), cls.getInterfaces(), new ExcludeHandler(obj)); + } else if (obj instanceof Object[]) { + Class componentType = expect.getComponentType(); + if (componentType == null) + { + componentType = Object.class; + } + Object[] array = (Object[]) obj; + List list = new ArrayList(array.length); + for (Object entry : array) + { + if ((entry instanceof Doc) && exclude((Doc) entry)) + continue; + list.add(process(entry, componentType)); + } + if (componentType == null) + { + System.out.println("Object: " + obj + "Expect: " + expect + " NULL; " + list); + + } + return list.toArray((Object[]) Array.newInstance(componentType, list.size())); + } else { + return obj; + } + } + + private static class ExcludeHandler implements InvocationHandler { + private final Object target; + + public ExcludeHandler(Object target) { + this.target = target; + } + + @Override + public Object invoke(Object proxy, Method method, Object[] args) throws Throwable { + if (args != null) { + String methodName = method.getName(); + if (methodName.equals("compareTo") || methodName.equals("equals") || methodName.equals("overrides") || methodName.equals("subclassOf")) { + args[0] = unwrap(args[0]); + } + } + try { + return process(method.invoke(target, args), method.getReturnType()); + } catch (InvocationTargetException e) { + throw e.getTargetException(); + } + } + + private Object unwrap(Object proxy) { + if (proxy instanceof Proxy) + return ((ExcludeHandler) Proxy.getInvocationHandler(proxy)).target; + return proxy; + } + } +} diff --git a/src/main/java/com/basho/riak/client/operations/StoreBucketProperties.java b/src/main/java/com/basho/riak/client/operations/StoreBucketProperties.java index 6e73ab359..feaee4c66 100644 --- a/src/main/java/com/basho/riak/client/operations/StoreBucketProperties.java +++ b/src/main/java/com/basho/riak/client/operations/StoreBucketProperties.java @@ -332,9 +332,7 @@ public Builder withBasicQuorum(boolean use) * * @param bigVClock a long representing a epoch time value. * @return a reference to this object. - * @see Vector - * Clock Pruning for details. + * @see Vector Clock Pruning */ public Builder withBigVClock(Long bigVClock) { @@ -477,9 +475,7 @@ public Builder withNotFoundOk(boolean ok) * * @param hook the Function to add. * @return a reference to this object. - * @see Using - * Commit Hooks + * @see Using Commit Hooks */ public Builder withPrecommitHook(Function hook) { @@ -497,9 +493,7 @@ public Builder withPrecommitHook(Function hook) * * @param hook the Function to add. * @return a reference to this object. - * @see Using - * Commit Hooks + * @see Using Commit Hooks */ public Builder withPostcommitHook(Function hook) { @@ -512,9 +506,7 @@ public Builder withPostcommitHook(Function hook) * * @param oldVClock an long representing a epoch time value. * @return a reference to this object. - * @see Vector - * Clock Pruning for details. + * @see Vector Clock Pruning */ public Builder withOldVClock(Long oldVClock) { @@ -527,9 +519,7 @@ public Builder withOldVClock(Long oldVClock) * * @param youngVClock a long representing a epoch time value. * @return a reference to this object. - * @see Vector - * Clock Pruning for details. + * @see Vector Clock Pruning */ public Builder withYoungVClock(Long youngVClock) { @@ -542,9 +532,7 @@ public Builder withYoungVClock(Long youngVClock) * * @param smallVClock a long representing a epoch time value. * @return a reference to this object. - * @see Vector - * Clock Pruning for details. + * @see Vector Clock Pruning */ public Builder withSmallVClock(Long smallVClock) { diff --git a/src/main/java/com/basho/riak/client/operations/kv/DeleteValue.java b/src/main/java/com/basho/riak/client/operations/kv/DeleteValue.java index c102eb33d..ef2744714 100644 --- a/src/main/java/com/basho/riak/client/operations/kv/DeleteValue.java +++ b/src/main/java/com/basho/riak/client/operations/kv/DeleteValue.java @@ -153,7 +153,7 @@ public static class Response { private final boolean deleted; - public Response(boolean deleted) + protected Response(boolean deleted) { this.deleted = deleted; } @@ -199,7 +199,7 @@ public Builder withVClock(VClock vClock) * @param option the option * @param value the value associated with the option * @param the type required by the option - * @return + * @return a reference to this object */ public Builder withOption(DeleteOption option, T value) { diff --git a/src/main/java/com/basho/riak/client/operations/kv/FetchValue.java b/src/main/java/com/basho/riak/client/operations/kv/FetchValue.java index ade98ce81..709d46fdf 100644 --- a/src/main/java/com/basho/riak/client/operations/kv/FetchValue.java +++ b/src/main/java/com/basho/riak/client/operations/kv/FetchValue.java @@ -32,7 +32,7 @@ /** - * Command used to fetch a value from Riak, referenced by its location. + * Command used to fetch a value from Riak. *

    * Fetching an object from Riak is a simple matter of supplying a {@link com.basho.riak.client.query.Location} * and executing the FetchValue operation. @@ -180,7 +180,7 @@ private FetchOperation buildCoreOperation() } /** - * A response from Riak containing results from a fetch operation. + * A response from Riak containing results from a FetchValue operation. *

    * The Response, unless marked not found or unchanged, will contain one or * more objects returned from Riak (all siblings are returned if present). @@ -225,6 +225,9 @@ public boolean isUnchanged() return unchanged; } + /** + * @ExcludeFromJavadoc + */ protected static abstract class Init> extends KvResponseBase.Init { private boolean notFound; @@ -282,13 +285,13 @@ public Builder(Location location) } /** - * Add an optional setting for this command. This will be passed along with the request to Riak to tell it how + * Add an optional setting for this command. + * This will be passed along with the request to Riak to tell it how * to behave when servicing the request. * - * @param option - * @param value - * @param - * @return + * @param option the option + * @param value the value for the option + * @return a reference to this object. */ public Builder withOption(FetchOption option, U value) { diff --git a/src/main/java/com/basho/riak/client/operations/kv/KvResponseBase.java b/src/main/java/com/basho/riak/client/operations/kv/KvResponseBase.java index 6cd2336e3..7b3bec4fd 100644 --- a/src/main/java/com/basho/riak/client/operations/kv/KvResponseBase.java +++ b/src/main/java/com/basho/riak/client/operations/kv/KvResponseBase.java @@ -229,6 +229,9 @@ private List convertValues(Converter converter) } + /** + * @ExcludeFromJavadoc + */ protected static abstract class Init> { private Location location; diff --git a/src/main/java/com/basho/riak/client/operations/kv/MultiFetch.java b/src/main/java/com/basho/riak/client/operations/kv/MultiFetch.java index 1a0a10a1d..59ee48354 100644 --- a/src/main/java/com/basho/riak/client/operations/kv/MultiFetch.java +++ b/src/main/java/com/basho/riak/client/operations/kv/MultiFetch.java @@ -42,24 +42,24 @@ /** * An operation to fetch multiple values from Riak *

    - * Riak itself does not support pipelining of requests. MutliFetch addresses this issue by using a threadpool to - * parallelize a set of fetch operations for a given set of keys. + * Riak itself does not support pipelining of requests. MutliFetch addresses this issue by using a thread to + * parallelize and manage a set of async fetch operations for a given set of keys. *

    *

    - * The result of executing this command is a {@code List} of {@link Future} objects, each one representing a single + * The result of executing this command is a {@code List} of {@link RiakFuture} objects, each one representing a single * fetch operation. The simplest use would be a loop where you iterate through and wait for them to complete: *

    * 

      * {@code
- * MultiFetch multifetch = ...;
- * MultiFetch.Response response = client.execute(multifetch);
+ * MultiFetch multifetch = ...;
+ * MultiFetch.Response response = client.execute(multifetch);
  * List myResults = new ArrayList();
- * for (Future> f : response)
+ * for (RiakFuture f : response)
  * {
  *     try
  *     {
- *          FetchValue.Response response = f.get();
- *          myResults.add(response.view().get(0));
+ *          FetchValue.Response response = f.get();
+ *          myResults.add(response.getValue(MyPojo.class));
  *     }
  *     catch (ExecutionException e)
  *     {
@@ -70,15 +70,8 @@
  *
    *

    *

    - * Thread Pool:
    - * The internal {@link ThreadPoolExecutor} is static; all multi-fetch operations performed by a single instance of the - * client use the same pool, unless overidden upon construction. This is to prevent resource starvation in the case of - * multiple simultaneous multi-fetch operations. Idle threads (including core threads) are timed out after 5 - * seconds. - *

    - * The defaults for {@code corePoolSize} is determined by the Java Runtime using: - *

    - * {@code Runtime.getRuntime().availableProcessors() * 2;} + * The maximum number of concurrent requests defaults to 10. This can be changed + * when constructing the operation. *

    *

    * Be aware that because requests are being parallelized performance is also @@ -217,7 +210,7 @@ public Builder addLocations(Iterable location) * parameter controls how many outstanding requests are allowed simultaneously. *

    * @param maxInFlight the max number of outstanding requests. - * @return + * @return a reference to this object. */ public Builder withMaxInFlight(int maxInFlight) { @@ -226,12 +219,12 @@ public Builder withMaxInFlight(int maxInFlight) } /** - * A {@see FetchOption} to use with each fetch operation + * A {@link FetchOption} to use with each fetch operation * * @param option an option * @param value the option's associated value * @param the type of the option's value - * @return this + * @return a reference to this object. */ public Builder withOption(FetchOption option, U value) { @@ -240,9 +233,9 @@ public Builder withOption(FetchOption option, U value) } /** - * Build a {@see MultiFetch} operation from this builder + * Build a {@link MultiFetch} operation from this builder * - * @return an initialized {@see MultiFetch} operation + * @return an initialized {@link MultiFetch} operation */ public MultiFetch build() { diff --git a/src/main/java/com/basho/riak/client/operations/kv/StoreValue.java b/src/main/java/com/basho/riak/client/operations/kv/StoreValue.java index e5c3b8861..f076a069a 100644 --- a/src/main/java/com/basho/riak/client/operations/kv/StoreValue.java +++ b/src/main/java/com/basho/riak/client/operations/kv/StoreValue.java @@ -203,6 +203,9 @@ public static class Response extends KvResponseBase super(builder); } + /** + * @ExcludeFromJavadoc + */ protected static abstract class Init> extends KvResponseBase.Init {} diff --git a/src/main/java/com/basho/riak/client/operations/kv/UpdateValue.java b/src/main/java/com/basho/riak/client/operations/kv/UpdateValue.java index e8ea8ff43..ff9198c09 100644 --- a/src/main/java/com/basho/riak/client/operations/kv/UpdateValue.java +++ b/src/main/java/com/basho/riak/client/operations/kv/UpdateValue.java @@ -200,6 +200,9 @@ public boolean wasUpdated() return wasUpdated; } + /** + * @ExcludeFromJavadoc + */ protected static abstract class Init> extends KvResponseBase.Init { private boolean wasUpdated; diff --git a/src/main/java/com/basho/riak/client/operations/kv/package-info.java b/src/main/java/com/basho/riak/client/operations/kv/package-info.java new file mode 100644 index 000000000..d51e993cf --- /dev/null +++ b/src/main/java/com/basho/riak/client/operations/kv/package-info.java @@ -0,0 +1,4 @@ +/** + * Operations for storing, fetching, and deleting objects. + * */ +package com.basho.riak.client.operations.kv; \ No newline at end of file diff --git a/src/main/java/com/basho/riak/client/query/Location.java b/src/main/java/com/basho/riak/client/query/Location.java index a4b7251c4..ad2d86e86 100644 --- a/src/main/java/com/basho/riak/client/query/Location.java +++ b/src/main/java/com/basho/riak/client/query/Location.java @@ -38,6 +38,10 @@ */ public final class Location { + /** + * The default bucket type used if none is suppled. + * The value is "default" + */ public static final BinaryValue DEFAULT_BUCKET_TYPE = BinaryValue.create("default", Charset.forName("UTF-8")); diff --git a/src/main/java/com/basho/riak/client/query/links/RiakLinks.java b/src/main/java/com/basho/riak/client/query/links/RiakLinks.java index d8f52bebb..5165bda7a 100644 --- a/src/main/java/com/basho/riak/client/query/links/RiakLinks.java +++ b/src/main/java/com/basho/riak/client/query/links/RiakLinks.java @@ -108,7 +108,7 @@ public void removeAllLinks() *

    * Changes to the returned set do not modify this container. *

    - * @return + * @return the set of RiakLink objects */ public Set getLinks() {