Guide pratique pour appeler le runtime Java dans les extensions de langage SQL Server

  • Article

S’applique à : SQL Server 2019 (15.x) et versions ultérieures

Les extensions de langage SQL Server utilisent la procédure stockée système sp_execute_external_script comme interface pour appeler le runtime Java.

Cet article décrit de manière pratique les détails relatifs à l’implémentation des classes et méthodes Java qui s’exécutent sur SQL Server.

Où placer les classes Java

Il existe deux méthodes pour appeler des classes Java dans SQL Server :

  1. Placez les fichiers .class ou .jar dans votre classpath Java.

  2. Chargez les classes compilées dans un fichier .jar et les autres dépendances dans la base de données à l’aide de l’instruction DDL relative à la bibliothèque externe.

Remarque

En règle générale, utilisez de préférence des fichiers .jar et non des fichiers .class individuels. Il s’agit d’une pratique courante en Java, qui rend l’expérience globale plus facile. Consultez également Créer un fichier .jar Java à partir de fichiers de classe.

Utiliser Classpath

Principes de base

Voici quelques principes de base liés à l’exécution de Java sur SQL Server.

  • Les classes Java personnalisées et compilées doivent exister dans les fichiers .class ou .jar de votre classpath Java. Le paramètre CLASSPATH fournit le chemin des fichiers Java compilés.

  • La méthode Java que vous appelez doit être indiquée dans le paramètre script de la procédure stockée.

  • Si la classe appartient à un package, le packageName doit être fourni.

  • params permet de passer des paramètres à une classe Java. L’appel d’une méthode qui nécessite des arguments n’est pas pris en charge. Les paramètres sont donc le seul moyen de passer des valeurs d’argument à votre méthode.

Remarque

Cette remarque rappelle les opérations prises en charge et non prises en charge spécifiques à Java dans SQL Server 2019 (15.x) et versions ultérieures. Dans la procédure stockée, les paramètres d’entrée sont pris en charge, tandis que les paramètres de sortie ne sont pas pris en charge.

Appeler la classe Java

La procédure stockée système sp_execute_external_script est l’interface utilisée pour appeler le runtime Java. L’exemple suivant montre une procédure stockée système sp_execute_external_script qui utilise l’extension Java, et des paramètres qui permettent de spécifier le chemin, le script et votre code personnalisé.

Remarque

Vous n’avez pas besoin de définir la méthode à appeler. Par défaut, une méthode nommée execute est appelée. Cette appellation signifie que vous devez suivre le kit SDK d’extensibilité Microsoft pour Java pour SQL Server, et implémenter une méthode execute dans votre 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;

Définir CLASSPATH

Une fois que vous avez compilé votre classe ou vos classes Java, et créé un fichier .jar dans votre classpath Java, vous avez deux options pour fournir le chemin d’accès à l’extension Java de SQL Server :

  1. Utiliser des bibliothèques externes

    L’option la plus simple consiste à permettre à SQL Server de trouver automatiquement vos classes, en créant des bibliothèques externes et en les faisant pointer vers un fichier jar. Utiliser des bibliothèques externes pour Java

  2. Inscrire une variable d’environnement système

    Vous pouvez créer une variable d’environnement système, et fournir les chemins vers votre fichier .jar qui contient les classes. Créez une variable d’environnement système appelée CLASSPATH.

Utiliser une bibliothèque externe

Dans SQL Server 2019 (15.x) et versions ultérieures, vous pouvez utiliser des bibliothèques externes pour le langage Java sur Windows et Linux. Vous pouvez compiler vos classes dans un fichier .jar et charger le fichier .jar ainsi que d’autres dépendances dans la base de données à l’aide de l’instruction DDL CRÉER UNE BIBLIOTHÈQUE EXTERNE.

Exemple de chargement d’un fichier .jar avec une bibliothèque externe :

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

Lorsque SQL Server crée une bibliothèque externe, il a automatiquement accès aux classes Java. De plus, il n’est pas nécessaire de définir des autorisations spéciales pour le chemin d’accès aux classes.

Le code suivant est un exemple d’appel d’une méthode dans une classe à partir d’un package, téléchargé comme bibliothèque externe :

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

Pour plus d’informations, consultez CREATE EXTERNAL LIBRARY.

Connexion de bouclage à SQL Server

Utilisez une connexion de bouclage pour vous reconnecter à SQL Server sur JDBC afin de lire ou d’écrire des données à partir de code Java exécuté dans sp_execute_external_script. Vous pouvez l’utiliser lorsque les arguments InputDataSet et OutputDataSet de sp_execute_external_script ne sont pas possibles. Pour établir une connexion de bouclage sur Windows, utilisez l’exemple suivant :

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

Pour établir une connexion de bouclage sur Linux, il est nécessaire de définir trois propriétés de connexion dans le certificat suivant pour le pilote JDBC :

Authentification par certificat client

Contenu connexe