Customização Storex - Customização de Parâmetros

Objetivo

Este documento tem como objetivo principal orientar no processo de implementação de novos parâmetros e a forma como são utilizados na aplicação.

Arquitetura

GerenciadorConfiguracaoStorex

É a classe que representa o gerenciador de configuração, e que é responsável por fazer a comunicação entre o componente e o servidor de configurações. É por meio dela que o componente atualiza seus parâmetros de configuração. Os parâmetros recebidos sao mapeados e acessados por meio da biblioteca do Linx Configuration. Usando um padrão Singleton (única instância), é possível obter sua instância de qualquer ponto da aplicação, através do método static getInstance() existente na classe.

A instância de GerenciadorConfiguracaoStorex nos fornece a interface ConfiguracaoStorex. Esta por sua vez, fornece diversas interfaces que encapsulam o acesso aos parâmetros que foram incluídos no arquivo XML de configuração. Através destas interfaces o desenvolvedor pode, de uma forma simples e transparente, fazer uso de toda a parametrização disponível para os componentes.

Arquivo XML de configuração

Em cada projeto é disponibilizado um arquivo de configuração no formato XML. O mesmo pode ser encontrado, dentro do projeto, no caminho mostrado na figura ao lado. Nesse arquivo é onde podemos acrescentar as novas parametrizações que serão definidas ao longo das customizações. Mais abaixo entraremos em mais detalhes a respeito de como acrescentar parâmetros, detalhes do layout utilizado, como também dos tipos de parâmetros que podem ser criados.

Esse arquivo XML, após realizadas as customizações, é utilizado para enviar os parâmetros para o servidor de configurações. Este que tem o papel de distribuir a parametrização para todas as lojas e componentes.

Ao longo do documento, vamos mostrar todo o processo de criação de novas interfaces e de novos parâmetros através de um exemplo prático.

Criação de Interfaces

O Storex disponibiliza uma série de interfaces, que fornecem acesso aos parâmetros de configuração existentes e que estão disponíveis para uso. Podemos encontrá-las abaixo do pacote com.linx.configuracao. A interface ConfiguracaoStorex é a porta de acesso a todas as demais interfaces, que é onde podemos obter as configurações disponíveis para o componente. A forma de acessá-las é obtendo a instância do ConfiguracaoStorex fornecida pelo GerenciadorConfiguracaoStorex.

Um exemplo de uso da ConfiguracaoStorex seria obter as informações de acesso ao EP, para podermos realizar um envio de mensagem partindo do PDV.

Para isso vamos obter a interface AmbienteCorporativo, acessando o método getAmbienteCorporativo() fornecido pela ConfiguracaoStorex. Por sua vez, a interface AmbienteCorporativo fornece acesso às configurações de acesso ao EP, como também aos demais componentes, conforme exemplo ao lado.

Atenção! É profundamente desaconselhável especializar a interface ConfiguracaoStorex na linha de desenvolvimento disponível para customização. Ou seja, não se deve criar uma interface de mesmo nome e na mesma estrutura de pacote análoga à ConfiguracaoStorex, sob o risco de perder o acesso às configurações existentes e de perder futuras evoluções no kernel do Storex.

Interface ConfiguracoesCustom

Nas situações onde seja preciso criar novas opções de interfaces de configuração que não foram disponibilizadas pelo Storex Custom, é preciso criar a interface ConfiguracoesCustom no pacote com.linx.configuracao.modelo e acessá-la através de ConfiguracaoStorex. Ao lado podemos ver um exemplo exemplo de implementação.

Ao lado podemos ver um exemplo de como acessar a nova interface usando a instância de ConfiguracaoStorex fornecida pelo GerenciadorConfiguracaoStorex.

Interface ServicosCustom

O Storex disponibiliza também duas interfaces chamadas de ServicosCustom, em pacotes distintos e que permitem a criação de parâmetros que serão utilizados nas novas customizações. Esta é que vai prover o acesso às demais interfaces de configuração que serão criadas de acordo com a customização de novas funcionalidades, ou seja, associadas às regras de negócio.

