Interface ExtensionHandler
-
- All Known Implementing Classes:
CloneableHandler
,CompletableHandler
,FreezableHandler
,GsonSupportHandler
,Jackson2SupportHandler
,LazyInitHandler
,ModificationAwareHandler
,NullSafeHandler
,StatefulExtensionHandler
,StatelessExtensionHandler
public interface ExtensionHandler
ExtensionHandler
s contain the logic for handling calls to extension interfaces of IBeans. They are used byProxyIBeanFactory
for internal extension interfaces but also for any custom extension interface. SeeIBeanFactory
for general descriptions about extension interfaces.ExtensionHandler
itself is just an interface and each extension interface requires its individual implementation ofExtensionHandler
. For example built in extension interfaceNullSafe
uses its matching handler implementationNullSafeHandler
.If you are just using existing extension interfaces provided by the IBean framework you will normally not get in touch with
ExtensionHandler
s. They become relevant if you want to implement your own extension interface. In this case you need to implementExtensionHandler
, bundle it with the extension interface usingExtensionSupport
and configure it in theProxyIBeanFactory
(ProxyIBeanFactory.Builder.withInterfaceSupport(ExtensionSupport)
).ExtensionHandler
implementations need to be instanciated by theIBeanFactory
. Therefore they need to have a public constructor without arguments. The implementation class itself also needs to be public.To increase performance by avoiding unnecessary instance creation two types of
ExtensionHandler
s were introduced, stateful and stateless handlers. Stateful handlers are used for extension interfaces that enrich the state of an IBean. Therefore each IBean instance holds its individual handler instance. For statelessExtensionHandler
s only one instances is created initially and that instance serves all interface calls to any bean.
For example extension interfaceModificationAware
requires a stateful handler as the handler needs to store a dirty flag internally, whereasNullSafe
can run with a stateless handler.
Whether stateful or stateless is determined inExtensionSupport
when configuring a handler for a factory.An IBean receives three types of method calls,
- calls to setter methods,
- calls to getter methods and
- calls to extension interface methods
As only the extension interface logic must be provided an the only mandatory overwritten method ishandleExtendedInterfaceCall(IBeanContext, IBeanFieldAccess, Object, Method, Object[])
. An implementation may overrideinterceptGetterCall(IBeanContext, IBeanFieldMetaInfo, Object, Object)
orinterceptSetterCall(IBeanContext, IBeanFieldMetaInfo, Object, Object)
for hooking into getter and setter calls.Handlers for built-in extension interfaces do not implement
ExtensionHandler
directly but extend eitherStatefulExtensionHandler
orStatelessExtensionHandler
. This is recommended for custom handlers as well.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description Object
handleExtendedInterfaceCall(IBeanContext<?> context, IBeanFieldAccess bean, Object proxyInstance, Method method, Object[] params)
Handles all calls to methods of its related extension interface.default Object
interceptGetterCall(IBeanContext<?> context, IBeanFieldMetaInfo fieldMeta, Object returnValue, Object proxyInstance)
Called as an optional hook with every getter call on an IBean.default Object
interceptSetterCall(IBeanContext<?> context, IBeanFieldMetaInfo fieldMeta, Object newValue, Object proxyInstance)
Called as an optional hook with every setter call on an IBean.default void
onInitStateful(Object proxyInstance, IBeanTypeMetaInfo<?> metaInfo, IBeanFactory factory)
Initialization method for stateful handlers that is called after initialization of the IBean.
-
-
-
Method Detail
-
handleExtendedInterfaceCall
Object handleExtendedInterfaceCall(IBeanContext<?> context, IBeanFieldAccess bean, Object proxyInstance, Method method, Object[] params) throws Throwable
Handles all calls to methods of its related extension interface. This is the only method that needs to be overwritten when creating a newExtensionHandler
implementations, all other methods are optional and have default implementations.When a method of an extension interface is called on an IBean the bean looks up the matching
ExtensionHandler
for the extension and calls this method on the handler. As the IBean implementation in this package is based on Java proxieshandleExtendedInterfaceCall
is very similar toInvocationHandler.invoke(Object, Method, Object[])
just extended by some IBean scope information. The last three parameters (proxyInstance
,method
andparams
) are simply passed through from theInvocationHandler
of the IBean. Therefore when implementing this method you need to follow the same rules that you need to consider when implementing anInvocationHandler
, for example in terms of thrown exceptions or return types.Bean values can be read or manipulated by this method. Used the passed
bean
parameter for doing so.The return value or exception coming out of this method will be the return value or exception returned from the extension method call.
- Parameters:
context
- provides meta information about the beanbean
- allows this method to read or change field values of the IBeanproxyInstance
- the IBean instance object (seeInvocationHandler.invoke(Object, Method, Object[])
for more details)method
- theMethod
of the extension interface that was called on the IBean (seeInvocationHandler.invoke(Object, Method, Object[])
for more details)params
- the parameters passed to the extension method call (seeInvocationHandler.invoke(Object, Method, Object[])
for more details)- Returns:
- an object that matches to the return type of the extension
method; return
null
if the return type isvoid
. (seeInvocationHandler.invoke(Object, Method, Object[])
for more details) - Throws:
Throwable
- can be anyError
,RuntimeException
or checked exception that is definied in the signature of the extension method. (seeInvocationHandler.invoke(Object, Method, Object[])
for more details)
-
interceptGetterCall
default Object interceptGetterCall(IBeanContext<?> context, IBeanFieldMetaInfo fieldMeta, Object returnValue, Object proxyInstance)
Called as an optional hook with every getter call on an IBean. Getter calls on IBeans are handled by the IBean implementation itself but anExtensionHandler
can implement this method to hook into the getter call. It can just peak on the return value or it can even change it or throw an exception.When you have several extension handlers registered for an IBean type the intercept calls will be called in the order in which the handlers are registered in the
ProxyIBeanFactory
. See alsoProxyIBeanFactory.Builder.withInterfaceSupport(ExtensionSupport)
.The default implementation just returns
returnValue
.- Parameters:
context
- provides meta information about the IBeanfieldMeta
- provides meta information about the field related to the getterreturnValue
- the current return value of the getter. This must not match to the field value of the IBean as the value might have already been changed by intercept calls from other handlersproxyInstance
- the IBean instance itself- Returns:
- the value to be returned from the getter call. If you do not want
to change the getter return value just pass the value provided in
returnValue
-
interceptSetterCall
default Object interceptSetterCall(IBeanContext<?> context, IBeanFieldMetaInfo fieldMeta, Object newValue, Object proxyInstance)
Called as an optional hook with every setter call on an IBean. Setter calls on IBeans are handled by the IBean implementation itself but anExtensionHandler
can implement this method to hook into the setter call. It can just peak on the new value or it can even change it or throw an exception.When you have several extension handlers registered for an IBean type the intercept calls will be called in the order in which the handlers are registered in the
ProxyIBeanFactory
. See alsoProxyIBeanFactory.Builder.withInterfaceSupport(ExtensionSupport)
.The default implementation just returns
newValue
.- Parameters:
context
- provides meta information about the IBeanfieldMeta
- provides meta information about the field related to the setternewValue
- the current new value of the field. This must not match to the initial value given in the setter call of the IBean as the value might have already been changed by intercept calls from other handlersproxyInstance
- the IBean instance itself- Returns:
- the value the field is supposed to be set to. If you do not want
to change the value just pass the value provided in
newValue
-
onInitStateful
default void onInitStateful(Object proxyInstance, IBeanTypeMetaInfo<?> metaInfo, IBeanFactory factory)
Initialization method for stateful handlers that is called after initialization of the IBean. If a handler is registered as stateful a new instance of theExtensionHandler
implementation is created for each new IBean. After the IBean itself and all handlers created this method is called on all stateful handlers. This method should therefore be overwritten if a handler needs some initialization after creation.The default implementation does nothing.
- Parameters:
proxyInstance
- the IBean instancemetaInfo
- meta information about the IBeanfactory
- the factory that creates the IBean instance
-
-