ObjectWrapperAndUnwrapper (FreeMarker 2.3.23 API)
Date: 2015-07-05

freemarker.template

## Interface ObjectWrapperAndUnwrapper

- All Superinterfaces:
    ObjectWrapper
  All Known Subinterfaces:
    RichObjectWrapper
  All Known Implementing Classes:
    BeansWrapper, DefaultObjectWrapper, RhinoWrapper, SimpleObjectWrapper

      public interface ObjectWrapperAndUnwrapper
      extends ObjectWrapper

  Experimental - subject to change: Adds functionality to `ObjectWrapper` that creates a plain Java object from a `TemplateModel`. This is usually implemented by `ObjectWrapper`-s and reverses `ObjectWrapper.wrap(Object)`. However, an implementation of this interface should make a reasonable effort to "unwrap" `TemplateModel`-s that wasn't the result of object wrapping (such as those created directly in FTL), or which was created by another `ObjectWrapper`. The author of an `ObjectWrapperAndUnwrapper` should be aware of the `TemplateModelAdapter` and `WrapperTemplateModel` interfaces, which should be used for unwrapping if the `TemplateModel` implements them.

  Experimental status warning: This interface is subject to change on non-backward compatible ways, hence, it shouldn't be implemented outside FreeMarker yet.

  Since:
    2.3.22

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Object` | `CANT_UNWRAP_TO_TARGET_CLASS` Indicates that while the unwrapping is maybe possible, the result surely can't be the instance of the desired class, nor it can be `null`.

    - ### Fields inherited from interface freemarker.template.ObjectWrapper

      `BEANS_WRAPPER, DEFAULT_WRAPPER, SIMPLE_WRAPPER`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `tryUnwrapTo(TemplateModel tm, Class targetClass)` Attempts to unwrap a `TemplateModel` to a plain Java object that's the instance of the given class (or is `null`).
    `Object` | `unwrap(TemplateModel tm)` Unwraps a `TemplateModel` to a plain Java object.

    - ### Methods inherited from interface freemarker.template.ObjectWrapper

      `wrap`

- - ### Field Detail

    - #### CANT_UNWRAP_TO_TARGET_CLASS

          static final Object CANT_UNWRAP_TO_TARGET_CLASS

      Indicates that while the unwrapping is maybe possible, the result surely can't be the instance of the desired class, nor it can be `null`.
      Since:
        2.3.22
      See Also:
        `tryUnwrapTo(TemplateModel, Class)`

  - ### Method Detail

    - #### unwrap

          Object unwrap(TemplateModel tm)
                 throws TemplateModelException

      Unwraps a `TemplateModel` to a plain Java object.
      Returns:
        The plain Java object. Can be `null`, if `null` is the appropriate Java value to represent the template model. `null` must not be used to indicate an unwrapping failure. It must NOT be `CANT_UNWRAP_TO_TARGET_CLASS`.
      Throws:
        `TemplateModelException` - If the unwrapping fails from any reason.
      Since:
        2.3.22
      See Also:
        `tryUnwrapTo(TemplateModel, Class)`

    - #### tryUnwrapTo

          Object tryUnwrapTo(TemplateModel tm,
                             Class targetClass)
                      throws TemplateModelException

      Attempts to unwrap a `TemplateModel` to a plain Java object that's the instance of the given class (or is `null`).
      Parameters:
        `targetClass` - The class that the return value must be an instance of (except when the return value is `null`). Can't be `null`; if the caller doesn't care, it should either use {#unwrap(TemplateModel)}, or `Object.class` as the parameter value.
      Returns:
        The unwrapped value that's either an instance of `targetClass`, or is `null` (if `null` is the appropriate Java value to represent the template model), or is `CANT_UNWRAP_TO_TARGET_CLASS` if the unwrapping can't satisfy the `targetClass` (nor the result can be `null`). However, `CANT_UNWRAP_TO_TARGET_CLASS` must not be returned if the `targetClass` parameter was `Object.class`.
      Throws:
        `TemplateModelException` - If the unwrapping fails for a reason than doesn't fit the meaning of the `CANT_UNWRAP_TO_TARGET_CLASS` return value.
      Since:
        2.3.22
      See Also:
        `unwrap(TemplateModel)`