Handler ArchitectureWSO2 Governance Registry

(By Denuwanthi De Silva)

HandlersHandlers are pluggable components, that

contain custom processing logic for handling resources.

High Level Handler Architecture

CacheBackedRegistry

UserRegistry

EmbeddedRegistry

HandlerLifeCycleManager

HandlerManager

Handlers

Filters Repository

FiltersHelp to filter the handlers which will be

executed on the resource.

1. Where Handlers & Filters are defined ?a. in registry.xml

Ex:<handler class="org.wso2.carbon.registry.extensions.handlers.ExtensionsSymLinkHandler" profiles="default,uddi-registry"><handler class="org.wso2.carbon.governance.registry.extensions.handlers.UriMediaTypeHandler" profiles="default,uddi-registry">

<filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.URLMatcher">

b. in registry-core (built-in handlers)Ex:

org.wso2.carbon.registry.core.jdbc.handlers.builtin.OperationStatisticsHandler

c. in carbon-registryEx:

Handler: org.wso2.carbon.registry.profiles.handlers.ProfilesAddHandler

Filter: org.wso2.carbon.registry.extensions.filters.EndpointMediaTypeMatcher

d. in carbon-governance

e. custom handler jars (dropins folder)f. mangement console

2. Writing a custom handler

● Extend the Handler class and override necessary methods.● Implement whatever custom behaviors in overwritten methods. You may use information provided in the RequestContext instance, in

your custom implementation.● Once the custom behavior is completed, it is usually required to perform the actual requested operation (for example, add the resource

in put(...) method).

public class CustomHandler extends Handler{@overridepublic void put(RequestContext requestContext) throws RegistryException {

String resourcePath = requestContext.getResourcePath().getPath(); Registry registry = requestContext.getRegistry(); if(registry.resourceExists(resourcePath)) { registry.applyTag(resourcePath, "CustomTag"); }

}}

RequestContext: holds all resource related information regarding a request.

Ex:● resourcePath● resource● sourceURL● parentPath

3. Two built-in Filter implementations for most common filtering scenarios are shipped with the Registry

● MediaTypeMatcher - Filters are based on the Media type of the resource.● URLMatcher - Evaluates to true, if the current resource path matches with a preconfigured regular expression.

Customized filters can be implemented by extending ‘Filter’ class or the above two Filters.Ex:- EndpointMediaTypeMatcher extends MediaTypeMatcher

4. Adding Handlers- Adding all the defined handlers (registry.xml, registry-core, etc), with the server startup.

RegistryConfigurationProcessor

HandlerLifeCycleManager

HandlerManager

ServiceComponents

registry.xml

built-in handlers*registry-core

*carbon-registry*carbon-gov

● RegistryConfigurationProcessor● populateRegistryConfig(): Extracts the registry.xml as an OMElement.● initializeHandlers(): Extracts ‘handler’ related parts from that OMElement.● buildHandler():

- Builds a handler definition object out of the handler OMElement .- Set the properties (<property>) of each handler & filter.- Invokes HandlerLifeCycleManager.

● ServiceComponents● Declarative service components.

Ex: - RegistryCoreServiceComponent (registry-core)- RegistryEventingServiceComponent (carbon-registry)- GovernanceMgtUIListMetadataServiceComponent (carbon-governance)

handlerLifeCycleManager.addHandler(methods,new Filter(),new Handler()) - Register/Setup built-in handlers and set properties of handlers & filters.

● Invokes HandlerLifeCycleManager.

Set Properties of Handlers & Filters

<handler class="org.wso2.carbon.registry.extensions.handlers.WSDLMediaTypeHandler" profiles="default,uddi-registry"> <property name="schemaLocationConfiguration" type="xml">

<location>/trunk/schemas/</location></property>

<filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher"> <property name="mediaType">application/wsdl+xml</property> </filter></handler>

Handler related properties are useful when using those handlers on resources. (Ex:

where to store schema )

Filter related properties are useful when filtering which handlers to be used on a resource.

(Ex: The above handler will be executed on a resource only if its media type is

‘application/wsdl+xml’)

