Como chamar o runtime Java nas Extensões de Linguagem do SQL Server

  • Artigo

Aplica-se a: SQL Server 2019 (15.x) e versões posteriores

As Extensões de Linguagem do SQL Server usam o procedimento armazenado do sistema sp_execute_external_script como a interface para chamar o runtime do Java.

Este artigo de instruções explica detalhes de implementação para classes e métodos Java executados no SQL Server.

Onde posicionar classes Java

Há dois métodos para chamar classes Java no SQL Server:

  1. Coloque os arquivos .class ou .jar no classpath do Java.

  2. Faça upload de classes compiladas em um arquivo .jar e outras dependências no banco de dados usando a DDL da biblioteca externa.

Observação

Como uma recomendação geral, use arquivos .jar, e não arquivos .class individuais. Essa é uma prática comum em Java e facilitará a experiência geral. Consulte também Criar um arquivo .jar Java com base em arquivos de classe.

Usar Classpath

Princípios básicos

Veja a seguir alguns princípios básicos ao executar o Java no SQL Server.

  • As classes Java personalizadas compiladas devem existir em arquivos .class ou .jar no classpath do Java. O parâmetro CLASSPATH fornece o caminho para os arquivos Java compilados.

  • O método Java que você está chamando deve ser fornecido no parâmetro script no procedimento armazenado.

  • Se a classe pertencer a um pacote, o packageName deverá ser fornecido.

  • params é usado para passar parâmetros para uma classe Java. Não há suporte à chamada de um método que requer argumentos. Portanto, os parâmetros são a única maneira de passar valores de argumento para seu método.

Observação

Esta observação reitera operações com e sem suporte específicas para Java no SQL Server 2019 (15.x) e versões posteriores. No procedimento armazenado, há suporte a parâmetros de entrada, mas não a parâmetros de saída.

Chamar classes Java

O procedimento armazenado do sistema sp_execute_external_script é a interface usada para chamar o runtime do Java. O exemplo a seguir mostra um sp_execute_external_script que usa a extensão do Java e parâmetros para especificar o caminho, o script e o código personalizado.

Observação

Observe que você não precisa definir qual método chamar. Por padrão, um método chamado execute é chamado. Isso significa que você precisa seguir o SDK de Extensibilidade da Microsoft para Java no SQL Server e implementar um método execute em sua classe Java.

DECLARE @param1 INT

SET @param1 = 3

EXEC sp_execute_external_script @language = N'Java',
    @script = N'<packageName>.<ClassName>',
    @input_data_1 = N'<Input Query>',
    @param1 = @param1;

Definir CLASSPATH

Depois de compilar sua classe ou classes Java e criado um arquivo .jar no classpath do Java, você terá duas opções para fornecer o caminho para a extensão de Java do SQL Server:

  1. Usar bibliotecas externas

    A opção mais fácil é fazer o SQL Server encontrar automaticamente suas classes criando bibliotecas externas e apontando a biblioteca para um jar. Usar bibliotecas externas para Java

  2. Registrar uma variável de ambiente do sistema

    Você pode criar uma variável de ambiente do sistema e fornecer os caminhos para o arquivo .jar que contém as classes. Criar uma variável de ambiente do sistema chamada CLASSPATH.

Usar biblioteca externa

No SQL Server 2019 (15.x) e versões posteriores, você pode usar bibliotecas externas para a linguagem Java no Windows e Linux. Você pode compilar suas classes em um arquivo .jar e fazer upload do arquivo .jar e de outras dependências no banco de dados usando a DDL CREATE EXTERNAL LIBRARY.

Exemplo de como fazer upload de um arquivo .jar com a biblioteca externa:

CREATE EXTERNAL LIBRARY myJar
FROM (CONTENT = '<local path to .jar file>')
WITH (LANGUAGE = 'Java');
GO

Ao criar uma biblioteca externa, o SQL Server recebe automaticamente acesso a classes Java e não é necessário definir nenhuma permissão especial como o classpath.

O seguinte código é um exemplo de chamada a um método em uma classe de um pacote carregado como uma biblioteca externa:

EXEC sp_execute_external_script
    @language = N'Java',
    @script = N'MyPackage.MyCLass',
    @input_data_1 = N'SELECT * FROM MYTABLE'
WITH RESULT SETS((column1 INT));

Para obter mais informações, confira CREATE EXTERNAL LIBRARY.

Conexão de loopback para o SQL Server

Use uma conexão de loopback para se conectar novamente ao SQL Server por JDBC a fim de ler ou gravar dados de um Java executado de sp_execute_external_script. Você pode fazer isso quando usar os argumentos InputDataSet e OutputDataSet de sp_execute_external_script não é possível. Para fazer uma conexão de loopback no Windows, use o seguinte exemplo:

jdbc:sqlserver://localhost:1433;databaseName=Adventureworks;integratedSecurity=true;

Para fazer uma conexão de loopback no Linux, o driver JDBC requer três propriedades de conexão definidas no seguinte certificado:

Autenticação de certificado de cliente

Conteúdo relacionado