Error Handling in Jaggery

Proper error handling is a key points in any application. If you are using WSO2 Jaggery, then you might have also come up with the same requirement.

Jaggery is JavaScript, hence try, catch and finally blocks can be used within your code as you usual. Also,  passed JavaScript Error object can be used to get a brief information about the error. But, as we are dealing with a server side environment, we might need to know additional details about the errors, such as stacktrace, line numbers etc.

Using the additional properties/methods which can be found in the passed Error object, error details can be accessed as below.

var log = new Log();

try {
    parse(null); //code where exception is thrown
} catch (e) {
    log.error(e.lineNumber); // Error occured line number
    log.error(e.fileName); // Error occured script name
    log.error(e.stack); // Executed JavaScript file stack
    log.error(e.message); // JavaScript error message

    log.error(e.rhinoException); // Rhino exception object
    log.error(e.javaException); // Java excepton object

    log.error(e); // Logs the stack trace

    print(e); // prints the stack trace
} finally {
    log.info('finally :)');
}

Logging in Jaggery

In Jaggery, you can log with different levels i.e. debug, info, warn, error, fatal which can be enabled/disabled using the logLevel parameter in the jaggery.conf.

{
    "welcomeFiles" : ["index.html"],
    "logLevel" : "debug"
} 

Logging can be done with the desired log level using log.debug(), log.info(), log.warn(), log.error() and log.fatal() methods. Also, whether the debug logs are enabled can be checked using log.isDebugEnabled().

var log = new Log();

if(log.isDebugEnabled()) {
    log.debug('This is a debug log');
}

log.info('This is an info log');
log.warn('This is a warning log');
log.error('This is an error log');
log.fatal('This is a fatal log');

Get Environment Variables and System Properties in Jaggery

Environment variables and system properties can be read using the process module as below.

var process = require('process');

print(process.getEnvs()); // json object
print(process.getEnv('PATH')); // string
print(process.getProperties()); // json object
print(process.getProperty('jaggery.home')); // string

How to Generate a UUID in Jaggery

A UUID can be generated in WSO2 Jaggery server using the uuid module as below.

var uuid = require('uuid');
var id = new uuid.UUID();

print(id.toString()); // 0af9cb30-f660-4d5c-8d39-28cf87c7e574

How to Execute Tasks in WSO2 Jaggery

If you have come across the requirement of executing timer tasks within a Jaggery code, then you can use the following code to do that. These are the same set of functions that you have in the browser.

You can also use clearTimeout and clearInterval functions to stop the task execution.

One time tasks

setTimeout(function() {
     var log = new Log();
     log.info('setTimeout() is executed after 2s');
}, 2000);  

Recurring tasks

setInterval(function() {
     var log = new Log();
     log.info('setInterval() is being executed within 4s intervals');
}, 4000);

Check your A/L Exam Results a Bit Earlier

If you have sat for the A/L exam in Sri Lanka, you can check your unofficial results a bit earlier(when it shows you the "AWAIT RESULTS" banner) by accessing the following url from your browser(Please replaces 0000000 with your index number).

http://www.doenets.lk/exam/exam_AL.jsp?submit=Submit&action=result&exyear=2012&indexno=0000000

WSO2 Ant Application Deployer

Note :  You would be able to achieve most the requirements described here using puppet scripts, which would be the ideal way of doing it. Anyway, if you are still interested, you can continue reading.

Ant application deployer is a custom deployer written to deploy an Ant script in a WSO2 Carbon based server, which will then get executed automatically. Using Ant deployer, you can deploy any artifact/jar/configuration into a carbon server using a single file.

Along with the Ant deployer, following custom tasks are also included.

1. server
• This can be used to shutdown/restart a local/remote Carbon Server
2. registry
• This can be used to insert metadata into a local/remote registry of a WSO2 server

Note : Ant application deployer should be used if and only if, Ant applications are deployed by trusted parties. Also, this shouldn't be used in a cloud environment.

Why Ant application deployer

Lets assume you have a requirement to configure an WSO2 ESB server as below.

1. Install a set of custom mediators
2. Deploy a set of carbon applications with sequences/registry resources which uses those custom mediators
3. Deploy APIs and templates which cannot be included in car file at the moment
4. Add metadata like properties, associations along with the registry resources.

Notes :  Support for APIs and templates would be added in the future, but at the moment it is not supported.

If you want to do above configurations, then you might need to follow below steps.

1. Copy jar files
2. Restart the server
3. Copy carbon applications
4. Copy APIs and templates
5. Manually add metadata

But, using Ant deployer with its custom tasks mentioned above, you can create a single deployable artifact which does everything mentioned above using ant. Only step that you will need to do is, just to copy the all in one zip file into the relevant location. Then the Ant script in the zip file will be automatically executed and above steps would be executed.

