Desenvolver Funções de Cálculo Definidas pelo Cliente

26 Desenvolver Funções de Cálculo Definidas pelo Cliente

Para aprimorar as funções de cálculo disponíveis para cubos de armazenamento em bloco do Essbase, você pode usar o Java para desenvolver suas próprias funções definidas pelo cliente (CDFs). Depois de gravar as funções, instale a classe Java e, em seguida, registre as funções globalmente com o Essbase Server ou localmente em um aplicativo.

Você pode usar suas funções definidas pelo cliente nos scripts de cálculo do Essbase.

O Essbase não fornece ferramentas para criar classes e arquivos Java; você deve ter uma versão suportada do JDK.

Para obter exemplos de funções definidas pelo usuário, consulte Exemplos de Código Java.

As funções definidas personalizadas estão disponíveis apenas para cubos de armazenamento em blocos (não relevantes para cubos de armazenamento agregado).

Para criar uma função definida pelo cliente, use o fluxo de trabalho a seguir.

Verifique os requisitos para funções definidas pelo cliente: Requisitos para Validade de Funções Definidas pelo Cliente
Crie uma classe Java pública que contenha pelo menos um método estático público a ser usado como uma função definida personalizada: Criar e Compilar uma Classe Java para Funções Definidas pelo Cliente
Instale a classe Java: Instalando Classes Java no Essbase Server
Registre a função definida pelo cliente como uma função local ou global: Registrar Funções Definidas pelo Cliente

Requisitos para Validade de Funções Personalizadas

Você cria suas funções definidas pelo Essbase como métodos em uma classe Java. Para funções globais, escreva métodos em uma classe. Para funções de aplicativo, use classes separadas e arquivos jar por aplicativo. Teste as funções localmente em um aplicativo antes de registrá-las globalmente. Observe os tipos de dados, as variáveis e as convenções de nomenclatura suportados.

Você pode criar vários métodos em uma classe para serem usados como uma função definida personalizada. Normalmente, a Oracle recomenda que você crie os métodos que planeja usar em todos os aplicativos em um Essbase Server como funções definidas pelo cliente em uma única classe. No entanto, se você planeja adicionar funções definidas pelo cliente que serão usadas em aplicativos seletivos no Essbase Server, crie essas funções definidas pelo cliente em uma classe separada e adicione-as ao Essbase Server em um arquivo .jar separado.

Ao criar várias classes Java que contêm métodos para uso como funções definidas personalizadas, verifique se o nome de cada classe é exclusivo. Nomes de classe duplicados fazem com que os métodos na classe duplicada não sejam reconhecidos, e você não pode registrar esses métodos como funções definidas pelo cliente.

Usando programas de teste em Java, teste as classes e os métodos Java. Quando estiver satisfeito com a saída dos métodos, instale-os no Essbase Server e registre-os em um único aplicativo de teste. Não registre funções globalmente para teste; isso dificulta a atualização se você encontrar problemas.

Os métodos em funções definidas personalizadas podem ter qualquer combinação dos seguintes tipos de dados suportados como parâmetros de entrada:

booliano
byte
caractere
com.hyperion.essbase.calculator.CalcBoolean
flutuante, duplo
java.lang.String
curto, int, longo
matrizes de qualquer um desses tipos

CalcBoolean é um tipo de dados específico do Essbase que pode incluir três valores — VERDADEIRO, FALSO e #MISSING. Para obter informações sobre os outros tipos de dados listados, consulte a documentação do JDK.

O tipo de dados de retorno do método pode ser void ou qualquer um dos tipos de dados anteriores. Os tipos de dados retornados são convertidos em tipos de dados específicos do Essbase. As strings são mapeadas para um tipo de string. Os valores boolianos são mapeados para o tipo de dados CalcBoolean. Todos os outros valores são mapeados para um tipo double.

Observação:

O Essbase não suporta variáveis duplas retornadas com valores infinitos ou Não Numéricos. Se esses valores forem retornados de um programa Java, eles podem não ser registrados ou exibidos corretamente no Essbase. As variáveis duplas devem ser verificadas quanto a valores infinitos ou Não Numéricos e definidas como valores finitos antes de serem retornadas ao Essbase. Consulte a entrada da classe Double na documentação do JDK.