- com.linx.configuracao.modelo.conectividade.custom.ServicosCustom
- com.linx.configuracao.modelo.negocio.custom.ServicosCustom

Dentro do pacote com.linx.configuracao.modelo, encontramos as pastas conectividade e negocio. Ambas disponibilizam a interface ServicosCustom.

A pasta conectividade tem o objetivo de armazenar interfaces que correspondam a parâmetros de comunicação.

A pasta negocio, possui o objetivo de armazenar interfaces que estão relacionadas às regras de negócio das funcionalidades do sistema.

Exemplo de uso da interface ConfiguracaoStorex

ConsultaFundoFixoRequest request = new ConsultaFundoFixoRequest();
request.setCodigoLoja(componente.getConfiguracao().getCodigoLoja());

ConfiguracaoStorex configuracaoStorex = GerenciadorConfiguracaoStorex.getInstance().getConfiguracao();
			
AmbienteCorporativo ambienteCorporativo = configuracaoStorex.getAmbienteCorporativo();
			
String ip = ambienteCorporativo.getEp().getHost();
Integer porta = ambienteCorporativo.getEp().getPorta();
	    	
Destination destination = new Destination(ip, porta) ;
try {
	MessagingService messagingService = MessagingService.getInstance();
	if (!messagingService.isStarted()) {
		messagingService.start();
	}
	ConsultaFundoFixoResponse  response = (ConsultaFundoFixoResponse) messagingService.send(request, destination);
				
} catch (MessagingException e) {
	
}

Exemplo de implementação de ConfiguracoesCustom

package com.linx.configuracao.modelo;

public interface ConfiguracoesCustom {

	@PropertyName("nova-interface")
	public NovaInterface getNovaInterface();   

}

Obtendo instância de ConfiguracoesCustom

ConfiguracaoStorex configuracaoStorex = GerenciadorConfiguracaoStorex.getInstance().getConfiguracao();

ConfiguracoesCustom configuracoesCustom = configuracaoStorex.getConfiguracao();
NovaInterface novaInterface = configuracoesCustom.getNovaInterface();

Cenário de exemplo

Interface EmprestimoPessoal

Como um exemplo, vamos imaginar um cenário onde será criado uma nova funcionalidade de Empréstimo Pessoal. Onde será preciso fazer uso de alguns métodos de acesso via webservice, para consulta de limites e simulações de empréstimo para um cliente. Para essa funcionalidade teremos configurações de acesso aos endpoints e também configurações de regra de negócio. Para isso vamos criar duas novas interfaces. Uma dentro de conectividade e outra dentro de negocio. Ambas serão chamadas de EmprestimoPessoal e cada uma ficará na sua respectiva pasta.

- com.linx.configuracao.modelo.conectividade.custom.EmprestimoPessoal
- com.linx.configuracao.modelo.negocio.custom.EmprestimoPessoal

Ao lado podemos ver a estrutura de diretórios e as interfaces EmprestimoPessoal criadas em cada um deles.

Parâmetros de Conectividade

Os endpoints de consulta de limites e de simulação de empréstimo, possuem suas respectivas URLs de acesso. Essas URLs estarão configuradas no servidor de configurações e vamos criar os métodos de acesso na interface EmprestimoPessoal, que fica dentro do pacote linx.configuracao.modelo.conectividade.custom.

No exemplo ao lado criamos três configurações. Onde a primeira corresponde a URL base de acesso aos endpoints da funcionalidade de empréstimo pessoal. Os demais correspondem aos endereços de acesso de cada um dos endpoints. Importante observar a nomenclatura dos métodos, onde é fundamental criarmos nomes que deixem claro o objetivo da configuração.

Nesses métodos devemos fazer uso de algumas annotatios.

@PropertyName É nela onde indicamos o nome da configuração, que será criada no servidor de configurações.

@Required Indica que a configuração é obrigatória. Uma exceção será levantada nos casos em que a aplicação não tenha recebido ainda a informação correspondente ao parâmetro.

