Package io.foldright.inspectablewrappers

Class Inspector

java.lang.Object

io.foldright.inspectablewrappers.Inspector

@DefaultAnnotationForParameters(edu.umd.cs.findbugs.annotations.NonNull.class)
public final class Inspector
extends Object

This Inspector class is used to inspect the wrapper chain.

Common simple usages

• Reports whether any instance on the wrapper chain matches the given type by static method containsInstanceTypeOnWrapperChain(Object, Class)
• Retrieves the attachment of instance on the wrapper chain by static method getAttachmentFromWrapperChain(Object, Object)
• Gets the wrapper chain, aka. the list of all instances on the wrapper chain by static method getInstancesOfWrapperChain(Object)
• Gets the base of the wrapper chain, aka. the last instance of the wrapper chain by static method getBaseOfWrapperChain(Object)
• Verifies the compliance of wrapper chain with the specification contracts by static method verifyWrapperChainContracts(Object) or verifyWrapperChainContracts(Object, Class)

Convenience methods for Wrapper interface

• Unwraps Wrapper to the underlying instance by static method unwrap(Object)
• Checks the input object is an instance of Wrapper or not by static method isWrapper(Object)

Advanced usages

• Reports whether any instance on the wrapper chain satisfy the given Predicate by static method testWrapperChain(Object, Predicate)
• Performs the given action for each instance on the wrapper chain by static method forEachOnWrapperChain(Object, Consumer)
• Traverses the wrapper chain and applies the given Function to each instance on the wrapper chain by static method travelWrapperChain(Object, Function)

You can implement your own inspection logic using above advanced methods.

Note about usage and methods naming

All method names contain the word "wrapper chain", so the usage code is easily recognizable as related to inspectable wrappers.

Because the method names are long and informative, it's recommended to static import these methods.

Author:

Jerry Lee (oldratlee at gmail dot com), Zava Xu (zava dot kid at gmail dot com)

See Also:

• Wrapper
• Attachable
• WrapperAdapter

Method Summary

Modifier and Type	Method	Description
static <W> boolean	containsInstanceTypeOnWrapperChain(W wrapper, Class<?> instanceType)	Reports whether any instance on the wrapper chain matches the given type.
static <W> void	forEachOnWrapperChain(W wrapper, Consumer<? super W> action)	Performs the given action for each instance on the wrapper chain until all elements have been processed or the action throws an exception.
static <W, K, V> V	getAttachmentFromWrapperChain(W wrapper, K key)	Retrieves the attachment of instance on the wrapper chain for the given key by calling Attachable.getAttachment_(Object).
static <W> W	getBaseOfWrapperChain(W wrapper)	Gets the base of the wrapper chain, aka.
static <W> List<W>	getInstancesOfWrapperChain(W wrapper)	Gets the wrapper chain, aka.
static boolean	isWrapper(Object obj)	Checks the input object is an instance of Wrapper or not, return false if input null.
static <W> boolean	testWrapperChain(W wrapper, Predicate<? super W> predicate)	Reports whether any instance on the wrapper chain satisfies the given predicate.
static <W, T> Optional<T>	travelWrapperChain(W wrapper, Function<? super W,Optional<T>> process)	Traverses the wrapper chain and applies the given process function to each instance on the wrapper chain, returns the first non-empty(Optional.empty()) result of the process function, otherwise returns Optional.empty().
static <W> W	unwrap(W obj)	Unwraps Wrapper to the underlying instance if input is a Wrapper instance.
static <W> void	verifyWrapperChainContracts(W wrapper)	Verifies the compliance of wrapper chain with the specification contracts.
static <W> void	verifyWrapperChainContracts(W wrapper, Class<W> bizInterface)	Verifies the compliance of wrapper chain with the specification contracts, and checks all instances on wrapper chain is an instance of the given bizInterface.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

containsInstanceTypeOnWrapperChain

@Contract(pure=true)
public static <W> boolean containsInstanceTypeOnWrapperChain(W wrapper,
 Class<?> instanceType)

Reports whether any instance on the wrapper chain matches the given type.

The wrapper chain consists of wrapper itself, followed by the wrappers obtained by repeatedly calling Wrapper.unwrap_().

