Configure, Compile, Deploy and Test User-Defined Functions
To compile and deploy user-defined functions
1. Add a folder with the name of your library under the default external UDF library deployment folder MashZoneNG-install/raql-udfs.
Note: | The folder for UDF library deployment is set in the system property -Dpresto.raql.udf.libsDir. This may be a different folder in clustered environments with a shared external configuration folder for Business Analytics. |
This new folder is the root deployment folder for your library. For example:
/SoftwareAG/MashZoneNG/raql-udfs/MyOrgRaqlLib
2. Complete configuration that identifies the Java packages for this library in a lib.json file. This file must reside in the root deployment folder for your library, created in the previous step.
Note: | You may also want to place a copy of this configuration in your library development folder to track in your source control system. |
This file uses the JSON format to identify packages that contain user-defined functions for a library. For example:
{
"exportedFuncs" : {
"annotatedPackages" : [
"com.jackbe.jbp.raql.samplelib.annotated.udf",
"com.jackbe.jbp.raql.samplelib.annotated.uda",
"com.jackbe.jbp.raql.samplelib.annotated.udw"
],
"classes" : [
{
"name" : "com.jackbe.jbp.raql.samplelib.configured.MoreStringFunctions",
"funcs" : [
{ "name" : "low", "method" : "lower" },
{ "method" : "hashCode" }
]
},
{
"name" : "com.jackbe.jbp.raql.samplelib.configured.AverageAggregationFunctionFactory",
"funcs" : [
{ "name" : "avg" }
]
},
{
"name" : "com.jackbe.jbp.raql.samplelib.configured.LeadWindowFunction",
"funcs" : [
{ "name" : "lead" }
]
}
]
}
}
This example identifies three packages for this library. The classes property must be present in configuration, but can be an empty array like this example. The RAQL Engine will search each class within the identified packages for function annotations to find the functions to add.
You can also optionally identify classes, functions and methods in this configuration. See
UDF Library Configuration for more information on this method.
3. Compile your Java class with user-defined functions, being sure to include the jackbe-presto-raql-version.jar and rtm-version.jar files and any third-party libraries you used in this class in the classpath.
For Windows for example:
%JAVA_HOME%/bin/javac -classpath c:\SoftwareAG\MashZoneNG\apache-tomee-jaxrs\webapps\presto\WEB-INF\lib\jackbe-presto-raql-3.8.jar,
c:\SoftwareAG\MashZoneNG\apache-tomee-jaxrs\webapps\presto\WEB-INF\lib\rtm-9.7.0.jar
-d classes src\com\MyOrg\raqlUdf\MyReplaceFunc.java
For Linux, OS/X or UNIX for example:
javac -classpath /SoftwareAG/MashZoneNG/apache-tomee-jaxrs/webapps/mashzone/WEB-INF/lib/jackbe-presto-raql-3.8.jar,
/SoftwareAG/MashZoneNG/apache-tomee-jaxrs/webapps/mashzone/WEB-INF/lib/rtm-9.7.0.jar
-d classes src/com/MyOrg/raqlUdf/MyStringFuncs.java
This will add the compiled class to the classes folder in your development folder for this library.
4. Deploy the classes and any third-party libraries for this library to the Business Analytics Server. Copy the following folders to the root deployment folder for your library:
/classes folder and all contents
/lib folder and all contents
Important: | If you have included either the RAQL or RTM JAR files in your library-name/lib folder, do not copy these JARs to the deployment folder for your library as this causes errors when functions in the library are used. |
5. Restart the Business Analytics Server.
6. Write mashups that use these new user-defined functions to test them.
You refer to user-defined functions in the form library-name.function-name(arg[,...) to identify both the library name and the function name. For example:
UDF Library Configuration
The lib.json file contains configuration that identifies the Java packages with user-defined functions for RAQL. It can also optionally contain configuration that identifies the specific classes and methods in these packages and the function names to map to methods.
Note: | It is a best practice to configure methods and function names using annotations in the Java classes directly. If you choose to use lib.json configuration instead, you should omit the annotations in your Java classes for user-defined functions. |
The following example includes method and function mapping configuration along with the required package configuration information:
{
"exportedFuncs": {
"annotatedPackages":[
"com.MyOrg.raqlUdf",
"com.MyOrg.aggregate.raqlUdf",
"com.MyOrg.window.raqlUdf" ],
"classes":[
{ "name": "com.MyOrg.raqlUDF.MyStringFuncs",
"funcs":[ {"method": "replace" },
{ "name": "capitalize", "method": "upper"} ] },
{ "name": "com.MyOrg.aggRaqlUdf.KurtosisFunction",
"funcs": [ {"name": "kurtosis" ] }
]
}
}
External UDF Library Deployment Folder
A default external UDF Library Deployment folder is created when you install Business Analytics at MashZoneNG-install/raql-udfs where you can deploy all your user-defined functions.
In clustered environments, you may want to create a shared external folder for Business Analytics configuration and move all user-defined functions, including the Business Analytics built-in function library, to this shared location for all members of the cluster. The structure would look something like this:
If you move user-defined functions from the default UDF Library Deployment folder, you must also update an environmental variable for each Business Analytics Server:
1. Edit the script for the appropriate operating system in any text editor of your choice:
MashZoneNG-install/apache-tomee-jaxrs/bin/setenv.bat file, for Windows systems, or
MashZoneNG-install/apache-tomee-jaxrs/bin/setenv.sh file for Linux, OS/X or UNIX systems.
2. Add or update the -Dpresto.raql.udf.libsDir system property with the path to point to the new shared location.
3. Save your changes and restart the Business Analytics Server.
