io.foldright.inspectablewrappers.WrapperAdapter Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of inspectable-wrappers Show documentation

🪐 Inspectable Wrappers Specification, provides a standard for wrapper chain with the inspection ability.

The newest version!

package io.foldright.inspectablewrappers;

import edu.umd.cs.findbugs.annotations.NonNull;


/**
 * This {@code WrapperAdapter} interface is used to
 * adapt an existed wrapper instance to type {@link Wrapper} without modifying it.
 * 
 * The existed wrapper may not be able to be modified to integrate with {@code inspectable wrappers};
 * Integration with {@code inspectable wrappers} means implementation the {@link Wrapper} interface.
 * 

 * The wrapper chain contained {@code WrapperAdapter} looks like:
 * 

 * 
 * 

 * Provided {@link io.foldright.inspectablewrappers.utils.WrapperAdapterUtils WrapperAdapterUtils}
 * to create {@link WrapperAdapter} instances of the given biz interface type by the underlying
 * and adaptee instances without writing boilerplate codes of creating new adapter classes.
 *
 * @param  the type of instances that be wrapped
 * @author Jerry Lee (oldratlee at gmail dot com)
 * @author Zava Xu (zava dot kid at gmail dot com)
 * @see Wrapper
 * @see io.foldright.inspectablewrappers.utils.WrapperAdapterUtils
 */
public interface WrapperAdapter extends Wrapper {
    /**
     * Returns the adapted/existed wrapper.
     * 

     * Specification contracts:
     * 

     * Do NOT return {@code null} which makes no sense.

     *     If returns {@code null}, the inspection operations of {@link Inspector} will
     *     throw {@link NullPointerException} when touch adaptee.
     * 
The adaptee MUST NOT an instance of {@link Wrapper},
     *     since adapting a {@link Wrapper} to a {@link Wrapper} is UNNECESSARY.

     *     If adapting a {@link Wrapper}, the inspection operations of {@link Inspector} will
     *     throw {@link IllegalStateException} when touch the {@link Wrapper} type adaptee.
     * 
     *
     * @return the adapted wrapper
     * @see Inspector
     */
    @NonNull
    T adaptee_();
}