Para criar, excluir e gerenciar funções definidas pelo cliente, o Essbase requer estas permissões de segurança:

Funções locais e definidas pelo cliente em todo o aplicativo: Application Manager ou superior
Funções globais, definidas pelo servidor e personalizadas: Administrador do Sistema

Ao registrar uma função definida pelo cliente no Essbase, você dá à função um nome, que é usado em scripts de cálculo e fórmulas e é distinto da classe Java e do nome do método usado pela função.

Siga estes requisitos para nomear funções definidas personalizadas:

Inicie o nome com o símbolo @. O resto de um nome de função pode conter letras, números e os seguintes símbolos: @, #, $ e _. Os nomes das funções não podem conter espaços.

Por exemplo: @MYFUNCTION
Inicie os nomes de funções definidas personalizadas que são chamadas apenas por macros definidas personalizadas com "@_", para distingui-las das funções e macros de uso geral.

Por exemplo: @_MYFUNCTION
Funções definidas pelo cliente devem ter nomes exclusivos. Os nomes das funções devem ser diferentes entre si, dos nomes das macros definidas pelo cliente e dos nomes das funções de cálculo existentes.
Se um aplicativo do Essbase contiver uma função local que tenha o mesmo nome de uma função global, a função local será usada para cálculo.

Criar e Compilar uma Classe Java para Funções Definidas pelo Cliente

Para criar e compilar uma classe Java para funções definidas personalizadas (CDFs) do Essbase, grave a classe usando um editor de texto ou IDE (ambiente de desenvolvimento integrado) e compile-a usando a ferramenta javac.

Veja a seguir um exemplo de workflow para criar uma classe Java para um CDF:

Em um editor de texto, crie uma classe Java.

Por exemplo:

public class CalcFunc {
  public static double sum (double[] data) {
    int i, n = data.length;
    double sum = 0.0d;
    for (i=0; i<n; i++) {
      double d = data [i];
      sum = sum + d;
    }
    return sum;
  }
}

Salve o arquivo com uma extensão .java.
Por exemplo:
```
CalcFunc.java
```
Navegue até o diretório onde o arquivo .java reside; em um prompt de comando, digite este comando:
```
javac java_filename
```
Por exemplo:
```
javac CalcFunc.java
```
Resolva qualquer erro de compilação até que o compilador crie um novo arquivo com uma extensão .class.
Por exemplo:
```
CalcFunc.class
```

Instalar Classes Java no Essbase Server

Para instalar as classes Java para suas funções de cálculo definidas personalizadas (CDFs) no Essbase Server, compile-as, copie o arquivo jar para um diretório udf global ou em nível de aplicativo, conforme especificado nestas instruções, e reinicie o aplicativo ou o servidor.

As classes Java devem ser compiladas em um arquivo JAR, usando a ferramenta jar do JDK.

Para criar um arquivo .jar e instalá-lo em um Essbase Server:

Navegue até o diretório onde o arquivo .class reside; em um prompt de comando, digite este comando:
```
jar cf jar_filename class_filename
```
Por exemplo:
```
jar cf CalcFunc.jar CalcFunc.class
```
No Essbase Server, copie o arquivo .jar para um dos seguintes diretórios (se o diretório não existir, crie-o):
- Para arquivos .jar que contêm funções globais definidas pelo cliente:
  ESSBASEPATH/java/udf/
- Para que os arquivos .jar sejam usados somente com aplicativos específicos:
  <Application Directory>/app/appname/udf/
  em que appname é o nome do aplicativo em que o CDF local será usado.
Se você não souber o local do ESSBASEPATH ou do <Application Directory>, consulte Variáveis de Ambiente na Plataforma Essbase.

Se o arquivo .jar for colocado subsequentemente em outro local, você deverá modificar a variável CLASSPATH para incluir o caminho completo e o nome do arquivo .jar.
Se as funções forem usadas somente por aplicativos específicos, reinicie esses aplicativos. Caso contrário, reinicie o Essbase Server. Consulte Iniciar, Interromper e Verificar Servidores para obter implantações independentes ou Usar Comandos para Iniciar, Interromper e Exibir Status de Processos para implantação de pilha no OCI.

