io.foldright.inspectablewrappers.Wrapper 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 Wrapper} interface is used to be implemented by wrapper classes,
 * make an inspectable wrapper chain(linked list).
 * 
 * Note about wrapper chain:
 * 

 * The wrapper chain consists of wrapper itself, followed by the wrappers
 *     obtained by repeatedly calling {@link Wrapper#unwrap_()}

 *     
 * 
The last instance of wrapper chain is NEVER an instance of {@link Wrapper}
 * 
Uses the static methods of {@link Inspector} to inspect the wrapper chain
 * 
 *
 * @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 Attachable
 * @see WrapperAdapter
 * @see Inspector
 */
public interface Wrapper {
    /**
     * Returns the underlying instance that be wrapped.
     * 
     * This method also make the wrapper instances as a wrapper chain(linked list),
     * The wrapper chain consists of wrapper itself, followed by the wrappers
     * obtained by repeatedly calling this method.
     * 

     * 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 the {@code null unwrap value}.
     * 
The wrapper chain can NOT be CYCLIC(aka. the return value/wrapper instance
     *     is duplicate on the wrapper chain).
If cyclic, the inspection operations of {@link Inspector}
     *     will throw {@link IllegalStateException} when touch the {@code duplicate unwrap instance}.
     * 
     */
    @NonNull
    T unwrap_();
}