Customização de Propriedades de Instância de Serviço ou Interface

Objetivos

Compreender conceitualmente o que são Custom Properties
Aprender a utilizar Custom Properties através da API do Lumis Portal
Aprender a utilizar Custom Properties através de Interfaces de Serviços

Referências complementares

Property Bags
Process Actions
Data Providers
Conceitos básicos de montagem em Lumis Portal

O que é Customização de Propriedades de Instância de Serviço ou Interface?

Customização de propriedades de instância de serviço/interface, ou Custom Properties, é um recurso oferecido pelo framework do Lumis Portal que possibilita ao desenvolvedor adicionar, consultar ou alterar propriedades referentes a uma instância de serviço ou interface. Cada propriedade possui um nome e um valor, ambos textuais. Existem métodos nas APIs de instância de serviço e de instância de interface para a manipulação dessas propriedades.

Diversos serviços nativos do Lumis Portal (ex.: Fale Conosco, Grupos e Páginas Personalizadas) utilizam custom properties para armazenar informações em instâncias de serviços/interfaces.

Estas propriedades são sempre referentes a instâncias de serviço e interface. Há outra classe de propriedades, organizadas em Property bags, que se associam a canais e páginas e podem ser herdadas hierarquicamente. Cada canal ou página possui um property bag, que pode conter zero ou mais propriedades. Para maiores detalhes sobre Property bags, consulte o artigo sobre Property bags na base de conhecimento.

Como utilizar Custom Properties?

As custom properties são manipuladas através de API. Para isso é necessário obter Managers que oferecem o recurso de manipulação de custom properties: “ServiceInstanceManager” ou “ServiceInterfaceInstanceManager” (para instâncias de serviço ou instâncias de interface, respectivamente). A partir desses, é possível acionar o método “setCustomProperty” ou “setCustomProperties” conforme apresentado no Código a seguir.

//Define uma única propriedade para uma	
//determinada instância de serviço
ManagerFactory.getServiceInstanceManager().setCustomProperty(sessionConfig, serviceInstanceId, name, value, transaction);
//Define um mapa de propriedades para uma
//determinada instância de serviço
ManagerFactory.getServiceInstanceManager().setCustomProperties(sessionConfig, serviceInstanceId, propertiesTable, transaction);

Código 1 – Definindo uma Custom Property em uma instância de serviço

O método “setCustomProperty” define uma custom property para uma determinada instância de interface ou serviço (dependendo do manager utilizado). Caso a custom property já tenha sido definida anteriormente, seu valor será substituído. O método “setCustomProperty” possui os seguintes parâmetros:

sessionConfig: é o objeto que contêm as informações da sessão do usuário. É possível obter-lo através do commando “SessionConfig.getCurrentSessionConfig();”.
serviceInstanceId ou serviceInterfaceInstanceId (para instância de serviço ou de interface, respectivamente): é o ID da instância de serviço ou de interface.
name1: nome da custom property. Este nome é a chave que irá identificá-la .
value2: valor da custom property.
transaction: transação com o banco de dados que será utilizada para persistir a custom property.

O método “setCustomProperties” é similar ao método “setCustomProperty”. A única diferença entre eles é que o último define um mapa de custom properties ao invés de uma única propriedade.

Para recuperarmos uma custom property de uma instância de serviço ou interface, o processo é similar ao de definição. É necessário acionar os métodos “getCustomProperty” ou “getCustomProperties” a partir dos managers “ServiceInstanceManager” ou “ServiceInterfaceInstanceManager” conforme apresentado no código a seguir.

//Recupera uma única propriedade de uma
//determinada instância de serviço
String value = ManagerFactory.getServiceInstanceManager().getCustomProperty(
sessionConfig,
serviceInstanceId,
name, 
transaction);
//Recupera um mapa de propriedades de uma
//determinada instância de serviço
Map<String, String> propertiesTable = ManagerFactory.getServiceInstanceManager().getCustomProperties(sessionConfig, serviceInstanceId, transaction);

Código 2 – Recuperando Custom Properties de uma instância de serviço

As custom properties possuem uma limitação quanto ao tamanho de seu identificador, podendo possuir até 100 caracteres. Já o tamanho máximo do valor de uma custom property é livre, havendo no máximo uma limitação imposta pelo banco de dados.

Acessando informações de Custom Properties através de interfaces Lumis