Registrar Funções Definidas pelo Cliente

Use MaxL para registrar suas funções definidas pelo cliente (CDFs) no Essbase. A tarefa de registro vem depois que você gravou os CDFs nas classes Java, compilou as classes e instalou os arquivos jar.

Depois de compilar as classes Java para CDFs em arquivos .jar e instalar os arquivos .jar no Essbase Server, você deverá registrar as funções antes de poder usá-las em scripts de cálculo e fórmulas. Consulte Requisitos para Validade de Funções Definidas pelo Cliente.

Quando você registra um CDF global, todos os aplicativos do Essbase no Essbase Server podem usá-lo. Teste as funções em um único aplicativo (e registre-as apenas nesse aplicativo) antes de torná-las globais.

Use o mesmo processo para atualizar o catálogo de funções como para atualizar o catálogo de macros. Consulte Atualizar o Catálogo de Macros Definidas pelo Cliente.

Atenção:

Não registre funções globais para teste; isso dificulta a sua alteração se você encontrar problemas.

Para registrar um CDF, use a instrução create function MaxL.

Para registrar um CDF com escopo local, inclua o nome do aplicativo como prefixo. Por exemplo, a seguinte instrução MaxL registra a função @JSUM na classe CalcFunc como uma função local para uso no aplicativo de Amostra:

create function Sample.'@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

Para registrar um CDF com escopo global, não inclua o nome do aplicativo como prefixo. Por exemplo, a seguinte instrução MaxL registra a função @JSUM na classe CalcFunc como uma função global para uso em qualquer aplicativo no Essbase Server:

create function '@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

Observação:

A especificação de parâmetros de entrada para o método Java é opcional. Se você não especificar parâmetros de entrada, o Essbase os lerá na definição do método no código Java. No entanto, se você estiver registrando vários CDFs com o mesmo nome de método, mas com diferentes conjuntos de parâmetros, deverá registrar cada versão da função separadamente, especificando os parâmetros para cada versão da função.

Implementar Funções Definidas pelo Cliente Registradas

Você pode usar funções personalizadas (CDFs) registradas em scripts de cálculo e fórmulas, da mesma forma que usa funções de cálculo nativas do Essbase.

Para usar um CDF registrado:

Crie ou abra um script ou fórmula de cálculo existente.
- Se o CDF tiver sido registrado localmente — dentro de um aplicativo específico — você deverá usar um script de cálculo ou uma fórmula dentro desse aplicativo.
- Se o CDF tiver sido registrado globalmente, você poderá usar qualquer script ou fórmula de cálculo no Essbase Server.
Adicione a função ao script de cálculo ou à fórmula.

Por exemplo, para usar o JSUM, use este script de cálculo:

"New York" = @JSUM(@LIST(2.3, 4.5, 6.6, 1000.34));

Use este script de cálculo com o banco de dados de amostra Sample.Basic ou substitua "Nova York" pelo nome de um membro em um banco de dados de teste.
Salve o script de cálculo ou a fórmula e, em seguida, execute-o normalmente.

Atualizar Funções Definidas pelo Cliente

Para atualizar uma função definida personalizada (CDF) do Essbase, determine se ela é de escopo local ou global, encerre o(s) aplicativo(s) afetado(s), substitua o arquivo .jar que contém o código da função e registre novamente a função.

O procedimento de actualização dos CDF depende das seguintes condições:

Se a função está registrada local ou globalmente.
Se a assinatura do CDF—nome da classe, nome do método ou parâmetros de entrada—foi alterada no código Java.

Normalmente, para atualizar um CDF, você deve substituir o arquivo .jar que contém o código da função e, em seguida, registrá-lo novamente. No entanto, se a assinatura do CDF não tiver sido alterada e tiver apenas um conjunto de parâmetros de entrada (não é um método sobrecarregado), você poderá substituir o arquivo .jar que contém a função.

Observação:

Somente administradores devem atualizar CDFs globais.

Para atualizar um CDF:

Determine se a função é local ou global.

