O Cronapp permite que novos blocos de programação (cliente ou servidor) sejam criados e adicionados na lista de blocos do Editor de Blockly. Dessa forma, é possível criar funções para atender as necessidades de cada projeto.

Pré-requisitos

Antes de começar a seguir os passos do tutorial é preciso ter certeza de que se tem um ambiente minimamente preparado para reproduzir o exemplo. Abaixo estão os requisitos principais.

Requisitos:

1. Projeto que possua o lado servidor criado. Caso haja dúvidas de como criar esse tipo de projeto acesse a documentação Criar projeto.
2. Habilitar o botão Modo Avançado.

Visão Geral

Nesse tutorial iremos criar uma função de bloco de programação do tipo servidor que obtém uma lista de números e retorna o menor valor.

Passos

Criando pacote 

É recomendável criar diretórios ou arquivos referentes aos novos blocos de programação do tipo servidor em um diretório específicos, de forma a melhorar a organização. Dessa forma, criaremos o pacote menorValorLista que irá conter a classe Java referente ao componente. Clique com o botão direito no diretório java  , em seguida, escolha Novo, selecione Pacote e insira o valor "menorValorLista" na janela de Confirmação.

Figura 1 - Criando o pacote

Criando classe Java

O pacote criado deve receber um arquivo do tipo Java, dessa forma, clique no botão "+" ao lado do pacote criado e selecione Java (Figura 2). 

Figura 2 - Criação da classe Java

Após solicitar a criação do arquivo Java, o Cronapp irá exibir a tela de escolha do modelo de arquivo. Selecione a opção Nova Função para Bloco de Programação (Figura 2.1). O botão Avançar confirma a seleção do modelo e exibe a tela de definição das informações.

Figura 2.1 - Escolha do modelo do arquivo

Para finalizar, preencha os campos informados na Figura 2.2.

Figura 2.2 - Definindo informações sobre o bloco

Campos:

• Nome da classe: define o nome da classe Java onde está inserida a função.
• Nome da função: atribui o nome da função ao bloco de programação que será exibido no Editor de Blockly.
• Nome reduzido da função: define o nome para a função Java.
• Descrição da função: descreve a finalidade da função e será exibida na aba lateral da lista de blocos ou ao colocar o mouse em cima do bloco.
• Categoria: define o nome da nova categoria que será criada para o bloco.

As informações preenchidas acima serão exibidas posteriormente ao selecionarmos a função criada no editor de blocos de programação servidor (Figura 6).

Alterando anotações do método

A geração do código base para o componente vem com algumas anotações padrão, como, por exemplo: type, returnType e String input. Esses valores não são fixos e podem ser alterados. Ver Figura 3.

Atributos dos parâmetros:

• type: tipo do parâmetro de entrada da função.
• description: descrição do parâmetro de entrada da função.
• returnType: tipo do parâmetro de saída da função String.
• String input: tipo da variável e seu nome "input". O nome da variável pode ser alterado para qualquer outro.

Figura 3 - Classe Java recém-criada

Utilize CTRL + Espaço para exibir os ObjectTypes disponíveis (Figura 3.1):

Figura 3.1 - Alguns dos tipos de parâmetro que podem ser utilizados

Adicionando código 

Primeiramente, devemos alterar os tipos de dados atuais para list, além disso, devemos acrescentar algumas informações sobre o parâmetro no código. Após a adequação dos parâmetros, o código referente a funcionalidade pode ser adicionado ao corpo da função. Nesse exemplo, o código retorna o menor valor contido em uma lista.

package menorValorLista;

import cronapi.CronapiMetaData;
import cronapi.ParamMetaData;


@CronapiMetaData(categoryName = "Obter Valor")
public class MenorValorLista {

	@CronapiMetaData(type = "function", name = "obterMenorValorLista", description = "Função que retorna o menor valor contido em uma lista")
	public static String obMenVaList(@ParamMetaData(description = "Parâmetro: Descrição do parâmetro") String input) throws Exception {
		return "Input " + input;
	}

}

package menorValorLista;

import java.util.Comparator;
import java.util.Optional;

import cronapi.CronapiMetaData;
import cronapi.ParamMetaData;
import cronapi.Var;
import cronapi.CronapiMetaData.ObjectType;


@CronapiMetaData(categoryName = "Obter Valor")
public class MenorValorLista {

	@CronapiMetaData(type = "function", name = "obterMenorValorLista", description = "Função que retorna o menor valor contido em uma lista")
	public static Var obMenVaList(@ParamMetaData(type =  ObjectType.LIST ,description = "Lista: Lista que será enviada para a função") Var list) throws Exception {

			Optional<Var> opt = list.getObjectAsList().stream().min(Comparator.comparingLong(Var::getObjectAsLong));
			return opt.get();

	}

}

Figura 4 - Alterações realizadas na função

Algumas alterações foram realizadas no código base, são elas, respectivamente:

• Tipo de retorno da função: alterado de String para Var;
• Tipo do parâmetro da função: foi acrescentado que o tipo do parâmetro é uma lista;
• Descrição do parâmetro: essa descrição será exibida no editor de bloco de programação (Figura 6); 
• Variável do parâmetro: o nome da variável do parâmetro foi definido como list e seu tipo é Var;
• Corpo da função: o corpo adicionado para a função é responsável por retornar o menor valor da lista recebida como parâmetro.

