MaxCompute:Desenvolvimento de UDFs em Java

Ao desenvolver sua UDF em Java, observe os pontos abaixo:

• Evite incluir classes com o mesmo nome, mas lógicas diferentes, em arquivos JAR de UDF distintos. Por exemplo, suponha que UDF1 e UDF2 correspondam aos arquivos de recurso udf1.jar e udf2.jar, e ambos contenham uma classe chamada com.aliyun.UserFunction.class, porém com implementações diferentes. Se você chamar UDF1 e UDF2 na mesma instrução SQL, o MaxCompute carregará aleatoriamente uma das classes. Isso pode gerar resultados de execução inesperados ou até falhas de compilação.

• Em uma UDF Java, os tipos de dados dos parâmetros de entrada e dos valores de retorno devem ser tipos de objeto (por exemplo, String, Long), e não tipos primitivos (como int, long).

• Valores NULL no SQL são mapeados como NULL em Java. Tipos primitivos do Java não representam valores NULL do SQL e, portanto, não são permitidos.

Após desenvolver uma UDF em Java conforme descrito no Fluxo de trabalho de desenvolvimento de UDF anterior, chame-a no MaxCompute SQL. Os métodos disponíveis são:

• Dentro de um projeto — Chame a UDF diretamente, assim como qualquer função integrada.

• Entre projetos — Para usar uma UDF do projeto B dentro do projeto A, referencie-a com o prefixo do projeto:

  select B:udf_in_other_project(arg0, arg1) as res from table_t;

  Para configurar o compartilhamento entre projetos, consulte Acesso a recursos entre projetos baseado em pacotes.

Uma UDF em Java é composta pelas seguintes partes:

• Pacote Java: Opcional.

  Agrupe suas classes Java em um pacote para facilitar a localização e a reutilização.

• Herança da classe UDF: Obrigatória.

  A classe base necessária é com.aliyun.odps.udf.UDF. Se precisar de outras classes de UDF ou tipos de dados complexos, adicione as classes correspondentes do SDK do MaxCompute. Por exemplo, a classe para o tipo de dados STRUCT é com.aliyun.odps.data.Struct.

• Anotação @Resolve: Opcional.

  O formato é @Resolve(<signature>), onde signature define os tipos de dados dos parâmetros de entrada e do valor de retorno. Ao usar o tipo STRUCT em uma UDF, a reflexão não recupera nomes e tipos de campos de com.aliyun.odps.data.Struct. Nesse cenário, use a anotação @Resolve para obtê-los. Se a UDF usar STRUCT, adicione a anotação @Resolve à classe da UDF. Essa anotação afeta apenas as sobrecargas cujos parâmetros ou valores de retorno contenham com.aliyun.odps.data.Struct. Exemplo: @Resolve("struct<a:string>,string->string"). Para um exemplo detalhado, consulte Exemplo de UDF: Tipos de Dados Complexos.

• Classe Java personalizada: Obrigatória.

  Representa a unidade que organiza o código da UDF, definindo variáveis e métodos que implementam a lógica de negócio.

• Método evaluate: Obrigatório.

  Sua classe Java personalizada deve incluir um método evaluate público e não estático. Os tipos de dados de seus parâmetros de entrada e valor de retorno definem a assinatura SQL da UDF.

  É possível implementar múltiplos métodos evaluate. Durante a chamada da UDF, o MaxCompute seleciona o método evaluate correto com base nos tipos dos argumentos.

  Ao escrever uma UDF em Java, use tipos Java ou tipos Java Writable. Para ver os mapeamentos detalhados entre tipos de dados do MaxCompute e Java, consulte Apêndice: Tipos de dados.

• Inicialização e limpeza da UDF: Opcional. Implemente essas rotinas usando void setup(ExecutionContext ctx) e void close(). O método void setup(ExecutionContext ctx) é chamado uma única vez antes do método evaluate e serve para inicializar recursos ou objetos membros necessários à computação. Já o método void close() é executado uma vez após todas as chamadas ao evaluate serem concluídas e serve para tarefas de limpeza, como fechar arquivos.

Os exemplos abaixo ilustram dois tipos de UDFs.

• Uso de tipos Java

  // Organize the Java class in the org.alidata.odps.udf.examples package.
  package org.alidata.odps.udf.examples;  
  // Inherit the UDF class.
  import com.aliyun.odps.udf.UDF;         
  // Define a custom Java class.
  public final class Lower extends UDF { 
  // The evaluate method defines the UDF's logic. It takes a String and returns a String.
      public String evaluate(String s) { 
          if (s == null) { 
          return null; 
      } 
          return s.toLowerCase(); 
    } 
  }

• Uso de tipos Java Writable

  // Organize the Java class in the com.aliyun.odps.udf.example package.
  package com.aliyun.odps.udf.example;
  // Add the required classes for the Java Writable type.
  import com.aliyun.odps.io.Text;
  // Inherit the UDF class.
  import com.aliyun.odps.udf.UDF;
  // Define a custom Java class.
  public class MyConcat extends UDF {
    private Text ret = new Text();
  // Define the evaluate method. `Text` specifies the data type of the input parameters, and the `return` value is also a Text object.
    public Text evaluate(Text a, Text b) {
        if (a == null || b == null) {
        return null;
      }
        ret.clear();
        ret.append(a.getBytes(), 0, a.getLength());
        ret.append(b.getBytes(), 0, b.getLength());
        return ret;
    }
  }

Mapeamentos de tipos de dados

Para garantir consistência entre os tipos usados em uma UDF Java e aqueles suportados pelo MaxCompute, use os mapeamentos a seguir.

O tipo Java byte[] não consta na lista de tipos suportados. Se você usar byte[] como parâmetro de entrada ou valor de retorno de um método evaluate, o erro ODPS-0130071 será reportado. Para processar dados binários em uma UDF, use os tipos Java correspondentes ao tipo BINARY do MaxCompute: com.aliyun.odps.data.Binary para o tipo Java padrão, ou com.aliyun.odps.io.BytesWritable para o tipo Writable. Alternativamente, converta os dados binários para uma string codificada em Base64 e use o tipo String como valor de retorno.

Compatibilidade com UDFs do Hive

Caso seu projeto do MaxCompute use a edição de tipos de dados 2.0, o sistema suporta UDFs no estilo Hive. Assim, é possível usar diretamente UDFs do Hive desenvolvidas em versões compatíveis com o MaxCompute.

A versão compatível do Hive é a 2.1.0, correspondente ao Hadoop 2.7.2. Se sua UDF foi compilada em uma versão diferente do Hive ou Hadoop, recompile o arquivo JAR usando Hive 2.1.0 ou Hadoop 2.7.2.

Para um exemplo detalhado de uso de UDFs do Hive no MaxCompute, consulte Exemplo de UDF: Compatibilidade com Hive.