Configuring 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, it is useful to look at the Handler class listed below.

Note

Here some details are omitted for clarity.

Here is a description of how each of these methods works.

Method	Important parameters (To extract from Request Context)	Return value	Description
`get`	requestContext.getResourcePath() // path, the resource is getting	Resource // the resource at the path	Retrieves a resource in a given path.
`put`	requestContext.getResourcePath() // path to put requestContext.getResource() // the resource to store	-	Stores a resource in a given path.
`importResource`	requestContext.getResourcePath() // path to put requestContext.getSourceURL() // the URL of the importing resource	-	Imports a resource from a URL.
`move`	requestContext.getSourcePath() // source to move from requestContext.getTargetPath() // target to move to	String // the new path	Moves a resource from one to another.
`copy`	requestContext.getSourcePath() // source to copy from requestContext.getTargetPath() // target to copy to	String // the new path	Copies a resource from one to another.
`rename`	requestContext.getSourcePath() // source of the resource requestContext.getTargetPath() // the new name	String // the new path	Changes 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	-	Creates a sym-link or a remote link.
`removeLink`	requestContext.getResourcePath() // the path of the link to remove	-	Removes a link.
`delete`	requestContext.getResourcePath() // the path of the resource to remove	-	Deletes a resource. If this is a collection, all the children will also be removed.
`putChild` `Deprecated.`	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[]	Returns all the associations of a given resource.
`getAssociations`	requestContext.getResourcePath() // the path of the resource requestContext.getAssociationType() // the type of the association	Association[]	Returns 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	-	Applies a tag to a particular path.
`removeTag`	requestContext.getResourcePath() // the path of the resource requestContext.getTag() // the tag to be removed	-	Removes a tag in a particular 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 version-ed resource.
`createVersion`	requestContext.getResourcePath() // Create a version of a resource	-	Triggered when creating a resource. This is triggered when you create a snapshot (but not a new version) of an asset. It is related to the Repository aspect of WSO2 G-Reg.
`editComment`	requestContext.getCommentPath() // The path of the comment of a resource requestContext.getComment() // The comment	-	Edits a comment in a given path.
`addComment`	requestContext.getResourcePath() // The path of the resource requestContext.getComment() // The comment	String // the comment path	Adds a comment to the given path.
`removeComment`	requestContext.getCommentPath() // The path of the comment of a resource requestContext.getComment() // The comment	-	Removes a comment in a given path.
`getComments`	requestContext.getResourcePath() // The path of the resource	Comment[]	Gets all comments in a given path.
`getAverageRating`	requestContext.getResourcePath() // The path of the resource	float	Gets the average rating of a resource.
`getRating`	requestContext.getResourcePath() // The path of the resource requestContext.getUserName() // The path of the resource	int	Gets the rating given by a user to a given resource.
`getVersions`	requestContext.getResourcePath() // The path of the resource	String[]	Returns version paths of a given resource.
`getTags`	requestContext.getResourcePath() // The path of the resource	Tag[]	Returns tags of a given resource.
`getResourcePathWithTag`	requestContext.getResourcePath() // The path of the resource requestContext.getTag() // The value of the tag	TaggedResourcePath[]	Returns resource paths with a given tag.
`executeQuery`	requestContext.getResourcePath() // The path of the query requestContext.getQueryParameters() // The query parameters	Collection	Returns collection (paths as the content) queried in the given query.
`searchContent`	requestContext.getKeywords() // The search keywords	Collection	Returns collection (paths as the content) found as a result of search operation.
`resourceExists`	requestContext.getResourcePath() // The path of the resource	boolean	Returns whether the resource in the given path exists.
`dump`	requestContext.getResourcePath() // The path of the resource requestContext.getDumpingWriter() // The writer that requested in dumping	-	Dumps a particular path.
`restore`	requestContext.getResourcePath() // The path of the resource requestContext.getDumpingReader() // The reader that used with restoring	-	Restores 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. For example:

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

Handler properties - Custom properties that will be used in handler processing logic. For example:

<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 the 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 the type java.lang.String. So the method signature for the above example property is:

public void setWsdlLocationConfiguration(OMElement locationConfiguration) throws RegistryException {
}

Filter is associated with the handler. You can refer a filter inside a handler which would provide the filter functionality to that particular handler. The handler for a particular method is invoked only if the filter is returning true for the corresponding method. For more details about filters, see Configuring Filters .

Common steps in writing a handler.

1. Extend the Handler class and overwrite necessary methods.

2. Implement whatever custom behaviors in overwritten methods. You may use information provided in the RequestContext instance, in your custom implementation.

3. Once the custom behavior is completed, it is usually required to perform the actual requested operation (for example, add the resource in put(...) method).

Tip

Use the Repository instance provided in the RequestContext to perform the actual operation. If it is required to version the resource in put operation, use VersionRepository instance.

Note

It is not recommended to use the Registry instance to perform resource related operations (get, put, import, delete) inside a handler as it may cause infinite loops as the Registry tries to invoke all handlers again.