Caso seja apontado algum erro em algum trecho do código, clique no termo e aperte "CRTL + . (ponto)" ou clique no ícone da lâmpada para exibir uma opção de correção. Ao digitar o código é possível usar o "CTRL + Espaço" para exibir os métodos de um objeto (Figura 4.1). Salve o arquivo Java em seguida.

Figura 4.1 - Alguns dos métodos contidos em uma instância de um objeto do tipo Var 

Acessando a função 

Após salvar o método da classe Java que criamos, clique, no menu do sistema, em Projeto > Recompilar > Recompilar e Reabrir Projeto para que a nossa função seja carregada (Figura 5).

Figura 5 - Recompilando e reabrindo o projeto

O último passo é a visualização desta função como um bloco de programação disponível. Abra um bloco de programação do tipo Servidor e verifique na categoria Obter Valor o bloco obterMenorValorLista (Figura 5.1).

Figura 5.1 - Função sendo exibida em sua respectiva categoria no bloco de programação servidor

As informações definidas durante o desenvolvimento da função são exibidas ao passar o ponteiro do mouse sobre o bloco ainda na Categoria (Figura 5.2).

 Figura 5.2 - Exibição das informações da função

Testando a função

Agora vamos testar a função que desenvolvemos nesse tutorial. Para isso foi criado a variável "lista" que recebe uma lista com 3 valores inteiros, essa variável é passada por parâmetro para o bloco criado (obterMenorValorLista), que retornará o menor valor da lista e exibirá em uma notificação na tela. Criamos um botão na tela para chamar a função de bloco mostrarMenorValor (Figura 6) e o resultado será exibido no navegador (Figura 6.1). 

Figura 6 - Bloco que exibe o menor valor da lista

 Figura 6.1 - Menor valor da lista exibido na tela

Anotações

As Anotações (annotations) têm o objetivo de possibilitar a declaração de metadados ao longo do código que podem ser posteriormente interpretadas por um compilador ou pré-compilador que irá realizar alguma tarefa predefinida. As anotações evitam, em muitos casos, a criação de arquivos XML de configuração que tornam tão difícil a compreensão de alguns sistemas. Anotações podem ser utilizadas, por exemplo, para indicar que um método não deve mais ser usado (@Deprecated) ou que ele foi sobrescrito (@Override).

Nos exemplos citados, é importante que fique claro que a presença de anotações não influi no comportamento da classe ou de seus objetos, mas sim adicionam funcionalidades anexas a uma determinada classe.

Observações:

• metadados são informações (dados) que falam sobre a classe mas não fazem parte da classe em si.
• Anotações são representadas com o símbolo prefixo @ (arroba). 

Como usar anotações na plataforma Cronapp

As anotações na plataforma Cronapp podem ser aplicadas nos seguintes casos: declaração de métodos, classes, interfaces, parâmetros e enumerações.

Existem duas anotações principais que podem ser referenciadas e utilizadas em classes do tipo Java, são elas:

• @CronapiMetaData
• @ParamMetaData

A anotação @CronapiMetaData contém os seguintes elementos:

 public enum ObjectType {

    BOOLEAN, LONG, DOUBLE, DATETIME, STRING, LIST, MAP, DATASET, JSON, XML, OBJECT, UNKNOWN, BLOCK, STATEMENT, STATEMENTSENDER, VOID

  }
 
 
 public enum CategoryType {

    IO, DATABASE, FRONTEND, SCREEN, CONVERSION, DATETIME, XML, EMAIL, FTP, JSON, LOGIC, TEXT, LIST, MAP, COLOR, LOOP, MATH, GRID, PRINT, OTHER, OBJECT, SEMAPHORE, UTIL, JSONORMAP, TREE

  }

Figura 7 - Exemplo do código de uma função utilizando alguns elementos da anotação @CronapiMetaData

A anotação @ParamMetaData contém os seguintes elementos:

Internacionalização

As chaves de internacionalização ficam contidas em um arquivo de extensão "*.properties". Arquivos desse tipo podem ser utilizados para armazenar parâmetros do tipo string no formato (chave=valor). Para utilização das chaves de internacionalização durante a criação de componentes de software na IDE Cronapp coloca-se a chave desejada entre chaves duplas, como por exemplo: description = "{{functionToQueryInDatasource}}".

Diferentemente das aplicações desenvolvidas no Cronapp que suportam todos os idiomas, o conteúdo desenvolvido para ser utilizado dentro do Cronapp, como bloco de programação ou componente visual, só poderão ser internacionalizados nos idiomas português e inglês.

Para conseguir internacionalizar os blocos de programação, uma pasta com o nome "i18n" (destaque 2 da figura 8) deve ser criada no mesmo diretório (destaque 1) onde está o arquivo Java que vão gerar os blocos de programação (destaque 8). A pasta "i18n" deve conter os arquivos de internacionalização: "Messages_en_US.properties" e "Messages_pt_BR.properties". Ao abrir os arquivos de internacionalização JSON, a ferramenta Chave de internacionalização é exibida, permitindo adicionar as novas chaves e traduzi-las automaticamente.

Figura 8 - Local do diretório i18n em relação ao arquivo Java e ferramenta que facilita a internacionalização