When you are using Scripting Process Actions, you may need to use additional libraries in your scripts.
For instance, you want to use a JDBC driver, or any other additional library.
From Stambia DI 2020, all libraries are managed through Modules, you will therefore need to use Modules in Scripting Process Actions if you want to use additional libraries, as explained in this article.
This article is dedicated to Stambia DI 2020 (S20.0.0) and higher from which libraries are managed through Modules.
On prior versions the libraries were simply copy / pasted in the lib folder of the Runtime, and scripting actions were able to use them directly.
Modules can be used natively with the following scripting languages: Beanshell, Rhino, Nashorn, Javascript.
Modules are not fully supported yet on following scripting languages: Jython, Groovy.
Prerequisites:
- Stambia DI Designer 2020 (S20.0.0) or higher
- Stambia DI Runtime 2020 (S20.0.0) or higher
About Modules
This article will focus on how to use Modules with Scripting Process Actions.
To follow this article, you must as a prerequisite be familiarized with what is a Module and how / when it is necessary to use so.
Refer to Getting started with Modules and complete reference documentation to learn the basics about Modules.
Defining Module on Scripting Process Action
Scripting Process Action Configuration
When you need to use additional libraries in your scripts, for instance when you need to use specific classes which are not shipped by default, you can specify a Module containing the related libraries on the Scripting Process Action.
This is the main and recommended method to use additional libraries in Scripting Process Actions.
Note that in Modules Management Preferences and Wizard, you can create Modules of "Generic" category which are not linked to any particular technology, they are particularly useful when you want to use specific libraries in scripting.
To use a Module on Scripting Process Action, simply specify its name in the corresponding parameter, you can use any available Module.
Defining a Module on Scripting Action is supported with the following scripting languages: Beanshell, Rhino, Nashorn, Javascript.
For other languages such as Jython and Groovy, this is not supported yet, refer to the next section of this article to learn how to retrieve a module directly in the script instead of using the Module parameter, which is also supported on those languages.
Example - using a JDBC Driver
You can find below a scripting example which retrieve and use a JDBC Connection in a Rhino script.
We defined a Module which contains a JDBC Driver, and then we are using the JDBC Driver inside the script.
Note that the syntax to import and use classes vary depending on the scripting language used.
In this example the language used is Rhino (javascript)
Defining Module directly within a script
About this method
We recommend, when possible, to prefer the first method presented in this article, which consists of defining the Module on the Scripting action through the Module Parameter.
It is more convenient and easier to use as you can then import and use all the libraries of the Module seamlessly.
However, there are some particular cases where you may need to manually define within the script itself from which Module a given class should be retrieved instead of using the Module Parameter, such as:
- When using Jython or Groovy scripting languages on which using the "Module" parameter of Scripting Process Action is not supported yet
- When trying to use the "java.lang.Class.forName" function to search for a class
- And more... We'll update this article if we find other examples and use cases.
When this is the case, the solution will most of the time be to indicate directly within your script from which Module to retrieve the given class from, which means in the Java world from which classloader to retrieve it from.
Function to retrieve the classloader related to a given Module
There is for this a function allowing to retrieve the classloader related to a given Module:
__ctx__.getModule("Module name").getClassLoader()
This returns the classloader related to a Module, you can then use it as you want to search for classes.
This function is supported on Stambia DI Runtime S20.3.0 and higher. If you are using a prior version, use instead the following legacy function:com.indy.engine.core.module.classloader.ClassLoaderServiceProvider.INSTANCE.getClassLoader(<Module name>)
Example - using Modules in Jython and Groovy
When you need to use classes from additional libraries in Jython or Groovy scripts, you can retrieve them manually directly within the script itself.
For this, you can use the java.lang.Class.forName function for instance to retrieve the class and use it.
Usage of this function is presented further in this article.
Example of Jython script
import java.util
import java.lang
import com.indy.engine.core.module.classloader as classloader
clazz = java.lang.Class.forName("oracle.jdbc.driver.OracleDriver",True,__ctx__.getModule("Oracle").getClassLoader())
driver = clazz.newInstance()
properties = java.util.Properties()
properties.setProperty("user","SYSTEM")
properties.setProperty("password","password")
conn = driver.connect("jdbc:oracle:thin:@local.database:1521:ORA112",properties)
conn.isValid(5)
Example - using Modules for the java.lang.Class.forName function
When you are using the java.lang.Class.forName function in your scripts, the function will not automatically use the Module specified on the Scripting Action, if any.
When you are using this function, you have to manually give it the Module you want to retrieve this class from, which in the Java world means the classloader which should be used.
For this, there is a dedicated function that allows to retrieve it, as explained in the introduction of this section.
Retrieving a given class from a Module manually:
clazz = java.lang.Class.forName("<class to be retrieved>", true, __ctx__.getModule("<Module name from which to retrieve the class from>"));
driver = clazz.newInstance();
Example
clazz = java.lang.Class.forName("oracle.jdbc.driver.OracleDriver", true, __ctx__.getModule("ORACLE_11"));
driver = clazz.newInstance();
Miscellaneous
Function to retrieve the classloader related to the Module specified on the Scripting Action
When you have a Module defined on a Scripting Process Action through the Module parameter, you can retrieve the classloader related to this Module through the given syntax.
__cl__
This is simply a shortcut of the previously described "__ctx__.getModule" function for the current Module.
This special object represents the classloader related to the Module defined on the Scripting Process Action, you can use it as you want to search for classes.
Example with a Rhino script
clazz = java.lang.Class.forName("oracle.jdbc.driver.OracleDriver",true,__cl__)
driver = clazz.newInstance()
properties = java.util.Properties()
properties.setProperty("user","SYSTEM");
properties.setProperty("password","password");
conn = driver.connect("jdbc:oracle:thin:@local.database:1521:ORA112",properties)
conn.isValid(5)
As a reminder, defining a Module on a Scripting Process Action is supported with the following scripting languages: Beanshell, Rhino, Nashorn, Javascript.
For other languages such as Jython and Groovy, you must use the complete function as described in previous sections.