O framework do Lumis Portal disponibiliza recursos para manipular custom properties em nível de Interfaces de Serviços, ou seja, desenvolvedores podem gerenciar custom properties de uma instância de serviço ou interface, através de implementações de interfaces de serviços.

Para que seja possível tal recurso, foi implementado um conjunto de classes para ler e escrever custom properties de instâncias de serviços/interfaces.

ServiceInstanceCustomPropertiesDataProvider – Data Provider que obtém todas as custom properties da instância do serviço corrente;
InterfaceInstanceCustomPropertiesDataProvider – Data Provider que obtém todas as custom properties da instância da interface corrente;
ServiceInstanceCustomPropertiesProcessActionHandler – ProcessAction que faz a persistência das custom properties da instância de serviço corrente;
InterfaceInstanceCustomPropertiesProcessActionHandler – ProcessAction que faz a persistência das custom properties da instância de interface corrente;

Exemplo de utilização de custom properties através de interfaces de serviços

No código a seguir é apresentado um exemplo de utilização de Custom Properties através de interfaces de serviço.

<doui:douiDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:doui="http://www.lumis.com.br/lumisportal/xsd/doui" xmlns:control="http://www.lumis.com.br/douicontrols">
  <service id="lumis.service.sample.maxrows">
    <sources>
      <source id="default">
<dataProviderClassName>lumis.service.doui.customproperties.ServiceInstanceCustomPropertiesDataProvider</dataProviderClassName>
        <fields>
          <field id="maxRows" name="STR_MAX_ROWS" dataType="integer"/>
        </fields>
      </source>
    </sources>
  </service>
  <interfaces>
    <interface id="maxRows">
      <sources>
        <source id="default" readData="always"/>
      </sources>
      <controls>
        <control:lum_form onEnterProcessActionId="commit">
          <control:lum_propertyPage>
            <control:lum_controlGroup title="STR_BASIC_INFORMATION">
              <control:lum_table>
                <tr>
                  <td>
                    <control:lum_label dataId="maxRows" />
                  </td>
                  <td>
                    <control:lum_inputText id="maxRows" />
                  </td>
                </tr>
              </control:lum_table>
            </control:lum_controlGroup>	
          </control:lum_propertyPage>
        </control:lum_form>
      </controls>
      <processActions>
        <processAction id="commit" className="lumis.service.doui.customproperties.ServiceInstanceCustomPropertiesProcessActionHandler">
          <customProperties>
            <customProperty name=" doui_maxRows" />
          </customProperties>
          <response type="doui_closeWindow" />
        </processAction>
      </processActions>
    </interface>
  </interfaces>
</doui:douiDefinition>

Código 3 – Exemplo de utilização de custom properties através de interface de serviço

Temos, neste código, a definição de uma interface de serviço que irá adquirir o número máximo de linhas permitidas em uma listagem de dados. Para tal, foi definido um source que utiliza a classe InterfaceInstanceCustomPropertiesDataProvider para recuperar os valores da custom property “maxRows” referente à instância de interface (linhas 4 a 9). Este source é utilizado pela interface de serviço “maxRows”, que possui um processActionHandler que persiste o novo valor, informado pelo usuário, na custom property “maxRows” (linha 36). Este mesmo processActionHandler define, ainda, o nome dacustom property que armazena o valor informado na interface (linhas 37 a 39).

O exemplo apresentado ilustra uma forma de criar interfaces que viabilizem a manipulação de custom properties de uma instância de serviço a partir de uma interface. Também é possível manipular custom properties de instâncias de interfaces bastando, para isso, trocar as classes do DataProvider paralumis.service.doui.customproperties.InterfaceInstanceCustomPropertiesDataProvider e a classe do processActionHandler paralumis.service.doui.customproperties.InterfaceInstanceCustomPropertiesProcessActionHandler.

Quando utilizar propriedades de instância de serviço ou de interface

A única diferença entre a utilização de custom properties no nível da instância de serviço ou de interface é para quem essa propriedade estará aplicada. Propriedades definidas no nível da instância de serviço estarão conceitualmente associadas a todas as instâncias de interface daquela instância de serviço. Propriedades definidas para uma instância de interface são específicas para essa única instância. É importante que a decisão do nível onde aplicar essas propriedades seja criteriosa para manter a consistência da modelagem da solução.

Autor: André Santos (Lumis)