Type Parameters:

W - the type of instances that be wrapped

Parameters:

wrapper - wrapper instance/wrapper chain

instanceType - target type

Returns:

return false if no wrapper on the wrapper chain matches the given type, otherwise return true

Throws:

NullPointerException - if any arguments is null, or any wrapper Wrapper.unwrap_() returns null, or the adaptee of WrapperAdapter is null

IllegalStateException - if the adaptee of WrapperAdapter is an instance of Wrapper or CYCLIC wrapper chain

getAttachmentFromWrapperChain

@Nullable
@Contract(pure=true)
public static <W,
K,
V> V getAttachmentFromWrapperChain(W wrapper,
 K key)

Retrieves the attachment of instance on the wrapper chain for the given key by calling Attachable.getAttachment_(Object).

The wrapper chain consists of wrapper itself, followed by the wrappers obtained by repeatedly calling Wrapper.unwrap_().

If the same key exists in multiple wrappers, outer wrapper win.

Type Parameters:

W - the type of instances that be wrapped

K - the type of attachment key

V - the type of attachment value

Parameters:

wrapper - wrapper instance

key - the attachment key

Returns:

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 Wrapper.unwrap_() returns null, or the adaptee of WrapperAdapter is null

ClassCastException - if the return value is not type <V>

IllegalStateException - if the adaptee of WrapperAdapter is an instance of Wrapper or CYCLIC wrapper chain

See Also:

• Attachable.getAttachment_(Object)

getInstancesOfWrapperChain

@NonNull
@Contract(pure=true)
public static <W> List<W> getInstancesOfWrapperChain(W wrapper)

Gets the wrapper chain, aka. the list of all instances on the wrapper chain.

The wrapper chain consists of wrapper itself, followed by the wrappers obtained by repeatedly calling Wrapper.unwrap_().

Type Parameters:

W - the type of instances that be wrapped

Parameters:

wrapper - wrapper instance

Throws:

NullPointerException - if wrapped argument is null, or any wrapper Wrapper.unwrap_() returns null, or the adaptee of WrapperAdapter is null

IllegalStateException - if the adaptee of WrapperAdapter is an instance of Wrapper or CYCLIC wrapper chain

getBaseOfWrapperChain

@NonNull
@Contract(pure=true)
public static <W> W getBaseOfWrapperChain(W wrapper)

Gets the base of the wrapper chain, aka. the last instance of the wrapper chain.

The wrapper chain consists of wrapper itself, followed by the wrappers obtained by repeatedly calling Wrapper.unwrap_().

Type Parameters:

W - the type of instances that be wrapped

Parameters:

wrapper - wrapper instance

Throws:

NullPointerException - if wrapped argument is null, or any wrapper Wrapper.unwrap_() returns null, or the adaptee of WrapperAdapter is null

IllegalStateException - if the adaptee of WrapperAdapter is an instance of Wrapper or CYCLIC wrapper chain

unwrap

@Nullable
@Contract(value="null -> null; !null -> !null",
          pure=true)
public static <W> W unwrap(@Nullable
 W obj)

Unwraps Wrapper to the underlying instance if input is a Wrapper instance.

This method is null-safe, return null iff input parameter is null; If input parameter is not a Wrapper just return input.

A convenience method for Wrapper.unwrap_()

Type Parameters:

W - the type of instances that be wrapped

Parameters:

obj - wrapper instance

Throws:

NullPointerException - if Wrapper.unwrap_() returns null

See Also:

• Wrapper.unwrap_()
• isWrapper(Object)

isWrapper

@Contract(value="null -> false",
          pure=true)
public static boolean isWrapper(@Nullable
 Object obj)

Checks the input object is an instance of Wrapper or not, return false if input null.

A convenience method for Wrapper interface.

See Also:

• unwrap(Object)

verifyWrapperChainContracts

public static <W> void verifyWrapperChainContracts(W wrapper)

Verifies the compliance of wrapper chain with the specification contracts.

The wrapper chain consists of wrapper itself, followed by the wrappers obtained by repeatedly calling Wrapper.unwrap_().

more about the specification contracts see the doc of below methods:

• Wrapper.unwrap_()
• WrapperAdapter.adaptee_()

