CopyExecutor explained

In my previous posts, I have explained about the lifecycle management functionality in WSO2 Governance Registry. These posts covered a variety of topics ranging from the configuration model to its extension points. Executors are one such extension point and I have given an introduction to executors and about the default executors in couple of my previous posts.

This post explains about the default copyExecutor that is shipped with WSO2 Governance Registry 4.5.0. First, lets look at the code of the copyExecutor. You can find the original code segment using this link (which in located in WSO2 code base).

Before explaining the copyExecutor code, we need to get an understanding about how to configure the copyExecutor. The copyExecutor is designed to do one specific registry operation. That is to do an copy operation of a resource from one location to another. With the lifecycle configuration model of WSO2 Governance Registry, we are able to pass parameters to an executor class and because of that, we have made those resource paths (the source path and the target path) configurable from the lifecycle configuration. So altogether the copyExcutor has the following configurations.

• Source path
• Target path
• Copy comments
• Copy tags
• Copy ratings
• Copy associations

The configuration of the copyExecutor is as follows.

Let us go through the copyExecutor code and see how we have implemented these.

In one of my earlier posts, I explained that each executor must implement the Execution interface. This interface has 2 methods.

• void init(Map parameterMap)
• boolean execute(RequestContext context,String currentState,String targetState)

Out of these 2, the init method is called when we parse the lifecycle configuration and initialize the aspect. Also this method gets the static parameters we defined in the lifecycle configuration. Hence in the copy executor, we pass these parameters and we keep track of them using several variables. 

The execute method is called when we invoke a lifecycle operation. Inside this method, we do all the operations. The copyExecutor has the ability to append a version to a given path and these versions can be sent from the Management Console. Hence inside this execute method, we read the parameters that were sent from the UI and create a path according to them. The underlying code segment is as follows.

After that we are checking whether the resource path is in the given current environment. If not, we can not proceed further in the code but the executor should not fail. Hence we return "true" to inform the lifecycle implementation that the executor executed successfully.

Finally, we do all the other operations such as doing the copy operation and copying tags,ratings,comments and associations.

As you all can see, the copyExecutor has a simple code but has a great set of use cases. During this webinar we used the same copyExecutor to copy artifacts from one environment to another. Likewise it has many use-cases when it comes to governance scenarios. 

Default transition UI - Part 02

WSO2 Governance Registry lifecycle model has many extension points. One of them is called the transition UI. In one of my previous posts, I have given an insight to what transition UIs are. This post is an continuation of my previous post.

WSO2 G-Reg distribution includes a single transition UI. This transition UI is used by the default service lifecycle for its service version functionality(more information can be found here). This transition UI does the following.

The name of the default transition UI is "pre_invoke_ajaxprocessor.jsp".

The main functionality of this UI is to take user input for the versions of services and their dependent resources, so that they can be passed to the service version executor.

It is displayed only for services. It will ignore all other media types.

It will list down all the dependencies of a service resource. These dependencies are gathered recursively. Hence all the dependencies of that service and its dependent resources, will be displayed in the UI.

Parameters can be passed to these UIs. The lifecycle configuration model supports adding parameters to a transition UI element and these parameters are added as URL parameters. Please note the section after the "?" in the following example.

The "pre_invoke_ajaxprocessor.jsp" accepts 5 different parameters and all of these are optional.

1. preserveOriginal - Setting this parameter will allow users to instruct the server to keep the old resource or whether to delete it. If this parameter is set to "false", then the underlying implementation will delete the resource after a state transition. This parameter is set to "true" by default.
2. viewVersion - This parameter is there to instruct the jsp page to avoid displaying the content of the page. If the viewVersions is set to "false", the underlying implementation of the jsp page will do an invokeAspct() call including parameters like "preserveOriginal". We use this parameter to pass the value of the "preserveOriginal" parameter to the server without displaying any additional UI to the user.
3. displayMediaType - This parameter is used to override the default media type which is checked by the jsp page. By default, this UI checks whether the resource has a media type equal to "application/vnd.wso2-service+xml"(which is the default service media type of WSO2 G-Reg). By setting this parameter, users can override the above mentioned value. 
4. showDependencies - Instructs the jsp page to not to show the dependent resources of the service. If this parameter is set to "false", the jsp file will only show an input field for the service resource in the custom UI(it will not give input fields for any dependent resources).
5. currentEnvironment - Defines what is the current environment of the service(or its dependencies). The value of this parameter should be a path in the registry. If this parameter is set, the jsp page will not show input fields for resources that are not in the given registry path. 

Default transition UI - Part 01

In one of my previous posts, I discussed about few improvements that we did in the lifecycle configuration of WSO2 Governance Registry 4.1.1. In that post I explained about one of those points, which is the executor interface. Today lets have some insight into the other improvement we did, which is the transition UI.

What is a transition UI?

We use the term "transition UI" to describe a portlet that is displayed as an result of an lifecycle action. In other words, transition UIs are used to get user input at runtime, as a part of a lifecycle transition. To get some clear idea about it, lets look at the following use case. 

