Package freemarker.ext.beans

Class BeansWrapper

    • 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​(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,
                       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

      • checkModifiable

        protected void checkModifiable()
        If this object is already read-only according to WriteProtectable, throws IllegalStateException, otherwise does nothing.
        Since:
        2.3.21

      • 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

      • 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.

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

      • 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

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

      • 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

      • coerceBigDecimals

        public static void coerceBigDecimals​(AccessibleObject callable,
                                     Object[] args)
        Converts any BigDecimals 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 BigDecimals in the passed array to the type of the corresponding formal argument of the method.

      • 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