Although above is a simple usecase, you would be able to do more cool stuff such as to configure/patch/migrate a whole carbon installation with a proper ant script.

 

Installation

1. Copy the jar named org.wso2.carbon.extensions.antdeployer-1.0.0.jar into repository/components/dropins directory of the carbon 4.0.x based server.
2. Restart the server

Using Ant Deployer

 

Properties

Following properties can be used within the Ant script to get the information about the server being runing.

Property	Example Value
carbon.home	/home/ruchira/wso2esb-4.5.0
carbon.conf	/home/ruchira/wso2esb-4.5.0/repository/conf
carbon.logs	/home/ruchira/wso2esb-4.5.0/repository/logs
carbon.dropins	/home/ruchira/wso2esb-4.5.0/repository/components/dropins
carbon.lib	/home/ruchira/wso2esb-4.5.0/repository/components/libs
carbon.repo	/home/ruchira/wso2esb-4.5.0/repository/deployment/server/
carbon.tenants	/home/ruchira/wso2esb-4.5.0/repository/tenants
carbon.components	/home/ruchira/wso2esb-4.5.0/repository/components/plugins
carbon.tmp	/home/ruchira/wso2esb-4.5.0/tmp
carbon.catalina	/home/ruchira/wso2esb-4.5.0/lib/tomcat/work/Catalina

Custom Ant Tasks

server

This Ant task can be used to restart/shutdown a local/remote carbon server.

<server
        url="https://serverhost:port/services"
        username="user"
        password="pass"
        action="restart|shutdown|gracerestart|graceshutdown"
        target="t1"/>

For the action, you need to specify one of the followings

1. shutdown
• Discard any requests currently being processed and immediately shutdown the server.
2. restart
• Discard any requests currently being processed and immediately restart the server.
3. graceshutdown
• Stop accepting new requests, continue to process already received requests, and then shutdown the server.
4. gracerestart
• Stop accepting new requests, continue to process already received requests, and then restart the server.

Shutdown/restart different server

<server
        url="https://serverhost:port/services"
        username="user"
        password="pass"
        action="restart|shutdown|gracerestart|graceshutdown"/>

Shutdown/restart same server

<server target="t1" action="restart|shutdown|gracerestart|graceshutdown"/>

When the same server is being restarted/shutdown, then everything that you need to execute after restart/shutdown, should be defined as a separate task/tasks and specify first task with "target" attribute.

If the server is just shutdown, then "target" attribute can be omitted.  But if you have specified a “target” attribute even for shutdown action, then that target will be executed whenever the server is being restarted.

registry

Registry metadata can be added by specifying  the paths to metadata files as below.

<registry password="pass" url="https://serverhost:port/registry" username="user">
    <metadata path="registry-meta/meta1.xml"/>
    <metadata path="registry-meta/meta2.xml"/>
</registry>

Further, if the metadata is added to the resources which are being deployed by the *.car files in the same Ant application, then there is a possibility of executing metadata task before the resources get added to the registry.

As a solution for this, registry Ant task waits and retries several times until resources get deployed.  Default value for wait is 10s and retry count is 5.

Anyway, these wait and retry times can be overridden by specifying following properties in the build.xml.

<property name="registry.retries" value="4"/>
<property name="registry.sleep" value="20000"/>

Using your own custom tasks

If any additional custom tasks are required depending on your environment, those jars can be added either into repository/components/dropins (OSGI bundles) or repository/components/lib (Non-OSGI jars).

Then, above custom tasks can be used in your ant scripts as below by defining the task class in every script.

<target name="use" description="Use the Task" depends="jar">
    <taskdef name="helloworld" classname="com.mycompany.HelloWorld"/>
    <helloworld/>
</target>

Adding task definitions in each script can be avoided by defining them in repository/conf/ant-deployer.xml as below.

<AntDeployer xmlns="http://wso2.org/carbon/antdeployer">
    <Tasks>
        <Task name="helloworld" classname="com.mycompany.HelloWorld"/>
        <Task name="hellouniverse" classname="com.mycompany.HelloUniverse"/>
    </Tasks>
</AntDeployer>

Then, tasks can be used directly without defining them in the scripts.

Metadata Configuration

Adding metadata

Following is an example metadata file. When there are multi-valued properties, “append” attribute need to be specified.

<metadata xmlns="http://wso2.org/carbon/registry/metadata">
    <resource path="/_system/config/resource1">
        <associations>
            <association path="/_system/governance/resource2"
                         type="depends"/>
            <association path="/_system/governance/resource3"
                         type="depends"/>
        </associations>
        <properties>
            <property name="p1" append=”true”>v1</property>
            <property name="p2">v2</property>
        </properties>
        <tags>
            <tag>t1</tag>
            <tag>t2</tag>
        </tags>
    </resource>