O próximo passo é criar o método de acesso a essa interface, dentro de ServicosCustom, que fica dentro do mesmo pacote. Conforme exemplo ao lado.

Fazendo uso da instância do GerenciadorConfiguracaoStorex, que é a classe que representa o gerenciador de configuração e que é o responsável por fazer a comunicação entre o componente e o servidor de configuração, é possível acessar as interfaces e todos os métodos que retornam as configurações disponíveis no componente, conforme exemplo ao lado.

Parâmetros de Negócio

Considere agora que antes da consulta de limite será preciso validar o cartão do cliente. Essa validação deve obedecer um número máximo de tentativas e também deverá ter uma opção de desabilitar essa solicitação do cartão. Para isso vamos criar duas novas configurações. Porém, agora vamos utilizar a interface EmprestimoPessoal, fornecida pela ServicosCustom do pacote linx.configuracao.modelo.negocio.custom. Observe o exemplo ao lado.

A interface ServicosCustom fornece o acesso à interface EmprestimoPessoal, onde deveremos colocar todos os métodos que darão acesso às configurações de regra de negócio da funcionalidade. A implementação da interface EmprestimoPessoal, pode ficar conforme exemplo ao lado.

Essa interface fornece acesso a duas configurações. Uma que vai ser usada para habilitar ou desabilitar a solicitação do cartão do cliente. Outra para controlar o número máximo de tentativas de fornecer o cartão. Observe que estamos usando annotations que não foram citadas anteriormente.

São elas: @DefaultIntegerValue e @DefaultBooleanValue. Essas annotations são usadas para definir um valor padrão de retorno para a configuração. Este valor será assumido enquanto a aplicação não tiver recebido essa informação do servidor de configurações.
Além dessas já citadas, existem outras que podem ser usadas de acordo com o tipo de retorno do parâmetro. Como por exemplo: @DefaultStringValue, @DefaultListValue, @DefaultDoubleValue, entre outras.

Atenção! A annotation @Required não pode ser usada ao mesmo tempo que qualquer uma das annotations que definem um valor default de retorno. Ao lado temos um exemplo de código que vai gerar um erro de execução.

Arquivo de Configuração (XML)

Agora vamos mostrar a forma como podemos acrescentar nossos parâmetros no arquivo de configurações. Como dito anteriormente, ele possui um formato XML e consequentemente precisamos seguir algumas regras para a edição do mesmo.

Principais Tags

Tag <groups>

A tag <groups> é utilizada para definir quais tipos de grupos estão disponíveis para serem utilizados na criação dos parâmetros. O grupo de id linx_storex_corporativo, é utilizado quando o parâmetro deve ficar visível para todas as lojas da rede. O grupo de id linx_storex_loja é utilizado quando um parâmetro deve ficar restrito a uma loja específica. O mais comum é que os parâmetros sejam criados para toda a rede, utilizando o grupo de id linx_storex_corporativo.

Tag <parameters>

Local onde ficam definidos todos os parâmetros e atributos que caracterizam cada um deles. Cada parâmetro é definido pela tag que define o seu tipo de dado. Por exemplo, um parâmetro de texto será definido com a tag <string></string>. Já um parâmetro numérico pode ser definido com a tag <integer></integer>.

Ao lado temos um exemplo de como ficariam as configurações dos parâmetros Url base e Consulta de limites.

No exemplo é preciso entender algumas tags importantes.

A tag <fqdn> (em inglês, Fully Qualified Domain Name, ou em Português, Nome de Domínio Completamente Qualificado)

<fqdn>conectividade.servicos-custom.emprestimo-pessoal.endpoint-consulta-limite-emprestimo</fqdn>

A formação do fqdn representa a estrutura de interfaces definida na aplicação, até chegar na configuração desejada.

Logo teremos uma interface Conectividade que provê um método de acesso à interface ServicosCustom. Esta por sua vez, provê um método de acesso a interface EmprestimoPessoal, que fornece o método que retorna o valor da configuração cujo PropertyName é endpoint-consulta-limite-emprestimo.

Vamos relembrar o código:

