Como criar um manipulador de UDF de Java¶

Como escrever o manipulador de UDF em Java¶

Use os seguintes requisitos e diretrizes ao escrever seu manipulador de UDF em Java.

• Defina a classe como pública.

• Dentro da classe, declare pelo menos um método público a ser usado como manipulador de UDF.

  Para uma UDF inline, declare apenas um método do manipulador. Se, em vez disso, você pretende inserir a classe em um JAR como um manipulador em estágio, você pode declarar vários métodos do manipulador, especificando mais tarde cada um como manipulador com a cláusula HANDLER de uma instrução CREATE FUNCTION.

  Para saber mais sobre a diferença entre um manipulador em linha e um manipulador em estágio, consulte Como manter o código do manipulador inline ou em um estágio.

  Você pode declarar outros métodos, se necessário, a serem chamados pelo método do manipulador.

  Use os seguintes requisitos e diretrizes para cada método do manipulador:

  • Declare o método do manipulador como público, estático ou não estático.

    Se o método não for estático, sua classe também deverá declarar um construtor sem argumentos ou nenhum construtor.

    O Snowflake não passa nenhum argumento para o construtor quando ele instancia a classe. Se o construtor lança um erro, o erro é lançado como um erro do usuário, juntamente com a mensagem de exceção.

  • Especifique um tipo de retorno adequado.

    O tipo de retorno deve ser um dos tipos de dados especificados na coluna Java Data Type da tabela de mapeamento de tipos SQL-Java. O tipo de retorno deve ser compatível com o tipo de dados SQL especificado na cláusula RETURNS da instrução CREATE FUNCTION.

  • Certifique-se de que cada argumento do método do manipulador (se houver) seja um tipo de dados especificado na coluna Java Data Type da tabela de mapeamento de tipos SQL-Java.

    Ao escolher os tipos de dados das variáveis de Java, leve em conta os valores máximos e mínimos possíveis dos dados que poderiam ser enviados do Snowflake (e devolvidos a ele).

  • Se você sobrecarregar um método em uma determinada classe Java, lembre-se de que o Snowflake usa apenas o número de argumentos do método, não seus tipos, para diferenciar os métodos do manipulador dentro de uma classe. A resolução baseada em tipos de dados não é prática, porque alguns tipos de dados de SQL podem ser mapeados para mais de um tipo de dados de Java e, portanto, potencialmente para mais de uma assinatura do método do manipulador.

    Por exemplo, se dois métodos Java em uma classe tiverem o mesmo nome, o mesmo número de argumentos e diferentes tipos de dados, chamar uma UDF que usa um desses métodos como manipulador gera um erro semelhante ao seguinte:

    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>
    

    Se um warehouse estiver disponível, o erro será detectado no momento em que a UDF for criada. Caso contrário, o erro ocorre quando a UDF é chamada.

  • Siga as restrições impostas pelo Snowflake para UDFs de Java em cada método do manipulador e nos métodos chamados por ele. Para saber mais sobre estas restrições, consulte Criação de manipuladores que ficam dentro das restrições impostas pelo Snowflake.

Adição de dependências ao Classpath¶

Se o código de seu manipulador exigir classes empacotadas em arquivos JAR externos, você poderá adicionar essas dependências ao classpath gerenciado pelo Snowflake disponível para seu manipulador. A seção a seguir descreve como adicionar arquivos JAR ao classpath visível a um manipulador de UDF de Java. Para obter mais informações, consulte Disponibilização das dependências para seus códigos.

Organização de seus arquivos¶

Se você planeja compilar o código de Java para criar o arquivo JAR por conta própria, você pode organizar os arquivos da forma mostrada abaixo. Este exemplo assume que você planeja usar o mecanismo de pacote do Java.

• developmentDirectory

  • packageDirectory

    • class_file1.java

    • class_file2.java

  • classDirectory

    • class_file1.class

    • class_file2.class

  • manifest_file.manifest (opcional)

  • jar_file.jar

  • put_command.sql

developmentDirectory

Esse diretório contém os arquivos específicos do projeto necessários para criar sua UDF em Java.

packageDirectory

Esse diretório contém os arquivos .java para compilar e incluir no pacote.

class_file#.java

Esses arquivos contêm o código-fonte de Java da UDF.

class_file#.class

Esses são os arquivos .class criados ao compilar os arquivos .java.

manifest_file.manifest

O arquivo do manifesto opcional usado ao combinar os arquivos .class (e, opcionalmente, os arquivos JAR de dependência) com o arquivo JAR.

jar_file.jar

O arquivo JAR que contém o código da UDF.

put_command.sql

Esse arquivo contém o comando SQL PUT para copiar o arquivo JAR em um estágio do Snowflake.