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

freemarker.ext.jython

## Class JythonWrapper

- java.lang.Object
- - freemarker.ext.jython.JythonWrapper

- All Implemented Interfaces:
    ObjectWrapper

      public class JythonWrapper
      extends Object
      implements ObjectWrapper

  An object wrapper that wraps Jython objects into FreeMarker template models and vice versa.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static JythonWrapper` | `INSTANCE`

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

      `BEANS_WRAPPER, DEFAULT_WRAPPER, SIMPLE_WRAPPER`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JythonWrapper()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `setAttributesShadowItems(boolean attributesShadowItems)` Sets whether attributes shadow items in wrapped objects.
    `void` | `setUseCache(boolean useCache)` Sets whether this wrapper caches model instances.
    `org.python.core.PyObject` | `unwrap(TemplateModel model)` Coerces a template model into a `PyObject`.
    `TemplateModel` | `wrap(Object obj)` Wraps the passed Jython object into a FreeMarker template model.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### INSTANCE

          public static final JythonWrapper INSTANCE

  - ### Constructor Detail

    - #### JythonWrapper

          public JythonWrapper()

  - ### Method Detail

    - #### setUseCache

          public void setUseCache(boolean useCache)

      Sets whether this wrapper caches model instances. Default is false. When set to true, calling `wrap(Object)` multiple times for the same object will return the same model.

    - #### setAttributesShadowItems

          public void setAttributesShadowItems(boolean attributesShadowItems)

      Sets whether attributes shadow items in wrapped objects. When true (this is the default value), `${object.name}` will first try to locate a python attribute with the specified name on the object using `PyObject.__findattr__(java.lang.String)`, and only if it doesn't find the attribute will it call `PyObject.__getitem__(org.python.core.PyObject)`. When set to false, the lookup order is reversed and items are looked up before attributes.

    - #### wrap

          public TemplateModel wrap(Object obj)

      Wraps the passed Jython object into a FreeMarker template model. If the object is not a Jython object, it's first coerced into one using `Py.java2py(java.lang.Object)`. `PyDictionary` and `PyStringMap` are wrapped into a hash model, `PySequence` descendants are wrapped into a sequence model, `PyInteger`, `PyLong`, and `PyFloat` are wrapped into a number model. All objects are wrapped into a scalar model (using `Object.toString()` and a boolean model (using `PyObject.__nonzero__()`. For internal general-purpose `PyObject`s returned from a call to `unwrap(TemplateModel)`, the template model that was passed to `unwrap` is returned.
      Specified by:
        `wrap` in interface `ObjectWrapper`
      Parameters:
        `obj` - The object to wrap into a `TemplateModel`. If it already implements `TemplateModel`, it should just return the object as is. If it's `null`, the method should return `null` (however, `BeansWrapper`, has a legacy option for returning a null model object instead, but it's not a good idea).
      Returns:
        a `TemplateModel` wrapper of the object passed in. To support un-wrapping, you may consider the return value to implement `WrapperTemplateModel` and `AdapterTemplateModel`. The default expectation is that the `TemplateModel` isn't less thread safe than the wrapped object. If the `ObjectWrapper` returns less thread safe objects, that should be clearly documented, as it restricts how it can be used, like, then it can't be used to wrap "shared variables" (`Configuration.setSharedVaribles(Map)`).

    - #### unwrap

          public org.python.core.PyObject unwrap(TemplateModel model)
                                          throws TemplateModelException

      Coerces a template model into a `PyObject`.
      Parameters:
        `model` - the model to coerce
      Returns:
        the coerced model.
        - `AdapterTemplateModel`s (i.e. `BeanModel`) are marshalled using the standard Python marshaller `Py.java2py(Object)` on the result of `getWrappedObject(PyObject.class)`s. The native JythonModel instances will just return the underlying PyObject.
        - All other models that are `scalars` are marshalled as `PyString`.
        - All other models that are `numbers` are marshalled using the standard Python marshaller `Py.java2py(Object)` on their underlying `Number`
        - All other models are marshalled to a generic internal `PyObject` subclass that'll correctly pass `__finditem__`, `__len__`, `__nonzero__`, and `__call__` invocations to appropriate hash, sequence, and method models.
      Throws:
        `TemplateModelException`