io.foldright.inspectablewrappers.Attachable 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;
import edu.umd.cs.findbugs.annotations.Nullable;


/**
 * This {@code Attachable} interface is used to be implemented by wrapper classes,
 * provide the attachment storage ability.
 * 
 * Retrieves the attachment from wrapper chain
 * by method {@link Inspector#getAttachmentFromWrapperChain(Object, Object)}.
 * 
 * Provided {@link io.foldright.inspectablewrappers.utils.AttachableDelegate AttachableDelegate}
 * as a simple delegate implementation.
 *
 * @param  the key type, requirements depending on which storage is used
 * @param  the value type to be stored
 * @author Jerry Lee (oldratlee at gmail dot com)
 * @author Yang Fang (snoop dot fy at gmail dot com)
 * @see Inspector#getAttachmentFromWrapperChain(Object, Object)
 * @see io.foldright.inspectablewrappers.utils.AttachableDelegate
 */
public interface Attachable {
    /**
     * Sets an attachment.
     *
     * @param key   the attachment key
     * @param value the attachment value
     * @throws NullPointerException if any arguments is null
     */
    void setAttachment_(@NonNull K key, @NonNull V value);

    /**
     * Gets the attachment value for the given key.
     *
     * @param key the attachment key
     * @return return the attachment value, or {@code null} if contains no attachment for the key
     * @throws NullPointerException if key argument is null
     * @throws ClassCastException   if the return value is not type {@code }
     * @see Inspector#getAttachmentFromWrapperChain(Object, Object)
     */
    @Nullable
    V getAttachment_(@NonNull K key);
}