Eg:-

Say that I'm a user who is going to govern all my services in WSO2 G-Reg using its lifecycle management capabilities. As a part of the governance process, I need to keep my services in different locations of G-Reg based on the lifecycle state of a service. As a part of this operation I also need to add a version to my services.

Adding a version to a service that is been moved to different environment is somewhat a tricky operation. The version that needs to be added, should be given by a user at runtime. For this, we need some kind of a mechanism to give user inputs for a lifecycle state transition.

We introduced the transition UI feature to achieve the above, which is to give user input for a lifecycle state transition. There are few key things that a user should know about transition UIs.

Transition UIs are registered for an action/event in a particular state. The registration happens through the lifecycle configuration.

If the lifecycle configuration demands the same transition UI for multiple actions/events, then it has to be re-registered.

Only one transition UI can be given for a action/event in a particular state.

Parameters can be passed to transition UI. These parameters are defined in the lifecycle configuration and they are considered as static parameters. Hence they can not be changed at runtime.

The input values that are given through the transition UI are passed to back-end and they can be read using an executor.

Transition UI appears below the lifecycle portlet and there are no popup windows.

There are few transition UIs that we ship by default. I'll be covering about them in another post.

WSO2 Governance Registry 4.5.0 - Lifecycles

At the time of this post, we are preparing for the release of WSO2 Governance Registry 4.5.0. This new version has lots of new features and performance improvements. From this post, I would like to mention one such improvement that we did for G-Reg Lifecycle management feature.

Lifecycles in a nutshell

WSO2 G-Reg has a powerful lifecycle model with lots of flexibility. In WSO2 G-Reg, users have the ability to define their own lifecycle model using a simple XML configuration. The default lifecycle configuration of G-Reg has the ability to define states,check items,permissions,transition UIs, pre and post transition actions. A detailed description about the lifecycle model of WSO2 G-Reg can be found in this post.


In G-Reg 4.5.0 we have introduced the ability to audit lifecycle operations. This means we capture all the lifecycle operations of a particular resource. Following are some key points when it comes to lifecycle auditing.

Lifecycle auditing is turned on by default.

Auditing can be turned off from the lifecycle configuration. This can be done by setting audit=false in the lifecycle element in the lifecycle configuration.

Lifecycle auditing happens per lifecycle. Based on the configuration, all the resources associated with that lifecycle are audited.

Audit logs are kept as a resource in G-Reg. These resources are stored under, "/_system/governance/repository/components/org.wso2.carbon.governance/lifecycles/history" collection. A resource is created for every resource/collection that is associated with a lifecycle. The name of this resource is calculated by replacing all the "/" with "_" of its full path.

Audit logs are kept as a XML file. A sample audit log is as follows.

Default Executors in G-Reg

This post applies to G-Reg 4.1.1 and upwards.

As you all know, WSO2 Governance Registry supports adding extensions to the execution logic of a lifecycle.This blog post covers about one particular extension point which is called an executor. This post discuss about the default executors that we have included in the Governance Registry distribution. To get more information about executors, please refer this.

We have 3 default executors in G-Reg. From this post, I'm planning to give an overview about these executors.

1. Service version executor
2. Demote action executor
3. Copy executor

Service Version Executor

The main functionality of this executor is to version services and dependent resources of services(wsdl,schema and policy) when a lifecycle promote action happens. This executor was introduced  to G-Reg with the service version functionality implementation. To get an idea about this executor, we need to have some idea about the service version functionality of G-Reg.

Service Versioning

In G-Reg, we have introduced the ability version services and its dependent resources as an part of lifecycle management of the service. With this improvement, a service in G-Reg are kept in 3 environments when it is governed using the default service lifecycle.

1. Trunk
2. Branches/testing
3. Branches/production

Each of these environments are correspond to a lifecycle state in the default service lifecycle. The default service lifecycle in G-Reg has 3 states.

1. Development
2. Testing
3. Production

The service version functionality happens in the following way.

1. At creation, the service resource(and its dependent resources) will be placed in "trunk" environment. The path structure of the service resource is like - "trunk/services/{namespace}/{name}". We limit the creation of 2 services with the same name and namespace in this environment. 
2. All the services in "trunk" environment are on "development" state of the lifecycle.
3. When a "promote" action happens, a UI is displayed to the user to enter the new versions of the service and its dependent resources(This is done using the "transition UI" functionality of G-Reg which I will be covering in another blog post).
4. After completing the above action, the service and its dependent resources are moved to "branches/testing"environment. The path structure of a service resource in this environment is like - "branches/testing/{namespace}/{version}/{name}". In this environment, we create a collection with the version that the user has given and because of that, we allow users to keep multiple versions of the same service in this environment.
5. With the above step, we do some additional processing and update the dependencies with the new paths and also update the version filed in the service to reflect the new version. 
6. Promotion from "Testing" state to "Production" state is similar to step 3,4 and 5. All the services and the its dependencies are moved from "branches/testing" to "branches/production" environment. 