com.linx.configuracao.modelo.conectividade.custom.EmprestimoPessoal

package com.linx.configuracao.modelo.conectividade.custom;

import com.linx.configuration.PropertyName;
import com.linx.configuration.Required;

public interface EmprestimoPessoal {

	@PropertyName("url-base-acesso-emprestimo")
	@Required
	public String getUrlBaseAcessoEmprestimo();
	
	@PropertyName("endpoint-consulta-limite-emprestimo")
	@Required
	public String getEndpointConsultaLimiteEmprestimo();
	
	@PropertyName("endpoint-simulacao-emprestimo")
	@Required
	public String getEndpointSimulacaoEmprestimo();
}

A tag <group-id>, indica se o parâmetro estará visível para toda a rede de lojas ou apenas para uma loja específica. No nosso exemplo, está configurado para toda a rede de lojas.

<group-id>linx_storex_corporativo</group-id>

A tag <required>, indica se o parâmetro é obrigatório ou não. Pode possuir os valores true ou false. No nosso exemplo, está configurado para ser um parâmetro obrigatório.

<required>true</required>

A tag <force>, se a tag estiver true no xml, e o parâmetro já existir no servidor, ele vai substituir o valor do parâmetro pelo que está no xml. Se a tag estiver false, ele mantém o valor do parâmetro no servidor de configuração.

<force>true</force>

A tag <value>, possui o valor que será atribuído no ato da criação do parâmetro no servidor de configurações. Este valor pode ser alterado direto no servidor, de acordo com a necessidade.

<value>http://localhost:8080/api/app</value>

Ao lado podemos ver um exemplo de configuração dos parâmetros de negócio. Vamos analisar o fqdn do primeiro parâmetro.

<fqdn>negocio.servicos-custom.emprestimo-pessoal.numero-maximo-tentativas-solcitacao-cartao-no-emprestimo</fqdn>

Neste caso, teremos uma interface Negocio que provê um método de acesso à interface ServicosCustom. Esta por sua vez, provê um método de acesso a interface EmprestimoPessoal, que fornece o método que retorna o valor da configuração cujo PropertyName é numero-maximo-tentativas-solcitacao-cartao-no-emprestimo.

com.linx.configuracao.modelo.conectividade.custom.EmprestimoPessoal

package com.linx.configuracao.modelo.conectividade.custom;

import com.linx.configuration.PropertyName;
import com.linx.configuration.Required;

public interface EmprestimoPessoal {

	@PropertyName("url-base-acesso-emprestimo")
	@Required
	public String getUrlBaseAcessoEmprestimo();
	
	@PropertyName("endpoint-consulta-limite-emprestimo")
	@Required
	public String getEndpointConsultaLimiteEmprestimo();
	
	@PropertyName("endpoint-simulacao-emprestimo")
	@Required
	public String getEndpointSimulacaoEmprestimo();
}

package com.linx.configuracao.modelo.conectividade.custom;

import com.linx.configuracao.modelo.negocio.custom.EmprestimoPessoal;
import com.linx.configuration.PropertyName;
import com.linx.configuration.Required;

public interface ServicosCustom {
	
	@PropertyName("emprestimo-pessoal")
	@Required
	public EmprestimoPessoal getEmprestimoPessoal();
}

Fazendo uso das configurações

ConfiguracaoStorex configuracaoStorex = GerenciadorConfiguracaoStorex.getInstance().getConfiguracao();
			
String urlBase = configuracaoStorex.getConectividade().
				getServicosCustom().getEmprestimoPessoal().getUrlBaseAcessoEmprestimo();
			
String urlConsultaLimite = configuracaoStorex.getConectividade().
					       getServicosCustom().getEmprestimoPessoal().getEndpointConsultaLimiteEmprestimo();

Interface de negócio ServicosCustom

package com.linx.configuracao.modelo.negocio.custom;

import com.linx.configuration.PropertyName;
import com.linx.configuration.Required;

public interface ServicosCustom {
	
	@PropertyName("emprestimo-pessoal")
	@Required
	public EmprestimoPessoal getEmprestimoPessoal();
}