Set Properties of Handlers & Filters

Use the setter methods in the related filter & handler classes to set those properties in the server startup.Ex:The property ‘mediaType’ has a corresponding ‘setMediaType’ method in the ‘MediaTypeMatcher’ filter.The property ‘pattern’ has a corresponding ‘setPattern’ method in the ‘URLMatcher’ filter.

● HandlerLifeCycleManagerManage handlers belonging to a particular lifecycle phase. (not the artifact LC state, we normally

refer).

Keeps a HandlerManager for each lifecycle phase using a HashtableHashtable<String, HandlerManager>

Invoking HandlerLifeCycleManager

HandlerLifeCycleManager

tenant

system

reporting

commit

rollback

Handler1

Handler2

Handler3

user HandlerManager

HandlerManager

HandlerManager

default HandlerManager

HandlerManager

HandlerManager

HandlerManager

●●●●●●●●●●●●●●●

Phases

Pre-Commit Handler Phases:default (built-in handlers)tenant (MountHandler (built-in-handler). When Mounted or Mounted+ tenant login)system (handlers defined in registry.xml)user (handlers uploaded & configured via mgt console (include tenant login + custom handler via magt console))reporting (eventing, statistic & simulation handlers)

Post-Commit Handler Phases:

commit (if a commit succeeds these handlers are executed)

rollback (if commit fails these handlers are executed)

Handler & Filter object with a lifecycle phase (if a phase is not given HandlerLifeCycleManager will attach ‘default’ phase to it)

HandlerLifeCycleManager

addHandler(String[] methods, Filter filter, Handler handler, String lifecyclePhase)

get the HandlerManager associated with the given ‘lifecyclePhase’

Invoke the HandlerManager

Invoking HandlerManager

● HandlerManagerManages the handlers and their invocations.

Maps of <Filter, Set<Handler>> pairs. A map exists for each supported operation.

HandlerManager

getHandlerMap<>putHandlerMap<>deleteHandlerMap<>importHandlerMap<>putChildHandlerMap<>importChildHandlerMap<>invokeAspectHandlerMap<>moveHandlerMap<>copyHandlerMap<>renameHandlerMap<>createLinkHandlerMap<>removeLinkHandlerMap<>addAssociationHandlerMap<>removeAssociationHandlerMap<>getAssociationsHandlerMap<>getAllAssociationsHandlerMap<>applyTagHandlerMap<>getResourcePathsWithTagHandlerMap<>getTagsHandlerMap<>removeTagHandlerMap<>addCommentHandlerMap<>editCommentHandlerMap<>removeCommentHandlerMap<>getCommentsHandlerMap<>rateResourceHandlerMap<>getAverageRatingHandlerMap<>getRatingHandlerMap<>createVersionHandlerMap<>getVersionsHandlerMap<>restoreVersionHandlerMap<>executeQueryHandlerMap<>searchContentHandlerMap<>resourceExistsHandlerMap<>getRegistryContextHandlerMap<>

Filter1

Handler1

Handler2

Handler3

Each handler should be registered with a Filter

HandlerLifeCycleManager

HandlerManager

addHandler(String[] methods, Filter filter, Handler handler) Handlers, which are required to be invoked must be registered using the ‘addHandler’ method.

Puts handlers to corresponding maps.

addHandler(String[] methods, Filter filter, Handler handler)

Handler

methods="GET,PUT,DELETE”

getHandlerMap<>

putHandlerMap<>

deleteHandlerMap<>

methods=null

getHandlerMap<>putHandlerMap<>deleteHandlerMap<>importHandlerMap<>putChildHandlerMap<>importChildHandlerMap<>invokeAspectHandlerMap<>moveHandlerMap<>copyHandlerMap<>renameHandlerMap<>createLinkHandlerMap<>removeLinkHandlerMap<>addAssociationHandlerMap<>removeAssociationHandlerMap<>getAssociationsHandlerMap<>getAllAssociationsHandlerMap<>applyTagHandlerMap<>getResourcePathsWithTagHandlerMap<>getTagsHandlerMap<>removeTagHandlerMap<>addCommentHandlerMap<>editCommentHandlerMap<>removeCommentHandlerMap<>getCommentsHandlerMap<>rateResourceHandlerMap<>getAverageRatingHandlerMap<>getRatingHandlerMap<>createVersionHandlerMap<>getVersionsHandlerMap<>restoreVersionHandlerMap<>executeQueryHandlerMap<>searchContentHandlerMap<>resourceExistsHandlerMap<>getRegistryContextHandlerMap<>