The service version executor is the one who does steps 4,5 and 6 when a promote transition happens. It is written in a way such that a user can change the environments from the lifecycle configuration. To get some idea about this, we need to look at the configuration of the service version executor.

Here you will notice several "parameter" elements. We focus our attention on 2 of these which are,

1.  currentEnvironment
2.  targetEnvironment 

The target environment parameter is the one who decides what is the next environment that the service is placed on. In other words, these 2 parameters say that, take the resource out from "/_system/governance/trunk/{@resourcePath}/{@resourceName}" and place it in "/_system/governance/branches/testing/{@resourcePath}/{@version}/{@resourceName}" path. By changing this configuration, an user has the ability to change the environments based on their requirement.

Also one important fact to note about this executor is that it is media type aware and it works only for services. 

Demote Action Executor

The demote action executor in G-Reg 4.1.1 does not do any copying of the resources to the previous environments. We have identified that the demote action requirement varies from one user to another. The ideal demote action would be to redirect the user to the resource in the previous environment but that is again challenging because there can be multiple versions of the same service in the previous environment. 

Therefore, we have introduced a demote action executor to avoid changing the lifecycle state when the demote action is performed for service in a particular state. In other words, this executor does not do anything apart from keeping the same lifecycle state when the demote action is preformed. 

Copy Executor

The idea behind the copy executor is to do a basic copy of resource from the given location to another. This executor has the ability to work with any media type and it is not media type aware. This executor does a basic copy operation(registry API copy operation) of that resource and it does modify the content or make associations like the service version executor. 

The configuration element of the copy executor is somewhat similar to the service version executor. 

Here you will find 2 parameters called the "currentEnvironment" and "targetEnvironment". These parameters work in the following way. The copy executor will copy any resource that is inside "currentEnvironment"  to the corresponding path in the "targetEnvironment". 

Eg: - Say that you have a resource in the following path.

    "/_system/governance/e1/foo/bar/xyz".

When the user applies a lifecycle (that is configured with the copy executor with the above configuration parameters) to resource "xyz" and do a promote operation, the copy executor will copy that resource to the following path.
"/_system/governance/e2/foo/bar/xyz"

Lifecycle extentions in WSO2 G-Reg - Part 1

This post applies to WSO2 Governance Registry 4.1.1 and upwards.

As you all know, WSO2 Governance Registry supports adding extensions to the execution logic of a lifecycle.This blog post covers about one particular extension point which is called an executor.

From this post, I'm planning to cover the following topics.

1. What is an Executor
2. How to write a Executor
3. Add a custom Executor to a lifecycle

What is an Executor

In WSO2 Governance Registry lifecycle model, there are several extension points that one can use to plug there own execution logic. There are several types of pluggable extension points. One of them is called the "executor". An executor is an execution logic that is executed once a state transition happens in a lifecycle.

How to write an Executor

Writing an Executor in G-Reg is very easy. We have an interface called "Execution" in G-Reg which can be found in "org.wso2.carbon.governance.registry.extensions" bundle. This interface has 2 methods.

• void init(Map parameterMap)

This method is called when the execution class is initialized. All the execution classes are initialized only once.
@param parameterMap Static parameter map given by the user. These are the parameters that have been given in the lifecycle configuration as the parameters of the executor.
Eg:- 
   

The parameters defined here are passed to the executor using this method.

• boolean execute(RequestContext context,String currentState,String targetState)

This method will be called when the invoke() method of the default lifecycle implementation is called. Execution logic should reside in this method since the default lifecycle implementation will determine

the execution output by looking at the output of this method.


@param context The request context that was generated from the registry core for the invoke() call. The request context contains the resource, resource path and other variables generated during the initial call.

@param currentState The current lifecycle state.

@param targetState The target lifecycle state.

@return Returns whether the execution was successful or not.

To write a custom executor, an user has to implement this interface and add the custom logic inside the execute method. The runtime will execute all the executors that is registered against a particular event an a particular state.

Add a custom Executor to a lifecycle

Adding an Executor to a lifecycle has several steps to follow. 

1. Compile the class and create a jar file out of it
2. If the jar file is an OSGI bundle add it to "GREG_HOME/repository/components/dropins" folder and if the jar file is not an OSGI bundle then add it to "GREG_HOME/repository/components/lib" folder. Here what we did is that we added the executor implementation to the classpath of the G-Reg server. 
3. Add the executor to the lifecycle configuration. Following is a segment of a lifecycle configuration that has an executor. 

There are 3 things that we need to focus our attention on. 

1. The event that we register the executor - defined by the "forEvent" attribute of the execution element.
2. The class of the executor - defined by the "class" attribute of the execution element.
3. Static parameters that is passed to it(optional) - defined by the "parameter" elements of the execution element. 

Using these configurations, an user has the ability to attach their own execution logic to a lifecycle in G-Reg.