Class BeansWrapper
- All Implemented Interfaces:
ObjectWrapper,ObjectWrapperAndUnwrapper,ObjectWrapperWithAPISupport,RichObjectWrapper,WriteProtectable
- Direct Known Subclasses:
DefaultObjectWrapper,RhinoWrapper
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 ClassesModifier and TypeClassDescriptionstatic classUsed forMethodAppearanceFineTuner.process(freemarker.ext.beans.BeansWrapper.MethodAppearanceDecisionInput, freemarker.ext.beans.BeansWrapper.MethodAppearanceDecision)to store the results; see there.static classUsed forMethodAppearanceFineTuner.process(freemarker.ext.beans.BeansWrapper.MethodAppearanceDecisionInput, freemarker.ext.beans.BeansWrapper.MethodAppearanceDecision)as input parameter; see there. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic intAt this level of exposure, all methods and properties of the wrapped objects are exposed to the template, and even theMemberAccessPolicyis ignored.static intAt this level of exposure, no Java Bean properties, and no methods are exposed.static intAt this level of exposure, only Java Bean properties are exposed.static intAt this level of exposure, all methods and properties of the wrapped objects are exposed to the template except methods that are deemed not safe by theMemberAccessPolicy.Fields inherited from interface freemarker.template.ObjectWrapper
BEANS_WRAPPER, DEFAULT_WRAPPER, SIMPLE_WRAPPERFields inherited from interface freemarker.template.ObjectWrapperAndUnwrapper
CANT_UNWRAP_TO_TARGET_CLASS -
Constructor Summary
ConstructorsModifierConstructorDescriptionDeprecated.protectedBeansWrapper(BeansWrapperConfiguration bwConf, boolean writeProtected)Same asBeansWrapper(BeansWrapperConfiguration, boolean, boolean)withtruefinalizeConstructionargument.protectedBeansWrapper(BeansWrapperConfiguration bwConf, boolean writeProtected, boolean finalizeConstruction)Initializes the instance based on theBeansWrapperConfigurationspecified.BeansWrapper(Version incompatibleImprovements)UseBeansWrapperBuilderinstead of the public constructors if possible. -
Method Summary
Modifier and TypeMethodDescriptionprotected voidIf this object is already read-only according toWriteProtectable, throwsIllegalStateException, otherwise does nothing.voidDeprecated.There's a typo in this method name, so useclearClassIntrospectionCache()instead.voidRemoves all class introspection data from the cache.static ObjectcoerceBigDecimal(BigDecimal bd, Class<?> formalType)ConvertsBigDecimalto the class given in theformalTypeargument if that's a known numerical type, returns theBigDecimalas is otherwise.static voidcoerceBigDecimals(Class<?>[] formalTypes, Object[] args)Converts anyBigDecimal-s in the passed array to the type of the corresponding formal argument of the method viacoerceBigDecimal(BigDecimal, Class).static voidcoerceBigDecimals(AccessibleObject callable, Object[] args)Converts anyBigDecimals in the passed array to the type of the corresponding formal argument of the method.protected voidfinalizeConstruction(boolean writeProtected)Meant to be called afterBeansWrapper(BeansWrapperConfiguration, boolean, boolean)when its last argument wasfalse; makes the instance read-only if necessary, then registers the model factories in the class introspector.protected voidfinetuneMethodAppearance(Class<?> clazz, Method m, BeansWrapper.MethodAppearanceDecision decision)Deprecated.UsesetMethodAppearanceFineTuner(MethodAppearanceFineTuner); no need to extend this class anymore.intReturns the default date type.static BeansWrapperDeprecated.UseBeansWrapperBuilderinstead.Returns a hash model that represents the so-called class enum models.intReturns the version given withBeansWrapper(Version), normalized to the lowest version where a change has occurred.protected TemplateModelgetInstance(Object object, ModelFactory factory)Deprecated.overridegetModelFactory(Class)instead.protected ModelFactorygetModelFactory(Class<?> clazz)By default returnsthis.booleanGetter pair ofsetPreferIndexedReadMethod(boolean)Returns a hash model that represents the so-called class static models.booleanbooleanprotected TemplateModelinvokeMethod(Object object, Method method, Object[] args)Invokes the specified method, wrapping the return value.booleanTells if this instance acts like if its class introspection cache is sharable with otherBeansWrapper-s.booleanReturns whether exposure of public instance fields of classes is enabled.booleanTells whether Maps are exposed as simple maps, without access to their method.booleanisStrict()booleannewInstance(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 VersionnormalizeIncompatibleImprovementsVersion(Version incompatibleImprovements)Returns the lowest version number that is equivalent with the parameter version.protected TemplateModelReads the specified field, returns its value asTemplateModel.voidremoveFromClassIntrospectionCache(Class<?> clazz)Removes the introspection data for a class from the cache.voidsetDefaultDateType(int defaultDateType)Sets the default date type to use for date models that result from a plainjava.util.Dateinstead ofjava.sql.Dateorjava.sql.Timeorjava.sql.Timestamp.voidsetDefaultZeroArgumentNonVoidMethodPolicy(ZeroArgumentNonVoidMethodPolicy defaultZeroArgumentNonVoidMethodPolicy)Sets theZeroArgumentNonVoidMethodPolicyfor classes that are not Java records; defaults toZeroArgumentNonVoidMethodPolicy.METHOD_ONLY.voidsetExposeFields(boolean exposeFields)Controls whether public instance fields of classes are exposed to templates.voidsetExposureLevel(int exposureLevel)Sets the method exposure level.voidsetMemberAccessPolicy(MemberAccessPolicy memberAccessPolicy)Sets theMemberAccessPolicy; default isDefaultMemberAccessPolicy.getInstance(Version), which is not appropriate if template editors aren't trusted.voidsetMethodAppearanceFineTuner(MethodAppearanceFineTuner methodAppearanceFineTuner)Used to tweak certain aspects of how methods appear in the data-model; seeMethodAppearanceFineTunerfor more.voidsetMethodsShadowItems(boolean methodsShadowItems)Sets whether methods shadow items in beans.voidsetNullModel(TemplateModel nullModel)Deprecated.Changing thenullmodel can cause a lot of confusion; don't do it.voidsetOuterIdentity(ObjectWrapper outerIdentity)When wrapping an object, the BeansWrapper commonly needs to wrap "sub-objects", for example each element in a wrapped collection.voidsetPreferIndexedReadMethod(boolean preferIndexedReadMethod)Sets if when a JavaBean property has both a normal read method (likeString[] getFoos()) and an indexed read method (likeString getFoos(int index)), and the JavaIntrospectorexposes both (which only happens since Java 8, apparently), which read method will be used when the property is accessed with the shorthand syntax (likemyObj.foos).voidsetRecordZeroArgumentNonVoidMethodPolicy(ZeroArgumentNonVoidMethodPolicy recordZeroArgumentNonVoidMethodPolicy)Sets theZeroArgumentNonVoidMethodPolicyfor classes that are Java records; if theBeansWrapper#BeansWrapper(Version) incompatibleImprovementsof the object wrapper is at least 2.3.33, then this defaults toZeroArgumentNonVoidMethodPolicy.BOTH_METHOD_AND_PROPERTY_UNLESS_BEAN_PROPERTY_READ_METHOD, otherwise this defaults toZeroArgumentNonVoidMethodPolicy.METHOD_ONLY.voidsetSimpleMapWrapper(boolean simpleMapWrapper)When set totrue, the keys inMap-s won't mix with the method names when looking at them from templates.voidsetStrict(boolean strict)Specifies if an attempt to read a bean property that doesn't exist in the wrapped object should throw anInvalidPropertyException.voidsetTreatDefaultMethodsAsBeanMembers(boolean treatDefaultMethodsAsBeanMembers)Controls whether Java 8 default methods that weren't overridden in a class will be recognized as bean property accessors and/or bean actions, and thus will be visible from templates.voidsetUseCache(boolean useCache)Sets whether this wrapper caches theTemplateModel-s created for the Java objects that has wrapped with this object wrapper.protected StringReturns the name-value pairs that describe the configuration of thisBeansWrapper; called fromtoString().toString()Returns the exact class name and the identity hash, also the values of the most often usedBeansWrapperconfiguration properties, also if which (if any) shared class introspection cache it uses.tryUnwrapTo(TemplateModel model, Class<?> targetClass)Attempts to unwrap aTemplateModelto a plain Java object that's the instance of the given class (or isnull).unwrap(TemplateModel model)Attempts to unwrap a model into underlying object.unwrap(TemplateModel model, Class<?> targetClass)Attempts to unwrap a model into an object of the desired class.Wraps the object with a template model that is most specific for the object's class.Wraps a Java method so that it can be called from templates, without wrapping its parent ("this") object.Wraps an object to aTemplateModelthat exposes the object's "native" (usually, Java) API.voidMakes the configuration properties (settings) of thisBeansWrapperobject read-only.
-
Field Details
-
EXPOSE_ALL
public static final int EXPOSE_ALLAt this level of exposure, all methods and properties of the wrapped objects are exposed to the template, and even theMemberAccessPolicyis ignored.- See Also:
- Constant Field Values
-
EXPOSE_SAFE
public static final int EXPOSE_SAFEAt this level of exposure, all methods and properties of the wrapped objects are exposed to the template except methods that are deemed not safe by theMemberAccessPolicy.Note that the
MemberAccessPolicywill further restrict what's visible. That mechanism was introduced much later than "exposure levels", and it's the primary place to look at if you are concerned with safety.- See Also:
- Constant Field Values
-
EXPOSE_PROPERTIES_ONLY
public static final int EXPOSE_PROPERTIES_ONLYAt this level of exposure, only Java Bean properties are exposed. For example, if you havepublic int getX()in a public class, then you can access that in templates likeobj.x(but not asobj.getX()).Note that the
MemberAccessPolicywill further restricts what's visible. Java Bean properties (likeobj.xearlier) whose read method (likegetX()earlier) is not accessible according the policy will not be visible.- See Also:
- Constant Field Values
-
EXPOSE_NOTHING
public static final int EXPOSE_NOTHINGAt this level of exposure, no Java Bean properties, and no 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 theTemplateHashModelinterface. You might want to callsetMethodsShadowItems(boolean)withfalsevalue to speed up map item retrieval.- See Also:
- Constant Field Values
-
-
Constructor Details
-
BeansWrapper
Deprecated.UseBeansWrapperBuilderor, in rare cases,BeansWrapper(Version)instead.Creates a new instance with the incompatible-improvements-version specified inConfiguration.DEFAULT_INCOMPATIBLE_IMPROVEMENTS. -
BeansWrapper
UseBeansWrapperBuilderinstead 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. Notnull. 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 thatObjectWrapperobjects are sometimes shared among multipleConfiguration-s, so the two version numbers are technically independent. But it's recommended to keep those two version numbers the same. Actually, if you leave theobject_wrappersetting at its default (and most do), then that will be kept the same as of theConfiguration.The changes enabled by
incompatibleImprovementsare (but also check the changes atDefaultObjectWrapper(Version), if you are usingDefaultObjectWrapper):-
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
nullarguments were fixed, as earlier they were only seen applicable to parameters of typeObject. Nownull-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 theObjectparameter type. For more details about overloaded method selection changes see the version history in the FreeMarker Manual. -
2.3.24 (or higher):
Iterator-s were always said to be non-empty when using?has_contentand such (i.e., operators that check emptiness without reading any elements). Now anIteratorcounts as empty exactly if it has no elements left. (Note that this bug has never affected basic functionality, like<#list ...>.) -
2.3.26 (or higher): The default of
getTreatDefaultMethodsAsBeanMembers()changes fromfalsetotrue. Thus, Java 8 default methods (and the bean properties they define) are exposed, despite thatIntrospector(the official JavaBeans introspector) ignores them, at least as of Java 8. -
2.3.27 (or higher): The default of the
preferIndexedReadMethodsetting changes fromtruetofalse. -
2.3.33 (or higher): The default of
setRecordZeroArgumentNonVoidMethodPolicy(ZeroArgumentNonVoidMethodPolicy)has changed toZeroArgumentNonVoidMethodPolicy.BOTH_METHOD_AND_PROPERTY_UNLESS_BEAN_PROPERTY_READ_METHOD, fromZeroArgumentNonVoidMethodPolicy.METHOD_ONLY. This means that Java record public methods with 0-arguments and non-void return type are now exposed both as properties, and as methods, while earlier they were only exposed as methods. That is, if in a record you havepublic String name(), now in templates the value can be accessed both asobj.name(like a property), and asobj.name()(for better backward compatibility only - it's bad style).
Note that the version will be normalized to the lowest version where the same incompatible
BeansWrapperimprovements were already present, sogetIncompatibleImprovements()might return a lower version than what you have specified.Note again that most projects use
DefaultObjectWrapper(which extendsBeansWrapper), in which case see the additional changes atDefaultObjectWrapper(Version)!-
- Since:
- 2.3.21
-
BeansWrapper
Same asBeansWrapper(BeansWrapperConfiguration, boolean, boolean)withtruefinalizeConstructionargument.- Since:
- 2.3.21
-
BeansWrapper
protected BeansWrapper(BeansWrapperConfiguration bwConf, boolean writeProtected, boolean finalizeConstruction)Initializes the instance based on theBeansWrapperConfigurationspecified.- Parameters:
writeProtected- Makes the instance's configuration settings read-only viaWriteProtectable.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 callfinalizeConstruction(boolean)itself.- Since:
- 2.3.22
-
-
Method Details
-
finalizeConstruction
protected void finalizeConstruction(boolean writeProtected)Meant to be called afterBeansWrapper(BeansWrapperConfiguration, boolean, boolean)when its last argument wasfalse; 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, ifwriteProtectedwastrue.- Since:
- 2.3.22
-
writeProtect
public void writeProtect()Makes the configuration properties (settings) of thisBeansWrapperobject 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
BeansWrapperBuilderinstead, which gives an instance that's already write protected and also uses some shared caches/pools.- Specified by:
writeProtectin interfaceWriteProtectable- Since:
- 2.3.21
-
isWriteProtected
public boolean isWriteProtected()- Specified by:
isWriteProtectedin interfaceWriteProtectable- Since:
- 2.3.21
-
checkModifiable
protected void checkModifiable()If this object is already read-only according toWriteProtectable, throwsIllegalStateException, 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 anInvalidPropertyException.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 isnull. The template can't tell the difference, and thus always can use?default('something')and?existsand similar built-ins to handle the situation.If this property is
truethen an attempt to read a bean propertly in the template (likemyBean.aProperty) that doesn't exist in the bean object (as opposed to just holdingnullvalue) will causeInvalidPropertyException, which can't be suppressed in the template (not even withmyBean.noSuchProperty?default('something')). This way?default('something')and?existsand similar built-ins can be used to handle existing properties whose value isnull, 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
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
By default returnsthis.- See Also:
setOuterIdentity(ObjectWrapper)
-
setSimpleMapWrapper
public void setSimpleMapWrapper(boolean simpleMapWrapper)When set totrue, the keys inMap-s won't mix with the method names when looking at them from templates. The default isfalsefor backward-compatibility, but is not recommended.When this is
false,myMap.fooormyMap['foo']either returns the methodfoo, or callsMap.get("foo"). If both exists (the method and theMapkey), one will hide the other, depending on theisMethodsShadowItems(), which default totrue(the method wins). Some frameworks use this so that you can callmyMap.get(nonStringKey)from templates [*], but it comes on the cost of polluting the key-set with the method names, and risking methods accidentally hidingMapentries (or the other way around). Thus, this setup is not recommended. (Technical note:Map-s will be wrapped intoMapModelin this case.)When this is
true,myMap.fooormyMap['foo']always callsMap.get("foo"). The methods of theMapobject aren't visible from templates in this case. This, however, spoils themyMap.get(nonStringKey)workaround. But now you can usemyMap(nonStringKey)instead, that is, you can use the map itself as thegetmethod. (Technical note:Map-s will be wrapped intoSimpleMapModelin 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, hencemyMap.getcan return thegetmethod. -
isSimpleMapWrapper
public boolean isSimpleMapWrapper()Tells whether Maps are exposed as simple maps, without access to their method. SeesetSimpleMapWrapper(boolean)for details.- Returns:
- true if Maps are exposed as simple hashes, false if they're exposed as full JavaBeans.
-
getPreferIndexedReadMethod
public boolean getPreferIndexedReadMethod()Getter pair ofsetPreferIndexedReadMethod(boolean)- Since:
- 2.3.27
-
setPreferIndexedReadMethod
public void setPreferIndexedReadMethod(boolean preferIndexedReadMethod)Sets if when a JavaBean property has both a normal read method (likeString[] getFoos()) and an indexed read method (likeString getFoos(int index)), and the JavaIntrospectorexposes both (which only happens since Java 8, apparently), which read method will be used when the property is accessed with the shorthand syntax (likemyObj.foos). BeforeincompatibleImprovements2.3.27 it defaults totruefor backward compatibility (although it's actually less backward compatible if you are just switching to Java 8; see later), but the recommended value and the default starting withincompatibleImprovements2.3.27 isfalse. This setting has no effect on properties that only has normal read method, or only has indexed read method. In case a property has both, using the indexed reader method is disadvantageous, as then FreeMarker can't tell what the highest allowed index is, and so the property will be unlistable (<#list foo as myObj.foos>will fail).Apparently, this setting only matters since Java 8, as before that
Introspectordid not expose the indexed reader method if there was also a normal reader method. As with Java 8 the behavior ofIntrospectorhas changed, some old templates started to break, as the property has suddenly become unlistable (see earlier why). So setting this tofalsecan be seen as a Java 8 compatibility fix.- Since:
- 2.3.27
-
setExposureLevel
public void setExposureLevel(int exposureLevel)Sets the method exposure level. By default, set toEXPOSE_SAFE.- Parameters:
exposureLevel- can be any of theEXPOSE_xxxconstants. Note thatsetMemberAccessPolicy(MemberAccessPolicy)further restricts what's visible, unless this is set toEXPOSE_ALL.
-
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.
-
setTreatDefaultMethodsAsBeanMembers
public void setTreatDefaultMethodsAsBeanMembers(boolean treatDefaultMethodsAsBeanMembers)Controls whether Java 8 default methods that weren't overridden in a class will be recognized as bean property accessors and/or bean actions, and thus will be visible from templates. (We expose bean properties and bean actions, not methods in general.) BeforeincompatibleImprovements2.3.26 this defaults tofalsefor backward compatibility. Starting withincompatibleImprovements2.3.26 it defaults totrue.Some explanation: FreeMarker uses
Introspectorto discover the bean properties and actions of classes, for maximum conformance to the JavaBeans specification. But for some reason (perhaps just a bug in the Oracle/OpenJDK Java 8 implementation) that ignores the Java 8 default methods coming from the interfaces. When this setting istrue, we search for non-overridden default methods ourselves, and add them to the set of discovered bean members.- Since:
- 2.3.26
-
setDefaultZeroArgumentNonVoidMethodPolicy
public void setDefaultZeroArgumentNonVoidMethodPolicy(ZeroArgumentNonVoidMethodPolicy defaultZeroArgumentNonVoidMethodPolicy)Sets theZeroArgumentNonVoidMethodPolicyfor classes that are not Java records; defaults toZeroArgumentNonVoidMethodPolicy.METHOD_ONLY.Note that methods in this class are inherited by
DefaultObjectWrapper, which is what you normally use.- Since:
- 2.3.33
-
setRecordZeroArgumentNonVoidMethodPolicy
public void setRecordZeroArgumentNonVoidMethodPolicy(ZeroArgumentNonVoidMethodPolicy recordZeroArgumentNonVoidMethodPolicy)Sets theZeroArgumentNonVoidMethodPolicyfor classes that are Java records; if theBeansWrapper#BeansWrapper(Version) incompatibleImprovementsof the object wrapper is at least 2.3.33, then this defaults toZeroArgumentNonVoidMethodPolicy.BOTH_METHOD_AND_PROPERTY_UNLESS_BEAN_PROPERTY_READ_METHOD, otherwise this defaults toZeroArgumentNonVoidMethodPolicy.METHOD_ONLY.Note that methods in this class are inherited by
DefaultObjectWrapper, which is what you normally use.- Since:
- 2.3.33
-
isExposeFields
public boolean isExposeFields()Returns whether exposure of public instance fields of classes is enabled. SeesetExposeFields(boolean)for details.- Returns:
- true if public instance fields are exposed, false otherwise.
- Since:
- 2.3.26
-
getTreatDefaultMethodsAsBeanMembers
public boolean getTreatDefaultMethodsAsBeanMembers() -
getDefaultZeroArgumentNonVoidMethodPolicy
- Since:
- 2.3.33
-
getRecordZeroArgumentNonVoidMethodPolicy
- Since:
- 2.3.33
-
getMethodAppearanceFineTuner
-
setMethodAppearanceFineTuner
Used to tweak certain aspects of how methods appear in the data-model; seeMethodAppearanceFineTunerfor more. -
getMemberAccessPolicy
- Since:
- 2.3.30
-
setMemberAccessPolicy
Sets theMemberAccessPolicy; default isDefaultMemberAccessPolicy.getInstance(Version), which is not appropriate if template editors aren't trusted.- Since:
- 2.3.30
-
isClassIntrospectionCacheRestricted
public boolean isClassIntrospectionCacheRestricted()Tells if this instance acts like if its class introspection cache is sharable with otherBeansWrapper-s. A restricted cache denies certain too "antisocial" operations, likeclearClassIntrospectionCache(). The value depends on how the instance was created; with a public constructor (then this isfalse), or withBeansWrapperBuilder(then it'strue). 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 willtrueeven 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 callobject.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 plainjava.util.Dateinstead ofjava.sql.Dateorjava.sql.Timeorjava.sql.Timestamp. Default value isTemplateDateModel.UNKNOWN.- Parameters:
defaultDateType- the new default date type.
-
getDefaultDateType
public int getDefaultDateType()Returns the default date type. SeesetDefaultDateType(int)for details.- Returns:
- the default date type
-
setUseCache
public void setUseCache(boolean useCache)Sets whether this wrapper caches theTemplateModel-s created for the Java objects that has wrapped with this object wrapper. Default isfalse. When set totrue, callingwrap(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
Deprecated.Changing thenullmodel can cause a lot of confusion; don't do it.Sets the null model. This model is returned from thewrap(Object)method whenever the wrapped object isnull. It defaults tonull, 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, thenullModelshould be anAdapterTemplateModelthat returnsnullforAdapterTemplateModel.getAdaptedObject(Class). -
getIncompatibleImprovements
Returns the version given withBeansWrapper(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
Deprecated.UseBeansWrapperBuilderinstead. 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 byObjectWrapper.BEANS_WRAPPERand 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 theEXPOSE_SAFEexposure level, and uses null reference as the null model. -
wrap
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
NumberModelfor it, - if the object is a Date returns a
DateModelfor it, - if the object is a Boolean returns
TemplateBooleanModel.TRUEorTemplateBooleanModel.FALSE - if the object is already a TemplateModel, returns it unchanged,
- if the object is an array, returns a
ArrayModelfor it - if the object is a Map, returns a
MapModelfor it - if the object is a Collection, returns a
CollectionModelfor it - if the object is an Iterator, returns a
IteratorModelfor it - if the object is an Enumeration, returns a
EnumerationModelfor it - if the object is a String, returns a
StringModelfor it - otherwise, returns a
GenericObjectModelfor it.
- Specified by:
wrapin interfaceObjectWrapper- Parameters:
object- The object to wrap into aTemplateModel. If it already implementsTemplateModel, it should just return the object as is. If it'snull, the method should returnnull(however,BeansWrapper, has a legacy option for returning a null model object instead, but it's not a good idea).- Returns:
- a
TemplateModelwrapper of the object passed in. To support un-wrapping, you may consider the return value to implementWrapperTemplateModelandAdapterTemplateModel. The default expectation is that theTemplateModelisn't less thread safe than the wrapped object. If theObjectWrapperreturns 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
- if the object is null, returns the
-
wrap
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 resultingTemplateHashModelby name. Except, if the wrapped method is overloaded, with this method you explicitly select an overload, while otherwise you would get aTemplateMethodModelExthat selects an overload each time it's called based on the argument values.- Parameters:
object- The object whose method will be called, ornullifmethodis a static method. This object will be used "as is", like without unwrapping it if it's aTemplateModelAdapter.method- The method to call, which must be an (inherited) member of the class ofobject, as described byMethod.invoke(Object, Object...)- Since:
- 2.3.22
-
wrapAsAPI
Description copied from interface:ObjectWrapperWithAPISupportWraps an object to aTemplateModelthat exposes the object's "native" (usually, Java) API.- Specified by:
wrapAsAPIin interfaceObjectWrapperWithAPISupport- Parameters:
obj- The object for which the API model has to be returned. Shouldn't benull.- Returns:
- The
TemplateModelthrough which the API of the object can be accessed. Can't benull. - Throws:
TemplateModelException- Since:
- 2.3.22
-
getInstance
Deprecated.overridegetModelFactory(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 wrapfactory- The factory that wraps the object
-
getModelFactory
-
unwrap
Attempts to unwrap a model into underlying object. Generally, this method is the inverse of thewrap(Object)method. In addition it will unwrap arbitraryTemplateNumberModelinstances into a number, arbitraryTemplateDateModelinstances into a date,TemplateScalarModelinstances into a String, arbitraryTemplateBooleanModelinstances into a Boolean, arbitraryTemplateHashModelinstances into a Map, arbitraryTemplateSequenceModelinto a List, and arbitraryTemplateCollectionModelinto a Set. All other objects are returned unchanged.- Specified by:
unwrapin interfaceObjectWrapperAndUnwrapper- Returns:
- The plain Java object. Can be
null, ifnullis the appropriate Java value to represent the template model.nullmust not be used to indicate an unwrapping failure. It must NOT beObjectWrapperAndUnwrapper.CANT_UNWRAP_TO_TARGET_CLASS. - Throws:
TemplateModelException- if an attempted unwrapping fails.- See Also:
ObjectWrapperAndUnwrapper.tryUnwrapTo(TemplateModel, Class)
-
unwrap
Attempts to unwrap a model into an object of the desired class. Generally, this method is the inverse of thewrap(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 unwraptargetClass- the class of the unwrapped result;Object.classif 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
Description copied from interface:ObjectWrapperAndUnwrapperAttempts to unwrap aTemplateModelto a plain Java object that's the instance of the given class (or isnull).- Specified by:
tryUnwrapToin interfaceObjectWrapperAndUnwrappertargetClass- The class that the return value must be an instance of (except when the return value isnull). Can't benull; if the caller doesn't care, it should either use {#unwrap(TemplateModel)}, orObject.classas the parameter value.- Returns:
- The unwrapped value that's either an instance of
targetClass, or isnull(ifnullis the appropriate Java value to represent the template model), or isObjectWrapperAndUnwrapper.CANT_UNWRAP_TO_TARGET_CLASSif the unwrapping can't satisfy thetargetClass(nor the result can benull). However,ObjectWrapperAndUnwrapper.CANT_UNWRAP_TO_TARGET_CLASSmust not be returned if thetargetClassparameter wasObject.class. - Throws:
TemplateModelException- If the unwrapping fails for a reason than doesn't fit the meaning of theObjectWrapperAndUnwrapper.CANT_UNWRAP_TO_TARGET_CLASSreturn value.- Since:
- 2.3.22
- See Also:
ObjectWrapperAndUnwrapper.unwrap(TemplateModel)
-
invokeMethod
protected TemplateModel invokeMethod(Object object, Method method, Object[] args) throws InvocationTargetException, IllegalAccessException, TemplateModelExceptionInvokes the specified method, wrapping the return value. All method invocations done in templates should go through this (assuming the target object was wrapped with thisObjectWrapper).This method is protected since 2.3.30; before that it was package private. The intended application of overriding this is monitoring what calls are made from templates. That can be useful to asses what will be needed in a
WhitelistMemberAccessPolicyfor example. Note thatObject.toString()calls caused by type conversion (like when you have${myObject}) will not go through here, as they aren't called by the template directly (and aren't called via reflection). On the other hand,${myObject[key]}, ifmyObjectis not aMap, will go through here as aget(String|Object)method call, if there's a such method.If the return value is null, and the return type of the invoked method is void,
TemplateModel.NOTHINGis returned.- Parameters:
object- the object to invoke the method on (nullmay be null for static methods)method- the method to invokeargs- the arguments to the method- Returns:
- the wrapped return value of the method.
- Throws:
InvocationTargetException- if the invoked method threw an exceptionIllegalAccessException- if the method can't be invoked due to an access restriction.TemplateModelException- if the return value couldn't be wrapped (this can happen if the wrapper has an outer identity or is subclassed, and the outer identity or the subclass throws an exception. Plain BeansWrapper never throws TemplateModelException).- Since:
- 2.3.30
- See Also:
readField(Object, Field)
-
readField
protected TemplateModel readField(Object object, Field field) throws IllegalAccessException, TemplateModelExceptionReads the specified field, returns its value asTemplateModel. All field reading done in templates should go through this (assuming the target object was wrapped with thisObjectWrapper).Just like in the case of
invokeMethod(Object, Method, Object[]), overriding this can be useful if you want to monitor what members are accessed by templates. However, it has the caveat that final field values are possibly cached, so you won't see all reads. Furthermore, at least static models pre-read final fields, so they will be read even if the templates don't read them.- Throws:
IllegalAccessExceptionTemplateModelException- Since:
- 2.3.30
- See Also:
invokeMethod(Object, Method, Object[])
-
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 theSystem.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
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.enums["java.math.RoundingMode"].UPto access theRoundingMode.UPvalue.- 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
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 ofTemplateModel-s to pass to the constructor after unwrapping them- Returns:
- The instance created; it's not wrapped into
TemplateModel. - Throws:
TemplateModelException
-
removeFromClassIntrospectionCache
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
Deprecated.There's a typo in this method name, so useclearClassIntrospectionCache()instead.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- ifisClassIntrospectionCacheRestricted()istrue.- Since:
- 2.3.20
-
clearClassIntrospectionCache
public void clearClassIntrospectionCache()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- ifisClassIntrospectionCacheRestricted()istrue.- Since:
- 2.3.29 (in earlier versions use
clearClassIntrospecitonCache())
-
finetuneMethodAppearance
@Deprecated protected void finetuneMethodAppearance(Class<?> clazz, Method m, BeansWrapper.MethodAppearanceDecision decision)Deprecated.UsesetMethodAppearanceFineTuner(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 themethodAppearanceFineTunerproperty is set to non-null, this method is not called anymore. -
coerceBigDecimals
Converts anyBigDecimals in the passed array to the type of the corresponding formal argument of the method. -
coerceBigDecimals
Converts anyBigDecimal-s in the passed array to the type of the corresponding formal argument of the method viacoerceBigDecimal(BigDecimal, Class). -
coerceBigDecimal
ConvertsBigDecimalto the class given in theformalTypeargument if that's a known numerical type, returns theBigDecimalas is otherwise. Overflow and precision loss are possible, similarly as with casting in Java. -
toString
Returns the exact class name and the identity hash, also the values of the most often usedBeansWrapperconfiguration properties, also if which (if any) shared class introspection cache it uses. -
toPropertiesString
Returns the name-value pairs that describe the configuration of thisBeansWrapper; called fromtoString(). 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
-
BeansWrapperBuilderor, in rare cases,BeansWrapper(Version)instead.