Interface de negócio EmprestimoPessoal

package com.linx.configuracao.modelo.negocio.custom;

import com.linx.configuration.DefaultBooleanValue;
import com.linx.configuration.DefaultIntegerValue;
import com.linx.configuration.PropertyName;

public interface EmprestimoPessoal {

	@PropertyName("numero-maximo-tentativas-solcitacao-cartao-no-emprestimo")
	@DefaultIntegerValue(3)
	public Integer getNumeroMaximoTentativasSolicitacaoCartaoNoEmprestimo();
	
	@PropertyName("solicitacao-cartao-cliente-na-consulta-habilitada")
	@DefaultBooleanValue(true)
	public boolean isSolicitacaoCartaoClienteNaConsultaHabilitada();
}

Código que vai gerar erro de execução

package com.linx.configuracao.modelo;

import com.linx.configuration.DefaultBooleanValue;
import com.linx.configuration.PropertyName;
import com.linx.configuration.Required;

public interface ParametrosCustom {

    // o código vai compilar, porém vai gerar um erro de execução porque não podemos combinar as annotations @Required com @DefaultBooleanValue
	@PropertyName("solicita-senha-operador-habilitada")
	@Required
	@DefaultBooleanValue(true) 
	public boolean isSolicitaSenhaOperadorHabilitada();
}

Tag groups

<groups>
	<group>
	   <id>linx_storex_corporativo</id>
	   <name>GRP-LINX-STOREX</name>
	   <domain>CORPORATIVO</domain>
	   <chain xsi:nil="true"/>
	   <super-group-id xsi:nil="true"/>
	</group>
    <group>
		<id>linx_storex_loja</id>
		<name>GRP-LINX-STOREX-LOJA</name>
		<domain>0190</domain>
		<chain xsi:nil="true"/>
		<super-group-id>linx_storex_corporativo</super-group-id>
	</group>
</groups>

Parâmetros de conectividade

<string>
     <parameter-definition>
           <fqdn>conectividade.servicos-custom.emprestimo-pessoal.url-base-acesso-emprestimo</fqdn>
           <descriptions>
                <parameter-description>
                     <completeDescription>URL base de acesso ao Empréstimo Pessoal</completeDescription>
                     <description>URL base de acesso ao Empréstimo Pessoal</description>
                     <locale>pt-BR</locale>
               </parameter-description>
               <parameter-description>
                     <completeDescription>Base URL for personal loan access</completeDescription>
                     <description>Base URL for personal loan access</description>
                     <locale>en-US</locale>
               </parameter-description>
               <parameter-description>
                    <completeDescription>URL base para el acceso a los préstamos personales</completeDescription>
                    <description>URL base para el acceso a los préstamos personales</description>
                    <locale>es_ES</locale>
              </parameter-description>
         </descriptions>
    </parameter-definition>
     <group-id>linx_storex_corporativo</group-id>
     <required>true</required>
     <force>true</force>
     <category>emprestimo-pessoal</category>
     <value>http://localhost:8080/api/app</value>
</string>
<string>
	<parameter-definition>
		<fqdn>conectividade.servicos-custom.emprestimo-pessoal.endpoint-consulta-limite-emprestimo</fqdn>
		<descriptions>
			<parameter-description>
				<completeDescription>Endpoint para consultar limite de empréstimo do cliente</completeDescription>
				<description>Endpoint para consultar limite de empréstimo do cliente</description>
				<locale>pt-BR</locale>
			</parameter-description>
			<parameter-description>
				<completeDescription>Endpoint for querying the customer's loan limit</completeDescription>
				<description>Endpoint for querying the customer's loan limit</description>
				<locale>en-US</locale>
			</parameter-description>
			<parameter-description>
				<completeDescription>Endpoint para consultar el límite de préstamo del cliente</completeDescription>
				<description>Endpoint para consultar el límite de préstamo del cliente</description>
				<locale>es_ES</locale>
			</parameter-description>
		</descriptions>
	</parameter-definition>
	<group-id>linx_storex_corporativo</group-id>
	<required>true</required>
	<force>true</force>
	<category>emprestimo-pessoal</category>
	<value>/v1/consultaLimite</value>