Type Parameters:

W - the type of instances that be wrapped

Parameters:

wrapper - wrapper instance

Throws:

NullPointerException - if wrapped argument is null, or any wrapper Wrapper.unwrap_() returns null, or the adaptee of WrapperAdapter is null

IllegalStateException - if the adaptee of WrapperAdapter is an instance of Wrapper or CYCLIC wrapper chain

verifyWrapperChainContracts

public static <W> void verifyWrapperChainContracts(W wrapper,
 Class<W> bizInterface)

Verifies the compliance of wrapper chain with the specification contracts, and checks all instances on wrapper chain is an instance of the given bizInterface.

The wrapper chain consists of wrapper itself, followed by the wrappers obtained by repeatedly calling Wrapper.unwrap_().

more about the specification contracts see the doc of below methods:

• Wrapper.unwrap_()
• WrapperAdapter.adaptee_()

Type Parameters:

W - the type of instances that be wrapped

Parameters:

wrapper - wrapper instance

Throws:

NullPointerException - if any arguments is null, or any wrapper Wrapper.unwrap_() returns null, or the adaptee of WrapperAdapter is null

IllegalStateException - if any instance on the wrapper chain is not an instance of bizInterface, or the adaptee of WrapperAdapter is an instance of Wrapper or CYCLIC wrapper chain

testWrapperChain

public static <W> boolean testWrapperChain(W wrapper,
 Predicate<? super W> predicate)

Reports whether any instance on the wrapper chain satisfies the given predicate. Exceptions thrown by the predicate are relayed to the caller.

The wrapper chain consists of wrapper itself, followed by the wrappers obtained by repeatedly calling Wrapper.unwrap_().

Type Parameters:

W - the type of instances that be wrapped

Parameters:

wrapper - wrapper instance/wrapper chain

predicate - inspect logic

Returns:

return false if no wrapper on the wrapper chain satisfy the given predicate, otherwise return true

Throws:

NullPointerException - if any arguments is null, or any wrapper Wrapper.unwrap_() returns null, or the adaptee of WrapperAdapter is null

IllegalStateException - if the adaptee of WrapperAdapter is an instance of Wrapper or CYCLIC wrapper chain

forEachOnWrapperChain

public static <W> void forEachOnWrapperChain(W wrapper,
 Consumer<? super W> action)

Performs the given action for each instance on the wrapper chain until all elements have been processed or the action throws an exception. Exceptions thrown by the action are relayed to the caller.

The wrapper chain consists of wrapper itself, followed by the wrappers obtained by repeatedly calling Wrapper.unwrap_().

Type Parameters:

W - the type of instances that be wrapped

Parameters:

wrapper - wrapper instance/wrapper chain

action - The action to be performed for each instance

Throws:

NullPointerException - if any arguments is null, or any wrapper Wrapper.unwrap_() returns null, or the adaptee of WrapperAdapter is null

IllegalStateException - if the adaptee of WrapperAdapter is an instance of Wrapper or CYCLIC wrapper chain

See Also:

• travelWrapperChain(Object, Function)

travelWrapperChain

@NonNull
public static <W,
T> Optional<T> travelWrapperChain(W wrapper,
 Function<? super W,Optional<T>> process)

Traverses the wrapper chain and applies the given process function to each instance on the wrapper chain, returns the first non-empty(Optional.empty()) result of the process function, otherwise returns Optional.empty(). Exceptions thrown by the process function are relayed to the caller.

The wrapper chain consists of wrapper itself, followed by the wrappers obtained by repeatedly calling Wrapper.unwrap_().

Type Parameters:

W - the type of instances that be wrapped

T - the return data type of process function

Parameters:

wrapper - wrapper instance

process - process function

Returns:

the first non-empty(Optional.empty()) result of the process function, otherwise returns Optional.empty()

Throws:

NullPointerException - if any arguments is null, or any wrapper Wrapper.unwrap_() returns null, or the adaptee of WrapperAdapter is null

IllegalStateException - if the adaptee of WrapperAdapter is an instance of Wrapper or CYCLIC wrapper chain

See Also:

• forEachOnWrapperChain(Object, Consumer)