ObjectWrapperAndUnwrapper (FreeMarker 2.3.35 API)
Description: declaration: package: freemarker.template, interface: ObjectWrapperAndUnwrapper

Package 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
  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

  Modifier and Type
  Method
  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 Details

  - ### 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 Details

  - ### 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)`