Création d’un gestionnaire d’UDF Java¶

Écriture du gestionnaire de l’UDF en Java¶

Utilisez les exigences et les lignes directrices suivantes lors de l’écriture de votre gestionnaire d’UDF Java.

• Définissez la classe comme publique.

• Dans la classe, déclarez au moins une méthode publique à utiliser comme gestionnaire d’UDF.

  Pour une UDF en ligne, déclarez une seule méthode de gestionnaire. Si, au contraire, vous avez l’intention d’empaqueter la classe dans un JAR en tant que gestionnaire en zone de préparation, vous pouvez déclarer plusieurs méthodes de gestionnaire, puis spécifier chacune d’elles en tant que gestionnaire avec la clause HANDLER d’une instruction CREATE FUNCTION.

  Pour en savoir plus sur la différence entre un gestionnaire en ligne et un gestionnaire mis en zone de préparation, voir Conserver le code du gestionnaire en ligne ou dans une zone de préparation.

  Vous pouvez déclarer d’autres méthodes, si nécessaire, qui seront appelées par la méthode de gestionnaire.

  Utilisez les exigences et les lignes directrices suivantes pour chaque méthode de gestionnaire :

  • Déclarez la méthode de gestionnaire comme publique, soit statique, soit non statique.

    Si la méthode n’est pas statique, votre classe doit également déclarer un constructeur à zéro argument ou pas de constructeur du tout.

    Snowflake ne transmet aucun argument au constructeur lorsqu’il instancie la classe. Si le constructeur génère une erreur, celle-ci est signalée comme une erreur de l’utilisateur, avec le message d’exception.

  • Spécifiez un type de retour approprié.

    Le type de retour doit être l’un des types de données spécifiés dans la colonne Java Data Type de la table SQL-Java Type Mappings. Le type de retour doit être compatible avec le type de données SQL spécifié dans la clause RETURNS de l’instruction CREATE FUNCTION.

  • Assurez-vous que chaque argument de méthode de gestionnaire (le cas échéant) est un type de données spécifié dans la colonne Java Data Type de la table SQL-Java Type Mappings.

    Lorsque vous choisissez les types de données des variables Java, tenez compte des valeurs maximales et minimales possibles des données qui pourraient être envoyées de (et retournées à) Snowflake.

  • Si vous surchargez une méthode dans une classe Java donnée, gardez à l’esprit que Snowflake utilise uniquement le nombre d’arguments de la méthode, et non leurs types, pour différencier les méthodes de gestionnaire au sein d’une classe. La résolution basée sur les types de données n’est pas pratique, car certains types de données SQL peuvent être mappés à plus d’un type de données Java et donc potentiellement à plusieurs signatures de méthode de gestionnaire.

    Par exemple, si deux méthodes Java d’une classe ont le même nom, le même nombre d’arguments et des types de données différents, l’appel d’une UDF qui utilise l’une de ces méthodes comme gestionnaire génère une erreur similaire à la suivante :

    Cannot determine which implementation of handler "handler name" to invoke since there are multiple
    definitions with <number of args> arguments in function <user defined function name> with
    handler <class name>.<handler name>
    

    Si un entrepôt est disponible, l’erreur est détectée au moment où l’UDF est créée. Sinon, l’erreur se produit lors de l’appel de l’UDF.

  • Respectez les contraintes imposées par Snowflake pour les UDFs Java dans chaque méthode du gestionnaire et dans les méthodes qu’il appelle. Pour en savoir plus sur ces contraintes, voir Concevoir des gestionnaires qui respectent les contraintes imposées par Snowflake.

Ajouter des dépendances au Classpath¶

Lorsque le code de votre gestionnaire nécessite des classes empaquetées dans des fichiers JAR externes, vous pouvez ajouter ces dépendances au classpath géré par Snowflake disponible pour votre gestionnaire. Ce qui suit décrit comment ajouter des fichiers JAR au classpath visible par un gestionnaire d’UDF Java. Pour plus d’informations, voir Mettre les dépendances à la disposition de votre code.

Organiser vos fichiers¶

Si vous prévoyez de compiler vous-même le code Java pour créer le fichier JAR, vous pouvez organiser les fichiers comme indiqué ci-dessous. Cet exemple suppose que vous prévoyez d’utiliser le mécanisme de paquetage de Java.

• developmentDirectory

  • packageDirectory

    • class_file1.java

    • class_file2.java

  • classDirectory

    • class_file1.class

    • class_file2.class

  • manifest_file.manifest (facultatif)

  • jar_file.jar

  • put_command.sql

developmentDirectory

Ce répertoire contient les fichiers spécifiques au projet nécessaires à la création de votre UDF Java.

packageDirectory

Ce répertoire contient les fichiers .java à compiler et à inclure dans le paquet.

class_file#.java

Ces fichiers contiennent le code source Java de l’UDF.

class_file#.class

Il s’agit du ou des fichiers .class créés en compilant des fichiers .java.

manifest_file.manifest

Le fichier manifeste facultatif utilisé lors de la combinaison des fichiers .class (et éventuellement des fichiers JAR de dépendance) dans le fichier JAR.

jar_file.jar

Le fichier JAR qui contient le code de l’UDF.

put_command.sql

Ce fichier contient la commande SQL PUT permettant de copier le fichier JAR vers une zone de préparation Snowflake.