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

freemarker.ext.beans

## Class BeansWrapper

- java.lang.Object
- - freemarker.ext.beans.BeansWrapper

- All Implemented Interfaces:
    ObjectWrapper, ObjectWrapperAndUnwrapper, ObjectWrapperWithAPISupport, RichObjectWrapper, WriteProtectable
  Direct Known Subclasses:
    DefaultObjectWrapper, RhinoWrapper

      public class BeansWrapper
      extends Object
      implements RichObjectWrapper, WriteProtectable

  `ObjectWrapper` that is able to expose the Java API of arbitrary Java objects. This is also the superclass of `DefaultObjectWrapper`. Note that instances of this class generally should be created with a `BeansWrapperBuilder`, not with its public constructors.

  As of 2.3.22, using `BeansWrapper` unextended is not recommended. Instead, `DefaultObjectWrapper` with its `incompatibleImprovements` property set to 2.3.22 (or higher) is the recommended `ObjectWrapper`.

  This class is only thread-safe after you have finished calling its setter methods, and then safely published it (see JSR 133 and related literature). When used as part of `Configuration`, of course it's enough if that was safely published and then left unmodified. Using `BeansWrapperBuilder` also guarantees thread safety.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `BeansWrapper.MethodAppearanceDecision` Experimental class; subject to change! Used for `MethodAppearanceFineTuner.process(freemarker.ext.beans.BeansWrapper.MethodAppearanceDecisionInput, freemarker.ext.beans.BeansWrapper.MethodAppearanceDecision)` to store the results; see there.
    `static class` | `BeansWrapper.MethodAppearanceDecisionInput` Experimental class; subject to change! Used for `MethodAppearanceFineTuner.process(freemarker.ext.beans.BeansWrapper.MethodAppearanceDecisionInput, freemarker.ext.beans.BeansWrapper.MethodAppearanceDecision)` as input parameter; see there.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `EXPOSE_ALL` At this level of exposure, all methods and properties of the wrapped objects are exposed to the template.
    `static int` | `EXPOSE_NOTHING` At this level of exposure, no bean properties and methods are exposed.
    `static int` | `EXPOSE_PROPERTIES_ONLY` At this level of exposure, only property getters are exposed.
    `static int` | `EXPOSE_SAFE` At this level of exposure, all methods and properties of the wrapped objects are exposed to the template except methods that are deemed not safe.

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

      `CANT_UNWRAP_TO_TARGET_CLASS`

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

      `BEANS_WRAPPER, DEFAULT_WRAPPER, SIMPLE_WRAPPER`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `BeansWrapper()` Deprecated. Use `BeansWrapperBuilder` or, in rare cases, `BeansWrapper(Version)` instead.
    `protected` | `BeansWrapper(BeansWrapperConfiguration bwConf, boolean writeProtected)` Same as `BeansWrapper(BeansWrapperConfiguration, boolean, boolean)` with `true` `finalizeConstruction` argument.
    `protected` | `BeansWrapper(BeansWrapperConfiguration bwConf, boolean writeProtected, boolean finalizeConstruction)` Initializes the instance based on the the `BeansWrapperConfiguration` specified.
    `` | `BeansWrapper(Version incompatibleImprovements)` Use `BeansWrapperBuilder` instead of the public constructors if possible.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `checkModifiable()` If this object is already read-only according to `WriteProtectable`, throws `IllegalStateException`, otherwise does nothing.
    `void` | `clearClassIntrospecitonCache()` Removes all class introspection data from the cache.
    `static Object` | `coerceBigDecimal(BigDecimal bd, Class formalType)`
    `static void` | `coerceBigDecimals(AccessibleObject callable, Object[] args)` Converts any `BigDecimal`s in the passed array to the type of the corresponding formal argument of the method.
    `static void` | `coerceBigDecimals(Class[] formalTypes, Object[] args)` Converts any `BigDecimal`s in the passed array to the type of the corresponding formal argument of the method.
    `protected void` | `finalizeConstruction(boolean writeProtected)` Meant to be called after `BeansWrapper(BeansWrapperConfiguration, boolean, boolean)` when its last argument was `false`; makes the instance read-only if necessary, then registers the model factories in the class introspector.
    `protected void` | `finetuneMethodAppearance(Class clazz, Method m, BeansWrapper.MethodAppearanceDecision decision)` Deprecated. Use `setMethodAppearanceFineTuner(MethodAppearanceFineTuner)`; no need to extend this class anymore. Soon this method will be final, so trying to override it will break your app. Note that if the `methodAppearanceFineTuner` property is set to non-`null`, this method is not called anymore.
    `int` | `getDefaultDateType()` Returns the default date type.
    `static BeansWrapper` | `getDefaultInstance()` Deprecated. Use `BeansWrapperBuilder` instead. The instance returned here is not read-only, so it's dangerous to use.
    `TemplateHashModel` | `getEnumModels()` Returns a hash model that represents the so-called class enum models.
    `int` | `getExposureLevel()`
    `Version` | `getIncompatibleImprovements()` Returns the version given with `BeansWrapper(Version)`, normalized to the lowest version where a change has occurred.
    `protected TemplateModel` | `getInstance(Object object, ModelFactory factory)` Deprecated. override `getModelFactory(Class)` instead. Using this method will now bypass wrapper caching (if it's enabled) and always result in creation of a new wrapper. This method will be removed in 2.4
    `MethodAppearanceFineTuner` | `getMethodAppearanceFineTuner()`
    `protected ModelFactory` | `getModelFactory(Class clazz)`
    `ObjectWrapper` | `getOuterIdentity()` By default returns `this`.
    `TemplateHashModel` | `getStaticModels()` Returns a hash model that represents the so-called class static models.
    `boolean` | `getUseCache()`
    `boolean` | `isClassIntrospectionCacheRestricted()` Tells if this instance acts like if its class introspection cache is sharable with other `BeansWrapper`-s.
    `boolean` | `isExposeFields()` Returns whether exposure of public instance fields of classes is enabled.
    `boolean` | `isSimpleMapWrapper()` Tells whether Maps are exposed as simple maps, without access to their method.
    `boolean` | `isStrict()`
    `boolean` | `isWriteProtected()`
    `Object` | `newInstance(Class clazz, List arguments)` Creates a new instance of the specified class using the method call logic of this object wrapper for calling the constructor.
    `protected static Version` | `normalizeIncompatibleImprovementsVersion(Version incompatibleImprovements)` Returns the lowest version number that is equivalent with the parameter version.
    `void` | `removeFromClassIntrospectionCache(Class clazz)` Removes the introspection data for a class from the cache.
    `void` | `setDefaultDateType(int defaultDateType)` Sets the default date type to use for date models that result from a plain `java.util.Date` instead of `java.sql.Date` or `java.sql.Time` or `java.sql.Timestamp`.
    `void` | `setExposeFields(boolean exposeFields)` Controls whether public instance fields of classes are exposed to templates.
    `void` | `setExposureLevel(int exposureLevel)` Sets the method exposure level.
    `void` | `setMethodAppearanceFineTuner(MethodAppearanceFineTuner methodAppearanceFineTuner)` Used to tweak certain aspects of how methods appear in the data-model; see `MethodAppearanceFineTuner` for more.
    `void` | `setMethodsShadowItems(boolean methodsShadowItems)` Sets whether methods shadow items in beans.
    `void` | `setNullModel(TemplateModel nullModel)` Deprecated. Changing the `null` model can cause a lot of confusion; don't do it.
    `void` | `setOuterIdentity(ObjectWrapper outerIdentity)` When wrapping an object, the BeansWrapper commonly needs to wrap "sub-objects", for example each element in a wrapped collection.
    `void` | `setSimpleMapWrapper(boolean simpleMapWrapper)` When set to `true`, the keys in `Map`-s won't mix with the method names when looking at them from templates.
    `void` | `setStrict(boolean strict)` Specifies if an attempt to read a bean property that doesn't exist in the wrapped object should throw an `InvalidPropertyException`.
    `void` | `setUseCache(boolean useCache)` Sets whether this wrapper caches the `TemplateModel`-s created for the Java objects that has wrapped with this object wrapper.
    `protected String` | `toPropertiesString()` Returns the name-value pairs that describe the configuration of this `BeansWrapper`; called from `toString()`.
    `String` | `toString()` Returns the exact class name and the identity hash, also the values of the most often used `BeansWrapper` configuration properties, also if which (if any) shared class introspection cache it uses.
    `Object` | `tryUnwrapTo(TemplateModel model, 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 model)` Attempts to unwrap a model into underlying object.
    `Object` | `unwrap(TemplateModel model, Class targetClass)` Attempts to unwrap a model into an object of the desired class.
    `TemplateModel` | `wrap(Object object)` Wraps the object with a template model that is most specific for the object's class.
    `TemplateMethodModelEx` | `wrap(Object object, Method method)` Wraps a Java method so that it can be called from templates, without wrapping its parent ("this") object.
    `TemplateHashModel` | `wrapAsAPI(Object obj)` Wraps an object to a `TemplateModel` that exposes the object's "native" (usually, Java) API.
    `void` | `writeProtect()` Makes the configuration properties (settings) of this `BeansWrapper` object read-only.

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

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

- - ### Field Detail

    - #### EXPOSE_ALL

          public static final int EXPOSE_ALL

      At this level of exposure, all methods and properties of the wrapped objects are exposed to the template.
      See Also:
        Constant Field Values

    - #### EXPOSE_SAFE

          public static final int EXPOSE_SAFE

      At this level of exposure, all methods and properties of the wrapped objects are exposed to the template except methods that are deemed not safe. The not safe methods are java.lang.Object methods wait() and notify(), java.lang.Class methods getClassLoader() and newInstance(), java.lang.reflect.Method and java.lang.reflect.Constructor invoke() and newInstance() methods, all java.lang.reflect.Field set methods, all java.lang.Thread and java.lang.ThreadGroup methods that can change its state, as well as the usual suspects in java.lang.System and java.lang.Runtime.
      See Also:
        Constant Field Values

    - #### EXPOSE_PROPERTIES_ONLY

          public static final int EXPOSE_PROPERTIES_ONLY

      At this level of exposure, only property getters are exposed. Additionally, property getters that map to unsafe methods are not exposed (i.e. Class.classLoader and Thread.contextClassLoader).
      See Also:
        Constant Field Values

    - #### EXPOSE_NOTHING

          public static final int EXPOSE_NOTHING

      At this level of exposure, no bean properties and methods are exposed. Only map items, resource bundle items, and objects retrieved through the generic get method (on objects of classes that have a generic get method) can be retrieved through the hash interface. You might want to call `setMethodsShadowItems(boolean)` with `false` value to speed up map item retrieval.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### BeansWrapper

          public BeansWrapper()

      Deprecated. Use `BeansWrapperBuilder` or, in rare cases, `BeansWrapper(Version)` instead.
      Creates a new instance with the incompatible-improvements-version specified in `Configuration.DEFAULT_INCOMPATIBLE_IMPROVEMENTS`.

    - #### BeansWrapper

          public BeansWrapper(Version incompatibleImprovements)

      Use `BeansWrapperBuilder` instead of the public constructors if possible. The main disadvantage of using the public constructors is that the instances won't share caches. So unless having a private cache is your goal, don't use them. See
      Parameters:
        `incompatibleImprovements` - Sets which of the non-backward-compatible improvements should be enabled. Not `null`. This version number is the same as the FreeMarker version number with which the improvements were implemented.

        For new projects, it's recommended to set this to the FreeMarker version that's used during the development. For released products that are still actively developed it's a low risk change to increase the 3rd version number further as FreeMarker is updated, but of course you should always check the list of effects below. Increasing the 2nd or 1st version number possibly mean substantial changes with higher risk of breaking the application, but again, see the list of effects below.

        The reason it's separate from `Configuration.setIncompatibleImprovements(Version)` is that `ObjectWrapper` objects are often shared among multiple `Configuration`-s, so the two version numbers are technically independent. But it's recommended to keep those two version numbers the same.

        The changes enabled by `incompatibleImprovements` are:

        - 2.3.0: No changes; this is the starting point, the version used in older projects.

        - 2.3.21 (or higher): Several glitches were fixed in overloaded method selection. This usually just gets rid of errors (like ambiguity exceptions and numerical precision loses due to bad overloaded method choices), still, as in some cases the method chosen can be a different one now (that was the point of the reworking after all), it can mean a change in the behavior of the application. The most important change is that the treatment of `null` arguments were fixed, as earlier they were only seen applicable to parameters of type `Object`. Now `null`-s are seen to be applicable to any non-primitive parameters, and among those the one with the most specific type will be preferred (just like in Java), which is hence never the one with the `Object` parameter type. For more details about overloaded method selection changes see the version history in the FreeMarker Manual.

        Note that the version will be normalized to the lowest version where the same incompatible `BeansWrapper` improvements were already present, so `getIncompatibleImprovements()` might returns a lower version than what you have specified.

      Since:
        2.3.21

    - #### BeansWrapper

          protected BeansWrapper(BeansWrapperConfiguration bwConf,
                                 boolean writeProtected)

      Same as `BeansWrapper(BeansWrapperConfiguration, boolean, boolean)` with `true` `finalizeConstruction` argument.
      Since:
        2.3.21

    - #### BeansWrapper

          protected BeansWrapper(BeansWrapperConfiguration bwConf,
                                 boolean writeProtected,
                                 boolean finalizeConstruction)

      Initializes the instance based on the the `BeansWrapperConfiguration` specified.
      Parameters:
        `writeProtected` - Makes the instance's configuration settings read-only via `WriteProtectable.writeProtect()`; this way it can use the shared class introspection cache.
        `finalizeConstruction` - Decides if the construction is finalized now, or the caller will do some more adjustments on the instance and then call `finalizeConstruction(boolean)` itself.
      Since:
        2.3.22

  - ### Method Detail

    - #### finalizeConstruction

          protected void finalizeConstruction(boolean writeProtected)

      Meant to be called after `BeansWrapper(BeansWrapperConfiguration, boolean, boolean)` when its last argument was `false`; makes the instance read-only if necessary, then registers the model factories in the class introspector. No further changes should be done after calling this, if `writeProtected` was `true`.
      Since:
        2.3.22

    - #### writeProtect

          public void writeProtect()

      Makes the configuration properties (settings) of this `BeansWrapper` object read-only. As changing them after the object has become visible to multiple threads leads to undefined behavior, it's recommended to call this when you have finished configuring the object.

      Consider using `BeansWrapperBuilder` instead, which gives an instance that's already write protected and also uses some shared caches/pools.

      Specified by:
        `writeProtect` in interface `WriteProtectable`
      Since:
        2.3.21

    - #### isWriteProtected

          public boolean isWriteProtected()

      Specified by:
        `isWriteProtected` in interface `WriteProtectable`
      Since:
        2.3.21

    - #### checkModifiable

          protected void checkModifiable()

      If this object is already read-only according to `WriteProtectable`, throws `IllegalStateException`, otherwise does nothing.
      Since:
        2.3.21

    - #### isStrict

          public boolean isStrict()

      See Also:
        `setStrict(boolean)`

    - #### setStrict

          public void setStrict(boolean strict)

      Specifies if an attempt to read a bean property that doesn't exist in the wrapped object should throw an `InvalidPropertyException`.

      If this property is `false` (the default) then an attempt to read a missing bean property is the same as reading an existing bean property whose value is `null`. The template can't tell the difference, and thus always can use `?default('something')` and `?exists` and similar built-ins to handle the situation.

      If this property is `true` then an attempt to read a bean propertly in the template (like `myBean.aProperty`) that doesn't exist in the bean object (as opposed to just holding `null` value) will cause `InvalidPropertyException`, which can't be suppressed in the template (not even with `myBean.noSuchProperty?default('something')`). This way `?default('something')` and `?exists` and similar built-ins can be used to handle existing properties whose value is `null`, without the risk of hiding typos in the property names. Typos will always cause error. But mind you, it goes against the basic approach of FreeMarker, so use this feature only if you really know what you are doing.

    - #### setOuterIdentity

          public void setOuterIdentity(ObjectWrapper outerIdentity)

      When wrapping an object, the BeansWrapper commonly needs to wrap "sub-objects", for example each element in a wrapped collection. Normally it wraps these objects using itself. However, this makes it difficult to delegate to a BeansWrapper as part of a custom aggregate ObjectWrapper. This method lets you set the ObjectWrapper which will be used to wrap the sub-objects.
      Parameters:
        `outerIdentity` - the aggregate ObjectWrapper

    - #### getOuterIdentity

          public ObjectWrapper getOuterIdentity()

      By default returns `this`.
      See Also:
        `setOuterIdentity(ObjectWrapper)`

    - #### setSimpleMapWrapper

          public void setSimpleMapWrapper(boolean simpleMapWrapper)

      When set to `true`, the keys in `Map`-s won't mix with the method names when looking at them from templates. The default is `false` for backward-compatibility, but is not recommended.

      When this is `false`, `myMap.foo` or `myMap['foo']` either returns the method `foo`, or calls `Map.get("foo")`. If both exists (the method and the `Map` key), one will hide the other, depending on the `isMethodsShadowItems()`, which default to `true` (the method wins). Some frameworks use this so that you can call `myMap.get(nonStringKey)` from templates [*], but it comes on the cost of polluting the key-set with the method names, and risking methods accidentally hiding `Map` entries (or the other way around). Thus, this setup is not recommended. (Technical note: `Map`-s will be wrapped into `MapModel` in this case.)

      When this is `true`, `myMap.foo` or `myMap['foo']` always calls `Map.get("foo")`. The methods of the `Map` object aren't visible from templates in this case. This, however, spoils the `myMap.get(nonStringKey)` workaround. But now you can use `myMap(nonStringKey)` instead, that is, you can use the map itself as the `get` method. (Technical note: `Map`-s will be wrapped into `SimpleMapModel` in this case.)

      *: For historical reasons, FreeMarker 2.3.X doesn't support non-string keys with the `[]` operator, hence the workarounds. This will be likely fixed in FreeMarker 2.4.0. Also note that the method- and the "field"-namespaces aren't separate in FreeMarker, hence `myMap.get` can return the `get` method.

    - #### isSimpleMapWrapper

          public boolean isSimpleMapWrapper()

      Tells whether Maps are exposed as simple maps, without access to their method. See `setSimpleMapWrapper(boolean)` for details.
      Returns:
        true if Maps are exposed as simple hashes, false if they're exposed as full JavaBeans.

    - #### setExposureLevel

          public void setExposureLevel(int exposureLevel)

      Sets the method exposure level. By default, set to `EXPOSE_SAFE`.
      Parameters:
        `exposureLevel` - can be any of the `EXPOSE_xxx` constants.

    - #### getExposureLevel

          public int getExposureLevel()

      Since:
        2.3.21

    - #### setExposeFields

          public void setExposeFields(boolean exposeFields)

      Controls whether public instance fields of classes are exposed to templates.
      Parameters:
        `exposeFields` - if set to true, public instance fields of classes that do not have a property getter defined can be accessed directly by their name. If there is a property getter for a property of the same name as the field (i.e. getter "getFoo()" and field "foo"), then referring to "foo" in template invokes the getter. If set to false, no access to public instance fields of classes is given. Default is false.

    - #### isExposeFields

          public boolean isExposeFields()

      Returns whether exposure of public instance fields of classes is enabled. See `setExposeFields(boolean)` for details.
      Returns:
        true if public instance fields are exposed, false otherwise.

    - #### getMethodAppearanceFineTuner

          public MethodAppearanceFineTuner getMethodAppearanceFineTuner()

    - #### setMethodAppearanceFineTuner

          public void setMethodAppearanceFineTuner(MethodAppearanceFineTuner methodAppearanceFineTuner)

      Used to tweak certain aspects of how methods appear in the data-model; see `MethodAppearanceFineTuner` for more.

    - #### isClassIntrospectionCacheRestricted

          public boolean isClassIntrospectionCacheRestricted()

      Tells if this instance acts like if its class introspection cache is sharable with other `BeansWrapper`-s. A restricted cache denies certain too "antisocial" operations, like `clearClassIntrospecitonCache()`. The value depends on how the instance was created; with a public constructor (then this is `false`), or with `BeansWrapperBuilder` (then it's `true`). Note that in the last case it's possible that the introspection cache will not be actually shared because there's no one to share with, but this will `true` even then.
      Since:
        2.3.21

    - #### setMethodsShadowItems

          public void setMethodsShadowItems(boolean methodsShadowItems)

      Sets whether methods shadow items in beans. When true (this is the default value), `${object.name}` will first try to locate a bean method or property with the specified name on the object, and only if it doesn't find it will it try to call `object.get(name)`, the so-called "generic get method" that is usually used to access items of a container (i.e. elements of a map). When set to false, the lookup order is reversed and generic get method is called first, and only if it returns null is method lookup attempted.

    - #### setDefaultDateType

          public void setDefaultDateType(int defaultDateType)

      Sets the default date type to use for date models that result from a plain `java.util.Date` instead of `java.sql.Date` or `java.sql.Time` or `java.sql.Timestamp`. Default value is `TemplateDateModel.UNKNOWN`.
      Parameters:
        `defaultDateType` - the new default date type.

    - #### getDefaultDateType

          public int getDefaultDateType()

      Returns the default date type. See `setDefaultDateType(int)` for details.
      Returns:
        the default date type

    - #### setUseCache

          public void setUseCache(boolean useCache)

      Sets whether this wrapper caches the `TemplateModel`-s created for the Java objects that has wrapped with this object wrapper. Default is `false`. When set to `true`, calling `wrap(Object)` multiple times for the same object will likely return the same model (although there is no guarantee as the cache items can be cleared any time).

    - #### getUseCache

          public boolean getUseCache()

      Since:
        2.3.21

    - #### setNullModel

          public void setNullModel(TemplateModel nullModel)

      Deprecated. Changing the `null` model can cause a lot of confusion; don't do it.
      Sets the null model. This model is returned from the `wrap(Object)` method whenever the wrapped object is `null`. It defaults to `null`, which is dealt with quite strictly on engine level, however you can substitute an arbitrary (perhaps more lenient) model, like an empty string. For proper working, the `nullModel` should be an `AdapterTemplateModel` that returns `null` for `AdapterTemplateModel.getAdaptedObject(Class)`.

    - #### getIncompatibleImprovements

          public Version getIncompatibleImprovements()

      Returns the version given with `BeansWrapper(Version)`, normalized to the lowest version where a change has occurred. Thus, this is not necessarily the same version than that was given to the constructor.
      Since:
        2.3.21

    - #### normalizeIncompatibleImprovementsVersion

          protected static Version normalizeIncompatibleImprovementsVersion(Version incompatibleImprovements)

      Returns the lowest version number that is equivalent with the parameter version.
      Since:
        2.3.21

    - #### getDefaultInstance

          public static final BeansWrapper getDefaultInstance()

      Deprecated. Use `BeansWrapperBuilder` instead. The instance returned here is not read-only, so it's dangerous to use.
      Returns the default instance of the wrapper. This instance is used when you construct various bean models without explicitly specifying a wrapper. It is also returned by `ObjectWrapper.BEANS_WRAPPER` and this is the sole instance that is used by the JSP adapter. You can modify the properties of the default instance (caching, exposure level, null model) to affect its operation. By default, the default instance is not caching, uses the `EXPOSE_SAFE` exposure level, and uses null reference as the null model.

    - #### wrap

          public TemplateModel wrap(Object object)
                             throws TemplateModelException

      Wraps the object with a template model that is most specific for the object's class. Specifically:
      - if the object is null, returns the `null model`,
      - if the object is a Number returns a `NumberModel` for it,
      - if the object is a Date returns a `DateModel` for it,
      - if the object is a Boolean returns `TemplateBooleanModel.TRUE` or `TemplateBooleanModel.FALSE`
      - if the object is already a TemplateModel, returns it unchanged,
      - if the object is an array, returns a `ArrayModel` for it
      - if the object is a Map, returns a `MapModel` for it
      - if the object is a Collection, returns a `CollectionModel` for it
      - if the object is an Iterator, returns a `IteratorModel` for it
      - if the object is an Enumeration, returns a `EnumerationModel` for it
      - if the object is a String, returns a `StringModel` for it
      - otherwise, returns a generic `StringModel` for it.
      Specified by:
        `wrap` in interface `ObjectWrapper`
      Parameters:
        `object` - 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)`).
      Throws:
        `TemplateModelException`

    - #### wrap

          public TemplateMethodModelEx wrap(Object object,
                                            Method method)

      Wraps a Java method so that it can be called from templates, without wrapping its parent ("this") object. The result is almost the same as that you would get by wrapping the parent object then getting the method from the resulting `TemplateHashModel` by name. Except, if the wrapped method is overloaded, with this method you explicitly select a an overload, while otherwise you would get a `TemplateMethodModelEx` that selects an overload each time it's called based on the argument values.
      Parameters:
        `object` - The object whose method will be called, or `null` if `method` is a static method. This object will be used "as is", like without unwrapping it if it's a `TemplateModelAdapter`.
        `method` - The method to call, which must be an (inherited) member of the class of `object`, as described by `Method.invoke(Object, Object...)`
      Since:
        2.3.22

    - #### wrapAsAPI

          public TemplateHashModel wrapAsAPI(Object obj)
                                      throws TemplateModelException

      Description copied from interface: `ObjectWrapperWithAPISupport`
      Wraps an object to a `TemplateModel` that exposes the object's "native" (usually, Java) API.
      Specified by:
        `wrapAsAPI` in interface `ObjectWrapperWithAPISupport`
      Parameters:
        `obj` - The object for which the API model has to be returned. Shouldn't be `null`.
      Returns:
        The `TemplateModel` through which the API of the object can be accessed. Can't be `null`.
      Throws:
        `TemplateModelException`
      Since:
        2.3.22

    - #### getInstance

          protected TemplateModel getInstance(Object object,
                                              ModelFactory factory)

      Deprecated. override `getModelFactory(Class)` instead. Using this method will now bypass wrapper caching (if it's enabled) and always result in creation of a new wrapper. This method will be removed in 2.4
      Parameters:
        `object` - The object to wrap
        `factory` - The factory that wraps the object

    - #### getModelFactory

          protected ModelFactory getModelFactory(Class clazz)

    - #### unwrap

          public Object unwrap(TemplateModel model)
                        throws TemplateModelException

      Attempts to unwrap a model into underlying object. Generally, this method is the inverse of the `wrap(Object)` method. In addition it will unwrap arbitrary `TemplateNumberModel` instances into a number, arbitrary `TemplateDateModel` instances into a date, `TemplateScalarModel` instances into a String, arbitrary `TemplateBooleanModel` instances into a Boolean, arbitrary `TemplateHashModel` instances into a Map, arbitrary `TemplateSequenceModel` into a List, and arbitrary `TemplateCollectionModel` into a Set. All other objects are returned unchanged.
      Specified by:
        `unwrap` in interface `ObjectWrapperAndUnwrapper`
      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 `ObjectWrapperAndUnwrapper.CANT_UNWRAP_TO_TARGET_CLASS`.
      Throws:
        `TemplateModelException` - if an attempted unwrapping fails.
      See Also:
        `ObjectWrapperAndUnwrapper.tryUnwrapTo(TemplateModel, Class)`

    - #### unwrap

          public Object unwrap(TemplateModel model,
                               Class targetClass)
                        throws TemplateModelException

      Attempts to unwrap a model into an object of the desired class. Generally, this method is the inverse of the `wrap(Object)` method. It recognizes a wide range of target classes - all Java built-in primitives, primitive wrappers, numbers, dates, sets, lists, maps, and native arrays.
      Parameters:
        `model` - the model to unwrap
        `targetClass` - the class of the unwrapped result; `Object.class` of we don't know what the expected type is.
      Returns:
        the unwrapped result of the desired class
      Throws:
        `TemplateModelException` - if an attempted unwrapping fails.
      See Also:
        `tryUnwrapTo(TemplateModel, Class)`

    - #### tryUnwrapTo

          public Object tryUnwrapTo(TemplateModel model,
                                    Class targetClass)
                             throws TemplateModelException

      Description copied from interface: `ObjectWrapperAndUnwrapper`
      Attempts to unwrap a `TemplateModel` to a plain Java object that's the instance of the given class (or is `null`).
      Specified by:
        `tryUnwrapTo` in interface `ObjectWrapperAndUnwrapper`
        `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 `ObjectWrapperAndUnwrapper.CANT_UNWRAP_TO_TARGET_CLASS` if the unwrapping can't satisfy the `targetClass` (nor the result can be `null`). However, `ObjectWrapperAndUnwrapper.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 `ObjectWrapperAndUnwrapper.CANT_UNWRAP_TO_TARGET_CLASS` return value.
      Since:
        2.3.22
      See Also:
        `ObjectWrapperAndUnwrapper.unwrap(TemplateModel)`

    - #### getStaticModels

          public TemplateHashModel getStaticModels()

      Returns a hash model that represents the so-called class static models. Every class static model is itself a hash through which you can call static methods on the specified class. To obtain a static model for a class, get the element of this hash with the fully qualified class name. For example, if you place this hash model inside the root data model under name "statics", you can use i.e. `statics["java.lang. System"]. currentTimeMillis()` to call the `System.currentTimeMillis()` method.
      Returns:
        a hash model whose keys are fully qualified class names, and that returns hash models whose elements are the static models of the classes.

    - #### getEnumModels

          public TemplateHashModel getEnumModels()

      Returns a hash model that represents the so-called class enum models. Every class' enum model is itself a hash through which you can access enum value declared by the specified class, assuming that class is an enumeration. To obtain an enum model for a class, get the element of this hash with the fully qualified class name. For example, if you place this hash model inside the root data model under name "enums", you can use i.e. `statics["java.math.RoundingMode"].UP` to access the `RoundingMode.UP` value.
      Returns:
        a hash model whose keys are fully qualified class names, and that returns hash models whose elements are the enum models of the classes.
      Throws:
        `UnsupportedOperationException` - if this method is invoked on a pre-1.5 JRE, as Java enums aren't supported there.

    - #### newInstance

          public Object newInstance(Class clazz,
                                    List arguments)
                             throws TemplateModelException

      Creates a new instance of the specified class using the method call logic of this object wrapper for calling the constructor. Overloaded constructors and varargs are supported. Only public constructors will be called.
      Parameters:
        `clazz` - The class whose constructor we will call.
        `arguments` - The list of `TemplateModel`-s to pass to the constructor after unwrapping them
      Returns:
        The instance created; it's not wrapped into `TemplateModel`.
      Throws:
        `TemplateModelException`

    - #### removeFromClassIntrospectionCache

          public void removeFromClassIntrospectionCache(Class clazz)

      Removes the introspection data for a class from the cache. Use this if you know that a class is not used anymore in templates. If the class will be still used, the cache entry will be silently re-created, so this isn't a dangerous operation.
      Since:
        2.3.20

    - #### clearClassIntrospecitonCache

          public void clearClassIntrospecitonCache()

      Removes all class introspection data from the cache.

      Use this if you want to free up memory on the expense of recreating the cache entries for the classes that will be used later in templates.

      Throws:
        `IllegalStateException` - if `isClassIntrospectionCacheRestricted()` is `true`.
      Since:
        2.3.20

    - #### finetuneMethodAppearance

          protected void finetuneMethodAppearance(Class clazz,
                                                  Method m,
                                                  BeansWrapper.MethodAppearanceDecision decision)

      Deprecated. Use `setMethodAppearanceFineTuner(MethodAppearanceFineTuner)`; no need to extend this class anymore. Soon this method will be final, so trying to override it will break your app. Note that if the `methodAppearanceFineTuner` property is set to non-`null`, this method is not called anymore.

    - #### coerceBigDecimals

          public static void coerceBigDecimals(AccessibleObject callable,
                                               Object[] args)

      Converts any `BigDecimal`s in the passed array to the type of the corresponding formal argument of the method.

    - #### coerceBigDecimals

          public static void coerceBigDecimals(Class[] formalTypes,
                                               Object[] args)

      Converts any `BigDecimal`s in the passed array to the type of the corresponding formal argument of the method.

    - #### coerceBigDecimal

          public static Object coerceBigDecimal(BigDecimal bd,
                                                Class formalType)

    - #### toString

          public String toString()

      Returns the exact class name and the identity hash, also the values of the most often used `BeansWrapper` configuration properties, also if which (if any) shared class introspection cache it uses.
      Overrides:
        `toString` in class `Object`
      Since:
        2.3.21

    - #### toPropertiesString

          protected String toPropertiesString()

      Returns the name-value pairs that describe the configuration of this `BeansWrapper`; called from `toString()`. The expected format is like `"foo=bar, baaz=wombat"`. When overriding this, you should call the super method, and then insert the content before it with a following `", "`, or after it with a preceding `", "`.
      Since:
        2.3.22