fix: Data model migration doc breadcrumb.

Merge pull request #139 from lizroth/migration-doc-note

Author: lizroth

.gitignore

@@ -3,3 +3,4 @@ release.sh
 target
 .idea/
 *.iml
+.DS_Store

README.md

@@ -111,6 +111,18 @@ Note that by default all attributes except the primary keys are both encrypted a
 
 There is a variety of existing [EncryptionMaterialsProvider][materialprovider] implementations that you can use to provide the encryption material, including [KeyStoreMaterialsProvider][keystoreprovider] which makes use of a Java keystore.  Alternatively, you can also plug in your own custom implementation.
 
+### Changing Your Data Model
+
+Every time you encrypt or decrypt an item, you need to provide attribute actions that tell the DynamoDB Encryption
+Client which attributes to encrypt and sign, which attributes to sign (but not encrypt), and which to ignore. Attribute
+actions are not saved in the encrypted item and the DynamoDB Encryption Client does not update your attribute actions
+automatically.
+
+Whenever you change your data model, that is, when you add or remove attributes from your table items, you need to take
+additional steps to safely migrate the client-side encryption configuration.
+
+For guidance on this process, please see the developer guide on [Changing Your Data Model](https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/data-model.html).
+
 ### Downloads
 
 You can download the [latest snapshot release][download] or pick it up from Maven:

sdk1/src/main/java/com/amazonaws/services/dynamodbv2/datamodeling/AttributeEncryptor.java

@@ -38,9 +38,13 @@
 
 /**
  * Encrypts all non-key fields prior to storing them in DynamoDB.
- * <em>This must be used with @{link SaveBehavior#PUT} or @{link SaveBehavior#CLOBBER}.</em>
- * 
- * @author Greg Rubin 
+ * <em>This must be used with {@link SaveBehavior#PUT} or {@link SaveBehavior#CLOBBER}.</em>
+ *
+ * <p>For guidance on performing a safe data model change procedure, please see
+ * <a href="https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/data-model.html" target="_blank">
+ * DynamoDB Encryption Client Developer Guide: Changing your data model</a></p>
+ *
+ *  @author Greg Rubin
  */
 public class AttributeEncryptor implements AttributeTransformer {
     private static final Log LOG = LogFactory.getLog(AttributeEncryptor.class);

sdk1/src/main/java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DoNotEncrypt.java

@@ -23,7 +23,11 @@
 
 /**
  * Prevents the associated item (class or attribute) from being encrypted.
- * 
+ *
+ * <p>For guidance on performing a safe data model change procedure, please see
+ * <a href="https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/data-model.html" target="_blank">
+ * DynamoDB Encryption Client Developer Guide: Changing your data model</a></p>
+ *
  * @author Greg Rubin 
  */
 @DynamoDB

sdk1/src/main/java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DoNotTouch.java

@@ -23,6 +23,10 @@
 
 /**
  * Prevents the associated item from being encrypted or signed.
+ *
+ * <p>For guidance on performing a safe data model change procedure, please see
+ * <a href="https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/data-model.html" target="_blank">
+ * DynamoDB Encryption Client Developer Guide: Changing your data model</a></p>
  * 
  * @author Greg Rubin 
  */

sdk1/src/main/java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.java

@@ -50,7 +50,11 @@
 /**
  * The low-level API used by {@link AttributeEncryptor} to perform crypto
  * operations on the record attributes.
- * 
+ *
+ * <p>For guidance on performing a safe data model change procedure, please see
+ * <a href="https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/data-model.html" target="_blank">
+ * DynamoDB Encryption Client Developer Guide: Changing your data model</a></p>
+ *
  * @author Greg Rubin 
  */
 public class DynamoDBEncryptor {

sdk1/src/main/java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBSigner.java

@@ -43,6 +43,10 @@
 import com.amazonaws.services.dynamodbv2.model.AttributeValue;
 
 /**
+ * <p>For guidance on performing a safe data model change procedure, please see
+ * <a href="https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/data-model.html" target="_blank">
+ * DynamoDB Encryption Client Developer Guide: Changing your data model</a></p>
+ *
  * @author Greg Rubin 
  */
 // NOTE: This class must remain thread-safe.

sdk1/src/main/java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/HandleUnknownAttributes.java

@@ -30,8 +30,12 @@
  * attributes will only be included in the signature calculation, and if it's
  * added to a class with default encryption behavior, the unknown attributes
  * will be signed and decrypted.
+ *
+ * <p>For guidance on performing a safe data model change procedure, please see
+ * <a href="https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/data-model.html" target="_blank">
+ * DynamoDB Encryption Client Developer Guide: Changing your data model</a></p>
  * 
- * @author Dan Cavallaro 
+ * @author Dan Cavallaro
  */
 @Target(value = {ElementType.TYPE})
 @Retention(value = RetentionPolicy.RUNTIME)

sdk1/src/main/java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/TableAadOverride.java

@@ -24,6 +24,10 @@
  * {@code tableName} instead. This can be useful when multiple tables are
  * used interchangably and data should be able to be copied or moved
  * between them without needing to be reencrypted.
+ *
+ * <p>For guidance on performing a safe data model change procedure, please see
+ * <a href="https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/data-model.html" target="_blank">
+ * DynamoDB Encryption Client Developer Guide: Changing your data model</a></p>
  * 
  * @author Greg Rubin 
  */

sdk1/src/test/java/com/amazonaws/services/dynamodbv2/datamodeling/TransformerHolisticIT.java

@@ -397,7 +397,7 @@ public void simpleSaveLoad() {
 
     /**
      * This test ensures that optimistic locking can be successfully done through the {@link DynamoDBMapper} when
-     * combined with the @{link AttributeEncryptor}. Specifically it checks that {@link SaveBehavior#PUT} properly
+     * combined with the {@link AttributeEncryptor}. Specifically it checks that {@link SaveBehavior#PUT} properly
      * enforces versioning and will result in a {@link ConditionalCheckFailedException} when optimistic locking should
      * prevent a write. Finally, it checks that {@link SaveBehavior#CLOBBER} properly ignores optimistic locking and
      * overwrites the old value.