Add more docs about equality and keys to BitmapTransformation.

bumptech · Dec 7, 2017 · 07ae4f7 · 07ae4f7
1 parent 06ba344
commit 07ae4f7
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 5 deletions.
diff --git a/library/src/main/java/com/bumptech/glide/load/Transformation.java b/library/src/main/java/com/bumptech/glide/load/Transformation.java
@@ -2,18 +2,26 @@
 
 import android.content.Context;
 import com.bumptech.glide.load.engine.Resource;
+import java.nio.charset.Charset;
+import java.security.MessageDigest;
 
 /**
  * A class for performing an arbitrary transformation on a resource that implements
  * {@link #equals(Object)} and {@link #hashCode()}} to identify the transformation in the memory
  * cache and {@link #updateDiskCacheKey(java.security.MessageDigest)}} to identify the
  * transformation in disk caches.
  *
- * <p>Using the fully qualified class name (not {@link Class#getName()} to avoid proguard
- * obfuscation) is an easy way to implement
- * {@link #updateDiskCacheKey(java.security.MessageDigest)}} correctly.
+ * <p>Using the fully qualified class name as a static final {@link String} (not
+ * {@link Class#getName()} to avoid proguard obfuscation) is an easy way to implement
+ * {@link #updateDiskCacheKey(java.security.MessageDigest)}} correctly. If additional arguments are
+ * required they can be passed in to the constructor of the {@code Transformation} and then used to
+ * update the {@link java.security.MessageDigest} passed in to
+ * {@link #updateDiskCacheKey(MessageDigest)}. If arguments are primitive types, they can typically
+ * easily be serialized using {@link java.nio.ByteBuffer}. {@link String} types can be serialized
+ * with {@link String#getBytes(Charset)} using the constant {@link #CHARSET}.
  *
- * <p>Implementations <em>must</em> implement {@link #equals(Object)} and {@link #hashCode()}.
+ * <p>Implementations <em>must</em> implement {@link #equals(Object)} and {@link #hashCode()} for
+ * memory caching to work correctly.
  *
  * @param <T> The type of the resource being transformed.
  */

diff --git a/library/src/main/java/com/bumptech/glide/load/resource/bitmap/BitmapTransformation.java b/library/src/main/java/com/bumptech/glide/load/resource/bitmap/BitmapTransformation.java
@@ -9,6 +9,8 @@
 import com.bumptech.glide.load.engine.bitmap_recycle.BitmapPool;
 import com.bumptech.glide.request.target.Target;
 import com.bumptech.glide.util.Util;
+import java.nio.charset.Charset;
+import java.security.MessageDigest;
 
 /**
  * A simple {@link com.bumptech.glide.load.Transformation} for transforming
@@ -18,7 +20,7 @@
  * Use cases will look something like this:
  * <pre>
  * <code>
- * public class FillSpace extends BaseBitmapTransformation {
+ * public class FillSpace extends BitmapTransformation {
  *     private static final String ID = "com.bumptech.glide.transformations.FillSpace";
  *     private static final String ID_BYTES = ID.getBytes(STRING_CHARSET_NAME);
  *
@@ -49,6 +51,18 @@
  * }
  * </code>
  * </pre>
+ *
+ * <p>Using the fully qualified class name as a static final {@link String} (not
+ * {@link Class#getName()} to avoid proguard obfuscation) is an easy way to implement
+ * {@link #updateDiskCacheKey(java.security.MessageDigest)}} correctly. If additional arguments are
+ * required they can be passed in to the constructor of the {@code Transformation} and then used to
+ * update the {@link java.security.MessageDigest} passed in to
+ * {@link #updateDiskCacheKey(MessageDigest)}. If arguments are primitive types, they can typically
+ * easily be serialized using {@link java.nio.ByteBuffer}. {@link String} types can be serialized
+ * with {@link String#getBytes(Charset)} using the constant {@link #CHARSET}.
+ *
+ * <p>As with all {@link Transformation}s, all subclasses <em>must</em> implement
+ * {@link #equals(Object)} and {@link #hashCode()} for memory caching to work correctly.
  */
 public abstract class BitmapTransformation implements Transformation<Bitmap> {