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 o link ( 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 

Faz parte da boa prática de desenvolvimento criar diretórios ou arquivos referentes ao bloco de programação do tipo servidor no diretório. 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 com o botão de contexto no pacote menorValorLista e escolha Novo, em seguida, selecione Java (Figura 2.1). 

Figura 2.1 - 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.2). O botão Avançar confirma a seleção do modelo e exibe a tela de definição das informações.

Figura 2.2 - Escolha do modelo do arquivo

Para finalizar, preencha os campos informados na Figura 2.3.

Figura 2.3 - 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 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 para ser exibido na sua descrição.
• Categoria: Define o nome da nova categoria.

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

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.1.

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.1 - Classe Java recém-criada

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

Figura 3.2 - 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 = "Parâmetro: Descrição do parâmetro") Var list) throws Exception {

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

	}

}

Figura 4.1 - 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 é exibida posteriormente no editor de bloco de programação (Figura 6.1); 
• 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.2). Salve o arquivo Java em seguida.

Figura 4.2 - 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 com o botão de contexto sobre a raiz do projeto e selecione a opção Recompilar e Reabrir Projeto para que a nossa função seja carregada (Figura 5.1).

Figura 5.1 - 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.2).

Figura 5.2 - 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.3).

 Figura 5.3 - 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.1) e o resultado será exibido no navegador (Figura 6.2). 

Figura 6.1 - Bloco que exibe o menor valor da lista

 Figura 6.2 - 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 influem 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: