Improve wording around need of SaveBehavior.CLOBBER

Author: SalusaSecondus

README.md

@@ -3,7 +3,8 @@
 The **[Amazon DynamoDB][ddb] Client-side Encryption in Java** supports encryption and signing of your data when stored in Amazon DynamoDB.
 
 A typical use of this library is when you are using [DynamoDBMapper][ddbmapper], where transparent protection of all objects serialized through the mapper can be enabled via configuring an [AttributeEncryptor][attrencryptor].
-**Please note that it is critically important that you use `SaveBehavior.CLOBBER` when using AttributeEncryptor.**
+
+> Important: Use `SaveBehavior.CLOBBER` with `AttributeEncryptor`. If you do not do so you risk corrupting your signatures and encrypted data.
 
 For more advanced use cases where tighter control over the encryption and signing process is necessary, the low-level [DynamoDBEncryptor][ddbencryptor] can be used directly.
 
@@ -75,7 +76,7 @@ To enable transparent encryption and signing, simply specify the necessary encry
     SecretKey cek = ...;        // Content encrypting key
     SecretKey macKey =  ...;    // Signing key
     EncryptionMaterialsProvider provider = new SymmetricStaticProvider(cek, macKey);
-    mapper = new DynamoDBMapper(client, DynamoDBMapperConfig.DEFAULT,
+    mapper = new DynamoDBMapper(client, DynamoDBMapperConfig.builder().withSaveBehavior(SaveBehavior.CLOBBER).build(),
                 new AttributeEncryptor(provider));
     Book book = new Book();
     book.setId(123);

examples/com/amazonaws/examples/AwsKmsEncryptedObject.java

@@ -52,7 +52,7 @@ public static void encryptRecord(final String cmkArn, final String region) {
     // Encryptor creation
     final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp);
     // Mapper Creation
-    // Please note the use of SaveBehavior.CLOBBER. Omitting this may result in data-corruption.
+    // Please note the use of SaveBehavior.CLOBBER. Omitting this can result in data-corruption.
     DynamoDBMapperConfig mapperConfig = DynamoDBMapperConfig.builder().withSaveBehavior(SaveBehavior.CLOBBER).build();
     DynamoDBMapper mapper = new DynamoDBMapper(ddb, mapperConfig, new AttributeEncryptor(encryptor));
 

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

@@ -38,8 +38,8 @@
 
 /**
  * Encrypts all non-key fields prior to storing them in DynamoDB.
- * <em>It is critically important that this is only used with @{link SaveBehavior#CLOBBER}. Use of
- * any other @{code SaveBehavior} may result in data-corruption.</em>
+ * <em>This must be used with @{link SaveBehavior#CLOBBER}. Use of
+ * any other @{code SaveBehavior} can result in data-corruption.</em>
  * 
  * @author Greg Rubin 
  */
@@ -66,12 +66,14 @@ public Map<String, AttributeValue> transform(final Parameters<?> parameters) {
         final ModelClassMetadata metadata = getModelClassMetadata(parameters);
 
         final Map<String, AttributeValue> attributeValues = parameters.getAttributeValues();
+        // If this class is marked as "DoNotTouch" then we know our encryptor will not change it at all
+        // so we may as well fast-return and do nothing. This also avoids emitting errors when they would not apply.
         if (metadata.doNotTouch) {
             return attributeValues;
         }
 
         if (parameters.isPartialUpdate()) {
-            LOG.error("Use of AttributeEncryptor without SaveBehavior.CLOBBER is an error and may result in data-corruption. " +
+            LOG.error("Use of AttributeEncryptor without SaveBehavior.CLOBBER is an error and can result in data-corruption. " +
                     "This occured while trying to save " + parameters.getModelClass());
         }