</metadata>

Removing resources/metadata from Registry

By defining an attribute named “remove” within each resource, association, property and tag elements,  you can instruct to remove those resources/metadata from the registry.

<metadata xmlns="http://wso2.org/carbon/registry/metadata">
    <resource path="/_system/config/resource1" remove="true"/>
    <resource path="/_system/config/resource2">
        <associations>
            <association path="/_system/governance/resource3"
                         type="depends" remove="true"/>
        </associations>
        <properties>
            <property name="p1" append=”true” remove="true">v1</property>
            <property name="p2" remove="true"/>
        </properties>
        <tags>
            <tag remove="true"/>
        </tags>
    </resource>
</metadata>

Trying it out

 

The source code, the pre-build jar and a sample Ant application written for WSO2 ESB server can be found at [1]. This sample Ant application will do the following steps.

1. Copying the mysql driver
2. Restarting the server
3. Deploying ESB sequence template named template1
4. Deploying ESB API named api1
5. Deploying the carbon application named sample-antapp_1.0.0.car which includes
• A proxy service named SampleProxy
• Registry resources named endpoint1.xml and endpoint2.xml which will be deployed at /_system/antapp-sample/endpoints
6. Creating a set of associations between /_system/antapp-sample and above endpoint1.xml, endpoint2.xml resources
7. Adding a set properties named p1, p2 etc. and tags named t1, t2 etc into the collection /_system/antapp-sample and endpoint1.xml, endpoint2.xml resources

In order to try it out,

1. Install the Ant deployer into WSO2 ESB 4.5.0 server following the above installation steps
• Pre-built jar can be found in lib directory at [1]
2. Create a directory at <cabon_home>/repository/deployment/server/antapps
• e.g. wso2esb-4.5.0/repository/deployment/server/antapps
3. Copy the sample-antapp.zip file into the antapps directory
• Pre-build antapp can be found in lib directory at [1]
4. Restarting logs should be able to notice either in the console or  server logs within a few seconds

Resources

[1] https://svn.wso2.org/repos/wso2/people/ruchira/ant-deployer
[2] build.xml in the sample antapp

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="sample-antapp" basedir="." default="t0">
    <target name="t0" description="Copy jars into Carbon Server and restart">
        <copy file="jars/mysql-connector-java-5.1.22-bin.jar"
              todir="${carbon.lib}"/>
        <server target="t1"/>
    </target>
    <target name="t1" description="Copy artifacts">
        <copy file="templates/template1.xml"
              todir="${carbon.repo}/synapse-configs/default/templates"/>
        <copy file="apis/api1.xml"
              todir="${carbon.repo}/synapse-configs/default/api"/>
        <copy file="carbonapps/sample-antapp_1.0.0.car"
              todir="${carbon.home}/repository/carbonapps/0"/>
        <registry url="https://localhost:9443/registry"
                  username="admin" password="admin">
            <metadata path="registry-meta/*"/>
        </registry>
    </target>
    <target name="t2" description="Create ruchira directory">
        <mkdir dir="${carbon.home}/ruchira"/>
    </target>
</project>

[3]  Registy metadata xml in the sample antapp

<metadata xmlns="http://wso2.org/carbon/registry/metadata">
    <resource path="/_system/antapp-sample">
        <associations>
            <association path="/_system/antapp-sample/endpoints/endpoint1.xml"
                         type="depends"/>
            <association path="/_system/antapp-sample/endpoints/endpoint2.xml"
                         type="depends"/>
        </associations>
        <properties>
            <property name="p1">v1</property>
            <property name="p2">v2</property>
        </properties>
        <tags>
            <tag>t1</tag>
            <tag>t2</tag>
        </tags>
    </resource>
    <resource path="/_system/antapp-sample/endpoints/endpoint1.xml">
        <associations>
            <association path="/_system/antapp-sample/endpoints/endpoint2.xml"
                         type="sibling"/>
        </associations>
        <properties>
            <property name="p1">e1v1</property>
            <property name="p2">e1v2</property>
        </properties>
        <tags>
            <tag>e1t1</tag>
            <tag>e1t2</tag>
        </tags>
    </resource>
    <resource path="/_system/antapp-sample/endpoints/endpoint2.xml">
        <associations>
            <association path="/_system/antapp-sample/endpoints/endpoint1.xml"
                         type="sibling"/>
        </associations>
        <properties>
            <property name="p1">e2v1</property>
            <property name="p2">e2v2</property>
        </properties>
        <tags>
            <tag>e2t1</tag>
            <tag>e2t2</tag>
        </tags>
    </resource>
</metadata>