Package io.microsphere.lang

Interface Wrapper

  • All Known Subinterfaces:
    DelegatingWrapper
    All Known Implementing Classes:
    DelegatingDeque, DelegatingQueue, ReversedDeque
    public interface Wrapper
    A Wrapper is an interface that provides the ability to wrap objects and provide access to their underlying implementations, especially when those implementations expose non-standard or extended APIs.

    Implementations of this interface must ensure that they can either directly implement a requested type, or delegate to a wrapped object recursively until the appropriate implementation is found. This allows for flexible proxying and unwrapping patterns, particularly useful in frameworks where implementations may be layered with proxies or decorators.

    Example Usage

    
 public class MyWrapper implements Wrapper {
     private final MyService wrapped;

     public MyWrapper(MyService wrapped) {
         this.wrapped = wrapped;
     }

     public <T> T unwrap(Class<T> type) {
         if (type.isInstance(wrapped)) {
             return type.cast(wrapped);
         }
         throw new IllegalArgumentException("Cannot unwrap to " + type.getName());
     }

     public boolean isWrapperFor(Class<?> type) {
         return type.isInstance(wrapped);
     }
 }

 // Usage:
 MyService service = new MyServiceImpl();
 Wrapper wrapper = new MyWrapper(service);

 if (wrapper.isWrapperFor(MyService.class)) {
     MyService unwrapped = wrapper.unwrap(MyService.class); // returns service
 }

    The above example demonstrates a basic implementation of the Wrapper interface. It checks whether the wrapped object supports the requested type via isWrapperFor(Class), and safely returns the underlying instance via unwrap(Class).

    See Also:
    unwrap(Class), isWrapperFor(Class), tryUnwrap(Object, Class)

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean isWrapperFor​(java.lang.Class<?> type)
      Returns true if this either extends or implements the type argument or is directly or indirectly a wrapper for an object that does.
      static <T> T tryUnwrap​(java.lang.Object object, java.lang.Class<T> type)
      Try to unwrap the specified object and target type
      <T> T unwrap​(java.lang.Class<T> type)
      Returns an object of the given class to allow access to non-standard methods, or standard methods not exposed by the proxy.

    • Method Detail

      • unwrap

        <T> T unwrap​(java.lang.Class<T> type)
      throws java.lang.IllegalArgumentException
        Returns an object of the given class to allow access to non-standard methods, or standard methods not exposed by the proxy.

        If the receiver extends or implements the type then the result is the receiver or a proxy for the receiver. If the receiver is a wrapper and the wrapped object extends or implements the type then the result is the wrapped object or a proxy for the wrapped object. Otherwise return the result of calling unwrap recursively on the wrapped object or a proxy for that result. If the receiver is not a wrapper and does not implement the type, then an IllegalArgumentException is thrown.

        Type Parameters:
        T - the wrapped type
        Parameters:
        type - the wrapped type
        Returns:
        an object of the given class. Maybe a proxy for the actual implementing object.
        Throws:
        java.lang.IllegalArgumentException

      • isWrapperFor

        boolean isWrapperFor​(java.lang.Class<?> type)
        Returns true if this either extends or implements the type argument or is directly or indirectly a wrapper for an object that does. Returns false otherwise. If this extends or implements the type then return true, else if this is a wrapper then return the result of recursively calling isWrapperFor on the wrapped object. If this does not implement the type and is not a wrapper, return false. This method should be implemented as a low-cost operation compared to unwrap so that callers can use this method to avoid expensive unwrap calls that may fail. If this method returns true then calling unwrap with the same argument should succeed.
        Parameters:
        type - the wrapped type
        Returns:
        true if this extends or implements the type or directly or indirectly wraps an object that does

      • tryUnwrap

        static <T> T tryUnwrap​(java.lang.Object object,
                       java.lang.Class<T> type)
        Try to unwrap the specified object and target type
        Type Parameters:
        T - target type
        Parameters:
        object - maybe Wrapper
        type - target type
        Returns:
        unwrapped instance if possible, or the original object