#外置UDF

YashanDB支持在PL/SQL中调用外部Java程序中定义的方法，实现数据库中的外置UDF功能。分布式部署中不可使用此功能。

# 环境要求

使用外置UDF要求数据库服务器已安装JDK（1.8及其以上版本），并配置如下环境变量：

#如下路径需更换为实际的jdk安装路径
export LD_LIBRARY_PATH=/etc/jdk-18.0.2/lib/server:$LD_LIBRARY_PATH

# 创建自定义库

将外置UDF所需要的自定义库创建到数据库中，YashanDB支持创建包含自定义Java函数的.class文件或者jar包的自定义库，通过CREATE LIBRARY中的CREATE LIBRARY语句创建自定义库。

创建自定义库时不检查库文件是否存在，在执行外置UDF时才检查并加载库文件。

示例

CREATE OR REPLACE LIBRARY ya_lib IS
'/home/yasdb/example/UDFexample.class';
/

UDFexample.class对应UDFexample.java文件内容如下：

package example;

public class UDFexample {
    public static String execJdbcexample(int ctrls) {
        switch (ctrls) {
        case 1:return "Hello";
        case 2:return "World";
        default:return "!";
        }
    }

    public static void main(String[] args) {
       String a = execJdbcexample(1);
    }
}

当class文件或jar包内容发生变化时，需重新生成自定义库。

# 定义外置UDF

通过创建一个函数，实现对外置UDF的定义，语法如下：

CREATE [OR REPLACE] FUNCTION [schema "."] function_name ["("  argument_define {"," argument_define}  ")"] RETURN return_datatype (IS|AS) 
call_spec;

其中，为实现向外置UDF传递参数和获得返回值，对函数定义的参数和返回值应与java_method里的参数和返回值一致，此处一致的具体含义为：

参数个数及顺序一致。
数据类型兼容，即显式地满足YashanDB和java数据类型对应关系，或者通过隐式转换后满足对应关系，对应关系见下面描述。

语法图

代码

call_spec

# LANGUAGE

指定外置UDF所用的语言，即java。

# NAME

指定需引用的java函数的函数签名，java_package.java_class部分长度需小于128字节，其格式为：

java_package.java_class.java_method(argu1_datatype,argu2_datatype...) [return return_datatype]

此处引用的java函数必须为static的java方法，且该方法的参数和返回类型必须在如下列示的java数据类型范围内：

bool：对应YashanDB的BOOLEAN
byte：对应YashanDB的TINYINT
char：对应YashanDB的INT（传入的值需在0-16位无符号整数最大值之间，暂不支持非数值的输入）
short：对应YashanDB的SMALLINT
int：对应YashanDB的INT
long：对应YashanDB的BIGINT
float：对应YashanDB的FLOAT
double：对应YashanDB的DOUBLE
string：对应YashanDB的VARCHAR

# library_name

指定已经创建的自定义库名称。

# library_path

通过LOADJAVA高级包程序加载的自定义库路径，YashanDB已提供直接创建自定义库的功能，此方式不再建议使用。

示例

CREATE OR REPLACE FUNCTION udf_func(argu INT) RETURN VARCHAR IS
LANGUAGE java
NAME 'example.UDFexample.execJdbcexample(int) return string'
LIBRARY ya_lib;
/

CREATE OR REPLACE FUNCTION udf_func(argu INT) RETURN VARCHAR IS
LANGUAGE java
NAME 'example.UDFexample.execJdbcexample(int) return string'
LIBRARY '/home/yasdb/example/UDFexample.class';
/

# 运行外置UDF

对于已成功定义的外置UDF，其调用方法与函数一致。

示例

SELECT udf_func(1) FROM dual;
UDF_FUNC(1)                                                      
---------------------------------------------------------------- 
Hello  

SELECT udf_func(2) FROM dual;
UDF_FUNC(2)                                                      
---------------------------------------------------------------- 
World

# 删除外置UDF

删除定义了某个外置UDF的函数，即实现对这个外置UDF的删除。

# 删除自定义库

确认外置UDF使用的自定义库不再使用时，可对其进行删除，使用DROP_LIBRARY语句删除自定义库。