Merge branch 'feature/composite-key' of https://github.com/oracle/nosql-spring-sdk into feature/composite-key

Author: Akshay-Sundarraj

src/main/java/com/oracle/nosql/spring/data/core/mapping/NosqlId.java

@@ -16,13 +16,20 @@
 /**
  * Identifies the primary key field of the entity. Primary key can be of a
  * basic type or of a type that represents a composite primary key. This
- * field corresponds to the {@literal PRIMARY KEY} of the corresponding Nosql
+ * field corresponds to the {@code PRIMARY KEY} of the corresponding Nosql
  * table. Only one field of the entity can be annotated with this annotation.
+ *
+ * If using a composite primary key, the fields comprising the composite key
+ * must have distinct names when viewed in lower case, otherwise an error is
+ * raised.
  */
-
 @Id
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 public @interface NosqlId {
+    /**
+     * Specifies if values for the field are automatically generated. Valid only
+     * for int, Integer, long, Long, BigInteger, BigDecimal,
+     */
     boolean generated() default false;
 }

src/main/java/com/oracle/nosql/spring/data/core/mapping/NosqlKey.java

@@ -17,69 +17,66 @@
 import static com.oracle.nosql.spring.data.Constants.NOTSET_SHARD_KEY;
 
 /**
- * Identifies the annotated field as a primary key of the composite
- * primary key.
- * Order of the primary keys are crucial for distribution of data, it
- * is recommended to provide both shard and order elements with this
- * annotation.
+ * Identifies the annotated field as a component of the composite
+ * primary key.<p>
+ *
+ * Order of the fields affects index selection on queries, and
+ * data distribution. Query performance is improved when field 1
+ * through field N appears as query predicates where N is less than
+ * or equal to the total fields in the composite key.<p>
+ *
+ * It is recommended to provide both {@code shardKey} and {@code order} options
+ * with this annotation.
  * <pre>
- *     Example:
+ *     Example creating the composite key (country, city, street):
  *     class CompositeKey {
- *          &#64;NosqlKey(shardKey=true, order = 1)
- *          private String city;
+ *          &#64;NosqlKey(shardKey = true, order = 1)
+ *          private String country;
  *
  *          &#64;NosqlKey(shardKey = false, order = 2)
- *          private String area;
+ *          private String city;
+ *
+ *          &#64;NosqlKey(shardKey = false, order = 3)
+ *          private String street;
  *     }
  * </pre>
- *   @since 1.6.0
+ * Queries using country, or country and city, or country and city and street
+ * as filtering predicates are faster than queries specifying only street.
+ *
+ * @since 1.6.0
  */
-
 @Documented
 @Retention(value = RetentionPolicy.RUNTIME)
 @Target(value = {ElementType.ANNOTATION_TYPE, ElementType.FIELD,
         ElementType.METHOD})
 public @interface NosqlKey {
     /**
-     * Specifies whether the field is shard key or not. Default value is
-     * {@link com.oracle.nosql.spring.data.Constants#NOTSET_SHARD_KEY}.
-     *
+     * Specifies whether the field is part of the shard key or not. Default value
+     * is {@link com.oracle.nosql.spring.data.Constants#NOTSET_SHARD_KEY}.
+     * Shard keys affect distribution of rows across shards and atomicity of
+     * operations on a single shard.
      * @since 1.6.0
      */
     boolean shardKey() default NOTSET_SHARD_KEY;
 
     /**
-     * Specifies the order of this primary key related to other primary keys
-     * of composite key class.
+     * Specifies the order of the field related to other fields with the same
+     * shardKey value listed in the composite key class.<p>
      * This ordering is used in table creation DDL to specify PRIMARY KEY and
-     * SHARD KEY ordering.
-     * Ordering is done based on below rules.
-     * <ul>
-     *  <li>SHARD KEYS are placed before non SHARD KEYS.</li>
-     *  <li>For each SHARD and non SHARD group</li>
-     *  <li>
-     *  <ul>
-     *     <li>
-     *         If order is specified it must be specified on all the fields
-     *     otherwise it is an error.
-     *     </li>
-     *     <li>
-     *          If order is specified it must be unique otherwise it is an
-     *          error.
-     *     </li>
-     *     <li>
-     *         If no order is specified then fields are sorted by lower case
-     *         alphabetical order of the field names
-     *     </li>
-     *   </ul>
-     *   </li>
-     * </ul>
+     * SHARD KEY ordering.<p>
+     * Ordering is done based on below rules:<ul><li>
+     *     Shard keys are placed at the beginning.</li><li>
+     *     When using the <code>order</code> option:<ul><li>
+     *         It must be specified on all the fields otherwise it is an error.
+     *           </li><li>
+     *         It must be unique otherwise it is an error.</li></ul></li><li>
+     *     If {@code order} is not specified then fields are sorted
+     *     alphabetically using lower case field names for fields grouped by the
+     *     same shardKey value.</li></ul><p>
      * Default value is
      * {@link com.oracle.nosql.spring.data.Constants#NOTSET_PRIMARY_KEY_ORDER}
      *
      * @since 1.6.0
      */
-
     int order() default NOTSET_PRIMARY_KEY_ORDER;
-
 }