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