Difference between revisions of "Develop Generic VCL Call"

From GreenVulcano Wiki
Jump to: navigation, search
Line 2: Line 2:
 
A VCL Generic Call is a facility to enable the use of custom Java libraries in {{GVESB}}.
 
A VCL Generic Call is a facility to enable the use of custom Java libraries in {{GVESB}}.
 
The plug-in must implement the [[VCLCallOperation|CallOperation]] interface and can be configured in {{L_GVCONSOLE}} or {{L_VULCON}} through a simple configuration interface.
 
The plug-in must implement the [[VCLCallOperation|CallOperation]] interface and can be configured in {{L_GVCONSOLE}} or {{L_VULCON}} through a simple configuration interface.
 
==Generic VCL Call life cycle==
 
A Generic VCL Call life cycle is the same as every VCL plug-in:
 
* the init method is called at instance creation time
 
* the perform method is called at every service invocation
 
* the cleanUp method is called after every perform invocation
 
* the destroy method is called at instance destruction time
 
  
 
==Configure the Eclipse workspace==
 
==Configure the Eclipse workspace==
Line 23: Line 16:
 
[[File:GVESBUserLibraries.png|border|800px]]
 
[[File:GVESBUserLibraries.png|border|800px]]
  
The create an Eclipse Java project (ex.GenericVCLCall) and add the GVESB User Libraries set to the project's classpath.
+
The create an Eclipse Java project (ex.<code>GenericVCLCall</code>) and add the GVESB User Libraries set to the project's classpath.
  
 
[[File:SetGVESBUserLibraries.png|border|800px]]
 
[[File:SetGVESBUserLibraries.png|border|800px]]
  
====
+
==Generic VCL Call life cycle==
 +
A Generic VCL Call life cycle is the same as every VCL plug-in:
 +
* VCL plug-in instances are pooled
 +
* the <code>init</code> method is called at instance creation time
 +
* the <code>perform</code> method is called at every service invocation
 +
* the <code>cleanUp</code> method is called after every perform invocation
 +
* the <code>destroy</code> method is called at instance destruction time
 +
 
 +
==Create a Generic VCL Call class==
 +
In the Eclipse project create a class with the parameters as illustrated in the image:
 +
 
 +
[[File:SampleGenericVCLClass.png|border|400px]]
 +
 
 +
The example plug-in is a simple class that perform a toupper|tolowe|echo operation on a String input or optionally to cancel the input data.
 +
 
 +
===Basic development guidelines===
 +
Following some guidelines useful to develop a {{GVESB}} VCL plug-in.
 +
 
 +
====Package name====
 +
Using a package name that starts with <code>it.greenvulcano.gvesb.virtual.</code> automatically enable the logging in the GVVCL log file.
 +
 
 +
====Logging====
 +
To enable the logging in {{GVESB}} plug-in import the following class anche defines the <code>logger</code> instance as illustraded:
 +
<syntaxhighlight lang="java5">
 +
import it.greenvulcano.log.GVLogger;
 +
 
 +
import org.apache.log4j.Logger;
 +
 
 +
public class TestGenericCall implements CallOperation {
 +
    private static final Logger logger    = GVLogger.getLogger(TestGenericCall.class);
 +
 
 +
</syntaxhighlight>
 +
The <code>GVLogger</code> class enable the logger reconfiguration at runtime.
 +
 
 +
====VCL internal methods====
 +
Some methods defined by the [[VCLCallOperation|CallOperation]] interface must be coded in a standard mode, as indicated in the following code:
 +
<syntaxhighlight lang="java5">
 +
    protected OperationKey      key      = null;
 +
    ....
 +
 
 +
    public OperationKey getKey() {
 +
        return key;
 +
    }
 +
 
 +
    public void setKey(OperationKey key) {
 +
        this.key = key;
 +
    }
 +
 
 +
    public String getServiceAlias(GVBuffer gvBuffer) {
 +
        return gvBuffer.getService();
 +
    }
 +
</syntaxhighlight>
 +
The indicated methods are used internally by the VCL framework.
 +
 
 +
 
 +
===Plug-in initialization===
 +
To read the plug-in's configuration parameters must be used the [[XMLConfig]] utility class.
 +
For the Generic VCL Call the XML node describing the configuration parameters is the following:
 +
<syntaxhighlight lang="xml">
 +
    <generic-call class="it.greenvulcano.gvesb.virtual.test.TestGenericCall"
 +
                  name="test-call" type="call">
 +
        <call-parameter name="operation"  value="toupper" type="param"/>
 +
        <!-- optional -->
 +
        <call-parameter name="cancelData" value="false"  type="param"/>
 +
    </generic-call>
 +
</syntaxhighlight>
 +
The following code illustrate the plug-in initialization:
 +
<syntaxhighlight lang="java5">
 +
    private String              operation  = null;
 +
    private boolean            cancelData = false;
 +
    ....
 +
 