<handler class="org.wso2.carbon.registry.extensions.handlers.RetentionHandler" methods="GET,PUT,DELETE"> </handler>

5. Invoking Handlers.

Resource

operationX()

Registry.operationX()

HandlerLifeCycleManager.operationX()

HandlerManager.operationX()

Handler.operationX()

Registry.operationX()

HandlerLifeCycleManager.operationX()

EmbeddedRegistry

operationX()

HandlerLifeCycleManager.operationX()

default HandlerManager.operationX()

tenant HandlerManager.operationX()

system HandlerManager.operationX()

user HandlerManager.operationX()

reporting HandlerManager.operationX()

HandlerLifeCycleManager

operationX()

processing is not complete

proc

essi

ng c

ompl

ete

processing is not complete

Filter1,Handler1 Handler2

Filter2,Handler3..FilterM,HandlerN

operationX Map

HandlerManager.operationX()

Filter

<filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher"> <property name="mediaType">application/wsdl+xml</property> </filter>

handleOperationX() determines whether the associating handlers should handle the operationX of the resource. Thus, filter is always evaluated before invoking the handlers.

Writing a custom filter which will only execute its handler if and only if the resource author is ‘admin’

5.Writing Custom Filter

-Create a custom filter class by extending generic Filter class or an existing filter class like MediaTypeMatcher or URLMatcher.-override the method you want to be executed. (If you want your handler to be executed only for put methods, you have to makesure the handlePut method of the corresponding Filter class returns true)

Ex: @Overridepublic boolean handlePut(RequestContext requestContext) throws RegistryException {

Resource resource = requestContext.getResource(); if (resource == null) { return false; } String resourceAuthor=resource.getAuthorUserName(); return resourceAuthor!=null && resourceAuthor.equals(author);

}

Corresponding registry.xml entry:<handler class="org.wso2.carbon.registry.samples.handler.CustomHandler"> <filter class="org.wso2.carbon.registry.samples.filter.CustomFilter"> <property name="author">admin</property> </filter></handler>Since the filter property is ‘author’. You need to have a corresponding setAuthor() method in your custom filter. Setter method = (set+property name)public void setAuthor(String resourceAuthor){ this.author = resourceAuthor;

}

.

.

.

.

.

operationX(){get the operationX map;loop{

}

}

Filter1 Handler1Handler2.HanlderN

Filter2 HandlerAHandler3.HanlderM

operationX Map

FilterX

Handler1.operationX()

exit loop

handleOperationX()==true

HandlerManager

Handler2.operationX() Handler3.operationX()

default

tenant

system

user

Phases

processing complete==true

operationX(){get the operationX map;loop{

}

}

FilterX

Handler1.operationX() Handler2.operationX() Handler3.operationX()

handleOperationX()==true

Phases

.

.

.

.

.

Filter1 Handler1Handler2.HanlderN

Filter2 HandlerAHandler3.HanlderM

reporting

rollback

commit

HandlerManager

operationX Map

Handler.operationX()

operationX(){

setProcessingComplete(true)

}

custom implementation of operationX

Once this is set, no more handlers of it’s phase(default/tenant/system/user) will be invoked.

The handlers belonging to reporting, rollback & commit phases will invoke all the handlers even if this is set.

References

[1]https://www.youtube.com/watch?v=4Dy3tnRHgt4[2]https://docs.wso2.com/display/Governance460/Configuring+Handlers[3]https://docs.wso2.com/display/Governance460/Configuring+Filters[4]https://docs.wso2.com/display/Governance460/Handler+Architecture[5]http://cnapagoda.blogspot.com/2014/02/wso2-governance-registry-apply-tags.html

Thank You!