WSO2 Governance Registry - Developer Guide [ Documentation Index ]

WSO2 Governance Registry - Developer User Guide

Extending Governance Registry

Governance Registry has lot of functionalities built-in. But there may be instances that you want to add custom functionality to the Registry. In such scenarios you can use the extending APIs provided by the Registry.

There are 3 main ways you can extend the Registry.

Handlers
Filters
Aspects

We will discuss each of these methods in the following sections.

Handlers

Handlers are pluggable components, that contain custom processing logic for handling resources. All handlers extend an abstract class named Handler, which provides default implementations for resource handling methods as well as a few utilities useful for concrete handler implementations. Handler implementations can provide alternative behaviors for basic resource related operations, by overwriting one or more methods in the Handler class. At this point, is useful to look at the Handler class listed below (please note that some details are omitted for clarity).

Figure 1: Handler class

Here is a description on how each of these handler works.

Method	Important parameters (To extract from Request Context)	Return value	Description
Get	requestContext.getResourcePath() // path get is called	Resource // the resource at the path	Retrieve a resource in a given path
Put	requestContext.getResourcePath() // path put is called requestContext.getResourceh() // the resource to store	-	Store a resource in a given path
importResource	requestContext.getResourcePath() // path importResource is called requestContext.getSourceURL() // the URL of the importing resource	-	Import a resource from a URL
move	requestContext.getSourcePath() // source to move from requestContext.getTargetPath() // target to move to	String // the new path	Move a resource from one to another
copy	requestContext.getSourcePath() // source to copy from requestContext.getTargetPath() // target to copy to	String // the new path	Copy a resource from one to another
rename	requestContext.getSourcePath() // source of the resource requestContext.getTargetPath() // the new name	String // the new path	Change a name of a resource
createLink	requestContext.getResourcePath() // the path of the link is creating requestContext.getTargetPath() // the target path or the target registry url requestContext.getTargetSubPath() // the target sub path if the target is a remote url	-	Create a symlink or a remote link
removeLink	requestContext.getResourcePath() // the path of the link to remove	-	Remove a link
delete	requestContext.getResourcePath() // the path of the resource to remove	-	Delete a resource. If this is a collection, all the childs will also be removed.
putChild	requestContext.getResourcePath() // the path resource is putting requestContext.getResource() // the resource to put	String // the path of the resource	Called when putting a resource to any path except root.
putChild	requestContext.getResourcePath() // the path resource is putting requestContext.getResource() // the resource to put	String // the path of the resource	Called when putting a resource to any path except root.
importChild	requestContext.getResourcePath() // the path resource is importing to requestContext.getSourceURL() // the URL of the importing resource	String // the path of the resource	Called when importing a resource to any path except root.
invokeAspect	requestContext.getResource() // the resource to invoke the aspect requestContext.getAspect() // the Aspect object to be invoked requestContext.getAction() // the action of the Aspect	-	Triggered when invoking an aspect (Aspects are described in detail in following sections).
addAssociation	requestContext.getSourcePath() // left branch of the association requestContext.getTargetPath() // right branch of the association requestContext.getAssociationType() // the type of the association	-	Triggered when adding an association
removeAssociation	requestContext.getSourcePath() // left branch of the association requestContext.getTargetPath() // right branch of the association requestContext.getAssociationType() // the type of the association	-	Triggered when removing an association
getAllAssociations	requestContext.getResourcePath() // the path of the resource	Association[]	Return all the associations of a given resource.
getAssociations	requestContext.getResourcePath() // the path of the resource requestContext.getAssociationType() // the type of the association	Association[]	Return associations of a give association type of a given resource.
applyTag	requestContext.getResourcePath() // the path of the resource requestContext.getTag() // the tag to be added	-	Apply a tag to a perticular path
removeTag	requestContext.getResourcePath() // the path of the resource requestContext.getTag() // the tag to be removed	-	Remove a tag in a perticular path
rateResource	requestContext.getResourcePath() // the path of the resource requestContext.getRating() // the value of the rating	-	Triggered when Rating a resource
restoreVersion	requestContext.getVersionPath() // the path + version of the resource	-	Triggered when restoring a versioned resource.
createVersion	requestContext.getResourcePath() // Create a version of a resource	-	Triggered when creating a resource
editComment	requestContext.getCommentPath() // The path of the comment of a resource requestContext.getText() // The comment text	-	Edit a comment in a given path
addComment	requestContext.getResourcePath() // The path of the resource requestContext.getText() // The comment text	String // the comment path	Add a comment to the given path.
getComments	requestContext.getResourcePath() // The path of the resource	Comment[]	get all comments in a given path.
getAverageRating	requestContext.getResourcePath() // The path of the resource	float	Get the average rating of a resource
getRating	requestContext.getResourcePath() // The path of the resource requestContext.getUserName() // The path of the resource	int	Get the rating given by a user to a given resource
getVersions	requestContext.getResourcePath() // The path of the resource	String[]	Retruns version paths of a given resource.
getTags	requestContext.getResourcePath() // The path of the resource	Tag[]	Retruns tags of a given resource.
getResourcePathWithTag	requestContext.getResourcePath() // The path of the resource requestContext.getTag() // The value of the tag	TaggedResourcePath[]	Retruns resource paths with a given tag
executeQuery	requestContext.getResourcePath() // The path of the query requestContext.getQueryParameters() // The query parameters	Collection	Retruns collection (paths as the content) queried in the given query
resourceExists	requestContext.getResourcePath() // The path of the resource	boolean	Retruns whether the resource in the given path exists
dump	requestContext.getResourcePath() // The path of the resource requestContext.getDumpingWriter() // The writer that requested in dumping	-	Dump a perticular path
restore	requestContext.getResourcePath() // The path of the resource requestContext.getDumpingReader() // The reader that used with restoring	-	Restore a dump

