MaxCompute:Desenvolvimento de UDFs em Java

Ao desenvolver uma 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, se UDF1 e UDF2 corresponderem a udf1.jar e udf2.jar respectivamente, e ambos os arquivos JAR contiverem com.aliyun.UserFunction.class com lógicas diferentes, a chamada simultânea dessas UDFs na mesma instrução SQL fará o MaxCompute carregar aleatoriamente uma das classes. Isso pode resultar em comportamentos inesperados ou falhas de compilação.

• Em uma UDF Java, utilize tipos de objeto (como String e Long) para parâmetros de entrada e valores de retorno, em vez de tipos primitivos (como int e long).

• Valores NULL no SQL correspondem a NULL em Java. Tipos primitivos do Java não aceitam valores NULL e, portanto, não são permitidos.

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

• Uso de UDF em um projeto do MaxCompute: O método é semelhante ao uso de funções integradas. Utilize uma função definida pelo usuário da mesma forma que uma função integrada.

• Uso de UDF entre projetos: Utilize uma UDF do Projeto B no Projeto A. A instrução a seguir mostra um exemplo: select B:udf_in_other_project(arg0, arg1) as res from table_t;. Para mais informações sobre compartilhamento entre projetos, consulte Cross-project resource access based on packages.

• Write a Hive UDF in Java

• Use complex data types in Java UDFs

• Replace strings by using regular expressions

• Obtain the values of strings that have no delimiters

• Obtain the values of strings that have delimiters

• Reference a file resource

• Reference a table resource

• Reference third-party packages in Python UDFs

Uma UDF em Java consiste nas seguintes partes:

• Pacote Java: Opcional.

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

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

  A classe base obrigatória é com.aliyun.odps.udf.UDF. Caso precise de outras classes UDF ou tipos de dados complexos, adicione as classes necessárias do MaxCompute SDK. 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 utilizar o tipo de dados STRUCT em uma UDF, a reflexão não consegue recuperar nomes e tipos de campos de com.aliyun.odps.data.Struct. Nesse caso, utilize a anotação @Resolve para recuperá-los. Se usar STRUCT em uma UDF, adicione a anotação @Resolve à classe da UDF. A 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 UDF Example: Complex Data Types.

• Classe Java personalizada: Obrigatório.

  Esta unidade organiza o código da UDF e define as 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.

  Implemente múltiplos métodos evaluate. Ao chamar a UDF, o MaxCompute seleciona o método evaluate correspondente com base nos tipos dos argumentos.

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

• Inicialização e limpeza da UDF: Opcional. Implemente a inicialização e a limpeza com void setup(ExecutionContext ctx) e void close(). O método void setup(ExecutionContext ctx) é executado uma vez antes do método evaluate e serve para inicializar recursos ou objetos membro necessários para a computação. O método void close() é executado uma vez após a conclusão de todas as chamadas de evaluate e realiza tarefas de limpeza, como fechar arquivos.

Os exemplos a seguir mostram 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 que os tipos de dados utilizados em uma UDF Java sejam consistentes com os tipos de dados do MaxCompute, utilize os mapeamentos a seguir.

O tipo Java byte[] não consta na lista de tipos Java suportados. Se você utilizar byte[] como parâmetro de entrada ou valor de retorno de um método evaluate, o sistema reportará um erro ODPS-0130071. Para processar dados binários em uma UDF, utilize 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. Também é possível converter dados binários em uma string codificada em Base64 e utilizar o tipo String para o valor de retorno.

Compatibilidade com UDFs do Hive

Se o seu projeto do MaxCompute utilizar a edição de tipos de dados 2.0, o MaxCompute suporta UDFs no estilo Hive. Utilize diretamente UDFs do Hive desenvolvidas para uma versão compatível do Hive.

A versão compatível do Hive é a 2.1.0, que corresponde ao Hadoop 2.7.2. Caso sua UDF tenha sido compilada em uma versão diferente do Hive ou do Hadoop, recompile o arquivo JAR da UDF com o Hive 2.1.0 ou Hadoop 2.7.2.

Para um exemplo detalhado de uso de uma UDF do Hive no MaxCompute, consulte UDF Example: Hive Compatibility.