1 概述

      为了能够在创建和使用自定义 DMSQL 程序时，使用其他语言实现的接口，DM 提供了 C、JAVA 外部函数，这样即使外部函数在执行中出现了任何问题，都不会影响到服务器的正常执行。
      无论是 C 外部函数还是 JAVA 外部函数，都需要将动态库或 jar 包上传到服务器端或在服务器端编译生成动态库或jar 包，系统管理员应对动态库和jar包进行严格审查，以防止外部函数中包含病毒或恶意代码，引发安全问题。
      下面主要介绍下如果使用JAVA外部函数。

2 实现原理

当用户调用 JAVA 外部函数时，服务器操作步骤如下：首先，确定调用（外部函数使用的）jar 包及函数；然后，通知代理进程工作。代理进程装载指定的jar包，并在函数执行后将结果返回给服务器。
需要注意的是，进行 JAVA 外部函数调用应保证当前用户可以运行 JAVA 命令，否则会导致调用失败。

3 目录和用户说明

数据库安装目录：/home/dmdba/dmdbms
dmagent配置文件：
DM7：/home/dmdba/dmdbms/tool/dmagent/config.properties
DM8：/home/dmdba/dmdbms/tool/dmagent/agent.ini
数据库配置文件：/dbdata/dmdata/DAMENG/dm.ini
数据库用户：dmdba

4 LINUX环境使用

4.1 创建JAVA项目

新建JAVA项目，编写完业务代码之后，打包成jar包。

4.2 JAR包放入指定的路径

使用dmdba用户在数据库安装目录/home/dmdba/dmdbms/bin下创建文件夹external_jar，然后将jar包放入该目录下。

4.3 配置数据库服务器JDK

拷贝jdk安装包到数据库服务器上，配置全局或者dmdba用户的jdk环境变量。jdk版本尽量用1.8，同时确保数据库服务器jdk的版本要高于或者等于jar包的jdk版本，否则可能会无法使用外部函数。
全局配置方式：在/etc/profile插入以下内容，运行source /etc/profile，使环境生效，在终端输入java -version，看是否成功，成功即出现相应的版本号。

export JAVA_HOME=/usr/local/jdk1.8.0_321
export PATH=.:$JAVA_HOME/bin:$PATH
export CLASSPATH=.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar

4.4 修改dmagent配置文件

4.4.1 DM7

dmagent 存在 3 种运行模式，run_mode为0则只开启 java 外部函数的代理模式。使用外部函数功能时dmagent 配置文件中ap_port要和数据库配置文件dm.ini中的EXTERNAL_JFUN_PORT 保持一致，配置文件内容如下：

#[General]
#run_mode values:
#0 - assist process
#1 - assist process & monitor
#2 - assist process & monitor & deployer
run_mode=0
ap_port=6363
rmi_port=6364
#[DEM]
center.url=http://localhost:8080/eunomia
center.agent_servlet=dem/dma_agent

4.4.2 DM8

ap_enable 设置为true则启用外部函数的代理功能能，使用外部函数功能时dmagent 配置文件中ap_port要和数据库配置文件dm.ini中的EXTERNAL_JFUN_PORT 保持一致，配置文件内容如下：

#ap
ap_enable    = true                                              
ap_port      = 6363

4.5 运行dmagent服务

4.5.1 DM7

命令行模式运行脚本：./DMAgentRunner.sh
服务模式运行脚本：./DMAgentService.sh start

4.5.2 DM8

前台启动：./start.sh agent.ini
后台启动：./start.sh -d agent.ini

4.6 修改数据库配置文件

可直接修改配置文件 ENABLE_EXTERNAL_CALL=1，或者SQL动态修改SP_SET_PARA_VALUE(2,‘ENABLE_EXTERNAL_CALL’,1)，同时确保参数 EXTERNAL_JFUN_PORT 和dmagent的ap_port保持一致，默认为6363。然后重启数据库服务。

4.7 创建外部函数

创建的用户需拥有DBA权限或者具有 CREATE FUNCTION 数据库权限，在达梦管理工具中创建外部函数，语句如下：

--base64加密
CREATE OR REPLACE FUNCTION F_ENCRYPTBASE64(A VARCHAR)
RETURN VARCHAR
EXTERNAL '/home/dmdba/dmdbms/bin/external_jar/externalFunction.jar'
"com/dm/Main.encryptBASE64" USING JAVA;

--base64解密
CREATE OR REPLACE FUNCTION F_DECRYPTBASE64(A VARCHAR)
RETURN VARCHAR
EXTERNAL '/home/dmdba/dmdbms/bin/external_jar/externalFunction.jar'
"com/dm/Main.decryptBASE64" USING JAVA;

--通过传参文件路径和文件名来解析文件内容并返回
CREATE OR REPLACE FUNCTION F_EXPLAIN_FILE(FILEPATH VARCHAR, 
FILENAME VARCHAR)
RETURN VARCHAR
EXTERNAL '/home/dmdba/dmdbms/bin/external_jar/externalFunction.jar'
"com/dm/Main.explainFile" USING JAVA;

--发送http post请求获取其他服务数据
CREATE OR REPLACE FUNCTION F_SEND_REQUEST(URL VARCHAR)
RETURN VARCHAR
EXTERNAL '/home/dmdba/dmdbms/bin/external_jar/externalFunction.jar'
"com/dm/Main.sendRequest" USING JAVA;

4.8 调用外部函数

5 使用说明

同名jar包更新后需要重启dmagent服务生效；

jar包中的函数应为 static 类型；

jar包必须存放在指定的路径bin/external_jar目录下；

函数参数最多不超过128个，参数类型和个数必须和jar包定义的一致。目前支持的函数参数类型：Int、字符串(char、varchar、varchar2)、bigint、double。分别对应 java 类型：Int、string、long、double；

返回值类型必须和jar包里函数定义的一致；

外部函数中jar包路径尽量用绝对路径，相对路径可能识别不到jar包；

引用函数名如果使用默认包名，则格式为：类名.方法名，例如Main.test；如果不使用默认包名，则包名内部、包名与类名间需要用/间隔，则格式为：包名/类名.方法名，例如：com/dm/Main.test。注意，此处的/，不能写反；