Utilizando APEX Collections: Estrutura temporária para armazenar dados na aplicação

Utilizando APEX Collections

APEX collection é uma estrutura temporária que se assemelha a uma tabela temporária. Os dados salvos podem ser acessados por toda a aplicação e ficam salvos ate que a sessão seja finalizada ou apagados propositalmente. Um bom exemplo de utilização é o carrinho de compras de uma loja online. Quando um usuário navega pela loja, os itens da possível compra são incluídos no carrinho e salvos temporariamente. Se o usuário desistir da compra e fechar o browser, a collection com os itens é apagada, evitando que dados salvos sem necessidade no banco de dados.

Uma collection possui a seguinte estrutura:

Não é possível inserir dados em uma collection utilizando os comandos DML, para isso é utilizado uma API do APEX chamado APEX_COLLECTION.

Criar uma Collection

Antes de utilizar a collection, precisamos inicializar ou cria-la. Para isso precisamos de um nome que não pode exceder 255 caracteres não importando se vai ter letras maiúsculas ou minúsculas. Quando a collection é criada, esse nome é convertido automaticamente para letras maiúsculas. É possível criar uma collection e depois inserir os dados ou já criar a collection informando uma consulta SQL que já vai criar a collection com os dados retornados pela consulta. No exemplo abaixo vou apenas criar a collection para depois inserir os dados.

Veja todas as opções aqui.

BEGIN
 APEX_COLLECTION.CREATE_COLLECTION(p_collection_name => 'ITENS_DO_CARRINHO');
END;

Agora com a collection criada, podemos inserir os dados.

Inserir dados

BEGIN
 apex_collection.add_member(p_collection_name => 'ITENS_DO_CARRINHO',
                            P_C001 => 'CAMISA001',     --Cod. Produto
                            P_C002 => 'M',             -- Tamanho
                            P_C003 => 'blue001',       -- Cod. Cor 
                            P_N001 => 1);              -- Quantidade
END;

Se acessarmos a partir da barra de desenvolvedor do APEX a opção “Session” e selecionarmos View = Collections, podemos ver todas as collections que possuem dados na sessão atual.

Nota: Se uma collection for criada e não possuir dados, ela não vai aparecer aqui.

É importante lembrar que para acessar os dados de uma collection, é necessário esta na mesma sessão da aplicação onde inserimos os dados. Para isso basta apenas realisar uma consulta na view APEX_COLLECTIONS informando o nome como parametro.

SELECT c001, c002, c003, n001
FROM APEX_collections
WHERE collection_name = 'ITENS_DO_CARRINHO';

Se realizarmos essa consulta em uma sessão do SQL developer ou ate mesmo do SQL Commands do APEX, ela vai retornar que nenhum dado foi encontrado. Como expliquei anteriormente, precisamos estar na mesma sessão da aplicação. Felizmente é possível acessar esses dados utilizando uma PL/SQL IDE, porém, precisamos habilitar o acesso a sessão da aplicação utilizado o APEX_SESSION API, porem isso é um tema para um próximo artigo.

Alterar um registro da collection

Para alterar os dados, podemos utilizar a procedure APEX_COLLECTION.UPDATE_MEMBER, porém, essa procedure altera todas as colunas. Se quisermos alterar somente a quantidade de itens de 1 para 2, teríamos que passar todos os dados do produto novamente, alterando a quantidade. Para alterar somente a quantidade sem a necessidade incluir todos os dados desse produto novamente, podemos utilizar a APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE.

BEGIN
     APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE (
         p_collection_name => 'ITENS_DO_CARRINHO',
         p_seq => 1,         -- Sequence ou ID da linha
         p_attr_number => 1, --N001
         p_number_value => 2); -- Quantidade modificada para 2
END;

Note que para cada tipo de dado, alteramos o parâmetro referente ao atributo a ser alterado. Nesse caso, utilizamos p_number_value para informar que o dado que desejamos alterar e o NUMBER na posicao 1 ou seja, n001. Para alterar por exemplo, o C001, basta trocar p_number_value para p_attr_value.

Veja como alterar outros atributos aqui

Apagar um registro

Para excluir um registro/membro da collection podemos utilizar o APEX_COLLECTION.DELETE_MEMBER

BEGIN
     APEX_COLLECTION.DELETE_MEMBER(
         p_collection_name => 'ITENS_DO_CARRINHO',
         p_seq => '1');
END;

Ainda temos a opção de alterar apenas o valor de uma coluna, para isso utilizamos o mesmo conceito do UPDATE_MEMBER_ATTRIBUTE, porém, chamando APEX_COLLECTION.DELETE_MEMBER_ATTRIBUTE.

Se precisarmos apagar todos os dados da collection porem sem apagá-la, podemos utilizar o APEX_COLLECTION.TRUNCATE_COLLECTION passando o nome da collection como parâmetro. Portanto, se quisermos apagar os dados e a collection basta utilizar APEX_COLLECTION.DELETE_COLLECTION.

É possível verificar se uma collection existe utilizando APEX_COLLECTION.COLLECTION_EXISTS passando como parâmetro o nome da collection. Isso é bem útil se for executado antes de criar uma collection. Caso uma collection já exista e tentarmos criar novamente irá retornar um erro. Se quisermos saber quantos registro existem, basta executar APEX_COLLECTION.COLLECTION_MEMBER_COUNT novamente passando o nome da collection como parâmetro.

Todos os exemplos mostrados nesse artigo estão disponíveis na APEX_COLLECTION API desde a versão 4.2., ou seja independente da versão que você esteja utilizando todos vão funcionar.