Difference between revisions of "Develop Generic VCL Call"
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. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==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
Contents
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.
The create an Eclipse Java project (ex.GenericVCLCall
) and add the GVESB User Libraries set to the project's classpath.
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:
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);
}
}