refactor: rename wrapper spec methods with postfix _, avoid naming …

…conflict with biz methods 👓

README.md

@@ -80,7 +80,7 @@ public class ChattyExecutorWrapper implements Executor, Wrapper<Executor> {
   }
 
   @Override
-  public Executor unwrap() {
+  public Executor unwrap_() {
     return executor;
   }
 }
@@ -102,20 +102,20 @@ public class LazyExecutorWrapper implements Executor, Wrapper<Executor>, Attacha
   }
 
   @Override
-  public Executor unwrap() {
+  public Executor unwrap_() {
     return executor;
   }
 
   private final Attachable<String, String> attachable = new AttachableDelegate<>();
 
   @Override
-  public void setAttachment(String key, String value) {
-    attachable.setAttachment(key, value);
+  public void setAttachment_(String key, String value) {
+    attachable.setAttachment_(key, value);
   }
 
   @Override
-  public String getAttachment(String key) {
-    return attachable.getAttachment(key);
+  public String getAttachment_(String key) {
+    return attachable.getAttachment_(key);
   }
 }
 ```
@@ -154,7 +154,7 @@ public class Demo {
     final Executor base = Runnable::run;
 
     final LazyExecutorWrapper lazy = new LazyExecutorWrapper(base);
-    lazy.setAttachment("busy", "very, very busy!");
+    lazy.setAttachment_("busy", "very, very busy!");
 
     return new ChattyExecutorWrapper(lazy);
   }
@@ -231,7 +231,7 @@ public class IntegrationDemo {
   private static ExistedExecutorWrapperAdapter createExistedExecutorWrapperAdapter(Executor base) {
     final ExistedExecutorWrapper existed = new ExistedExecutorWrapper(base);
     final ExistedExecutorWrapperAdapter adapter = new ExistedExecutorWrapperAdapter(base, existed);
-    adapter.setAttachment("adapted-existed-executor-wrapper-msg", "I'm an adapter of an existed executor which have nothing to do with ~inspectable~wrappers~.");
+    adapter.setAttachment_("adapted-existed-executor-wrapper-msg", "I'm an adapter of an existed executor which have nothing to do with ~inspectable~wrappers~.");
     return adapter;
   }
 
@@ -248,12 +248,12 @@ public class IntegrationDemo {
     }
 
     @Override
-    public Executor unwrap() {
+    public Executor unwrap_() {
       return base;
     }
 
     @Override
-    public Executor adaptee() {
+    public Executor adaptee_() {
       return adaptee;
     }
 
@@ -265,14 +265,14 @@ public class IntegrationDemo {
     private final Attachable<String, String> attachable = new AttachableDelegate<>();
 
     @Override
-    public void setAttachment(String key, String value) {
-      attachable.setAttachment(key, value);
+    public void setAttachment_(String key, String value) {
+      attachable.setAttachment_(key, value);
     }
 
     @Nullable
     @Override
-    public String getAttachment(String key) {
-      return attachable.getAttachment(key);
+    public String getAttachment_(String key) {
+      return attachable.getAttachment_(key);
     }
   }
 }
@@ -329,7 +329,7 @@ public class IntegrationDemoUsingWrapperAdapterUtils {
     final Executor existed = new ExistedExecutorWrapper(base);
 
     Attachable<String, String> attachable = new AttachableDelegate<>();
-    attachable.setAttachment("adapted-existed-executor-wrapper-msg", "I'm an adapter of an existed executor which have nothing to do with ~inspectable~wrappers~.");
+    attachable.setAttachment_("adapted-existed-executor-wrapper-msg", "I'm an adapter of an existed executor which have nothing to do with ~inspectable~wrappers~.");
 
     return WrapperAdapterUtils.createWrapperAdapter(Executor.class, base, existed, attachable);
   }

src/main/java/io/foldright/inspectablewrappers/Attachable.java

@@ -29,7 +29,7 @@ public interface Attachable<K, V> {
      * @param value the attachment value
      * @throws NullPointerException if any arguments is null
      */
-    void setAttachment(@NonNull K key, @NonNull V value);
+    void setAttachment_(@NonNull K key, @NonNull V value);
 
     /**
      * Gets the attachment value for the given key.
@@ -41,5 +41,5 @@ public interface Attachable<K, V> {
      * @see Inspector#getAttachmentFromWrapperChain(Object, Object)
      */
     @Nullable
-    V getAttachment(@NonNull K key);
+    V getAttachment_(@NonNull K key);
 }

src/main/java/io/foldright/inspectablewrappers/Inspector.java

@@ -78,15 +78,15 @@ public final class Inspector {
      * Reports whether any instance on the wrapper chain matches the given type.
      * <p>
      * The wrapper chain consists of wrapper itself, followed by the wrappers
-     * obtained by repeatedly calling {@link Wrapper#unwrap()}.
+     * obtained by repeatedly calling {@link Wrapper#unwrap_()}.
      *
      * @param wrapper      wrapper instance/wrapper chain
      * @param instanceType target type
      * @param <W>          the type of instances that be wrapped
      * @return return {@code false} if no wrapper on the wrapper chain matches the given type,
      * otherwise return {@code true}
      * @throws NullPointerException  if any arguments is null,
-     *                               or any wrapper {@link Wrapper#unwrap()} returns null,
+     *                               or any wrapper {@link Wrapper#unwrap_()} returns null,
      *                               or the adaptee of {@link WrapperAdapter} is null
      * @throws IllegalStateException if the adaptee of {@link WrapperAdapter} is an instance of {@link Wrapper}
      *                               or CYCLIC wrapper chain
@@ -104,10 +104,10 @@ private static boolean isInstanceOf(final Object o, final Class<?> clazz) {
 
     /**
      * Retrieves the attachment of instance on the wrapper chain for the given key
-     * by calling {@link Attachable#getAttachment(Object)}.
+     * by calling {@link Attachable#getAttachment_(Object)}.
      * <p>
      * The wrapper chain consists of wrapper itself, followed by the wrappers
-     * obtained by repeatedly calling {@link Wrapper#unwrap()}.
+     * obtained by repeatedly calling {@link Wrapper#unwrap_()}.
      * <p>
      * If the same key exists in multiple wrappers, outer wrapper win.
      *
@@ -119,12 +119,12 @@ private static boolean isInstanceOf(final Object o, final Class<?> clazz) {
      * @return the attachment value of wrapper for given key on the wrapper chain,
      * or null if the attachment is absent
      * @throws NullPointerException  if any arguments is null,
-     *                               or any wrapper {@link Wrapper#unwrap()} returns null,
+     *                               or any wrapper {@link Wrapper#unwrap_()} returns null,
      *                               or the adaptee of {@link WrapperAdapter} is null
      * @throws ClassCastException    if the return value is not type {@code <V>}
      * @throws IllegalStateException if the adaptee of {@link WrapperAdapter} is an instance of {@link Wrapper}
      *                               or CYCLIC wrapper chain
-     * @see Attachable#getAttachment(Object)
+     * @see Attachable#getAttachment_(Object)
      */
     @Nullable
     @Contract(pure = true)
@@ -134,7 +134,7 @@ public static <W, K, V> V getAttachmentFromWrapperChain(final W wrapper, final K
         requireNonNull(key, "key is null");
         return travelWrapperChain(wrapper, w -> {
             if (w instanceof Attachable) {
-                V value = ((Attachable<K, V>) w).getAttachment(key);
+                V value = ((Attachable<K, V>) w).getAttachment_(key);
                 return Optional.ofNullable(value);
             } else {
                 return Optional.empty();
@@ -146,12 +146,12 @@ public static <W, K, V> V getAttachmentFromWrapperChain(final W wrapper, final K
      * Gets the wrapper chain, aka. the list of all instances on the wrapper chain.
      * <p>
      * The wrapper chain consists of wrapper itself, followed by the wrappers
-     * obtained by repeatedly calling {@link Wrapper#unwrap()}.
+     * obtained by repeatedly calling {@link Wrapper#unwrap_()}.
      *
      * @param wrapper wrapper instance
      * @param <W>     the type of instances that be wrapped
      * @throws NullPointerException  if wrapped argument is null,
-     *                               or any wrapper {@link Wrapper#unwrap()} returns null,
+     *                               or any wrapper {@link Wrapper#unwrap_()} returns null,
      *                               or the adaptee of {@link WrapperAdapter} is null
      * @throws IllegalStateException if the adaptee of {@link WrapperAdapter} is an instance of {@link Wrapper}
      *                               or CYCLIC wrapper chain
@@ -168,12 +168,12 @@ public static <W> List<W> getInstancesOfWrapperChain(final W wrapper) {
      * Gets the base of the wrapper chain, aka. the last instance of the wrapper chain.
      * <p>
      * The wrapper chain consists of wrapper itself, followed by the wrappers
-     * obtained by repeatedly calling {@link Wrapper#unwrap()}.
+     * obtained by repeatedly calling {@link Wrapper#unwrap_()}.
      *
      * @param wrapper wrapper instance
      * @param <W>     the type of instances that be wrapped
      * @throws NullPointerException  if wrapped argument is null,
-     *                               or any wrapper {@link Wrapper#unwrap()} returns null,
+     *                               or any wrapper {@link Wrapper#unwrap_()} returns null,
      *                               or the adaptee of {@link WrapperAdapter} is null
      * @throws IllegalStateException if the adaptee of {@link WrapperAdapter} is an instance of {@link Wrapper}
      *                               or CYCLIC wrapper chain
@@ -193,12 +193,12 @@ public static <W> W getBaseOfWrapperChain(final W wrapper) {
      * This method is {@code null}-safe, return {@code null} iff input parameter is {@code null};
      * If input parameter is not a {@link Wrapper} just return input.
      * <p>
-     * A convenience method for {@link Wrapper#unwrap()}
+     * A convenience method for {@link Wrapper#unwrap_()}
      *
      * @param obj wrapper instance
      * @param <W> the type of instances that be wrapped
-     * @throws NullPointerException if {@link Wrapper#unwrap()} returns null
-     * @see Wrapper#unwrap()
+     * @throws NullPointerException if {@link Wrapper#unwrap_()} returns null
+     * @see Wrapper#unwrap_()
      * @see #isWrapper(Object)
      */
     @Nullable
@@ -226,18 +226,18 @@ public static boolean isWrapper(@Nullable Object obj) {
      * Verifies the compliance of wrapper chain with the specification contracts.
      * <p>
      * The wrapper chain consists of wrapper itself, followed by the wrappers
-     * obtained by repeatedly calling {@link Wrapper#unwrap()}.
+     * obtained by repeatedly calling {@link Wrapper#unwrap_()}.
      * <p>
      * more about the specification contracts see the doc of below methods:
      * <ul>
-     * <li>{@link Wrapper#unwrap()}
-     * <li>{@link WrapperAdapter#adaptee()}
+     * <li>{@link Wrapper#unwrap_()}
+     * <li>{@link WrapperAdapter#adaptee_()}
      * </ul>
      *
      * @param wrapper wrapper instance
      * @param <W>     the type of instances that be wrapped
      * @throws NullPointerException  if wrapped argument is null,
-     *                               or any wrapper {@link Wrapper#unwrap()} returns null,
+     *                               or any wrapper {@link Wrapper#unwrap_()} returns null,
      *                               or the adaptee of {@link WrapperAdapter} is null
      * @throws IllegalStateException if the adaptee of {@link WrapperAdapter} is an instance of {@link Wrapper}
      *                               or CYCLIC wrapper chain
@@ -251,18 +251,18 @@ public static <W> void verifyWrapperChainContracts(final W wrapper) {
      * and checks all instances on wrapper chain is an instance of the given {@code bizInterface}.
      * <p>
      * The wrapper chain consists of wrapper itself, followed by the wrappers
-     * obtained by repeatedly calling {@link Wrapper#unwrap()}.
+     * obtained by repeatedly calling {@link Wrapper#unwrap_()}.
      * <p>
      * more about the specification contracts see the doc of below methods:
      * <ul>
-     * <li>{@link Wrapper#unwrap()}
-     * <li>{@link WrapperAdapter#adaptee()}
+     * <li>{@link Wrapper#unwrap_()}
+     * <li>{@link WrapperAdapter#adaptee_()}
      * </ul>
      *
      * @param wrapper wrapper instance
      * @param <W>     the type of instances that be wrapped
      * @throws NullPointerException  if any arguments is null,
-     *                               or any wrapper {@link Wrapper#unwrap()} returns null,
+     *                               or any wrapper {@link Wrapper#unwrap_()} returns null,
      *                               or the adaptee of {@link WrapperAdapter} is null
      * @throws IllegalStateException if any instance on the wrapper chain is not an instance of {@code bizInterface},
      *                               or the adaptee of {@link WrapperAdapter} is an instance of {@link Wrapper}
@@ -284,15 +284,15 @@ public static <W> void verifyWrapperChainContracts(final W wrapper, final Class<
      * Exceptions thrown by the {@code predicate} are relayed to the caller.
      * <p>
      * The wrapper chain consists of wrapper itself, followed by the wrappers
-     * obtained by repeatedly calling {@link Wrapper#unwrap()}.
+     * obtained by repeatedly calling {@link Wrapper#unwrap_()}.
      *
      * @param wrapper   wrapper instance/wrapper chain
      * @param predicate inspect logic
      * @param <W>       the type of instances that be wrapped
      * @return return {@code false} if no wrapper on the wrapper chain satisfy the given {@code predicate},
      * otherwise return {@code true}
      * @throws NullPointerException  if any arguments is null,
-     *                               or any wrapper {@link Wrapper#unwrap()} returns null,
+     *                               or any wrapper {@link Wrapper#unwrap_()} returns null,
      *                               or the adaptee of {@link WrapperAdapter} is null
      * @throws IllegalStateException if the adaptee of {@link WrapperAdapter} is an instance of {@link Wrapper}
      *                               or CYCLIC wrapper chain
@@ -312,13 +312,13 @@ public static <W> boolean testWrapperChain(final W wrapper, final Predicate<? su
      * Exceptions thrown by the {@code action} are relayed to the caller.
      * <p>
      * The wrapper chain consists of wrapper itself, followed by the wrappers
-     * obtained by repeatedly calling {@link Wrapper#unwrap()}.
+     * obtained by repeatedly calling {@link Wrapper#unwrap_()}.
      *
      * @param wrapper wrapper instance/wrapper chain
      * @param action  The action to be performed for each instance
      * @param <W>     the type of instances that be wrapped
      * @throws NullPointerException  if any arguments is null,
-     *                               or any wrapper {@link Wrapper#unwrap()} returns null,
+     *                               or any wrapper {@link Wrapper#unwrap_()} returns null,
      *                               or the adaptee of {@link WrapperAdapter} is null
      * @throws IllegalStateException if the adaptee of {@link WrapperAdapter} is an instance of {@link Wrapper}
      *                               or CYCLIC wrapper chain
@@ -340,7 +340,7 @@ public static <W> void forEachOnWrapperChain(final W wrapper, final Consumer<? s
      * Exceptions thrown by the process function are relayed to the caller.
      * <p>
      * The wrapper chain consists of wrapper itself, followed by the wrappers
-     * obtained by repeatedly calling {@link Wrapper#unwrap()}.
+     * obtained by repeatedly calling {@link Wrapper#unwrap_()}.
      *
      * @param wrapper wrapper instance
      * @param process process function
@@ -349,7 +349,7 @@ public static <W> void forEachOnWrapperChain(final W wrapper, final Consumer<? s
      * @return the first non-empty({@link Optional#empty()}) result of the process function,
      * otherwise returns {@link Optional#empty()}
      * @throws NullPointerException  if any arguments is null,
-     *                               or any wrapper {@link Wrapper#unwrap()} returns null,
+     *                               or any wrapper {@link Wrapper#unwrap_()} returns null,
      *                               or the adaptee of {@link WrapperAdapter} is null
      * @throws IllegalStateException if the adaptee of {@link WrapperAdapter} is an instance of {@link Wrapper}
      *                               or CYCLIC wrapper chain
@@ -391,7 +391,7 @@ public static <W, T> Optional<T> travelWrapperChain(
      */
     @Contract(pure = true)
     private static Object adapteeNonWrapper(final Object wrapper) {
-        final Object adaptee = ((WrapperAdapter<?>) wrapper).adaptee();
+        final Object adaptee = ((WrapperAdapter<?>) wrapper).adaptee_();
 
         Supplier<String> msg = () -> "adaptee of WrapperAdapter(" + wrapper.getClass().getName() + ") is null";
         requireNonNull(adaptee, msg);
@@ -410,7 +410,7 @@ private static Object adapteeNonWrapper(final Object wrapper) {
      */
     @Contract(pure = true)
     private static Object unwrapNonNull(final Object wrapper) {
-        Object unwrap = ((Wrapper<?>) wrapper).unwrap();
+        Object unwrap = ((Wrapper<?>) wrapper).unwrap_();
         Supplier<String> msg = () -> "unwrap of Wrapper(" + wrapper.getClass().getName() + ") is null";
         return requireNonNull(unwrap, msg);
     }

src/main/java/io/foldright/inspectablewrappers/Wrapper.java

@@ -10,7 +10,7 @@
  * <strong>Note about wrapper chain:</strong>
  * <ul>
  * <li>The wrapper chain consists of wrapper itself, followed by the wrappers
- *     obtained by repeatedly calling {@link Wrapper#unwrap()}<br>
+ *     obtained by repeatedly calling {@link Wrapper#unwrap_()}<br>
  *     <img src="https://github.com/foldright/inspectable-wrappers/assets/1063891/7bb7db14-2dee-44e6-b843-9817a94eef44"
  *      width="350" alt="Wrapper Chain">
  * <li>The last instance of wrapper chain is NEVER an instance of {@link Wrapper}
@@ -43,5 +43,5 @@ public interface Wrapper<T> {
      * </ul>
      */
     @NonNull
-    T unwrap();
+    T unwrap_();
 }

src/main/java/io/foldright/inspectablewrappers/WrapperAdapter.java

@@ -44,5 +44,5 @@ public interface WrapperAdapter<T> extends Wrapper<T> {
      * @see Inspector
      */
     @NonNull
-    T adaptee();
+    T adaptee_();
 }

src/main/java/io/foldright/inspectablewrappers/utils/AttachableDelegate.java

@@ -35,7 +35,7 @@ public class AttachableDelegate<K, V> implements Attachable<K, V> {
      * @throws NullPointerException if any arguments is null
      */
     @Override
-    public void setAttachment(@NonNull K key, @NonNull V value) {
+    public void setAttachment_(@NonNull K key, @NonNull V value) {
         requireNonNull(key, "key is null");
         requireNonNull(value, "value is null");
         attachments.put(key, value);
@@ -52,7 +52,7 @@ public void setAttachment(@NonNull K key, @NonNull V value) {
      */
     @Nullable
     @Override
-    public V getAttachment(@NonNull K key) {
+    public V getAttachment_(@NonNull K key) {
         requireNonNull(key, "key is null");
         return attachments.get(key);
     }