IGNITE-28475 Document CacheInterceptor interaction with keepBinary cache wrapper (#13002)

Author: zstan

docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/WorkingWithBinaryObjects.java

@@ -142,6 +142,45 @@ public static void configuringBinaryObjects() {
 
     }
 
+    //tag::keepBinaryWithCacheInterceptor[]
+    public static void cacheWithInterceptorExample() {
+        try (Ignite ignite = Ignition.start()) {
+            CacheConfiguration specConfig = new CacheConfiguration("personSpecCache");
+            ccfg.setInterceptor(new CustomInterceptor(false));
+            IgniteCache<Integer, Person> cache = ignite.createCache(ccfg);
+            cache.put(1, new Person(1, "FirstPerson"));
+
+            CacheConfiguration boConfig = new CacheConfiguration("boSpecCache");
+            ccfg.setInterceptor(new CustomInterceptor(true));
+            IgniteCache<Integer, Person> cache = ignite.createCache(ccfg);
+            cache = cache.withKeepBinary();
+            cache.put(1, new Person(1, "FirstPerson"));
+        }
+    }
+
+    private static class CustomInterceptor implements CacheInterceptor<Object, Object> {
+        boolean keepBinary;
+
+        CustomInterceptor(boolean keepBinary) {
+            this.keepBinary = keepBinary;
+        }
+
+        @Nullable @Override public Object onBeforePut(Cache.Entry<Object, Object> entry, Object newVal) {
+            assert keepBinary == newVal instanceof BinaryObject;
+            // do smth.
+        }
+
+        @Nullable @Override public IgniteBiTuple<Boolean, Object> onBeforeRemove(Cache.Entry<Object, Object> entry) {
+            Object val = entry.getValue();
+
+            if (val != null) {
+                assert keepBinary == entry.getValue() instanceof BinaryObject;
+            }
+            // do smth.
+        }
+    }
+    //end::keepBinaryWithCacheInterceptor[]
+
     private static class MyBinaryNameMapper implements BinaryNameMapper {
 
         @Override

docs/_docs/key-value-api/binary-objects.adoc

@@ -71,6 +71,21 @@ The following classes are never converted (e.g., the `toBinary(Object)` method r
 * `Enums` and array of enums
 * Maps, collections and arrays of objects (but the objects inside them are reconverted if they are binary)
 
+`CacheInterceptor` also take into account cache `keepBinary` mode and process a value appropriately.
+
+[tabs]
+--
+tab:Java[]
+[source,java]
+----
+include::{javaCodeDir}/WorkingWithBinaryObjects.java[tag=keepBinaryWithCacheInterceptor,indent=0]
+----
+
+tab:C#/.NET[unsupported]
+
+tab:C++[unsupported]
+--
+
 tab:C#/.NET[]
 [source,csharp]
 ----
@@ -177,7 +192,6 @@ tab:C#/.NET[unsupported]
 tab:C++[unsupported]
 --
 
-
 == Recommendations on Binary Objects Tuning
 
 Ignite keeps a _schema_ for every  Binary Object of a given type, which specifies the fields present in the object as well as their order and types.

modules/core/src/main/java/org/apache/ignite/cache/CacheInterceptor.java

@@ -33,6 +33,9 @@
  * Cache interceptor is configured via {@link CacheConfiguration#getInterceptor()}
  * configuration property.
  * <p>
+ * The type of incoming values depends on cache operation context, that is, the {@link IgniteCache#withKeepBinary()}
+ * is taken into account.
+ * <p>
  * Any grid resource from {@code org.apache.ignite.resources} package can be injected
  * into implementation of this interface.
  */