Consulte Exibir Funções Definidas pelo Cliente.
Faça as alterações na classe Java para o CDF e use programas de teste Java para testar sua saída.
Compile as classes Java e arquive-as em um novo arquivo .jar, usando o mesmo nome do arquivo .jar anterior.

Inclua quaisquer outras classes e métodos para CDFs que foram incluídos no arquivo .jar anterior.
Execute uma ação, dependendo se você está atualizando uma função definida personalizada local ou global:
1. Local: Desligue todos os aplicativos do Essbase que usam as funções no arquivo .jar.
2. Global: Desligar todos os aplicativos do Essbase
Se você não tiver certeza de quais aplicativos do Essbase usam quais funções no arquivo .jar, desative todos os aplicativos do Essbase.
Copie o novo arquivo .jar para o Essbase Server, substituindo o arquivo .jar existente pelo mesmo nome.
Se a assinatura do CDF não tiver sido alterada, passe para a etapa 8.

Para substituir o CDF, use a instrução create or replace function MaxL. Por exemplo:

Local:

create or replace function sample.'@JSUM'
as 'CalcFunc.sum';

Global:

create or replace function '@JSUM'
as 'CalcFunc.sum';

Reinicie os aplicativos que você encerrou, o que atualiza o catálogo.

Exibir Funções Definidas pelo Cliente

Exiba uma função definida pelo cliente (CDF) no Essbase para determinar se ela foi registrada com sucesso e se é de escopo local ou global. CDFs não são exibidos até que tenham sido criados e registrados.

Para visualizar um CDF:

Use a instrução display function MaxL.

Por exemplo, use a seguinte instrução MaxL para exibir os CDFs no aplicativo de Amostra e quaisquer funções globais registradas:

display function Sample;

A instrução display function lista funções globais sem um nome de aplicativo para indicar que são globais. Se o aplicativo contiver uma função com o mesmo nome de uma função global, somente a função local será listada.

Remover Funções Definidas pelo Cliente

Para remover/cancelar o registro de funções definidas pelo cliente (CDFs) do Essbase, primeiro certifique-se de que elas não estejam em uso. Em seguida, faça shutdown dos aplicativos nos quais os CDFs estão definidos, remova os CDFs emitindo a função drop MaxL e reinicie os aplicativos afetados.

As seguintes permissões são necessárias para remover um CDF:

Local: Pelo menos a permissão do Application Manager para o aplicativo
Global: permissão Administrador do Sistema

Antes de remover CDFs, verifique se nenhum script de cálculo ou fórmula os está usando. Os CDFs globais podem ser usados em scripts de cálculo e fórmulas no Essbase Server, portanto, verifique se nenhum script ou fórmula de cálculo no Essbase Server está usando um CDF global antes de removê-lo.

Atenção:

Remova os CDFs globais somente quando os usuários não estiverem acessando cubos do Essbase e as rotinas de cálculo não estiverem sendo executadas.

Para remover um CDF:

Determine se a função é local ou global.

Consulte Exibir Funções Definidas pelo Cliente.
Execute uma ação, dependendo se você está removendo um CDF local ou global:
1. Local: Desligue todos os aplicativos do Essbase que usam as funções no arquivo .jar.
2. Global: Desligue todos os aplicativos do Essbase.
Para remover o CDF, use a instrução drop function MaxL. Por exemplo:
- Local:
```
drop function Sample.'@JSUM';
```
- Global:
```
drop function '@JSUM';
```
Reinicie os aplicativos que você encerrou, o que atualiza o catálogo.

Copiar Funções Definidas pelo Cliente

É possível copiar funções definidas pelo cliente (CDFs) para qualquer Essbase Server e aplicativo ao qual você tenha acesso apropriado.

Para copiar um CDF, use a instrução create or replace function as MaxL.

Considerações de Desempenho para Funções Definidas pelo Cliente

Como as funções definidas pelo cliente são implementadas como uma extensão da estrutura da calculadora do Essbase, você pode esperar que os CDFs operem com menos eficiência do que as funções de cálculo nativas do Essbase.

Para otimizar o desempenho, limite o uso de funções definidas pelo cliente a cálculos que você não pode executar com comandos e funções de cálculo nativos do Essbase, especialmente em aplicativos em que a velocidade de cálculo é crítica.