 +
    public void init(Node cfg) throws InitializationException {
 +
        try {
 +
            // reads the 'operation' configuration parameter as String
 +
            operation = XMLConfig.get(cfg, "call-parameter[@name='operation']/@value");
 +
            // reads the 'cancelData' configuration parameter as boolean, setting 'false' as default value
 +
            cancelData = XMLConfig.getBoolean(cfg, "call-parameter[@name='cancelData']/@value", false);
 +
 
 +
            // check the 'operation' parameter value
 +
            if ((operation == null) || !(operation.equals("toupper") || operation.equals("tolower") || operation.equals("echo"))) {
 +
                logger.error("Invalid 'operation' value:" + operation);
 +
                throw new InitializationException("GVVCL_XML_CONFIG_ERROR", new String[][]{{"exc", "Invalid 'operation' value:" + operation},
 +
                        {"key", key.toString()}});
 +
            }
 +
 
 +
            logger.debug("Initialized TestGenericCall: operation[" + operation + "] cancelData["
 +
                        + cancelData + "]");
 +
        }
 +
        catch (InitializationException exc) {
 +
            throw exc;
 +
        }
 +
        catch (Exception exc) {
 +
            logger.error("An error occurred reading configuration data.", exc);
 +
            throw new InitializationException("GVVCL_XML_CONFIG_ERROR", new String[][]{{"exc", exc.toString()},
 +
                    {"key", key.toString()}}, exc);
 +
        }
 +
    }
 +
</syntaxhighlight>

Revision as of 12:52, 16 December 2012

Description

A VCL Generic Call is a facility to enable the use of custom Java libraries in GreenVulcano® ESB. The plug-in must implement the CallOperation interface and can be configured in GV Console® or VulCon® through a simple configuration interface.

Configure the Eclipse workspace

To develop the plug-in is needed to reference some GreenVulcano® ESB libraries: in GV_HOME/application/deploy/gvesb-javaee5-*.ear/lib

  • gvbase-*.jar
  • gvcore-*.jar
  • gvvcl-*.jar

in JBOSS_HOME/commons/lib

  • log4j.jar

The simplest mode is to define a User Libaries set, named "GVESB", as show in the image.

GVESBUserLibraries.png

The create an Eclipse Java project (ex.GenericVCLCall) and add the GVESB User Libraries set to the project's classpath.

SetGVESBUserLibraries.png

Generic VCL Call life cycle

A Generic VCL Call life cycle is the same as every VCL plug-in:

  • VCL plug-in instances are pooled
  • the init method is called at instance creation time
  • the perform method is called at every service invocation
  • the cleanUp method is called after every perform invocation
  • the destroy method is called at instance destruction time

Create a Generic VCL Call class

In the Eclipse project create a class with the parameters as illustrated in the image:

SampleGenericVCLClass.png

The example plug-in is a simple class that perform a toupper|tolowe|echo operation on a String input or optionally to cancel the input data.

Basic development guidelines

Following some guidelines useful to develop a GreenVulcano® ESB VCL plug-in.

Package name

Using a package name that starts with it.greenvulcano.gvesb.virtual. automatically enable the logging in the GVVCL log file.

Logging

To enable the logging in GreenVulcano® ESB plug-in import the following class anche defines the logger instance as illustraded:

import it.greenvulcano.log.GVLogger;

import org.apache.log4j.Logger;

public class TestGenericCall implements CallOperation {
    private static final Logger logger    = GVLogger.getLogger(TestGenericCall.class);

The GVLogger class enable the logger reconfiguration at runtime.

VCL internal methods

Some methods defined by the CallOperation interface must be coded in a standard mode, as indicated in the following code:

    protected OperationKey      key       = null;
    ....

    public OperationKey getKey() {
        return key;
    }

    public void setKey(OperationKey key) {
        this.key = key;
    }

    public String getServiceAlias(GVBuffer gvBuffer) {
        return gvBuffer.getService();
    }

The indicated methods are used internally by the VCL framework.


Plug-in initialization

To read the plug-in's configuration parameters must be used the XMLConfig utility class. For the Generic VCL Call the XML node describing the configuration parameters is the following:

    <generic-call class="it.greenvulcano.gvesb.virtual.test.TestGenericCall"
                  name="test-call" type="call">
        <call-parameter name="operation"  value="toupper" type="param"/>
        <!-- optional -->
        <call-parameter name="cancelData" value="false"   type="param"/>
    </generic-call>

The following code illustrate the plug-in initialization:

    private String              operation  = null;
    private boolean             cancelData = false; 
    ....

    public void init(Node cfg) throws InitializationException {
        try {
            // reads the 'operation' configuration parameter as String
            operation = XMLConfig.get(cfg, "call-parameter[@name='operation']/@value");
            // reads the 'cancelData' configuration parameter as boolean, setting 'false' as default value
            cancelData = XMLConfig.getBoolean(cfg, "call-parameter[@name='cancelData']/@value", false);

            // check the 'operation' parameter value
            if ((operation == null) || !(operation.equals("toupper") || operation.equals("tolower") || operation.equals("echo"))) {
                logger.error("Invalid 'operation' value:" + operation);
                throw new InitializationException("GVVCL_XML_CONFIG_ERROR", new String[][]{{"exc", "Invalid 'operation' value:" + operation},
                        {"key", key.toString()}});
            }

            logger.debug("Initialized TestGenericCall: operation[" + operation + "] cancelData["
                         + cancelData + "]");
        }
        catch (InitializationException exc) {
            throw exc;
        }
        catch (Exception exc) {
            logger.error("An error occurred reading configuration data.", exc);
            throw new InitializationException("GVVCL_XML_CONFIG_ERROR", new String[][]{{"exc", exc.toString()},
                    {"key", key.toString()}}, exc);
        }
    }