</string>
<string>
	<parameter-definition>
		<fqdn>conectividade.servicos-custom.emprestimo-pessoal.endpoint-simulacao-emprestimo</fqdn>
		<descriptions>
			<parameter-description>
				<completeDescription>Endpoint para simular planos de empréstimo, a partir de um valor solicitado</completeDescription>
				<description>Endpoint para simular planos de empréstimo, a partir de um valor solicitado</description>
				<locale>pt-BR</locale>
			</parameter-description>
			<parameter-description>
				<completeDescription>Endpoint for simulating loan plans, starting from an amount requested</completeDescription>
				<description>Endpoint for simulating loan plans, starting from an amount requested</description>
				<locale>en-US</locale>
			</parameter-description>
			<parameter-description>
				<completeDescription>Endpoint para simular planes de préstamo, a partir de un importe solicitado</completeDescription>
				<description>para simular planes de préstamo a partir de un importe solicitado.</description>
				<locale>es_ES</locale>
			</parameter-description>
		</descriptions>
	</parameter-definition>
	<group-id>linx_storex_corporativo</group-id>
	<required>true</required>
	<force>true</force>
	<category>emprestimo-pessoal</category>
	<value>/v1/simulaEmprestimo</value>
</string>

Parâmetros de negócio

<integer>
	<parameter-definition>
		<fqdn>negocio.servicos-custom.emprestimo-pessoal.numero-maximo-tentativas-solcitacao-cartao-no-emprestimo</fqdn>
		<descriptions>
			<parameter-description>
				<completeDescription>Número máximo de tentativas de solicitação do cartão do cliente na consulta de limite</completeDescription>
				<description>Número máximo de tentativas de solicitação do cartão do cliente na consulta de limite</description>
				<locale>pt_BR</locale>
			</parameter-description>
			<parameter-description>
				<completeDescription>Maximum number of attempts to request the customer's card in the limit check</completeDescription>
				<description>Maximum number of attempts to request the customer's card in the limit check</description>
				<locale>en_US</locale>
			</parameter-description>
			<parameter-description>
				<completeDescription>Número máximo de intentos para solicitar la tarjeta del cliente en la consulta de límites</completeDescription>
				<description>Número máximo de intentos para solicitar la tarjeta del cliente en la consulta de límites</description>
				<locale>es_ES</locale>
			</parameter-description>
		</descriptions>
	</parameter-definition>
	<group-id>linx_storex_corporativo</group-id>
	<required>true</required>
	<force>true</force>
	<category>emprestimo-pessoal</category>
	<value>3</value>
</integer>

<boolean>
	<parameter-definition>
		<fqdn>negocio.servicos-custom.emprestimo-pessoal.solicitacao-cartao-cliente-na-confirmacao-habilitada</fqdn>
		<descriptions>
			<parameter-description>
				<completeDescription>Habilita a solicitação de cartão para confirmação de empréstimo pessoal</completeDescription>
				<description>Habilita a solicitação de cartão para confirmação de empréstimo pessoal</description>
				<locale>pt_BR</locale>
			</parameter-description>
			<parameter-description>
				<completeDescription>Enables the card request for personal loan confirmation</completeDescription>
				<description>Enables the card request for personal loan confirmation</description>
				<locale>en_US</locale>
			</parameter-description>
			<parameter-description>
				<completeDescription>Habilita la solicitud de tarjeta para la confirmación del préstamo personal</completeDescription>
				<description>Habilita la solicitud de tarjeta para la confirmación del préstamo personal</description>
				<locale>es_ES</locale>
			</parameter-description>
		</descriptions>
	</parameter-definition>
	<group-id>linx_storex_corporativo</group-id>
	<required>true</required>
	<force>true</force>
	<category>emprestimo-pessoal</category>
	<domain>true, false</domain>
	<value>true</value>
</boolean>

Árvore de páginas