Handlers can be engaged and configured using the registry configuration file (registry.xml). Here is an example of using registry.xml to declare a handler.

    <handler class="org.wso2.carbon.registry.extensions.handlers.WSDLMediaTypeHandler">
        <property name="schemaLocationConfiguration" type="xml">
            <locationType>absolute</locationType>
            <location>/governance/schemas/</location>
        </property>
        <property name="wsdlLocationConfiguration" type="xml">
            <locationType>absolute</locationType>  <!-- absolute or relative -->
            <location>/governance/wsdls/</location>
        </property>
        <filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
            <property name="mediaType">application/wsdl+xml</property>
        </filter>
    </handler>

Here are the important parameters you can provide in the handler configuration.

Handler class : The class name of the handler. Provided in the "class" attribute in the Handler

Example:

    <handler class="org.wso2.carbon.registry.extensions.handlers.WSDLMediaTypeHandler">
       ...
    </handler>

Handler properties : Custom properties that will be used in handler processing logic. Example of a handler property.
```
    <property name="wsdlLocationConfiguration" type="xml">
```
The attributes in the property element
- name: The name of the property. In order to store the property value you should have an setter method in the particular handler class. The method name should be "set" + property name with first letter capitalized. The method name for the above property would be:
```
setWsdlLocationConfiguration
```
- type: The type of the property. Possible values are "xml" and null. If the type is "xml" the handler method should have an method argument of the type 'org.apache.axiom.om.OMElement'. If the type attribute is not given, the method argument will be of type 'java.lang.String'. So the method signaure for the above example property is:
```
    public void setWsdlLocationConfiguration(OMElement locationConfiguration) throws RegistryException {
    }  
```
Filter Associated with the Handler: You can refer a filter inside a handler which would provid the filter functionality to that perticular handler. The handler for a perticular method is invoked only if the filter is returning true for the corrosponding method. More details about filters is covered in the next section.

Filters

Each handler is associated with a filter. Filters provide criteria for engaging handlers. Registry always evaluates the associated filter before invoking a handler. If the filter evaluates to true, it will invoke its associated handler. All filters should extend from a abstract class named Filter. Filter implementations should provide criteria for all handler methods by overwriting corresponding Filter method. Below is the listing of Filter class.

Figure 2: Filter class

Aspects

Aspects are using to associate custom behaviors with resources; Aspects differ form handlers, in that handlers are automatically applied to a resource, whereas, aspects are needed to be invoked manually through user action (e.g. by clicking a button in the user interface).

You can create an aspect by implementing the 'Aspect' class.

Figure 3: Aspect class

Request Context

Per each request made to the registry, a Handler Manager decides whether the call will be intercepted through one or more handlers before it being served by the registry itself. For a given method implemented by the registry, the handler manager stores a dictionary of filters and associated handlers.

If a filter evaluates to true, the associated handler will be invoked. Soon after the handler being invoked, the call will be returned to the handler manager, which evaluates whether the request has been completely served by the handler. If the handler has not completely served the request, the handler manager will poll the remaining filters to determine whether any downstream handlers need to be invoked. This process will continue until the handler manager is being told that a handler completely served the request or until there are no more filters to poll.

In order to facilitate the ability for more than one handler to act upon a resource or collection, and also pass information downstream, a request context is passed to each handler operation. It contains a number of methods through which you can extract data from the request and also add information to. If a handler decides that it has completely served a request and no downstream handlers should be invoked it can set the Processing Complete flag.

requestContext.setProcessingComplete(true)

This will cause the downstream handlers to not be invoked. Also, in such a situation, the registry implementation can decide, based on the result returned by the handler chain to whether it should continue processing or simply return. Therefore, the request context serves as the basis for handler-handler and handler-registry communication and plays a vital role in the process of extending the registry.

Figure 4: RequestContext class (Only the Accessors are shown here)

WSO2 Governance Registry v3.0.1

Downloads

Documentation

Samples

Getting Help

Get Involved